Renew Subscription
Create checkout baskets to renew an existing subscription. The basket is pre-populated with the subscription's renewal context.
Create a checkout basket for renewing an existing subscription. Looks up the subscription by its external reference, verifies the supplied customer details against it, and creates a basket pre-populated with the renewal context.
OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.
Obtain a token via the OAuth flow described in OAuth Bearer Token.
Pass the token in the Authorization header: Bearer <token>
The external reference of the subscription to renew. The lookup is by reference only; Limio subscription IDs are not accepted.
A-S00012345External order reference.
renewal-2024-001Pattern: ^[0-9a-zA-Z-_]+$Renewal checkout basket created successfully.
The unique ID of the created renewal basket.
basket-a1b2c3d4e5f6Customer segments applicable to the renewal. When a Salesforce contact is found for the subscription this is a JSON-encoded string containing an array of SHA-1 hashed segment paths; when no contact is found it is an empty array.
Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.
Application error. Returned when the subscription cannot be found for the supplied reference, or when verification of the supplied customer details fails.
Bad Gateway — an upstream service returned an unexpected response. This typically indicates an issue with the request payload (e.g. invalid field values, missing required fields) or a transient infrastructure error. Retry the request, and if the issue persists, verify the request body matches the expected schema.
POST /api/admin/checkout/initiate/renew HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 253
{
"subscriptionReference": "A-S00012345",
"external_id": "renewal-2024-001",
"verify": {
"customerDetails": {
"hashedEmail": "973dfe463ec85785f5f95af5ba3906eedb2d931c24e69824a89ea65dba4e813b",
"firstName": "text",
"lastName": "text"
},
"address": {
"postalCode": "text"
}
}
}{
"id": "basket-a1b2c3d4e5f6",
"segments": "text",
"order": {
"external_id": "text",
"order_type": "renew",
"subId": "text",
"subRef": "text",
"customerDetails": {
"firstName": "text",
"lastName": "text",
"email": "text"
},
"country": "text",
"renewalDetails": {
"subscription": {},
"attributes": {}
},
"tracking": {},
"hideEmailField": true,
"hidePriceField": true
}
}Queue a checkout for a subscription that a later job fills. Use it when the basket cannot be built in one request, for example when the subscription is only in Zuora and Limio must sync it first. The request returns at once with a queueLink. A job then syncs the subscription and fills the basket, while the customer waits on the waiting page.
jobParameters.order names the use case. A renewal names its variant. An offer change names no variant: it changes the offer from the effective date. Send only the fields of the use case. Limio derives the items, the price and the customer from the synced subscription.
| Use case | order_type | variant | Other fields | Available | | --- | --- | --- | --- | --- | | Renew on the same offer | renew_subscription | standard | none | yes | | Renew onto another offer | renew_subscription | switch | orderItems | not yet | | Change offer | change_offer | none | orderItems, effectiveDate | not yet |
A use case that is not available yet returns 422 use_case_not_supported. Its fields are provisional and can change before it is available.
The queueLink is a relative path to the assisted login. Open it on the shop domain of the customer, not on the admin host. The login signs the customer in as the basket owner and sends them to the waiting page, which polls the job and goes to checkout when the basket is ready.
OAuth 2.0 Bearer token for authenticated API access. Required for order submission, object management, and administrative operations.
Obtain a token via the OAuth flow described in OAuth Bearer Token.
Pass the token in the Authorization header: Bearer <token>
The job that fills the basket.
The checkout is queued.
The relative path to open on the shop domain of the customer. It signs the customer in and sends them to the waiting page.
/api/checkout/assisted?basketId=basket-a1b2c3d4&cl=…The request is not valid. Returned when a journey page does not exist on this shop, or when jobType or jobParameters fail validation.
Unauthorized: the request lacks valid authentication credentials. Verify your Bearer token or API key is correct and has not expired.
The use case is valid but not available yet. Limio creates no basket.
Bad Gateway — an upstream service returned an unexpected response. This typically indicates an issue with the request payload (e.g. invalid field values, missing required fields) or a transient infrastructure error. Retry the request, and if the issue persists, verify the request body matches the expected schema.
POST /api/admin/checkout/queue HTTP/1.1
Host: your-environment.prod.limio.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 383
{
"jobType": "synced_subscription_checkout",
"journey": {
"checkout": "/renewal-checkout",
"waiting": "/renewal-waiting"
},
"jobParameters": {
"recordToSync": {
"service": "zuora",
"id": "A-S00012345",
"type": "subscription"
},
"owner": {
"service": "zuora",
"id": "A00012345",
"type": "account"
},
"paymentTypes": [
"zuora_card"
],
"order": {
"order_type": "renew_subscription",
"variant": "standard",
"customFields": {}
}
}
}{
"queueLink": "/api/checkout/assisted?basketId=basket-a1b2c3d4&cl=…"
}Last updated
Was this helpful?