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

# Subscriptions

> Create and manage subscriptions for recurring billing. Subscriptions support multiple phases for trials, promotional periods, and plan changes.

This API allows you to create and manage subscriptions for your account. Subscriptions represent recurring billing arrangements with customers, supporting multiple phases for complex billing scenarios like trials, promotional periods, and plan changes.

## The subscription object

<ResponseField name="id" type="string">
  Unique identifier with `sub_` prefix (e.g., `sub_abc123def456`).
</ResponseField>

<ResponseField name="customer_id" type="string">
  The customer's ID associated with this subscription.
</ResponseField>

<ResponseField name="proration_behavior" type="string">
  How proration is handled: `create_prorations`, `always_invoice`, or `none`.
</ResponseField>

<ResponseField name="billing_cycle_anchor" type="string">
  The anchor date for billing cycles (ISO 8601).
</ResponseField>

<ResponseField name="start_date" type="string">
  When the subscription started (ISO 8601).
</ResponseField>

<ResponseField name="end_date" type="string">
  When the subscription ends. `null` for ongoing subscriptions.
</ResponseField>

<ResponseField name="next_billing_date" type="string">
  When the next invoice will be generated (ISO 8601).
</ResponseField>

<ResponseField name="total_amount" type="string">
  The total recurring amount for the subscription.
</ResponseField>

<ResponseField name="phases" type="array">
  Array of subscription phases.

  <Expandable title="phase properties">
    <ResponseField name="phases[].start_date" type="string">
      Phase start date (ISO 8601).
    </ResponseField>

    <ResponseField name="phases[].end_date" type="string">
      Phase end date (ISO 8601). `null` for ongoing phases.
    </ResponseField>

    <ResponseField name="phases[].is_active" type="boolean">
      Whether this phase is currently active.
    </ResponseField>

    <ResponseField name="phases[].items" type="array">
      Array of items in this phase.

      <Expandable title="item properties">
        <ResponseField name="price_id" type="string">
          The price ID for this item.
        </ResponseField>

        <ResponseField name="product_id" type="string">
          The product ID.
        </ResponseField>

        <ResponseField name="product_name" type="string">
          The product name.
        </ResponseField>

        <ResponseField name="quantity" type="integer">
          Item quantity.
        </ResponseField>

        <ResponseField name="unit_amount" type="string">
          Price per unit.
        </ResponseField>

        <ResponseField name="overridden_price_amount" type="string">
          Overridden price amount. `null` if using the standard price.
        </ResponseField>

        <ResponseField name="effective_price" type="string">
          The actual price used (overridden or standard).
        </ResponseField>

        <ResponseField name="recurring" type="boolean">
          Whether this item recurs.
        </ResponseField>

        <ResponseField name="interval" type="string">
          Billing interval (e.g., `month`).
        </ResponseField>

        <ResponseField name="interval_count" type="integer">
          Number of intervals between charges.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  When the subscription was created (ISO 8601).
</ResponseField>

<ResponseField name="updated_at" type="string">
  When the subscription was last updated (ISO 8601).
</ResponseField>

## List subscriptions

```
GET /v1/subscriptions
```

Retrieves a paginated list of all subscriptions in your account.

<ParamField query="page" type="integer" default="1">
  Page number for pagination. Results are returned 25 items per page.
</ParamField>

