Retrieve a subscription
Retrieve a subscription by its unique identifier.
Use this endpoint to get the current state and details of a specific subscription.
Request
The ID of the subscription.
Example: "Bearer sk_1234567890ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890-Ab_cdeFGHijkLMNopq"
This parameter accepts the Merchant API Secret key to authorise requests coming from the merchant's backend.
It ensures that ensures that each request is authenticated and authorised by verifying the secret key. The secret key should be included in all request headers as a Bearer token.
For more information, see: Authentication
Possible values: [2023-09-01, 2024-05-01, 2024-09-01, 2025-10-16, 2025-12-04, 2026-03-12, 2026-04-20]
Example: "2026-04-20"
The version of the Merchant API, specified in YYYY-MM-DD format.
If not specified, you will receive an error.
For more information about API versioning, see: API versions.
Response
Subscription retrieved successfully
Unique identifier for the subscription.
Possible length: <= 1024 characters
Optional external reference for the subscription.
Use this field to store your own system's identifier for easy tracking and correlation.
Possible values: [pending, active, overdue, paused, cancelled, finished]
The state of the subscription.
| State | Description |
|---|---|
pending | The subscription has been created but is not yet active. This typically occurs when awaiting the first payment or setup completion. |
active | The subscription is currently active and billing cycles are processing normally. |
overdue | The subscription has a failed payment and is awaiting resolution. |
paused | The subscription has been temporarily paused and no billing will occur. |
cancelled | The subscription has been cancelled and will not renew. |
finished | The subscription has completed all billing cycles (for limited-duration subscriptions). |
Unique identifier for the customer.
Unique identifier for the subscription plan.
Unique identifier for the subscription plan variation.
Possible values: [automatic, manual]
The type of payment method used for the subscription.
| Type | Description |
|---|---|
automatic | Payments are automatically charged to the customer's saved payment method. |
manual | Payments require manual processing by the customer. |
Unique identifier for the payment method.
The date and time the subscription was created in ISO 8601 format.
The date and time the subscription was last updated in ISO 8601 format.
The date and time the subscription started in ISO 8601 format.
This field is null until the subscription becomes active.
Unique identifier for the subscription cycle.
Pattern: Value must match regular expression ^P[0-9]+D$
Example: "P14D"
The trial period duration for this subscription in ISO 8601 duration format (e.g., "P14D" for 14 days).
Override plan defaults
Subscription plans can define a default trial duration. When creating a subscription, you can use this field to override the plan's default trial period:
| Field value | Behaviour | Example |
|---|---|---|
| Not provided | Uses the trial duration defined in the plan (if any) | Plan has "P7D" → subscription gets 7-day trial |
| Different value | Overrides the plan's default trial duration | Plan has "P7D" → set to "P30D" for promotional offer, or "P3D" to reduce |
"P0D" | Explicitly skips the trial period | Plan has "P7D" → set to "P0D" to skip trial entirely |
Only days (D) are allowed. Time components such as hours, minutes, or seconds are not permitted.
Example: "2025-06-19T21:00:00.036001Z"
The date and time when the subscription's trial period ends in ISO 8601 format.
This value is automatically calculated by the system as: start_date + trial_duration
The trial_duration used in the calculation comes from either:
- The subscription's custom
trial_duration(if provided at creation time), or - The plan's default
trial_duration(if no override was specified)
This field is null when the subscription has no trial period (e.g., when trial_duration is not set or is "P0D").
The ID of the order created for handling the setup payment for the subscription.
Use the Retrieve an order endpoint with this ID to get order details, including the checkout_url for redirecting customers to the Hosted Payment Page or the token for widget integration.
The order is created in parallel to the subscription and is used to collect the initial payment and save the customer's payment method for future billing cycles.
A pending scheduled action on the subscription, applied at the end of the current billing cycle.
A cancellation scheduled to take effect at the end of the current billing cycle.
Possible values: [cancel, change_plan_variation]
Example: "change_plan_variation"
The type of the scheduled action.
| Value | Description |
|---|---|
cancel | A cancellation scheduled to take effect at the end of the current billing cycle. |
change_plan_variation | A plan variation change scheduled to take effect at the end of the current billing cycle. |
Possible values: [customer_request, merchant_request]
Example: "customer_request"
Default value: merchant_request
The reason for the scheduled action. This field is informational and does not affect how the action is processed.
| Value | Description |
|---|---|
customer_request | The action was requested by the customer. |
merchant_request | The action was initiated by the merchant. |