Create a checkout link

POST

checkout-links

curl -X POST \
 /checkout-links \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer <token>" \
 --data '{
    "afterCheckout": {
        "url": "https:\/\/example.com\/checkout\/confirmation",
        "confirmationMessage": "Thank you for your order!",
        "action": "redirect",
        "backToProviderUrl": "https:\/\/example.com\/checkout\/confirmation"
    },
    "options": {
        "trialDays": "14",
        "allowCoupons": "",
        "quantityEditable": "",
        "forceCompany": ""
    },
    "isEnabled": "1",
    "items": [
        []
    ]
}'

{
  "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
  "afterCheckout": {
    "url": "https://example.com/checkout/confirmation",
    "confirmationMessage": "Thank you for your order!",
    "action": "redirect",
    "backToProviderUrl": "https://example.com/checkout/confirmation"
  },
  "options": {
    "trialDays": 14,
    "allowCoupons": true,
    "quantityEditable": true,
    "forceCompany": true
  },
  "slug": "my-checkout-slug",
  "isEnabled": true,
  "items": [
    {
      "type": "<any>",
      "product": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "name": "Basic",
        "description": "For small teams.",
        "type": "product",
        "invoiceVisibility": "always",
        "customFields": {
          "field1": "value1",
          "field2": "value2"
        }
      },
      "quantity": 1,
      "plan": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "family": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
        },
        "code": "basic-m2023",
        "originProduct": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "name": "Basic",
          "description": "For small teams.",
          "type": "product",
          "invoiceVisibility": "always",
          "customFields": {
            "field1": "value1",
            "field2": "value2"
          }
        },
        "allowCheckout": true,
        "status": "<any>",
        "createdAt": "2023-11-07T05:31:56Z",
        "name": "<string>",
        "description": "<string>"
      },
      "price": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "internalName": "Exclusive pricing for partners.",
        "status": "<any>",
        "salesChannel": {},
        "type": "<any>",
        "applyTrial": true,
        "payInAdvance": true,
        "proRata": true,
        "freeUnits": {},
        "billingInterval": "1M",
        "showPricePerInterval": "1M",
        "currencyCode": {},
        "price": {
          "amount": 123,
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00",
          "tenantId": "<string>"
        },
        "custom": true,
        "charge": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "productSetOption": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "product": "<any>",
        "customer": "<any>",
        "inUse": true,
        "checkoutLinkIds": [
          "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
        ]
      },
      "periods": [
        {
          "contractPeriod": {},
          "cancellationPeriod": {}
        }
      ]
    }
  ],
  "url": "https://example.com/checkout/my-checkout-slug"
}

Authorizations

Authorization

string

header

required

Value for the Authorization header parameter.

Body

The new CheckoutLink resource

afterCheckout

object

The action to perform after checkout.

options

object

The options for the checkout link.

isEnabled

boolean

default:

true

Whether the checkout link is enabled or not.

items

object[]

Response

201

application/json

CheckoutLink resource created

string

The unique identifier of the checkout link.

afterCheckout

object

The action to perform after checkout.

options

object

slug

string

The name of the checkout link.

isEnabled

boolean

Whether the checkout link is enabled or not.

items

object[]

items.type

any

The type of the checkout link item.

Possible values:

product: A product will be added to the cart, with the given quantity.
plan: A plan will be added to the cart, and can be configured by the customer.

items.product

object | null

This is required when the type is "product".

items.quantity

object | null

This is required when the type is "product".

items.plan

object | null

This is required when the type is "plan".

items.plan.id

string

The unique identifier of the plan.

items.plan.family

object | null

Allow to group plans together. This allows to upgrade or downgrade between plans in the same family.

items.plan.code

string

The code of the plan. This is used to identify the plan e.g. in the checkout url.

items.plan.originProduct

object | null

The origin product this plan belongs to. This is relevant for advanced analytics.

items.plan.allowCheckout

boolean

default:

true

Allow to checkout this plan. If this is set to false, the plan will not be available in the checkout and can only be assigned to a subscription by the API or in the admin panel. The plan.code is a part of the checkout url.

items.plan.status

any

The status of the plan.

Possible values:

draft: The plan is a draft and not available for usage in a subscription.
active: The plan is active and can be used in a subscription.
archived: The plan is archived and not longer available for usage in a subscription.
inactive: The plan is inactive and not available for usage in a subscription.

items.plan.createdAt

string

items.plan.name

string

The name of this plan

items.plan.description

string | null

The description of this plan

items.price

object | null

This is required when the type is "product", "plan".

items.price.type

any

required

The type of the charge. This defines how the price is calculated.

Possible values:

flat_fee: A flat fee is charged, e.g. 10€ per month independent of the number of units.
volume: A volume based price is charged, e.g. 10€ for the first 10 units and 9€ for all units when the number of units is above 10. Useful for volume discounts.
percentage: A percentage of the total price is charged, e.g. 10% of the total price multiplied by the number of units. Useful for provisions.
per_unit: A price per unit is charged, e.g. 10€ per unit per billing interval. Useful for per seat based pricing.
tiered: A tiered price is charged. E.g. 10€ per unit for the first 10 units, 9€ per unit for the next 10 units and 8€ per unit for all units above 20.
stair_step: A stair step price is charged. E.g. 10€ per unit for the first 10 units, 9€ per unit for all units above 10.

items.price.currencyCode

object

required

The currency of the price

items.price.price

object

required

The price in the defined billing interval.

items.price.id

string

The unique identifier of the price plan.

items.price.internalName

string | null

The internal name of the price plan.

Required string length: 3 - 255

