Skip to content

Start a new checkout session for renewing a subscription.

POST
/cms/customer/subscription/{subscription_id}/checkout
curl --request POST \
--url https://api.example.com/cms/customer/subscription/1/checkout \
--header 'API-Key: <API-Key>' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Token: <Token>' \
--data '{ "payment_method": "", "ip_address": "", "country": "NL", "source": "example", "page": "example", "button": "example", "properties": {} }'

Use this when the initial renewal attempt failed and you need to collect payment details again. This will create a new unpaid payment and return the checkout session details from the payment provider.

subscription_id
required
integer

Subscription ID

Media typeapplication/json
object
payment_method

Optional payment method to use for this renewal. If not provided, the existing payment method on the subscription will be used.

string

Example

ip_address

IP address of the customer. If not provided, the IP address from the request will be used.

string

Example

country

Country of the customer. If not provided, the country will be determined based on the IP address.

string

Example

NL
source

Source (web, app, etc.)

string
page

Source page URL

string
button

Source button

string
properties

Additional properties to save for this payment, such as UTM parameters, coupon code, affiliate info, etc.

object

Renewal successful

Media typeapplication/json
object
success

Indicates if request for renewal was successful. If not, only the subscription details are returned.

boolean
response

Payment provider response

object
payment
Payment

API representation of a payment

object
id

Payment ID

price

Order amount (DB decimal serialized as a string)

string
currency

Order currency

string
price_baseCurrency

Order amount in base currency (DB decimal serialized as a string)

string
status

Payment status

string
responseMessage

Response message

string
nullable
lastUpdate

Last update timestamp, MySQL datetime (Y-m-d H:i:s)

string
timestamp

Payment timestamp, MySQL datetime (Y-m-d H:i:s)

string
userId

User ID

nullable
paymentMethod

Payment method

string
renewal_id

Renewal ID

integer
nullable
cart

Cart items

Array<object>
object
item

Purchased product item. Currently serialized as a string reference of the form “WhiteBeard\ECommerce\ProductItems:” (see items_details for full objects).

One of:
Pricing Tier

API representation of an ecommerce pricing tier (product item)

object
id

Item ID

description

Description

string
productId

Product ID

product

Product name

string
price

Price

sale_price

The price it sells at today: its timed offer’s price while one runs, otherwise price

currency

Currency

string
available

Available

item_order

Item order

shippable

Shippable

weight

Weight

installments

Installments

oncePerUser

Once per user

isUpgrade

Is upgrade

upgradeType

Upgrade type

string
nullable
upgradeFrom

Upgrade from

string
upgradeExcludeItems

Upgrade exclude items

string
nullable
upgradePriceWeb

Upgrade price web

upgradePriceMobile

Upgrade price mobile

settings

Field values, keyed by field key (each {name, value, type}), e.g. {“size”: {“name”: “Size”, “value”: “large”, “type”: “list”}}: the same keys the product search takes in settings; an empty array when there are none

One of:
object
key
additional properties
object
name
string
value
string
type
string
hasImage

Has image

additional_label_1

Additional label 1

string
nullable
additional_label_2

Additional label 2

string
nullable
additional_label_3

Additional label 3

string
nullable
diameter

Diameter

length

Length

depth

Depth

width

Width

recurrent

Recurrent

recurrentPrice

Recurrent price

recurrentStart

Recurrent start

string
recurrentSchedule

Recurrent schedule

string
sku

SKU

string
prices

Prices per currency code, or an empty array when none

One of:
object
key
additional properties
object
price
One of:
string
recurrentPrice
One of:
string
stock_enabled

Stock enabled

stock_available

Stock available

allow_backorder

Whether orders are accepted when out of stock

packageQuantity

Package quantity

relatedItems

Related items

Array<object>
object
images

Images (attachments)

Array<object>
object
id
string
name
string
description
string
url

High resolution URL

string
url_original
string
url_thumbnail
string
focal
string
image_width
integer
nullable
image_height
integer
nullable
video

Video (only for video attachments)

object
type
string
duration

Duration (only when present in metadata)

integer
files

Files (attachments)

Array<object>
object
id
string
name
string
description
string
url
string
type
string
duration

Duration (only when present in metadata)

integer
product_details

Product details. Deprecated to avoid circular references. Use productId instead.

object
translations

Translations

action_data

Action data to be executed when a pricing tier is bought

Array<object>
nullable
object
function
string
param
string
group
string
action_data_renew

Action data to be executed when a pricing tier is bought as a renewal

Array<object>
nullable
object
function
string
param
string
group
string
quantity
integer
price
One of:
number
price_matrix

Price matrix

object
subtotal

Subtotal amount

number
shipping

Shipping amount

number
tax

Tax amount

number
discount

Discount amount

number
total

Total amount

number
shippingStatus

Shipping status. “delivered” means digitally delivered (no physical product); “shipped_delivered” is a physical shipment that arrived.

string
Allowed values: waiting backordered shipped shipped_delivered delivered
shippingTrackingNumber

Shipment tracking number: from the shipping provider when it created the shipment, or set by hand on the order. Null when there is none.

string
nullable
authorization

Authorization

string
nullable
address

Address. An empty address is serialized as the string “[]”.

nullable
One of:
object
shipping_address

Shipping address. An empty address may be serialized as the string “[]” or null.

nullable
One of:
object
shipping_price

Shipping price

tax_price

Tax price

referenceOrderId

Reference order ID

integer
nullable
source

Source of the payment (such as website or mobile app store)

string
properties

Payment properties: those sent when the payment was created (such as UTM parameters, coupon code, affiliate info, stripe_mode), and those the system keeps on it (such as renewal_id, or payment method and CRM sync details)

