Create Checkout Session

POST

companies

{company_id}

checkout

curl --request POST \
  --url https://api.maplebilling.com/api/v1/companies/{company_id}/checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "config_items": [
    {
      "hide_at_checkout": "<unknown>",
      "minimum_units": 1,
      "num_licenses": 1,
      "product_metric_pricing_id": "<unknown>",
      "product_pricing_id": "<unknown>",
      "quantity_config": {
        "allow_custom_quantity": true,
        "max_quantity": 123,
        "min_quantity": 123
      },
      "sort_order": "<unknown>",
      "upsell_product_metric_pricing_id": "<unknown>"
    }
  ],
  "customer_id": "<string>",
  "type": "CHECKOUT_SESSION",
  "auto_charges": "<unknown>",
  "auto_renews": "<unknown>",
  "bundle_pricing_id": "<unknown>",
  "change_proration_type": "NEXT",
  "change_reset_billing_anchor": "<unknown>",
  "change_timing": "IMMEDIATE",
  "discounts": [
    {
      "name": "<string>",
      "type": "DISCOUNT_AMOUNT",
      "amount": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "cap": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "coupon_id": "<unknown>",
      "customer_id": "<unknown>",
      "expiration_date": "<unknown>",
      "import_created_at_ref": "<unknown>",
      "import_ref": "<unknown>",
      "imported_from": "<unknown>",
      "item_pricing_id": "<unknown>",
      "onetime_billable_id": "<unknown>",
      "percent": 0.5,
      "product_id": "<unknown>",
      "product_pricing_id": "<unknown>",
      "proposal_id": "<unknown>",
      "state": "ACTIVE",
      "subscription_id": "<unknown>"
    }
  ],
  "metadata": {},
  "onetime_items": [
    {
      "aggregate": 123,
      "custom_price": {
        "amount": {
          "currency": "<string>",
          "value_in_cents": 123
        },
        "product_id": "<string>",
        "description": "<string>"
      },
      "product_pricing_id": "<unknown>",
      "quantity_config": {
        "allow_custom_quantity": true,
        "max_quantity": 123,
        "min_quantity": 123
      },
      "sort_order": "<unknown>"
    }
  ],
  "options": {
    "allow_promo_code": "<unknown>",
    "completion_action": "REDIRECT",
    "confirmation_message": "<unknown>",
    "redirect_url": "<unknown>",
    "requires_customer_address": "<unknown>"
  },
  "previous_subscription_id": "<unknown>",
  "product_pricing_ids": [
    "<string>"
  ],
  "term": {
    "count": 123,
    "frequency": "HOUR"
  },
  "trial": "<unknown>",
  "trial_term": {
    "count": 123,
    "frequency": "HOUR"
  }
}
'

