Subscriptions

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

string

Unique identifier with sub_ prefix (e.g., sub_abc123def456).

string

The customer’s ID associated with this subscription.

string

How proration is handled: create_prorations, always_invoice, or none.

string

The anchor date for billing cycles (ISO 8601).

string

When the subscription started (ISO 8601).

string

When the subscription ends. null for ongoing subscriptions.

string

When the next invoice will be generated (ISO 8601).

string

The total recurring amount for the subscription.

array

Array of subscription phases.

Show phase properties

string

Phase start date (ISO 8601).

string

Phase end date (ISO 8601). null for ongoing phases.

boolean

Whether this phase is currently active.

array

Array of items in this phase.

Show item properties

string

The price ID for this item.

string

The product ID.

string

The product name.

integer

Item quantity.

string

Price per unit.

string

Overridden price amount. null if using the standard price.

string

The actual price used (overridden or standard).

boolean

Whether this item recurs.

string

Billing interval (e.g., month).

integer

Number of intervals between charges.

string

When the subscription was created (ISO 8601).

string

When the subscription was last updated (ISO 8601).

List subscriptions

GET /v1/subscriptions

Retrieves a paginated list of all subscriptions in your account.

integer

default:"1"

Page number for pagination. Results are returned 25 items per page.

curl https://api.gettrxn.com/v1/subscriptions \
  -H "Authorization: Bearer $TRXN_TOKEN"

Response

{
  "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.

string

required

The subscription’s ID (e.g., sub_abc123def456).

curl https://api.gettrxn.com/v1/subscriptions/sub_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN"

Response

{
  "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.

string

required

The customer’s ID. Must belong to your account.

string

default:"create_prorations"

How to handle proration. One of: create_prorations, always_invoice, none.

string

The anchor date for billing cycles (ISO 8601 format).

array

required

Array of phase objects. Must include at least one phase.

Show phase properties

string

required

Phase start date (format: YYYY-MM-DD or ISO 8601).

string

Phase end date. null or omit for ongoing phases.

array

required

Array of phase item objects.

Show item properties

string

required

The price ID for the item. Must belong to your account.

integer

default:"1"

Quantity for this item.

string

Override the price amount for this item.

Simple subscription

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}
        ]
      }
    ]
  }'

Response

{
  "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:

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

Customer not found

{
  "error": "Customer not found"
}

Price not found

{
  "error": "Price not found: pri_invalid123"
}

Missing phases

{
  "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.

string

required

The subscription’s ID.

string

How to handle proration. One of: create_prorations, always_invoice, none.

string

The anchor date for billing cycles (ISO 8601 format).

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"
  }'

Response

{
  "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.

string

required

The subscription’s ID.

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

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

Phases must have at least one item.
All recurring items within a phase must have the same interval.
Phases cannot overlap.
Phases must be sequential without gaps (if an end date is specified).
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:

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

Integration example

# 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

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.

Introduction

Core resources

Billing

Crypto

Webhooks

Subscriptions

The subscription object

List subscriptions

Get subscription

Create subscription

Simple subscription

Multi-phase subscription (trial then paid)

Error responses

Update subscription

Delete subscription

Proration behavior values

Subscription phases

Phase rules

Billing cycle anchor

Automatic invoice generation

Integration example

Sandbox support

​The subscription object

​List subscriptions

​Get subscription

​Create subscription

​Simple subscription

​Multi-phase subscription (trial then paid)

​Error responses

​Update subscription

​Delete subscription

​Proration behavior values

​Subscription phases

​Phase rules

​Billing cycle anchor

​Automatic invoice generation

​Integration example

​Sandbox support

The subscription object

List subscriptions

Get subscription

Create subscription

Simple subscription

Multi-phase subscription (trial then paid)

Error responses

Update subscription

Delete subscription

Proration behavior values

Subscription phases

Phase rules

Billing cycle anchor

Automatic invoice generation

Integration example

Sandbox support