```bash theme={null}
curl https://api.gettrxn.com/v1/subscriptions \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

```json Response theme={null}
{
  "subscriptions": [
    {
      "id": "sub_abc123def456",
      "customer_id": "cus_xyz789",
      "proration_behavior": "create_prorations",
      "billing_cycle_anchor": "2025-02-01T00:00:00Z",
      "start_date": "2025-01-15T00:00:00Z",
      "end_date": null,
      "next_billing_date": "2025-02-15T00:00:00Z",
      "total_amount": "99.99",
      "created_at": "2025-01-15T12:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z",
      "phases": [
        {
          "start_date": "2025-01-15T00:00:00Z",
          "end_date": null,
          "is_active": true,
          "items": [
            {
              "price_id": "pri_abc123",
              "product_id": "pro_xyz789",
              "product_name": "Premium Plan",
              "quantity": 1,
              "unit_amount": "99.99",
              "overridden_price_amount": null,
              "effective_price": "99.99",
              "recurring": true,
              "interval": "month",
              "interval_count": 1
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "pages": 2,
    "count": 45
  }
}
```

## Get subscription

```
GET /v1/subscriptions/:id
```

Retrieves a specific subscription by ID with all phases and items.

<ParamField path="id" type="string" required>
  The subscription's ID (e.g., `sub_abc123def456`).
</ParamField>

```bash theme={null}
curl https://api.gettrxn.com/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

```json Response theme={null}
{
  "id": "sub_abc123def456",
  "customer_id": "cus_xyz789",
  "proration_behavior": "create_prorations",
  "billing_cycle_anchor": "2025-02-01T00:00:00Z",
  "start_date": "2025-01-15T00:00:00Z",
  "end_date": null,
  "next_billing_date": "2025-02-15T00:00:00Z",
  "total_amount": "99.99",
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-15T12:00:00Z",
  "phases": [
    {
      "start_date": "2025-01-15T00:00:00Z",
      "end_date": null,
      "is_active": true,
      "items": [
        {
          "price_id": "pri_abc123",
          "product_id": "pro_xyz789",
          "product_name": "Premium Plan",
          "quantity": 1,
          "unit_amount": "99.99",
          "overridden_price_amount": null,
          "effective_price": "99.99",
          "recurring": true,
          "interval": "month",
          "interval_count": 1
        }
      ]
    }
  ]
}
```

## Create subscription

```
POST /v1/subscriptions
```

Creates a new subscription with phases and items.

<ParamField body="customer_id" type="string" required>
  The customer's ID. Must belong to your account.
</ParamField>

<ParamField body="proration_behavior" type="string" default="create_prorations">
  How to handle proration. One of: `create_prorations`, `always_invoice`, `none`.
</ParamField>

<ParamField body="billing_cycle_anchor" type="string">
  The anchor date for billing cycles (ISO 8601 format).
</ParamField>

<ParamField body="phases" type="array" required>
  Array of phase objects. Must include at least one phase.

  <Expandable title="phase properties">
    <ParamField body="phases[].start_date" type="string" required>
      Phase start date (format: `YYYY-MM-DD` or ISO 8601).
    </ParamField>

    <ParamField body="phases[].end_date" type="string">
      Phase end date. `null` or omit for ongoing phases.
    </ParamField>

    <ParamField body="phases[].items" type="array" required>
      Array of phase item objects.

      <Expandable title="item properties">
        <ParamField body="phases[].items[].price_id" type="string" required>
          The price ID for the item. Must belong to your account.
        </ParamField>

        <ParamField body="phases[].items[].quantity" type="integer" default="1">
          Quantity for this item.
        </ParamField>

        <ParamField body="phases[].items[].overridden_price_amount" type="string">
          Override the price amount for this item.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Simple subscription

```bash theme={null}
curl -X POST https://api.gettrxn.com/v1/subscriptions \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xyz789",
    "billing_cycle_anchor": "2025-02-01T00:00:00Z",
    "proration_behavior": "create_prorations",
    "phases": [
      {
        "start_date": "2025-01-15",
        "items": [
          {"price_id": "pri_monthly_plan", "quantity": 1}
        ]
      }
    ]
  }'
```

```json Response theme={null}
{
  "id": "sub_new123subscription456",
  "customer_id": "cus_xyz789",
  "proration_behavior": "create_prorations",
  "billing_cycle_anchor": "2025-02-01T00:00:00Z",
  "start_date": "2025-01-15T00:00:00Z",
  "end_date": null,
  "next_billing_date": "2025-02-01T00:00:00Z",
  "total_amount": "99.99",
  "created_at": "2025-01-15T14:30:00Z",
  "updated_at": "2025-01-15T14:30:00Z",
  "phases": [...]
}
```

### Multi-phase subscription (trial then paid)

Create a subscription with a trial phase followed by a paid phase:

```bash theme={null}
curl -X POST https://api.gettrxn.com/v1/subscriptions \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xyz789",
    "phases": [
      {
        "start_date": "2025-01-15",
        "end_date": "2025-02-15",
        "items": [
          {"price_id": "pri_trial_plan", "quantity": 1}
        ]
      },
      {
        "start_date": "2025-02-15",
        "items": [
          {"price_id": "pri_monthly_plan", "quantity": 1}
        ]
      }
    ]
  }'
```

### Error responses

```json Customer not found theme={null}
{
  "error": "Customer not found"
}
```

```json Price not found theme={null}
{
  "error": "Price not found: pri_invalid123"
}
```

```json Missing phases theme={null}
{
  "errors": {
    "subscription_phases": ["must have at least one phase"]
  }
}
```

## Update subscription

```
PATCH /v1/subscriptions/:id
```

Updates an existing subscription's proration behavior or billing cycle anchor.

<ParamField path="id" type="string" required>
  The subscription's ID.
</ParamField>

<ParamField body="proration_behavior" type="string">
  How to handle proration. One of: `create_prorations`, `always_invoice`, `none`.
</ParamField>

<ParamField body="billing_cycle_anchor" type="string">
  The anchor date for billing cycles (ISO 8601 format).
</ParamField>

```bash theme={null}
curl -X PATCH https://api.gettrxn.com/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "proration_behavior": "none"
  }'
```

```json Response theme={null}
{
  "id": "sub_abc123def456",
  "customer_id": "cus_xyz789",
  "proration_behavior": "none",
  "billing_cycle_anchor": "2025-02-01T00:00:00Z",
  "start_date": "2025-01-15T00:00:00Z",
  "end_date": null,
  "next_billing_date": "2025-02-15T00:00:00Z",
  "total_amount": "99.99",
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-16T10:00:00Z",
  "phases": [...]
}
```

## Delete subscription

```
DELETE /v1/subscriptions/:id
```

Cancels and deletes a subscription.

<ParamField path="id" type="string" required>
  The subscription's ID.
</ParamField>

```bash theme={null}
curl -X DELETE https://api.gettrxn.com/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

Returns `204 No Content` on successful deletion.

## Proration behavior values

| Value               | Description                                                                            |
| ------------------- | -------------------------------------------------------------------------------------- |
| `create_prorations` | Create prorated charges/credits when subscription changes mid-billing cycle (default). |
| `always_invoice`    | Always create a full invoice immediately regardless of billing cycle.                  |
| `none`              | No proration -- charges start on the next billing cycle.                               |

## Subscription phases

Subscriptions support multiple phases to handle complex billing scenarios:

* **Trial phases**: Free or discounted periods at the start of a subscription.
* **Promotional phases**: Temporary discounts or special pricing.
* **Plan changes**: Scheduled upgrades or downgrades.
* **Ongoing phases**: Indefinite billing with no end date.

### Phase rules

<Note>
  All recurring items within a phase must have the same interval (e.g., all monthly). Phases cannot overlap and must be sequential without gaps.
</Note>

1. Phases must have at least one item.
2. All recurring items within a phase must have the same interval.
3. Phases cannot overlap.
4. Phases must be sequential without gaps (if an end date is specified).
5. Only one phase can be active at any time.

## Billing cycle anchor

The `billing_cycle_anchor` determines when recurring invoices are generated:

* If set, invoices are generated relative to this date.
* If not set, invoices are generated relative to the subscription start date.
* Useful for aligning billing to specific dates (e.g., 1st of the month).

## Automatic invoice generation

When a subscription is created:

1. An initial invoice may be generated based on proration behavior.
2. Recurring invoices are automatically generated on billing dates.
3. The `next_billing_date` field shows when the next invoice will be created.

## Integration example

```bash theme={null}
# 1. Create a customer
curl -X POST https://api.gettrxn.com/v1/customers \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "subscriber@example.com"}'

# Response: {"id": "cus_abc123", ...}

# 2. Create a subscription with a trial and regular phase
curl -X POST https://api.gettrxn.com/v1/subscriptions \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_abc123",
    "phases": [
      {
        "start_date": "2025-01-15",
        "end_date": "2025-01-29",
        "items": [
          {"price_id": "pri_free_trial", "quantity": 1}
        ]
      },
      {
        "start_date": "2025-01-29",
        "items": [
          {"price_id": "pri_monthly_plan", "quantity": 1}
        ]
      }
    ]
  }'

# 3. Check subscription status
curl https://api.gettrxn.com/v1/subscriptions/sub_xyz789 \
  -H "Authorization: Bearer $TRXN_TOKEN"

# 4. Update proration behavior if needed
curl -X PATCH https://api.gettrxn.com/v1/subscriptions/sub_xyz789 \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"proration_behavior": "none"}'
```

## Sandbox support

<Note>
  The API respects sandbox scoping. If your API token is associated with a sandbox, you can only access subscriptions created in that sandbox. Subscriptions created in sandbox mode will be isolated from production data.
</Note>