{
  "id": "<string>",
  "url": "<unknown>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

The idempotency key that will be used to ensure the request is only performed once

Path Parameters

company_id

string

required

The company ID with the prefix 'cmp_'.

Body

application/json

config_items

object[]

required

Show child attributes

config_items.hide_at_checkout

null | boolean

Whether the pricing row will be hidden at checkout, defaults to false

config_items.minimum_units

number<double>

The number of minimum units for this usage-based component

Required range: x >= 0

config_items.num_licenses

number<double>

The number of licenses for this license-based component

Required range: x >= 0

config_items.product_metric_pricing_id

null | string

The product metric pricing ID to which this config applies.

config_items.product_pricing_id

null | string

The product pricing ID to which this config applies. If the product pricing contains multiple components, the same config will apply to all of them

config_items.quantity_config

object

Show child attributes

config_items.quantity_config.allow_custom_quantity

boolean

config_items.quantity_config.max_quantity

integer

config_items.quantity_config.min_quantity

integer

config_items.sort_order

null | number

The sort index

config_items.upsell_product_metric_pricing_id

null | string

customer_id

string

required

The customer attached to the checkout session

type

enum<string>

required

The type of the checkout session

Available options:

CHECKOUT_SESSION

auto_charges

null | boolean

Whether the subscription is automatically charged to the payment method after the checkout session

auto_renews

null | boolean

Whether this subscription auto renews at the end of the term. This is to be used without end date or renewal date

bundle_pricing_id

null | string

The bundle pricing that forms the checkout session

change_proration_type

null | enum<string>

The proration type of the existing subscription, if provided. This is one of NEXT, IMMEDIATE or NONE based on whether the proration is charged on the next invoice, immediately or no proration is applied respectively

Available options:

NEXT,

IMMEDIATE,

NONE

change_reset_billing_anchor

null | boolean

Whether to reset the billing anchor of the existing subscription, if provided

change_timing

null | enum<string>

The change timing of the existing subscription, if provided. This is one of IMMEDIATE, PERIOD_END or RENEWAL based on whether the change timing needs to be immediate, at the end of the current period, on renewal respectively

Available options:

IMMEDIATE,

PERIOD_END,

RENEWAL

discounts

object[] | null

The discounts attached to the checkout session

Show child attributes

discounts.name

string

required

discounts.type

enum<string>

required

Available options:

DISCOUNT_AMOUNT,

DISCOUNT_PERCENT

discounts.amount

object

The amount which has value in cents and a currency

Show child attributes

discounts.amount.currency

string

discounts.amount.value_in_cents

integer<int64>

discounts.cap

object

The amount which has value in cents and a currency

Show child attributes

discounts.cap.currency

string

discounts.cap.value_in_cents

integer<int64>

discounts.coupon_id

null | string

discounts.customer_id

null | string

discounts.expiration_date

null | string<date-time>

discounts.import_created_at_ref

null | string<date-time>

discounts.import_ref

null | string

discounts.imported_from

null | string

discounts.item_pricing_id

null | string

discounts.onetime_billable_id

null | string

discounts.percent

number<double>

Required range: 0 <= x <= 1

discounts.product_id

null | string

discounts.product_pricing_id

null | string

discounts.proposal_id

null | string

discounts.state

null | enum<string>

Available options:

ACTIVE,

PENDING,

REVOKED,

EXPIRED,

CONSUMED

discounts.subscription_id

null | string

metadata

object

Any additional as key-value pairs that needs to be attached to the subscription after the checkout session

onetime_items

object[] | null

Any one time charges to be attached to the checkout session

Show child attributes

onetime_items.aggregate

number<double>

required

The quantity of the one-time charge

onetime_items.custom_price

object

The custom pricing for the product. Either 'product_pricing_id' or 'custom_price' is required

Show child attributes

onetime_items.custom_price.amount

object

required

The amount of quantity

Show child attributes

onetime_items.custom_price.amount.currency

string

onetime_items.custom_price.amount.value_in_cents

integer<int64>

onetime_items.custom_price.product_id

string

required

The product ID

onetime_items.custom_price.description

string | null

The description of the one-time charge

onetime_items.product_pricing_id

null | string

The product pricing for the one-time charge. Either 'product_pricing_id' or 'custom_price' is required

onetime_items.quantity_config

object

Show child attributes

onetime_items.quantity_config.allow_custom_quantity

boolean

onetime_items.quantity_config.max_quantity

integer

onetime_items.quantity_config.min_quantity

integer

onetime_items.sort_order

null | number

The sort index

options

object

The detailed options for the checkout session such as confirmation messages, redirect urls etc.

Show child attributes

Whether promo codes are allowed

options.completion_action

null | enum<string>

The action to perform upon completion which can be REDIRECT or CONFIRMATION_PAGE

Available options:

REDIRECT,

CONFIRMATION_PAGE

options.confirmation_message

null | string

The message to show on completion, if the completion action is CONFIRMATION_PAGE

options.redirect_url

null | string

The url to redirect to on completion, if the completion action is REDIRECT

options.requires_customer_address

null | boolean

Whether the customer address is required, typically for tax purposes

previous_subscription_id

null | string

The ID of an existing subscription whose plan will change with the checkout session

product_pricing_ids

string[] | null

The list of product pricings that form the checkout session

term

object

The term for the subscription created by the checkout session

Show child attributes

term.count

integer<int64>

required

The number of times the frequency elapses

term.frequency

enum<string>

required

The frequency at which the term repeats

Available options:

HOUR,

DAY,

WEEK,

BI_MONTH,

MONTH,

QUARTER,

BI_ANNUAL,

YEAR,

ONETIME

trial

null | boolean

Whether the checkout session creates a subscription in a trial

trial_term

object

The trial term for the subscription after the checkout session

Show child attributes

trial_term.count

integer<int64>

required

The number of times the frequency elapses

trial_term.frequency

enum<string>

required

The frequency at which the term repeats

Available options:

HOUR,

DAY,

WEEK,

BI_MONTH,

MONTH,

QUARTER,

BI_ANNUAL,

YEAR,

ONETIME

Response

200 - application/json

string

The ID of the checkout session

url

null | string

The checkout link generated

Get Checkout SessionRetrieve a checkout session by ID

⌘I

Create Checkout Session

curl --request POST \
  --url https://api.maplebilling.com/api/v1/companies/{company_id}/checkout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "config_items": [
    {
      "hide_at_checkout": "<unknown>",
      "minimum_units": 1,
      "num_licenses": 1,
      "product_metric_pricing_id": "<unknown>",
      "product_pricing_id": "<unknown>",
      "quantity_config": {
        "allow_custom_quantity": true,
        "max_quantity": 123,
        "min_quantity": 123
      },
      "sort_order": "<unknown>",
      "upsell_product_metric_pricing_id": "<unknown>"
    }
  ],
  "customer_id": "<string>",
  "type": "CHECKOUT_SESSION",
  "auto_charges": "<unknown>",
  "auto_renews": "<unknown>",
  "bundle_pricing_id": "<unknown>",
  "change_proration_type": "NEXT",
  "change_reset_billing_anchor": "<unknown>",
  "change_timing": "IMMEDIATE",
  "discounts": [
    {
      "name": "<string>",
      "type": "DISCOUNT_AMOUNT",
      "amount": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "cap": {
        "currency": "<string>",
        "value_in_cents": 123
      },
      "coupon_id": "<unknown>",
      "customer_id": "<unknown>",
      "expiration_date": "<unknown>",
      "import_created_at_ref": "<unknown>",
      "import_ref": "<unknown>",
      "imported_from": "<unknown>",
      "item_pricing_id": "<unknown>",
      "onetime_billable_id": "<unknown>",
      "percent": 0.5,
      "product_id": "<unknown>",
      "product_pricing_id": "<unknown>",
      "proposal_id": "<unknown>",
      "state": "ACTIVE",
      "subscription_id": "<unknown>"
    }
  ],
  "metadata": {},
  "onetime_items": [
    {
      "aggregate": 123,
      "custom_price": {
        "amount": {
          "currency": "<string>",
          "value_in_cents": 123
        },
        "product_id": "<string>",
        "description": "<string>"
      },
      "product_pricing_id": "<unknown>",
      "quantity_config": {
        "allow_custom_quantity": true,
        "max_quantity": 123,
        "min_quantity": 123
      },
      "sort_order": "<unknown>"
    }
  ],
  "options": {
    "allow_promo_code": "<unknown>",
    "completion_action": "REDIRECT",
    "confirmation_message": "<unknown>",
    "redirect_url": "<unknown>",
    "requires_customer_address": "<unknown>"
  },
  "previous_subscription_id": "<unknown>",
  "product_pricing_ids": [
    "<string>"
  ],
  "term": {
    "count": 123,
    "frequency": "HOUR"
  },
  "trial": "<unknown>",
  "trial_term": {
    "count": 123,
    "frequency": "HOUR"
  }
}
'

{
  "id": "<string>",
  "url": "<unknown>"
}

API Features

API Reference

Webhook Reference

Authorizations

Headers

Path Parameters

Body

Response