Skip to main content
POST
/
api
/
v1
/
checkout-session
Create Checkout Session
curl --request POST \
  --url https://demo.api.loopcrypto.xyz/api/v1/checkout-session \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --header 'entity-id: <api-key>' \
  --data '{
  "elements": [
    {
      "externalPriceId": "price_12345",
      "itemId": "12334-55322-122-123314"
    }
  ],
  "externalSubscriptionId": "sub_12345",
  "externalCustomerId": "cus_12345",
  "externalInvoiceId": "in_12345",
  "externalInvoiceNumber": "A1234-001",
  "freeTrialDays": 7,
  "couponCode": "SUMMER2025",
  "email": "info@loopcrypto.xyz",
  "referenceId": "ref_12345",
  "payInvoiceImmediately": true,
  "cartEnabled": false,
  "metadata": "{'\''customerId'\'': '\''12345'\''}",
  "template": false,
  "suggestedAllowanceAmount": 1001,
  "minimumAllowanceAmount": 1001,
  "minimumBalanceAmount": 1001,
  "upgradeSubscription": true,
  "successUrl": "https://www.loopcrypto.xyz/success",
  "paymentTokens": [
    {
      "networkId": 1,
      "tokenSymbols": [
        "USDC",
        "USDT"
      ],
      "tokenAddresses": [
        "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "0x1234567890123456789012345678901234567890"
      ]
    }
  ],
  "resetBillingCycle": true
}'
{
  "id": "cs_12345",
  "active": "true",
  "elements": [
    {
      "itemId": "12334-55322-122-123314",
      "externalPriceId": "price_12345"
    }
  ],
  "externalSubscriptionId": "sub_12345",
  "externalCustomerId": "cus_12345",
  "externalInvoiceId": "in_12345",
  "referenceId": "ref_12345",
  "emailAddress": "info@loopcrypto.xyz",
  "freeTrialDays": 7,
  "couponCodeId": "12345",
  "payInvoiceImmediately": true,
  "cartEnabled": false,
  "billDate": 1746869711,
  "metadata": {},
  "expirationDate": "1746869711",
  "childTemplate": true,
  "suggestedAllowanceAmount": 1001,
  "minimumAllowanceAmount": 1001,
  "minimumBalanceAmount": 1001,
  "upgradeSubscription": true,
  "template": false,
  "successUrl": "https://www.loopcrypto.xyz/success",
  "tokens": [
    {
      "networkId": 1,
      "tokenSymbol": "USDC",
      "tokenAddress": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174"
    }
  ],
  "resetBillingCycle": true
}

Authorizations

​
api-key
string
header
required
​
entity-id
string
header
required

Body

application/json
​
elements
object[]

Items included in the checkout session

​
externalSubscriptionId
string

Existing Stripe subscription ID. If provided, the items and quantities from the subscription will be added to the checkout session

Example:

"sub_12345"

​
externalCustomerId
string

Existing Stripe Customer ID. If provided, the new invoice or subscription will be created for this customer

Example:

"cus_12345"

​
externalInvoiceId
string

Existing Stripe Invoice ID that is not connected to a subscription. If provided, the items and quantities from the invoice will be added to the checkout session

Example:

"in_12345"

​
externalInvoiceNumber
string

Existing Stripe Invoice Number that is not connected to a subscription. If provided, the items and quantities from the invoice will be added to the checkout session

Example:

"A1234-001"

​
freeTrialDays
number

Number of free trial days. If provided, the Stripe subscription will be created with this trial period

Example:

7

​
couponCode
string

Stripe coupon code

Example:

"SUMMER2025"

​
email
string

Customer email. If provided, the customer will not be able to change this email. If a Stripe customer does not exist, it will be created with this email.

Example:

"info@loopcrypto.xyz"

​
referenceId
string

External reference ID. This will be included in all webhooks

Example:

"ref_12345"

​
payInvoiceImmediately
boolean

