> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tirdad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout Sessions API

> Create a time-bounded payment session that activates a subscription on successful payment.

A Checkout Session represents a single payment attempt. Call `POST /v1/checkout/sessions`, get back a payment URL, redirect your customer, and Tirdad 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

```bash theme={null}
curl -X POST https://api.tirdad.ai/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):**

```json theme={null}
{
  "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 Tirdad. |
| `action` | Yes | Billing action to perform. `create_subscription` is supported. |
| `payment_provider` | Yes | Payment gateway to use. See [Choose your provider](https://docs.tirdad.ai/docs/checkout/overview#choose-your-payment-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](https://docs.tirdad.ai/docs/checkout/autopay-mandates.md). |
| `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 Tirdad can compute the amount and defer the change itself:

| Action | Create it with |
| - | - |
| `modify_subscription` | `POST /subscriptions/{id}/modify/execute` |
| `add_addon` | `POST /subscriptions/{id}/modify/execute` with `type: "addon"` (or the deprecated `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 (for `add_addon`, the error names the deprecated `POST /subscriptions/addon`). 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](https://docs.tirdad.ai/docs/checkout/pay-first-checkout.md).

## Get a Checkout Session

```bash theme={null}
curl https://api.tirdad.ai/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):**

```json theme={null}
{
  "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](#cancel-a-checkout-session).

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`.

```bash theme={null}
curl -X POST https://api.tirdad.ai/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

```bash theme={null}
curl -X DELETE https://api.tirdad.ai/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 |

> [!NOTE]
>
> Safe to receive the same event twice. If your payment provider delivers
> `payment_link.paid` more than once, Tirdad 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 Tirdad. 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.

> [card] [Razorpay Setup](https://docs.tirdad.ai/docs/checkout/razorpay-checkout.md)
>
> Configure the webhook events Razorpay needs to send Tirdad.

> [card] [Implementation Guide](https://docs.tirdad.ai/docs/checkout/implementation-guide.md)
>
> Full end-to-end integration with code examples.

**API References**

* [Create a Checkout Session](https://docs.tirdad.ai/api-reference/checkout/create-checkout-session.md)
* [Get a Checkout Session](https://docs.tirdad.ai/api-reference/checkout/get-checkout-session.md)
* [Cancel a Checkout Session](https://docs.tirdad.ai/api-reference/checkout/cancel-checkout-session.md)
* [Delete a Checkout Session](https://docs.tirdad.ai/api-reference/checkout/delete-checkout-session.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.