---
title: "Create a checkout session"
method: POST
path: "/api/v1/checkout-sessions"
tags: ["Checkout Sessions"]
---

# Create a checkout session

`POST /api/v1/checkout-sessions`

## Request body

- CreateCheckoutSessionRequest
  - `add_ons` CreateSubscriptionAddOn[], nullable
    - `add_on_id` string, MeteroidId, required
    - `customization` union
      - SubscriptionAddOnPriceOverride
        - `name` string, nullable
        - `price_entry` union, required
          - ExistingPriceRef
            - `id` string, MeteroidId, required
          - PriceInput
            - `cadence` 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL', required
            - `currency` string, required
            - `pricing` union, required
              - …
      - SubscriptionAddOnParameterization
        - `billing_period` 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL'
        - `committed_capacity` integer, nullable
        - `initial_slot_count` integer, nullable
    - `quantity` integer
  - `auto_advance_invoices` boolean, nullable — If false, invoices will stay in Draft until manually reviewed and finalized. Default is true.
  - `billing_day_anchor` integer, nullable
  - `billing_start_date` string, date, nullable
  - `charge_automatically` boolean, nullable — Automatically try to charge the customer's configured payment method on finalize. Default is true.
  - `components` CreateSubscriptionComponents
    - `extra_components` ExtraComponent[], nullable
      - `name` string, required
      - `price_entry` union, required
        - ExistingPriceRef
          - `id` string, MeteroidId, required
        - PriceInput
          - `cadence` 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL', required
          - `currency` string, required
          - `pricing` union, required
            - RatePricing
              - …
            - SlotPricing
              - …
            - CapacityPricing
              - …
            - UsagePricing
              - …
            - ExtraRecurringPricing
              - …
            - OneTimePricing
              - …
      - `product_ref` union, required
        - ExistingProductRef
          - `id` string, MeteroidId, required
        - NewProductRef
          - `fee_structure` union, required
            - RateFeeStructure
            - SlotFeeStructure
              - …
            - CapacityFeeStructure
              - …
            - UsageFeeStructure
              - …
            - ExtraRecurringFeeStructure
              - …
            - OneTimeFeeStructure
          - `fee_type` 'RATE' | 'SLOT' | 'CAPACITY' | 'USAGE' | 'EXTRA_RECURRING' | 'ONE_TIME', required
          - `name` string, required
    - `overridden_components` ComponentOverride[], nullable
      - `component_id` string, MeteroidId, required
      - `name` string, required
      - `price_entry` union, required
        - ExistingPriceRef
          - `id` string, MeteroidId, required
        - PriceInput
          - `cadence` 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL', required
          - `currency` string, required
          - `pricing` union, required
            - RatePricing
              - …
            - SlotPricing
              - …
            - CapacityPricing
              - …
            - UsagePricing
              - …
            - ExtraRecurringPricing
              - …
            - OneTimePricing
              - …
    - `parameterized_components` ComponentParameterization[], nullable
      - `component_id` string, MeteroidId, required
      - `parameters` ComponentParameters, required
        - `billing_period` 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL'
        - `committed_capacity` integer, nullable
        - `initial_slot_count` integer, nullable
    - `remove_components` PriceComponentId[], nullable
  - `coupon_code` string, nullable
  - `coupon_ids` CouponId[]
  - `customer_id` string, CustomerId or customer alias, required — Customer ID or alias
  - `end_date` string, date, nullable
  - `expires_in_hours` integer, nullable — Session expiry time in hours. Default is 1 hour for self-serve checkout.
  - `invoice_memo` string, nullable
  - `invoice_threshold` string, decimal, nullable
  - `metadata` unknown
  - `net_terms` integer, nullable
  - `payment_methods_config` union — Online (card/direct debit), BankTransfer, or External.
    - OnlinePaymentMethodConfig
      - `config` OnlineMethodsConfig
        - `card` OnlineMethodConfig
          - `enabled` boolean, required
        - `direct_debit` OnlineMethodConfig
          - `enabled` boolean, required
    - BankTransferPaymentMethodConfig
      - `account_id` string, MeteroidId
    - ExternalPaymentMethodConfig
  - `plan_version_id` string, MeteroidId, required
  - `purchase_order` string, nullable
  - `trial_duration_days` integer, nullable