Requires payment of any finalized or draft invoice immediately during checkout. Does not apply to upcoming invoices (e.g. preview).

Example:

true

​
cartEnabled
boolean

Enable or disable cart on the checkout page

Example:

false

​
metadata
object

Metadata info that will be included on the Agreement Created webhook

​
template
boolean

Creates a template checkout session. This session is an ever green session that can be used to create new subscriptions when the link is clicked. Default is false.

Example:

false

​
suggestedAllowanceAmount
number

Authorization amount in cents that will be suggested to the customer. Example: $49.99 = 4999 cents

Example:

1001

​
minimumAllowanceAmount
number

Minimum authorization amount in cents that the customer must agree to. Example: $49.99 = 4999 cents

Example:

1001

​
minimumBalanceAmount
number

Minimum required balance amount in cents that the customer must have in their wallet. Example: $49.99 = 4999 cents

Example:

1001

​
upgradeSubscription
boolean

Upgrade flag to upgrade the subscription with a new item

Example:

true

​
successUrl
string

Success URL. If provided, the customer will be redirected to this URL after a successful checkout. If the URL does not start with http/https, it will be prefixed with https://.

Example:

"https://www.loopcrypto.xyz/success"

​
paymentTokens
object[]

Accepted payment tokens for the checkout session. If provided, the customer will be able to pay with these tokens. If not provided, the checkout session will accept all tokens defined at the merchant or organization level

​
resetBillingCycle
boolean

Reset billing cycle reset the subscription billing cycle to the current time.

Example:

true

Response

Ok

​
id
string
required

Checkout session ID This is used in the URL to retrieve the checkout session

Example:

"cs_12345"

​
active
boolean
required

The checkout session is an active session

Example:

"true"

​
elements
object[] | null
required

Items and fees included in the checkout session

​
externalSubscriptionId
string | null
required

External subscription ID

Example:

"sub_12345"

​
externalCustomerId
string | null
required

External customer ID

Example:

"cus_12345"

​
externalInvoiceId
string | null
required

External invoice ID

Example:

"in_12345"

​
referenceId
string | null
required

External reference ID

Example:

"ref_12345"

​
emailAddress
string | null
required

Customer email address

Example:

"info@loopcrypto.xyz"

​
freeTrialDays
number | null
required

Number of free trial days

Example:

7

​
couponCodeId
string | null
required

Coupon code ID

Example:

"12345"

​
payInvoiceImmediately
boolean
required

Pay invoice immediately. Do not wait for the bill date to process the invoice

Example:

true

​
cartEnabled
boolean
required

Enable or disable cart on checkout page

Example:

false

​
billDate
number | null
required

The date the subscription will be started, expressed as a UNIX date in seconds

Example:

1746869711

​
metadata
object
required

Metadata info that will be included on the Agreement Created webhook Construct a type with a set of properties K of type T

​
expirationDate
number | null
required

Date the checkout session will expire in seconds as a UNIX date in seconds

Example:

"1746869711"

​
childTemplate
boolean
required

Indicates if this session was generated from a template

Example:

true

​
suggestedAllowanceAmount
number
required

Suggested allowance amount in cents

Example:

1001

​
minimumAllowanceAmount
number
required

Minimum required allowance amount in cents

Example:

1001

​
minimumBalanceAmount
number
required

Minimum required balance amount in cents

Example:

1001

​
upgradeSubscription
boolean
required

Upgrade flag to upgrade the subscription with a new item

Example:

true

​
template
boolean
required

Session is a template session that is ever green and can be used to create new sessions when the link is clicked

Example:

false

​
successUrl
string | null
required

URL to redirect the customer after a successful checkout.

Example:

"https://www.loopcrypto.xyz/success"

​
tokens
object[] | null
required

A list of the tokens and the networks they're on that are accepted as payment for this checkout session

​
resetBillingCycle
boolean
required

Reset billing cycle reset the subscription billing cycle to the current time.

Example:

true

⌘I