Subscriptions
Subscriptions allow customers to purchase products on a recurring basis. They can be created, retrieved, updated, and canceled through the provided endpoints. Subscriptions are associated with a specific store and customer and can have different statuses such as created, active, and canceled.
See the subscription fields for more details and options.
The Subscription object
Fields
- Name
id- Type
- int64
- Tags
- Description
id of the subscription
- Name
pretty_id- Type
- string
- Tags
- Description
human-readable id of the subscription
- Name
store_id- Type
- int64
- Tags
- Description
id of the store the subscription belongs to
- Name
customer- Type
- Customer
- Tags
- Description
the customer associated with this subscription
- Name
status- Type
- string
- Tags
- Description
status of the subscription (created, active, canceled)
- Name
billing_name- Type
- string
- Tags
- NULLABLE
- Description
billing name associated with the subscription
- Name
billing_email- Type
- string
- Tags
- NULLABLE
- Description
billing email associated with the subscription
- Name
gift- Type
- boolean
- Tags
- Description
whether the subscription is a gift
- Name
gift_to_customer- Type
- Customer
- Tags
- NULLABLE
- Description
the customer to whom the subscription is gifted
- Name
product_id- Type
- int64
- Tags
- Description
id of the product associated with the subscription
- Name
product_name- Type
- string
- Tags
- Description
name of the product associated with the subscription
- Name
product_image_url- Type
- string
- Tags
- NULLABLE
- Description
image URL of the product associated with the subscription
- Name
interval_value- Type
- int
- Tags
- Description
interval value indicating the frequency of the subscription
- Name
interval_scale- Type
- string
- Tags
- Description
interval scale indicating the unit of time for the subscription frequency (e.g., day, week, month)
- Name
currency- Type
- string
- Tags
- Description
currency of the subscription
- Name
tax_inclusive- Type
- boolean
- Tags
- Description
whether the subscription price is tax-inclusive
- Name
price- Type
- int64
- Tags
- Description
price of the subscription in zero-decimal format (where "$10.00" is 1000)
- Name
discount_amount- Type
- int64
- Tags
- Description
discount amount applied to the subscription
- Name
subtotal_amount- Type
- int64
- Tags
- Description
subtotal amount of the subscription
- Name
tax_amount- Type
- int64
- Tags
- Description
tax amount applied to the subscription
- Name
total_amount- Type
- int64
- Tags
- Description
total amount of the subscription
- Name
created_at- Type
- timestamp
- Tags
- Description
timestamp of when the subscription was created
- Name
updated_at- Type
- timestamp
- Tags
- NULLABLE
- Description
timestamp of when the subscription was last updated
- Name
active_at- Type
- timestamp
- Tags
- NULLABLE
- Description
timestamp of when the subscription became active
- Name
canceled_at- Type
- timestamp
- Tags
- NULLABLE
- Description
timestamp of when the subscription was canceled
- Name
cancel_reason- Type
- string
- Tags
- NULLABLE
- Description
reason for canceling the subscription
The Subscription object
{
"id": "150580776499843072",
"pretty_id": "pn-123abcd",
"store_id": "94688451781206016",
"customer": {
"id": "11084680073842688",
"first_name": "Example",
"last_name": "Customer"
},
"status": "active",
"billing_name": "Example Customer",
"billing_email": "[email protected]",
"gift": false,
"gift_to_customer": null,
"product_id": "123456789",
"product_name": "Example Product",
"product_image_url": "http://example.com/product-image.jpg",
"interval_value": 1,
"interval_scale": "month",
"currency": "usd",
"tax_inclusive": true,
"price": 1000,
"discount_amount": 0,
"subtotal_amount": 1000,
"tax_amount": 100,
"total_amount": 1100,
"created_at": "2023-04-11T16:42:58.197319Z",
"updated_at": null,
"active_at": "2023-04-11T16:42:58.197319Z",
"canceled_at": null,
"cancel_reason": null
}
Get Subscriptions
Retrieves a list of subscriptions for a specific store.
Query Parameters
- Name
limit- Type
- integer?
- Tags
- OPTIONAL
- Description
the max number of results to return (1 - 100)
- Name
after- Type
- flake?
- Tags
- OPTIONAL
- Description
an ID flake, after which to start returning results
- Name
before- Type
- flake?
- Tags
- OPTIONAL
- Description
an ID flake, before which to start returning results
- Name
customer_id- Type
- flake?
- Tags
- OPTIONAL
- Description
filter subscriptions created by a customer
Returns
Returns a list of subscriptions.
Request
Response
[
{
"id": "150580776499843072",
"pretty_id": "pn-123abcd",
"store_id": "94688451781206016",
"customer": {
"id": "11084680073842688",
"first_name": "Example",
"last_name": "Customer"
},
"status": "active",
"created_at": "2023-04-11T16:42:58.197319Z"
}
]
Get Subscription
Request
Response
{
"id": "150580776499843072",
"pretty_id": "pn-123abcd",
"store_id": "94688451781206016",
"customer": {
"id": "11084680073842688",
"first_name": "Example",
"last_name": "Customer"
},
"status": "active",
"created_at": "2023-04-11T16:42:58.197319Z"
}
Cancel Subscription
Cancels a specific subscription by ID.
Returns
Returns a 204 No Content response upon successful cancellation.