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 Unique identifier with sub_ prefix (e.g., sub_abc123def456).
The customer’s ID associated with this subscription.
How proration is handled: create_prorations, always_invoice, or none.
The anchor date for billing cycles (ISO 8601).
When the subscription started (ISO 8601).
When the subscription ends. null for ongoing subscriptions.
When the next invoice will be generated (ISO 8601).
The total recurring amount for the subscription.
Array of subscription phases. Phase start date (ISO 8601).
Phase end date (ISO 8601). null for ongoing phases.
Whether this phase is currently active.
Array of items in this phase. The price ID for this item.
Overridden price amount. null if using the standard price.
The actual price used (overridden or standard).
Whether this item recurs.
Billing interval (e.g., month).
Number of intervals between charges.
When the subscription was created (ISO 8601).
When the subscription was last updated (ISO 8601).
List subscriptions Retrieves a paginated list of all subscriptions in your account.
Page number for pagination. Results are returned 25 items per page.
curl https://api.gettrxn.com/v1/subscriptions \ -H "Authorization: Bearer $TRXN_TOKEN "
{ "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.
The subscription’s ID (e.g., sub_abc123def456).
curl https://api.gettrxn.com/v1/subscriptions/sub_abc123def456 \ -H "Authorization: Bearer $TRXN_TOKEN "
{ "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 Creates a new subscription with phases and items.
The customer’s ID. Must belong to your account.
proration_behavior
string
default: "create_prorations"
How to handle proration. One of: create_prorations, always_invoice, none.
The anchor date for billing cycles (ISO 8601 format).
Array of phase objects. Must include at least one phase. Phase start date (format: YYYY-MM-DD or ISO 8601).
Phase end date. null or omit for ongoing phases.
Array of phase item objects. phases[].items[].price_id
The price ID for the item. Must belong to your account.
phases[].items[].quantity
Quantity for this item.
phases[].items[].overridden_price_amount
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} ] } ] }'
{ "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 { "error" : "Customer not found" }
{ "error" : "Price not found: pri_invalid123" }
{ "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.
How to handle proration. One of: create_prorations, always_invoice, none.
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" }'
{ "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.
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_prorationsCreate prorated charges/credits when subscription changes mid-billing cycle (default). always_invoiceAlways create a full invoice immediately regardless of billing cycle. noneNo 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": "[email protected] "}' # 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.
