---
title: "Create a checkout session for a subscription offer (recommended)"
method: POST
path: "/api/checkout/sessions/subscription/{subscriptionOfferId}"
tags: ["Checkout Sessions"]
---

# Create a checkout session for a subscription offer (recommended)

`POST /api/checkout/sessions/subscription/{subscriptionOfferId}`

Recommended way to start a hosted subscription checkout for an existing offer. Replaces the deprecated `POST /subscription/offer/:subscriptionOfferId/initiate`.

Returns `{ sessionId, checkoutUrl }` — redirect the buyer to `checkoutUrl` to subscribe. The subscription and first payment are created once the buyer submits a payment method during the session. Subscribe to `checkout_session.*` merchant webhooks — the `paymentId` is included in the payload once the session is completed (e.g. `checkout_session.completed`).

## Path parameters

- `subscriptionOfferId` string, required

## Request body

- CreateApiSubscriptionSessionDto
  - `successUrl` string — Optional override for the successful payment redirect URL. If not provided, uses the subscription offer's successUrl, then the system default.
  - `cancelUrl` string — Optional override for the cancel/failed payment redirect URL. If not provided, uses the subscription offer's cancelUrl.
  - `customerEmail` string — Default customer email pre-filled in the checkout session. @deprecated Prefer `customer.email`.
  - `metadatas` object — Custom metadata for the session/subscription
  - `expiresIn` number — Duration in hours before the session expires. 0.75 = 45 minutes, 24 = 1 day. Minimum 0.25 (15 minutes). If not provided, the session will not have an automatic expiration.
  - `billingCountry` string — Optional default billing country (ISO 3166-1 alpha-2). When set, the checkout session is pre-filled with this country and VAT is recomputed accordingly. Ignored silently if the country is not supported for tax. @deprecated Prefer `customer.billingCountry`.
  - `customer` ApiSessionCustomerInfoDto
    - `id` string — Existing Inflow customer id (cus_...). When provided, the payment — and any saved payment method — is always attached to this customer, even if the buyer edits the pre-filled info on the checkout (the buyer's email is then kept on the payment only; no other customer is created or looked up). The customer's stored info pre-fills the checkout fields, which stay editable unless `locked` is set. The customer must belong to the merchant and have an email.
    - `email` string, email — Customer email pre-filled in the checkout session.
    - `billingCountry` string — Default billing country (ISO 3166-1 alpha-2). When set, the checkout session is pre-filled with this country and VAT is recomputed accordingly. Ignored silently if the country is not supported for tax.
    - `purchasingAsBusiness` boolean — Whether the buyer purchases as a business. Determines which identity set is used: when false/omitted the individual set (firstName/lastName), when true the business set (businessName/taxId).
    - `firstName` string — Customer first name (individual purchase set, used when purchasingAsBusiness is false/omitted).
    - `lastName` string — Customer last name (individual purchase set, used when purchasingAsBusiness is false/omitted).
    - `businessName` string — Business name (business purchase set, used when purchasingAsBusiness is true).
    - `taxId` string — Business tax identification number (business purchase set, used when purchasingAsBusiness is true).
    - `locked` boolean — When true, all customer info pre-filled here is locked on the checkout: the buyer sees the fields but cannot edit them.
  - `marketplaceFeeInCents` number — Marketplaces only: fixed fee to collect on the first subscription payment, in cents. Can only be set by the parent marketplace acting on behalf of a sub-merchant. Defaults to the marketplace's configured fee.
  - `savePaymentMethod` boolean — When true, the checkout offers the buyer the option to save their payment method (card / wallet) for future payments. The saved payment method is attached to the merchant's customer matching the buyer's email (created if needed). Pass `customer.id` to instead anchor it to a specific existing customer, regardless of the email the buyer enters. Subscriptions always store the payment method for renewals; this flag surfaces the reusable-save consent to the buyer.

## Response `201`

Checkout session created

- CheckoutSessionResponseDto
  - `sessionId` string, required — Checkout session unique identifier
  - `checkoutUrl` string, required — Hosted Checkout V2 URL. Redirect the buyer here to complete the checkout.

---

[API](https://skmtc.dev/inflowpay/apis/inflow-api.md) · [All operations](https://skmtc.dev/inflowpay/apis/inflow-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/inflowpay/inflow-api/revisions/3012dd3dd14a/schema)