Skip to main content
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

StatusMeaning
initiatedSession created; payment provider call in progress
pendingPayment URL returned; awaiting customer payment
completedPayment confirmed; subscription activated, invoice finalized
failedPayment failed or provider cancelled the link
expiredSession timed out without payment

​
Create a Checkout Session

curl -X POST https://api.flexprice.io/v1/checkout/sessions \
  -H "Authorization: Bearer <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

FieldRequiredDescription
customer_external_idYesYour identifier for the customer. Must already exist in Flexprice.
actionYesBilling action to perform. create_subscription is supported.
payment_providerYesPayment gateway to use. See Choose your provider.
configuration.create_subscription_params.plan_idYesThe plan to subscribe the customer to.
configuration.create_subscription_params.currencyYesBilling currency (e.g., INR, USD).
configuration.create_subscription_params.billing_periodNomonthly, quarterly, annual, etc. Defaults to the plan’s period.
configuration.create_subscription_params.start_dateNoSubscription start date. Defaults to now.
success_urlNoWhere to redirect after successful payment.
failure_urlNoWhere to redirect after a failed payment.
cancel_urlNoWhere to redirect if the customer cancels.
idempotency_keyNoPrevents duplicate sessions on retry. A duplicate key for an active session returns 409.

​
Get a Checkout Session

curl https://api.flexprice.io/v1/checkout/sessions/<SESSION_ID> \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Environment-ID: <ENVIRONMENT_ID>"
Use this to confirm checkout_status on your redirect pages before showing the customer a result.

​
Delete a Checkout Session

curl -X DELETE https://api.flexprice.io/v1/checkout/sessions/<SESSION_ID> \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Environment-ID: <ENVIRONMENT_ID>"
Sessions in a terminal state (completed, failed, expired) cannot be deleted.

​
Webhook events

Subscribe to these in Settings > Webhooks to drive fulfillment from your backend.
EventFired when
checkout.session.initiatedSession created and payment URL returned
checkout.session.completedPayment confirmed; subscription active, invoice finalized
checkout.session.failedPayment failed or provider cancelled
checkout.session.expiredSession timed out without payment
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. If your create call times out, retry with the same idempotency_key. You’ll get back the existing session instead of a duplicate.

Razorpay Setup

Configure the webhook events Razorpay needs to send Flexprice.

Implementation Guide

Full end-to-end integration with code examples.
API References