> ## Documentation Index > Fetch the complete documentation index at: https://alguna.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a checkout session > Creates a checkout session and returns a browser-safe session token plus a hosted checkout URL. Embed the URL with the Alguna Checkout SDK, or redirect the customer to it directly. The session charges a plan's prices, ad-hoc line items, or a bare amount, and expires after `expires_in_seconds`. ## OpenAPI ````yaml /api-reference/v2/specs/2026-04-01.json post /checkout-sessions openapi: 3.1.0 info: title: Alguna Public API version: '2026-04-01' servers: - url: https://api.alguna.io security: - bearerAuth: [] tags: - name: Billing Events and Metrics - name: Checkout Sessions - name: Credit Notes - name: Credits - name: Customer Portal Sessions - name: Customers - name: Insights - name: Integrations - name: Invoices - name: Payments - name: Plans - name: Product Bundles - name: Products - name: Refunds - name: Revenue Schedules - name: Subscription Changes - name: Subscription Versions - name: Subscriptions - name: Tax - name: Wallet Grants - name: Wallets paths: /checkout-sessions: post: tags: - Checkout Sessions summary: Create a checkout session description: >- Creates a checkout session and returns a browser-safe session token plus a hosted checkout URL. Embed the URL with the Alguna Checkout SDK, or redirect the customer to it directly. The session charges a plan's prices, ad-hoc line items, or a bare amount, and expires after `expires_in_seconds`. operationId: create-checkout-session parameters: - in: header name: Alguna-Version required: true schema: enum: - '2026-04-01' type: string - in: header name: Idempotency-Key schema: description: >- A unique string used to ensure the request is processed exactly once. If you retry a request with the same idempotency key within 24 hours, the original response is returned without re-executing the operation. example: ik_a1b2c3d4e5f6 maxLength: 255 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CheckoutSessionCreateRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/CheckoutSessionResponse' description: Success headers: Idempotency-Key: description: Echo of the idempotency key provided in the request schema: type: string Idempotent-Replayed: description: >- Whether this response was replayed from a previous request (true) or freshly executed (false) schema: type: boolean '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: >- Conflict — a request with this idempotency key is currently being processed '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error components: schemas: CheckoutSessionCreateRequest: properties: amount: description: >- Total amount to charge when neither plan_id nor line_items are provided example: '99.00' nullable: true type: string checkout_intent: description: >- payment charges the customer; vault only collects and stores a payment method. Defaults to payment. enum: - payment - vault example: payment nullable: true type: string client_reference_id: description: >- Your own reference for this checkout (order ID, cart ID). Echoed on the session and the checkoutsession.completed webhook. example: order_1234 nullable: true type: string currency: description: ISO 4217 currency code; defaults to the organization currency example: USD nullable: true type: string customer: allOf: - $ref: '#/components/schemas/CheckoutCustomerRequest' description: >- Details the customer account is created from when checkout completes. When neither this nor customer_id/customer_alias is provided, the embedded checkout collects them from the customer. nullable: true customer_alias: description: >- Alternative identifier (external ID) for the customer. Used when customer_id is not provided. example: ext_39003209203023902 nullable: true type: string customer_id: description: >- Customer the checkout is for. Omit for guest checkout and pass customer instead — the customer account is created when checkout completes. example: cust_abc123 nullable: true type: string expires_in_seconds: description: >- Session lifetime in seconds (5 minutes to 7 days). Defaults to 86400 (24 hours). example: 86400 format: int64 nullable: true type: integer legal_entity_id: description: >- Legal entity to bill from. Defaults to the customer's legal entity, falling back to the organization default. example: le_01H1VECT nullable: true type: string line_items: description: >- Ad-hoc line items to charge instead of a plan. Mutually exclusive with plan_id. items: $ref: '#/components/schemas/CheckoutLineItemRequest' type: array plan_id: description: >- Plan to check out. The session's line items and amount are derived from the plan's prices. Mutually exclusive with line_items. example: plan_01H1VECT nullable: true type: string success_url: description: URL the customer can be sent to after a successful checkout example: https://example.com/welcome nullable: true type: string type: object CheckoutSessionResponse: properties: amount: description: Total amount for the session example: '99.00' nullable: true type: string checkout_intent: description: >- Whether the session charges the customer or only stores a payment method enum: - payment - vault example: payment type: string client_reference_id: description: Your reference supplied at creation example: order_1234 nullable: true type: string created_at: description: Timestamp when the session was created example: '2026-04-01T10:00:00Z' format: date-time type: string currency: description: ISO 4217 currency code example: USD type: string customer_id: description: Customer the checkout is for, once known example: cust_abc123 nullable: true type: string expires_at: description: Timestamp when the session token expires example: '2026-04-02T10:00:00Z' format: date-time nullable: true type: string id: description: Unique identifier for the checkout session example: chks_01H1VECT type: string invoice_id: description: >- Invoice created by the session, once completed. One-off sessions (line_items or amount) produce a paid invoice instead of a subscription. example: inv_01H1VECT nullable: true type: string payment_id: description: Payment created by the session, once completed example: pay_01H1VECT nullable: true type: string session_token: description: >- Browser-safe token that scopes the embedded checkout to this session. Pass it to the Alguna Checkout SDK. example: elt_01H1VECT type: string status: description: Checkout session status enum: - created - started - successful - expired example: created type: string subscription_id: description: Subscription created by the session, once completed example: sub_01H1VECT nullable: true type: string url: description: >- Hosted checkout URL for this session. The Alguna Checkout SDK embeds this URL; it can also be used directly as a redirect target. example: https://acme.alguna.io/embed/checkout/elt_01H1VECT type: string required: - checkout_intent - created_at - currency - id - session_token - status - url type: object ErrorResponse: properties: detail: type: string status: format: int64 type: integer required: - status - detail type: object CheckoutCustomerRequest: properties: address: allOf: - $ref: '#/components/schemas/CheckoutAddressRequest' description: Billing address. When provided, checkout skips address re-entry. nullable: true email: description: Billing email; becomes the account's primary contact example: billing@acme.com type: string first_name: description: Primary contact first name example: Ada nullable: true type: string last_name: description: Primary contact last name example: Lovelace nullable: true type: string name: description: Company or customer name the account is created with example: Acme Corp type: string website_url: description: >- Company website. When an account with this website already exists, checkout completion updates it instead of creating a duplicate. example: https://acme.com nullable: true type: string required: - email - name type: object CheckoutLineItemRequest: properties: description: description: Line item description shown to the customer example: Implementation fee type: string product_name: description: Product name shown alongside the description example: Onboarding nullable: true type: string quantity: description: Quantity example: '1' type: string unit_price: description: Price per unit example: '99.00' type: string required: - description - quantity - unit_price type: object CheckoutAddressRequest: properties: city: description: City example: San Francisco type: string country: description: Two-letter ISO country code example: US type: string line1: description: Address line 1 example: 123 Main St type: string line2: description: Address line 2 example: Suite 4 nullable: true type: string postal_code: description: Postal or ZIP code example: '94105' type: string state: description: State / province / region example: CA nullable: true type: string required: - city - country - line1 - postal_code type: object securitySchemes: bearerAuth: bearerFormat: API Key description: API key authentication. Pass your API key as a Bearer token. scheme: bearer type: http ````