Skip to main content
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

​
id
string
Unique identifier. Prefixed with sub_.
​
object
string
Always "subscription".
​
customer_id
string
The customer this subscription belongs to.
​
product_id
string
The product being subscribed to.
​
status
string
One of trialing, active, past_due, paused, or canceled.
​
current_period_start
string
ISO 8601 timestamp. Start of the current billing period.
​
current_period_end
string
ISO 8601 timestamp. End of the current billing period.
​
cancel_at_period_end
boolean
If true, the subscription will cancel at the end of the current period rather than renewing.
​
canceled_at
string
ISO 8601 timestamp. Set when the subscription is canceled.
​
paused_at
string
ISO 8601 timestamp. Set when the subscription is paused.
​
trial_days
number
Number of trial days, if any.
​
failed_payment_count
number
Number of consecutive failed renewal attempts.
​
metadata
object
Arbitrary key-value data.
​
created_at
string
ISO 8601 timestamp.
​
updated_at
string
ISO 8601 timestamp.

​
List subscriptions

GET /subscriptions?customer_id={customer_id} Returns all subscriptions for a customer. 
curl "https://api.stellartools.dev/subscriptions?customer_id=cus_01jx..." \
  -H "x-api-key: YOUR_API_KEY"
​
customer_id
string
required
The customer whose subscriptions to list.

​
Retrieve a subscription

GET /subscriptions/{id} Fetches the subscription and syncs its status with the Stellar network before returning. 
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} 
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

​
cancel_at_period_end
boolean
Set to true to schedule cancellation at the end of the current period, or false to undo a scheduled cancellation.
​
metadata
object
Merged with existing metadata.
​
product_id
string
Swap to a different product.

​
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. 
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 
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 
curl -X POST https://api.stellartools.dev/subscriptions/sub_01jx.../resume \
  -H "x-api-key: YOUR_API_KEY"