{
"id": "sub_1a2b3c4d5e6f",
"customer": {
"customer_id": "cust_xyz789",
"email": "jane@example.com",
"name": "Jane Doe",
"phone_number": "+2348012345678",
"metadata": {
"plan": "pro"
},
"created_at": "2026-01-24T12:00:00.000Z",
"updated_at": "2026-01-24T12:00:00.000Z",
"billing_address": {
"line1": "40 Yaba Road",
"line2": null,
"city": "Lagos",
"state": "Lagos",
"postal_code": "101245",
"country": "NG"
}
},
"payment_method_id": "pm_7h8i9j0k",
"status": "active",
"collection_method": "charge_automatically",
"currency": "USD",
"amount": "10.00",
"billing_cycle": {
"interval": "month",
"frequency": 1
},
"quantity": 1,
"current_period_start": "2026-04-01T00:00:00Z",
"current_period_end": "2026-05-01T00:00:00Z",
"previously_billed_at": "2026-04-01T00:00:00Z",
"next_billed_at": "2026-05-01T00:00:00Z",
"trial_end": "2026-04-15T00:00:00Z",
"cancel_at_period_end": false,
"canceled_at": null,
"created_at": "2026-03-01T12:00:00Z",
"product": {
"id": "prod_abc123",
"name": "Pro plan",
"description": "Everything in Basic, plus priority support.",
"status": "active",
"billing_cycle": {
"interval": "month",
"frequency": 1
},
"trial_period": {
"interval": "day",
"frequency": 14
},
"created_at": "2026-03-01T12:00:00Z",
"updated_at": "2026-03-01T12:00:00Z"
},
"items": [
{
"id": "si_11aa22bb",
"status": "active",
"quantity": 1,
"recurring": true,
"price_type": "fixed",
"unit_amount": "10.00",
"currency": "USD",
"previously_billed_at": "2026-04-01T00:00:00Z",
"next_billed_at": "2026-05-01T00:00:00Z",
"price": {
"id": "price_pro_usd",
"product_id": "prod_abc123",
"price_type": "fixed",
"currency": "USD",
"unit_amount": "10.00",
"billing_cycle": {
"interval": "month",
"frequency": 1
},
"trial_period": {
"interval": "day",
"frequency": 14
},
"seat_tiers": null,
"is_archived": false,
"created_at": "2026-03-01T12:00:00Z",
"updated_at": "2026-03-01T12:00:00Z"
},
"product": {
"id": "prod_abc123",
"name": "Pro plan",
"description": "Everything in Basic, plus priority support.",
"status": "active",
"billing_cycle": {
"interval": "month",
"frequency": 1
},
"trial_period": {
"interval": "day",
"frequency": 14
},
"created_at": "2026-03-01T12:00:00Z",
"updated_at": "2026-03-01T12:00:00Z"
},
"created_at": "2026-03-01T12:00:00Z",
"updated_at": "2026-04-01T00:00:00Z"
}
],
"metadata": {
"plan": "pro",
"seat_count": "5"
}
}The subscription object
A subscription bills a customer for a recurring product on a fixed cadence. It is created when a customer completes a checkout for a recurring product, and it renews automatically until canceled.
Unique identifier for the subscription.
"sub_1a2b3c4d5e6f"
The customer billed on each renewal, expanded inline so you can show who is being charged without a second call.
Show child attributes
Show child attributes
The saved payment method billed on each renewal. null until a payment method is attached.
"pm_7h8i9j0k"
Status of the subscription. Set automatically by Bachs as payments succeed or fail. trialing: In a free trial. No payment has been collected yet. trial_end marks when billing begins. active: Active and paid. Bachs is billing this subscription automatically each cycle. past_due: A cycle payment failed. Bachs is retrying the payment while access continues. unpaid: Payment retries have been exhausted. Access should be restricted. canceled: Canceled and will not renew. This is a terminal state. paused: Temporarily suspended. Billing is halted until the subscription resumes.
trialing, active, past_due, unpaid, canceled, paused "active"
How renewals are collected. charge_automatically bills the saved card each cycle.
"charge_automatically"
The currency the subscription is billed in, as an ISO 4217 code. Subscriptions are USD only today.
"USD"
Recurring amount as a decimal string
"10.00"
How often the subscription renews, as an interval unit and a frequency, for example month with a frequency of 1 for monthly billing.
Show child attributes
Show child attributes
Total billable quantity across the subscription's line items.
1
Start of the period currently being billed for, in UTC.
"2026-04-01T00:00:00Z"
End of the period currently being billed for, in UTC. The next charge lands at this time unless the subscription is canceled first.
"2026-05-01T00:00:00Z"
Start of the period that was last billed
"2026-04-01T00:00:00Z"
Next scheduled charge date
"2026-05-01T00:00:00Z"
When the free trial ends and billing begins, in UTC. null if the subscription is not trialing.
"2026-04-15T00:00:00Z"
When true, the subscription stays active until current_period_end and is not renewed. When false, it renews normally.
false
When the subscription was canceled, in UTC. null if it has not been canceled.
null
When the subscription was created, in UTC.
"2026-03-01T12:00:00Z"
The catalog product this subscription bills for, or null when the subscription is not tied to a single product.
Show child attributes
Show child attributes
The line items that make up the subscription. Each item ties a product and its price to a billed quantity.
Show child attributes
Show child attributes
Your own key-value data attached to the subscription at creation, returned unchanged.
{ "plan": "pro", "seat_count": "5" }