Skip to main content
POST
/
api
/
v1
/
checkout-sessions
Create a checkout session
curl --request POST \
  --url https://api.example.com/api/v1/checkout-sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "<string>",
  "plan_version_id": "<string>",
  "add_ons": [
    {
      "add_on_id": "<string>",
      "customization": {
        "price_entry": {},
        "name": "<string>"
      },
      "quantity": 1
    }
  ],
  "auto_advance_invoices": true,
  "billing_day_anchor": 123,
  "billing_start_date": "2023-12-25",
  "charge_automatically": true,
  "components": {
    "extra_components": [
      {
        "name": "<string>",
        "price_entry": {},
        "product_ref": {}
      }
    ],
    "overridden_components": [
      {
        "component_id": "<string>",
        "name": "<string>",
        "price_entry": {}
      }
    ],
    "parameterized_components": [
      {
        "component_id": "<string>",
        "parameters": {
          "billing_period": "MONTHLY",
          "committed_capacity": 1,
          "initial_slot_count": 1
        }
      }
    ],
    "remove_components": [
      "<string>"
    ]
  },
  "coupon_code": "<string>",
  "coupon_ids": [
    "<string>"
  ],
  "end_date": "2023-12-25",
  "expires_in_hours": 1,
  "invoice_memo": "<string>",
  "invoice_threshold": "<string>",
  "metadata": "<unknown>",
  "net_terms": 123,
  "payment_methods_config": {
    "type": "online",
    "config": {
      "card": {
        "enabled": true
      },
      "direct_debit": {
        "enabled": true
      }
    }
  },
  "purchase_order": "<string>",
  "trial_duration_days": 123
}
'
{
  "session": {
    "checkout_type": "SELF_SERVE",
    "created_at": "2023-11-07T05:31:56Z",
    "customer_id": "<string>",
    "id": "<string>",
    "plan_version_id": "<string>",
    "status": "CREATED",
    "billing_day_anchor": 123,
    "billing_start_date": "2023-12-25",
    "checkout_url": "<string>",
    "completed_at": "2023-11-07T05:31:56Z",
    "coupon_code": "<string>",
    "expires_at": "2023-11-07T05:31:56Z",
    "net_terms": 123,
    "payment_methods_config": {
      "type": "online",
      "config": {
        "card": {
          "enabled": true
        },
        "direct_debit": {
          "enabled": true
        }
      }
    },
    "subscription_id": "sub_7n42DGM5Tflk9n8mt7Fhc7",
    "trial_duration_days": 123
  }
}

Authorizations

Authorization
string
header
required

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

Body

application/json
customer_id
string<CustomerId or customer alias>
required

Customer ID or alias

plan_version_id
string<MeteroidId>
required
Example:

"plv_7n42DGM5Tflk9n8mt7Fhc7"

add_ons
object[] | null
auto_advance_invoices
boolean | null

If false, invoices will stay in Draft until manually reviewed and finalized. Default is true.

billing_day_anchor
integer<int32> | null
billing_start_date
string<date> | null
charge_automatically
boolean | null

Automatically try to charge the customer's configured payment method on finalize. Default is true.

components
object
coupon_code
string | null
coupon_ids
string<MeteroidId>[]
end_date
string<date> | null
expires_in_hours
integer<int32> | null

Session expiry time in hours. Default is 1 hour for self-serve checkout.

Required range: x >= 0
invoice_memo
string | null
invoice_threshold
string<decimal> | null
metadata
any
net_terms
integer<int32> | null
payment_methods_config
object

Payment methods configuration. If not specified, inherits from the invoicing entity.

purchase_order
string | null
trial_duration_days
integer<int32> | null

Response

Checkout session created

session
object
required