object
key
additional properties
any
subscription
Subscription

API representation of a customer subscription

object
id

Subscription ID

activationDate

Activation date, MySQL datetime (Y-m-d H:i:s)

string
deactivationDate

Deactivation date, MySQL datetime (Y-m-d H:i:s); “0000-00-00 00:00:00” when not set

string
userId

User ID

status

Status (“1” enabled, “0” disabled)

string
purchased_item

Purchased item

nullable
One of:
Pricing Tier

API representation of an ecommerce pricing tier (product item)

object
id

Item ID

description

Description

string
productId

Product ID

product

Product name

string
price

Price

sale_price

The price it sells at today: its timed offer’s price while one runs, otherwise price

currency

Currency

string
available

Available

item_order

Item order

shippable

Shippable

weight

Weight

installments

Installments

oncePerUser

Once per user

isUpgrade

Is upgrade

upgradeType

Upgrade type

string
nullable
upgradeFrom

Upgrade from

string
upgradeExcludeItems

Upgrade exclude items

string
nullable
upgradePriceWeb

Upgrade price web

upgradePriceMobile

Upgrade price mobile

settings

Field values, keyed by field key (each {name, value, type}), e.g. {“size”: {“name”: “Size”, “value”: “large”, “type”: “list”}}: the same keys the product search takes in settings; an empty array when there are none

One of:
object
key
additional properties
object
name
string
value
string
type
string
hasImage

Has image

additional_label_1

Additional label 1

string
nullable
additional_label_2

Additional label 2

string
nullable
additional_label_3

Additional label 3

string
nullable
diameter

Diameter

length

Length

depth

Depth

width

Width

recurrent

Recurrent

recurrentPrice

Recurrent price

recurrentStart

Recurrent start

string
recurrentSchedule

Recurrent schedule

string
sku

SKU

string
prices

Prices per currency code, or an empty array when none

One of:
object
key
additional properties
object
price
One of:
string
recurrentPrice
One of:
string
stock_enabled

Stock enabled

stock_available

Stock available

allow_backorder

Whether orders are accepted when out of stock

packageQuantity

Package quantity

relatedItems

Related items

Array<object>
object
images

Images (attachments)

Array<object>
object
id
string
name
string
description
string
url

High resolution URL

string
url_original
string
url_thumbnail
string
focal
string
image_width
integer
nullable
image_height
integer
nullable
video

Video (only for video attachments)

object
type
string
duration

Duration (only when present in metadata)

integer
files

Files (attachments)

Array<object>
object
id
string
name
string
description
string
url
string
type
string
duration

Duration (only when present in metadata)

integer
product_details

Product details. Deprecated to avoid circular references. Use productId instead.

object
translations

Translations

action_data

Action data to be executed when a pricing tier is bought

Array<object>
nullable
object
function
string
param
string
group
string
action_data_renew

Action data to be executed when a pricing tier is bought as a renewal

Array<object>
nullable
object
function
string
param
string
group
string
nextRenewal

Next renewal date, MySQL datetime (Y-m-d H:i:s)

string
lastFailedOrder

Last failed order ID

nullable
One of:
integer
attempts

Renewal attempts (DB integer serialized as a string)

string
referenceOrderId

Reference order ID

nullable
One of:
integer
group

Group code

string
group_name

Group name

string
paymentMethod

Payment method

string
cancellationRequestDate

Cancellation request date, MySQL datetime (Y-m-d H:i:s)

string
nullable
cancellationReason

Cancellation reason

string
nullable
cancellationReasonCustom

Cancellation reason (custom user text)

string
nullable
currency

Currency

string
nullable
in_grace_period

Subscription is in grace period

boolean
status_code

Computed status code. 1=Active, 2=Active (grace period), 3=On hold (retrying), 4=Active (Pending user cancellation), 5=User cancelled, 6=On hold, 7=Active (Renewal disabled), 8=Not started, 9=Upgraded, 10=Paused

integer
Allowed values: 1 2 3 4 5 6 7 8 9 10
status_code_text

Computed status code as human-readable text

string

Example

{
"payment": {
"price": "12",
"price_baseCurrency": "12",
"lastUpdate": "2026-09-29 13:22:40",
"timestamp": "2026-09-18 14:46:39",
"cart": [
{
"item": "WhiteBeard\\ECommerce\\ProductItems:133",
"price": 12
}
],
"shippingStatus": "waiting",
"shippingTrackingNumber": "1Z999AA10123456784",
"address": "[]",
"shipping_address": "[]",
"properties": {
"utm_source": "newsletter",
"renewal_id": 3
}
},
"subscription": {
"activationDate": "2026-09-18 15:30:29",
"deactivationDate": "2026-10-18 15:30:29",
"status": "1",
"purchased_item": {
"prices": {
"ZAR": {
"price": "1",
"recurrentPrice": "1"
}
},
"images": [
{
"id": "4",
"name": "watermarked",
"focal": "50% 50%",
"image_width": 654,
"image_height": 529,
"type": "image"
}
],
"files": [
{
"id": "5",
"type": "file"
}
],
"translations": {
"en": {
"description": "Description text",
"label1": "Label 1",
"label2": "Label 2",
"label3": "Label 3"
}
},
"action_data": [
{
"function": "registerSubscription",
"param": "365",
"group": "subscription"
}
],
"action_data_renew": [
{
"function": "registerSubscription",
"param": "365",
"group": "subscription"
}
]
},
"nextRenewal": "2026-10-18 15:30:29",
"lastFailedOrder": "20241",
"attempts": "0",
"referenceOrderId": "20241",
"cancellationRequestDate": "2026-09-18 15:30:29",
"status_code": 1
}
}

Bad Request

Unauthorized

Subscription not found