items.price.status

any

The status of the price plan.

Possible values:

active: The price is active and can be used.
archived: The price is archived and cannot be used anymore. It will be not shown in any lists until explicitly requested.

items.price.salesChannel

object | null

This price is only available for a specific sales channel. If this is set, the price is only available for the sales channel with the given ID. All other price plans will be ignored.

items.price.applyTrial

boolean

default:

true

If this is set to true, the price plan can be applied on a trial. If the product is in trial, and this is false, the price will be charged on subscription start, otherwise after trial.

items.price.payInAdvance

boolean | null

default:

true

If this is set to true, the price will be charged in advance. If this is false, the price will be charged at the end of the billing interval.

items.price.proRata

boolean

If this is set to true, the price will be charged prorated when a partial billing interval is billed. This applies to measurements of type "recurring" or non-one-time billing intervals. For other measurements this parameter will be ignored.

items.price.freeUnits

object | null

The amount of free units. If null, no free units are available. Free units will be applied before passed to the price calculation and are available prorated. If the customer does not uses the free units during a billing period, they are not carried over to the next billing period. If the customer cancels the subscription before ending the billing period, the free units are only available prorated for the remaining billing period.

Example: You offer 2400 free units for 12 months and your price has a billing interval for 1 month. The customer cancels after 6 months. Only 1200 free units are available.

A price plan for a recurring product cannot have free units. Use a metered product instead.

A price plan related to a product of type charge cannot have free units.

items.price.billingInterval

object | null

The billing interval of the price plan. If null, this is a one-time charge. Billing intervals of null cannot be prorated.

items.price.showPricePerInterval

object | null

Display the billed price per interval in customerfront or invoices. If null, the price will be shown per billing interval. Currently only available for billing intervals of months, years. Currently only allowed to show price per month (1M)

items.price.custom

boolean

If this price plan is a custom price plan. A price plan is custom if it is defined specific for a plan addon, plan charge, customer or sales channel.

items.price.charge

string

The charge related to this price plan.

items.price.productSetOption

string

The product set option related to this price plan.

items.price.product

any

The product this price plan belongs to.

items.price.customer

any

The customer this price plan belongs to.

items.price.inUse

boolean

If this price plan is in use.

items.price.checkoutLinkIds

string[]

The checkout link IDs related to this price plan.

items.periods

object[]

The contract period terms of the product item. If none provided, the billing period will be used as contract period, the cancellation period is set to 1 day.

url

string

The URL of the checkout link.

Was this page helpful?

Toggle a coupon Get a checkout link

curl -X POST \
 /checkout-links \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer <token>" \
 --data '{
    "afterCheckout": {
        "url": "https:\/\/example.com\/checkout\/confirmation",
        "confirmationMessage": "Thank you for your order!",
        "action": "redirect",
        "backToProviderUrl": "https:\/\/example.com\/checkout\/confirmation"
    },
    "options": {
        "trialDays": "14",
        "allowCoupons": "",
        "quantityEditable": "",
        "forceCompany": ""
    },
    "isEnabled": "1",
    "items": [
        []
    ]
}'

{
  "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
  "afterCheckout": {
    "url": "https://example.com/checkout/confirmation",
    "confirmationMessage": "Thank you for your order!",
    "action": "redirect",
    "backToProviderUrl": "https://example.com/checkout/confirmation"
  },
  "options": {
    "trialDays": 14,
    "allowCoupons": true,
    "quantityEditable": true,
    "forceCompany": true
  },
  "slug": "my-checkout-slug",
  "isEnabled": true,
  "items": [
    {
      "type": "<any>",
      "product": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "name": "Basic",
        "description": "For small teams.",
        "type": "product",
        "invoiceVisibility": "always",
        "customFields": {
          "field1": "value1",
          "field2": "value2"
        }
      },
      "quantity": 1,
      "plan": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "family": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
        },
        "code": "basic-m2023",
        "originProduct": {
          "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
          "name": "Basic",
          "description": "For small teams.",
          "type": "product",
          "invoiceVisibility": "always",
          "customFields": {
            "field1": "value1",
            "field2": "value2"
          }
        },
        "allowCheckout": true,
        "status": "<any>",
        "createdAt": "2023-11-07T05:31:56Z",
        "name": "<string>",
        "description": "<string>"
      },
      "price": {
        "id": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "internalName": "Exclusive pricing for partners.",
        "status": "<any>",
        "salesChannel": {},
        "type": "<any>",
        "applyTrial": true,
        "payInAdvance": true,
        "proRata": true,
        "freeUnits": {},
        "billingInterval": "1M",
        "showPricePerInterval": "1M",
        "currencyCode": {},
        "price": {
          "amount": 123,
          "createdAt": "2021-01-01T00:00:00+00:00",
          "updatedAt": "2021-01-01T00:00:00+00:00",
          "tenantId": "<string>"
        },
        "custom": true,
        "charge": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "productSetOption": "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b",
        "product": "<any>",
        "customer": "<any>",
        "inUse": true,
        "checkoutLinkIds": [
          "ad8f1c2c-3b1c-4b0a-8b0a-0b0b0b0b0b0b"
        ]
      },
      "periods": [
        {
          "contractPeriod": {},
          "cancellationPeriod": {}
        }
      ]
    }
  ],
  "url": "https://example.com/checkout/my-checkout-slug"
}

API documentation

User

Tenant

Feature

Entitlement

User & permissions

Settings

Payment

Analytics

Customer

Billing

Dunning

Subscription

Offers

Catalogue

Checkout

Accounting

Taxes

Create a checkout link

Authorizations

Body

Response