Checkout Sessions API

A Checkout Session represents a single payment attempt. Call POST /v1/checkout/sessions, get back a payment URL, redirect your customer, and Flexprice activates the subscription once payment is confirmed.

Session lifecycle

Status	Meaning
`initiated`	Session created; payment provider call in progress
`pending`	Payment URL returned; awaiting customer payment
`completed`	Payment confirmed; subscription activated, invoice finalized
`failed`	Payment failed or provider cancelled the link
`expired`	Session timed out without payment, or was cancelled

Create a Checkout Session

curl -X POST https://us.api.flexprice.io/v1/checkout/sessions \
  -H "x-api-key: <API_KEY>" \
  -H "X-Environment-ID: <ENVIRONMENT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_external_id": "cust_abc123",
    "action": "create_subscription",
    "payment_provider": "razorpay",
    "configuration": {
      "create_subscription_params": {
        "plan_id": "plan_xyz",
        "currency": "INR",
        "billing_period": "monthly"
      }
    },
    "success_url": "https://app.example.com/checkout/success",
    "failure_url": "https://app.example.com/checkout/failure",
    "cancel_url": "https://app.example.com/checkout/cancel",
    "idempotency_key": "order_unique_ref_001"
  }'

Response (201):

{
  "id": "chk_01HXXX",
  "customer_id": "cust_01HABC",
  "action": "create_subscription",
  "checkout_status": "pending",
  "payment_provider": "razorpay",
  "expires_at": "2024-01-01T12:15:00Z",
  "payment_action": {
    "type": "payment_link",
    "url": "https://rzp.io/l/XXXXXXX"
  }
}

Redirect the customer to payment_action.url. Each session has its own link. Do not reuse URLs across sessions.

Request fields

Field	Required	Description
`customer_external_id`	Yes	Your identifier for the customer. Must already exist in Flexprice.
`action`	Yes	Billing action to perform. `create_subscription` is supported.
`payment_provider`	Yes	Payment gateway to use. See Choose your provider.
`configuration.create_subscription_params.plan_id`	Yes	The plan to subscribe the customer to.
`configuration.create_subscription_params.currency`	Yes	Billing currency (e.g., `INR`, `USD`).
`configuration.create_subscription_params.billing_period`	Yes	`monthly`, `quarterly`, `annual`, etc.
`configuration.create_subscription_params.start_date`	No	Subscription start date. Defaults to now.
`payment_provider_config`	No	Collect a recurring mandate instead of a one-time link. Omit for the default payment-link flow. See Autopay & Mandates.
`payment_provider_config.collection_method`	No	Set to `charge_automatically` to register a mandate.
`payment_provider_config.preferred_method`	No	`UPI` or `CARD`. Selects the mandate type.
`payment_provider_config.max_mandate_limit`	No	Ceiling for any single future auto-charge, in the major currency unit.
`success_url`	No	Where to redirect after successful payment.
`failure_url`	No	Where to redirect after a failed payment.
`cancel_url`	No	Where to redirect if the customer cancels.
`idempotency_key`	No	Prevents duplicate sessions on retry. A duplicate key for an active session returns 409.

Other Checkout Actions

Four more actions exist, but they are not created through this endpoint. Each is triggered by adding a checkout object to the endpoint that owns the change, so that Flexprice can compute the amount and defer the change itself:

Action	Create it with
`modify_subscription`	`POST /subscriptions/{id}/modify/execute`
`add_addon`	`POST /subscriptions/addon`
`wallet_topup`	`POST /wallets/{id}/top-up`
`pay_invoice`	`POST /invoices`

Passing any of these actions here returns a validation error naming the endpoint to use instead. Once created, all of them are read, cancelled, deleted, and monitored through the same endpoints and webhook events described on this page. See Pay-First Checkout.

Get a Checkout Session

curl https://us.api.flexprice.io/v1/checkout/sessions/<SESSION_ID> \
  -H "x-api-key: <API_KEY>" \
  -H "X-Environment-ID: <ENVIRONMENT_ID>"

Use this to confirm checkout_status on your redirect pages before showing the customer a result. Response (200):

{
  "id": "chk_01HXXX",
  "customer_id": "cust_01HABC",
  "action": "create_subscription",
  "checkout_status": "pending",
  "payment_provider": "razorpay",
  "expires_at": "2024-01-01T12:15:00Z",
  "payment_action": {
    "type": "payment_link",
    "url": "https://rzp.io/l/XXXXXXX"
  },
  "terminal": false,
  "next_poll_after_ms": 2000,
  "stale": false,
  "payment": {
    "id": "pay_01HDEF",
    "status": "PENDING",
    "gateway": "razorpay"
  }
}

Polling for the result

Reading a session that is still initiated or pending checks it against the payment provider and completes it if the customer has already paid, so a late or dropped webhook does not leave a paying customer waiting. Gateway calls are debounced, so reading in a tight loop does not add load. Poll until terminal is true, waiting next_poll_after_ms between reads.