## Response `200`

Checkout session created

- CreateCheckoutSessionResponse
  - `session` CheckoutSession, required
    - `billing_day_anchor` integer, nullable
    - `billing_start_date` string, date, nullable
    - `checkout_type` 'SELF_SERVE' | 'SUBSCRIPTION_ACTIVATION' | 'PLAN_CHANGE' | 'ADDON_PURCHASE', required
    - `checkout_url` string, nullable
    - `completed_at` string, date-time, nullable
    - `coupon_code` string, nullable
    - `created_at` string, date-time, required
    - `customer_id` string, MeteroidId, required
    - `expires_at` string, date-time, nullable — When the session expires. None means the session never expires.
    - `id` string, MeteroidId, required
    - `net_terms` integer, nullable
    - `payment_methods_config` union — Online (card/direct debit), BankTransfer, or External.
      - OnlinePaymentMethodConfig
        - `config` OnlineMethodsConfig
          - `card` OnlineMethodConfig
            - `enabled` boolean, required
          - `direct_debit` OnlineMethodConfig
            - `enabled` boolean, required
      - BankTransferPaymentMethodConfig
        - `account_id` string, MeteroidId
      - ExternalPaymentMethodConfig
    - `plan_version_id` string, MeteroidId, required
    - `status` 'CREATED' | 'AWAITING_PAYMENT' | 'COMPLETED' | 'EXPIRED' | 'CANCELLED', required
    - `subscription_id` string, MeteroidId
    - `trial_duration_days` integer, nullable

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `429` — Too many requests
- `500` — Internal server error

## Changes

> 54 revisions in range; 1 could not be searched.

- **2026-08-12** (v1) `4e013b4e4a8f` — 24 info
  - the request property `add_ons/items/customization/oneOf[#/components/schemas/SubscriptionAddOnCustomization]/oneOf[#/components/schemas/SubscriptionAddOnPriceOverride]/price_entry/oneOf[#/components/schemas/PriceInput]/pricing/oneOf[#/components/schemas/UsagePricing]/model/oneOf[#/components/schemas/TieredPricing]/tiers/items/flat_cap` became nullable
  - the request property `add_ons/items/customization/oneOf[#/components/schemas/SubscriptionAddOnCustomization]/oneOf[#/components/schemas/SubscriptionAddOnPriceOverride]/price_entry/oneOf[#/components/schemas/PriceInput]/pricing/oneOf[#/components/schemas/UsagePricing]/model/oneOf[#/components/schemas/TieredPricing]/tiers/items/flat_fee` became nullable
  - the request property `add_ons/items/customization/oneOf[#/components/schemas/SubscriptionAddOnCustomization]/oneOf[#/components/schemas/SubscriptionAddOnPriceOverride]/price_entry/oneOf[#/components/schemas/PriceInput]/pricing/oneOf[#/components/schemas/UsagePricing]/model/oneOf[#/components/schemas/VolumePricing]/tiers/items/flat_cap` became nullable
  - the request property `add_ons/items/customization/oneOf[#/components/schemas/SubscriptionAddOnCustomization]/oneOf[#/components/schemas/SubscriptionAddOnPriceOverride]/price_entry/oneOf[#/components/schemas/PriceInput]/pricing/oneOf[#/components/schemas/UsagePricing]/model/oneOf[#/components/schemas/VolumePricing]/tiers/items/flat_fee` became nullable
  - …20 more
- …earlier changes not shown

[Full history](https://skmtc.dev/meteroid-oss/apis/meteroid/changes/api/v1/checkout-sessions/post.md)

---

[API](https://skmtc.dev/meteroid-oss/apis/meteroid.md) · [All operations](https://skmtc.dev/meteroid-oss/apis/meteroid/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/meteroid-oss/meteroid/revisions/03f9d8ae5c5e/schema)