> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stellartools.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions

> Manage recurring billing subscriptions

Subscriptions are created automatically when a customer completes a checkout for a `subscription` product. Use these endpoints to retrieve, update, pause, resume, or cancel them.

## The subscription object

<ResponseField name="id" type="string">
  Unique identifier. Prefixed with `sub_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"subscription"`.
</ResponseField>

<ResponseField name="customer_id" type="string">
  The customer this subscription belongs to.
</ResponseField>

<ResponseField name="product_id" type="string">
  The product being subscribed to.
</ResponseField>

<ResponseField name="status" type="string">
  One of `trialing`, `active`, `past_due`, `paused`, or `canceled`.
</ResponseField>

<ResponseField name="current_period_start" type="string">
  ISO 8601 timestamp. Start of the current billing period.
</ResponseField>

<ResponseField name="current_period_end" type="string">
  ISO 8601 timestamp. End of the current billing period.
</ResponseField>

<ResponseField name="cancel_at_period_end" type="boolean">
  If `true`, the subscription will cancel at the end of the current period rather than renewing.
</ResponseField>

<ResponseField name="canceled_at" type="string">
  ISO 8601 timestamp. Set when the subscription is canceled.
</ResponseField>

<ResponseField name="paused_at" type="string">
  ISO 8601 timestamp. Set when the subscription is paused.
</ResponseField>

<ResponseField name="trial_days" type="number">
  Number of trial days, if any.
</ResponseField>

<ResponseField name="failed_payment_count" type="number">
  Number of consecutive failed renewal attempts.
</ResponseField>

<ResponseField name="metadata" type="object">
  Arbitrary key-value data.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

***

## List subscriptions

`GET /subscriptions?customer_id={customer_id}`

Returns all subscriptions for a customer.

```bash theme={null}
curl "https://api.stellartools.dev/subscriptions?customer_id=cus_01jx..." \
  -H "x-api-key: YOUR_API_KEY"
```

<ParamField query="customer_id" type="string" required>
  The customer whose subscriptions to list.
</ParamField>

***

## Retrieve a subscription

`GET /subscriptions/{id}`

Fetches the subscription and syncs its status with the Stellar network before returning.

```bash theme={null}
curl https://api.stellartools.dev/subscriptions/sub_01jx... \
  -H "x-api-key: YOUR_API_KEY"
```

The response includes `related_resources` (the product and asset) and `last_attempt` (the most recent payment).

***

## Update a subscription

`PUT /subscriptions/{id}`

```bash theme={null}
curl -X PUT https://api.stellartools.dev/subscriptions/sub_01jx... \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cancel_at_period_end": true }'
```

### Body

<ParamField body="cancel_at_period_end" type="boolean">
  Set to `true` to schedule cancellation at the end of the current period, or `false` to undo a scheduled cancellation.
</ParamField>

<ParamField body="metadata" type="object">
  Merged with existing metadata.
</ParamField>

<ParamField body="product_id" type="string">
  Swap to a different product.
</ParamField>

***

## Cancel a subscription

`POST /subscriptions/{id}/cancel`

Schedules the subscription to cancel at the end of the current billing period. The customer keeps access until `current_period_end`; no further renewals are charged. On-chain cancellation happens automatically when the period ends.

```bash theme={null}
curl -X POST https://api.stellartools.dev/subscriptions/sub_01jx.../cancel \
  -H "x-api-key: YOUR_API_KEY"
```

Returns the updated subscription object with `cancel_at_period_end: true` and `status` still `active`.

To undo a scheduled cancellation before the period ends, use `PUT /subscriptions/{id}` with `{ "cancel_at_period_end": false }`.

***

## Pause a subscription

`POST /subscriptions/{id}/pause`

```bash theme={null}
curl -X POST https://api.stellartools.dev/subscriptions/sub_01jx.../pause \
  -H "x-api-key: YOUR_API_KEY"
```

***

## Resume a subscription

`POST /subscriptions/{id}/resume`

```bash theme={null}
curl -X POST https://api.stellartools.dev/subscriptions/sub_01jx.../resume \
  -H "x-api-key: YOUR_API_KEY"
```