---
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
  - `activation_condition` 'ON_START' | 'ON_CHECKOUT' | 'MANUAL'
  - `add_ons` CreateSubscriptionAddOn[], nullable
    - `add_on_id` string, MeteroidId, required
    - `customization` union
      - SubscriptionAddOnOverride
        - `fee` union, required
          - RateFee
            - `rate` string, decimal, required
          - OneTimeFee
            - `quantity` integer, required
            - `rate` string, decimal, required
          - RecurringFee
            - `billing_type` 'ADVANCE' | 'ARREARS', required
            - `quantity` integer, required
            - `rate` string, decimal, required
          - CapacityFee
            - `included` integer, required
            - `metric_id` string, MeteroidId, required
            - `overage_rate` string, decimal, required
            - `rate` string, decimal, required
          - SlotFee
            - `initial_slots` integer, required
            - `max_slots` integer, nullable
            - `min_slots` integer, nullable
            - `unit` string, required
            - `unit_rate` string, decimal, required
          - UsageFee
            - `metric_id` string, MeteroidId, required
            - `model` union, required
              - …
        - `name` string, required
        - `period` 'ONE_TIME' | 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL', required
      - SubscriptionAddOnParameterization
        - `billing_period` 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL'
        - `committed_capacity` integer, nullable
        - `initial_slot_count` integer, nullable
  - `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
      - `component` SubscriptionComponent, required
        - `fee` union, required
          - RateFee
            - `rate` string, decimal, required
          - OneTimeFee
            - `quantity` integer, required
            - `rate` string, decimal, required
          - RecurringFee
            - `billing_type` 'ADVANCE' | 'ARREARS', required
            - `quantity` integer, required
            - `rate` string, decimal, required
          - CapacityFee
            - `included` integer, required
            - `metric_id` string, MeteroidId, required
            - `overage_rate` string, decimal, required
            - `rate` string, decimal, required
          - SlotFee
            - `initial_slots` integer, required
            - `max_slots` integer, nullable
            - `min_slots` integer, nullable
            - `unit` string, required
            - `unit_rate` string, decimal, required
          - UsageFee
            - `metric_id` string, MeteroidId, required
            - `model` union, required
              - …
        - `name` string, required
        - `period` 'ONE_TIME' | 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL', required
        - `price_component_id` string, MeteroidId
        - `product_id` string, MeteroidId
    - `overridden_components` ComponentOverride[], nullable
      - `component` SubscriptionComponent, required
        - `fee` union, required
          - RateFee
            - `rate` string, decimal, required
          - OneTimeFee
            - `quantity` integer, required
            - `rate` string, decimal, required
          - RecurringFee
            - `billing_type` 'ADVANCE' | 'ARREARS', required
            - `quantity` integer, required
            - `rate` string, decimal, required
          - CapacityFee
            - `included` integer, required
            - `metric_id` string, MeteroidId, required
            - `overage_rate` string, decimal, required
            - `rate` string, decimal, required
          - SlotFee
            - `initial_slots` integer, required
            - `max_slots` integer, nullable
            - `min_slots` integer, nullable
            - `unit` string, required
            - `unit_rate` string, decimal, required
          - UsageFee
            - `metric_id` string, MeteroidId, required
            - `model` union, required
              - …
        - `name` string, required
        - `period` 'ONE_TIME' | 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUAL' | 'ANNUAL', required
        - `price_component_id` string, MeteroidId
        - `product_id` string, MeteroidId
      - `component_id` string, MeteroidId, required
    - `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, MeteroidId, required
  - `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_strategy` 'AUTO' | 'BANK' | 'EXTERNAL'
  - `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', 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
    - `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
- `500` — Internal server error

## Changes

- **2026-01-19** (v1) `7d4a46169b06` — 1 info
  - endpoint added
- **2025-07-09** (v1) `dece17f86f99` — 1 breaking
  - api path removed without deprecation

[Change 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/85bfeb5a17c7/schema)