Field	Description
`terminal`	`true` once the session has finished (`completed`, `failed`, or `expired`). Poll on this rather than on the status set.
`next_poll_after_ms`	Milliseconds to wait before the next read: `2000`, rising to `5000` after 30 seconds and `10000` after 2 minutes. `0` on finished sessions, list results, and webhook payloads. Stop polling on `terminal`, not on this value.
`stale`	`true` when this response is stored state that was not checked against the provider on this read: the check was debounced, the gateway did not answer, or no payment exists yet. Show “still checking” rather than a final result.
`payment`	The payment the session is waiting on, with its `id`, `status`, and `gateway`. Omitted when no payment has been created yet.

A declined payment does not fail the session. The payment link stays live so the customer can retry, and the session remains pending until the customer pays, the session reaches expires_at, or you cancel it. Reconciliation on read applies to Razorpay sessions. Chargebee sessions reconcile through webhooks, and reads return stored state.

Cancel a Checkout Session

Cancel a session the customer has abandoned so that everything it was holding is released immediately instead of waiting for expires_at.

curl -X POST https://us.api.flexprice.io/v1/checkout/sessions/<SESSION_ID>/cancel \
  -H "x-api-key: <API_KEY>" \
  -H "X-Environment-ID: <ENVIRONMENT_ID>"

The response has the same shape as GET /checkout/sessions/{id}, with terminal set to true. An active session comes back as expired. A session that had already failed or expired is returned unchanged, so checkout_status can also be failed. Cancelling releases whatever the session was holding:

Draft subscription: A subscription created behind the session is archived along with its addons, coupons, credit grants, and tax associations. A change deferred behind the session is never applied.
Pending addon attachments: Addons attached behind the session are archived.
Pending wallet top-up: The pending wallet transaction is marked failed, along with any pending bonus credit earned from the purchase.
Payment and invoice: The payment and invoice created for the session are archived. If the invoice already holds customer value, such as applied prepaid credits, it is voided first so that value is returned.

Cleanup runs in a single transaction. If any step fails, nothing is changed and the session stays active, so the call is safe to retry. A cancel that races the expiry job cleans up once.

Session status	Result
`initiated`, `pending`	Cleaned up and marked `expired`; `checkout.session.expired` fires
`failed`, `expired`	Returned unchanged
`completed`	`400`: a completed session cannot be cancelled

Cancelling frees the session’s idempotency_key for reuse.

Delete a Checkout Session

curl -X DELETE https://us.api.flexprice.io/v1/checkout/sessions/<SESSION_ID> \
  -H "x-api-key: <API_KEY>" \
  -H "X-Environment-ID: <ENVIRONMENT_ID>"

Deleting an active session first cancels it, releasing everything it holds exactly as POST /checkout/sessions/{id}/cancel does, and then archives it. Sessions already in a terminal state (completed, failed, expired) are archived as is. Use cancel instead of delete when you still want to read the session’s final state afterwards.

Webhook events

Subscribe to these in Settings > Webhooks to drive fulfillment from your backend.

Event	Fired when
`checkout.session.initiated`	Session created and payment URL returned
`checkout.session.completed`	Payment confirmed; subscription active, invoice finalized
`checkout.session.failed`	Payment failed or provider cancelled
`checkout.session.expired`	Session timed out without payment, or was cancelled

Safe to receive the same event twice. If your payment provider delivers payment_link.paid more than once, Flexprice ignores the duplicate. Your webhook handler should also be idempotent for the same reason.

Requirements

Customer must exist first. The customer_external_id must refer to a customer already in Flexprice. Create them at sign-up if they don’t exist yet. Plan must have a non-zero charge. Checkout requires a payable invoice amount to generate a payment link. Plans with only free or zero-amount charges will cause session creation to fail. Idempotency on retry. An idempotency_key is reserved while its session is active, so retrying with the same key returns 409 rather than creating a duplicate. Read the open session with GET /checkout/sessions/{id} to recover its payment URL. Once the session reaches a terminal state the key can be reused.

Razorpay Setup

Configure the webhook events Razorpay needs to send Flexprice.

Implementation Guide

Full end-to-end integration with code examples.

API References

Introduction

Getting Started

Event Ingestion

Product Catalogue

Customers

Checkout

Subscriptions

Wallet

Invoices

Settings

Collectors

Data Exports

RBAC

Cookbooks

AI Cost Tracking

Checkout Sessions API

Session lifecycle

Create a Checkout Session

Request fields

Other Checkout Actions

Get a Checkout Session

Polling for the result

Cancel a Checkout Session

Delete a Checkout Session

Webhook events

Requirements

Razorpay Setup

Implementation Guide

​Session lifecycle

​Create a Checkout Session

​Request fields

​Other Checkout Actions

​Get a Checkout Session

​Polling for the result

​Cancel a Checkout Session

​Delete a Checkout Session

​Webhook events

​Requirements

Razorpay Setup

Implementation Guide

Session lifecycle

Create a Checkout Session

Request fields

Other Checkout Actions

Get a Checkout Session

Polling for the result

Cancel a Checkout Session

Delete a Checkout Session

Webhook events

Requirements