# Create Subscription Session

Source: https://recoupable.dev/docs/api-reference/subscriptions/sessions-create

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.

## POST /api/subscriptions/sessions

Full OpenAPI specification: https://recoupable.dev/docs/spec/accounts.json

## Authentication

The supplied specification does not declare an OpenAPI security object for this operation. Its declared headers and parameters still apply. Consult the authentication guide and the full specification before calling it.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Accounts",
    "description": "API documentation for the Recoup platform - an AI agent platform for the music industry",
    "license": {
      "name": "MIT"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/subscriptions/sessions": {
      "post": {
        "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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CreateSubscriptionSessionRequest": {
        "type": "object",
        "required": [
          "successUrl"
        ],
        "properties": {
          "plan": {
            "type": "string",
            "enum": [
              "starter",
              "pro"
            ],
            "description": "The plan to buy. Defaults to `pro` when omitted (back-compat for authenticated callers). `pro` carries the 30-day trial; `starter` charges on completion.",
            "example": "pro"
          },
          "successUrl": {
            "type": "string",
            "format": "uri",
            "description": "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.",
            "example": "https://chat.recoupable.dev?checkout=success&session_id={CHECKOUT_SESSION_ID}"
          },
          "cancelUrl": {
            "type": "string",
            "format": "uri",
            "description": "Where Stripe sends the buyer if they leave Checkout without paying.",
            "example": "https://recoupable.dev/pricing"
          }
        }
      },
      "CreateSubscriptionSessionResponse": {
        "type": "object",
        "required": [
          "id",
          "url"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The checkout session ID.",
            "example": "cs_test_a1b2c3d4e5f6g7h8i9j0"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The hosted checkout URL. Redirect to this URL to complete Checkout.",
            "example": "https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6g7h8i9j0"
          }
        }
      },
      "SubscriptionSessionErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message.",
            "example": "successUrl is required"
          }
        }
      }
    }
  }
}
```