RecoupGet a free auditFree audit

API REFERENCE

Create Subscription Session

On this page
POST/api/subscriptions/sessions

Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. plan picks the price: pro (default) is pre-configured with a 30-day trial period; starter is charged at checkout with no trial.

Authentication

See the authentication guide for API key and account access requirements.

Request

cURL
curl --request POST \
  --url 'https://api.recoupable.dev/api/subscriptions/sessions' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "successUrl": "https://chat.recoupable.dev?checkout=success&session_id={CHECKOUT_SESSION_ID}"
}'

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request POST \
  --url 'https://recoup-api.vercel.app/api/subscriptions/sessions' \
  --header 'Content-Type: application/json' \
  --data '{
  "successUrl": "https://chat.recoupable.dev?checkout=success&session_id={CHECKOUT_SESSION_ID}"
}'

Request body required

Session creation parameters

application/json

planstring · enum

The plan to buy. Defaults to pro when omitted (back-compat for authenticated callers). pro carries the 30-day trial; starter charges on completion.

Values: "starter", "pro"

successUrlstringrequired

Where Stripe sends the buyer after payment. For anonymous checkout include the literal {CHECKOUT_SESSION_ID} placeholder so the client can call Claim Subscription if the sign-in email differs.

format: uri

cancelUrlstring

Where Stripe sends the buyer if they leave Checkout without paying.

format: uri

Responses

200Checkout session created successfully

application/json

idstringrequired

The checkout session ID.

urlstringrequired

The hosted checkout URL. Redirect to this URL to complete Checkout.

format: uri

400Bad request - missing or invalid parameters, or plan is starter while the Starter price is not configured (error is literally starter_unavailable).

application/json

errorstringrequired

Human-readable error message.

400 example
{
  "error": "starter_unavailable"
}

401Unauthorized - an auth header was supplied but is invalid (omit it entirely for an anonymous session)

application/json

errorstringrequired

Human-readable error message.

500Internal server error

application/json

errorstringrequired

Human-readable error message.

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download accounts.json
View operation source
json
{
  "description": "Create a checkout session to start a subscription for the authenticated account. Returns a hosted checkout URL that the client should redirect to. `plan` picks the price: `pro` (default) is pre-configured with a 30-day trial period; `starter` is charged at checkout with no trial.",
  "requestBody": {
    "description": "Session creation parameters",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateSubscriptionSessionRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Checkout session created successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateSubscriptionSessionResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - missing or invalid parameters, or `plan` is `starter` while the Starter price is not configured (`error` is literally `starter_unavailable`).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubscriptionSessionErrorResponse"
          },
          "example": {
            "error": "starter_unavailable"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - an auth header was supplied but is invalid (omit it entirely for an anonymous session)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubscriptionSessionErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/SubscriptionSessionErrorResponse"
          }
        }
      }
    }
  }
}