> ## Documentation Index > Fetch the complete documentation index at: https://docs.kelviq.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a checkout session > Creates a new checkout session for a customer to proceed with a purchase or subscription. Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment. ## OpenAPI ````yaml /api-reference/openapi.json post /checkout/ openapi: 3.0.0 info: title: kelviq API version: 1.0.0 description: >- API for interacting with kelviq services, derived from Python SDK documentation. servers: - url: https://sandboxapi.kelviq.com/api/v1 description: Sandbox — Test payments - url: https://api.kelviq.com/api/v1 description: Production — Live payments security: - bearerAuth: [] tags: - name: Products description: Catalog products. - name: Product Settings description: Per-product settings (currency, VPN/Tor/proxy, product URL). - name: Product Files description: Product images and downloadable assets. - name: Features description: Catalog features that can be granted as plan entitlements. - name: Plans description: Catalog plans (CRUD, publish, versions, prices). - name: Plan Entitlements description: Feature entitlements attached to a plan. - name: Plan Files description: Files attached to plans, and signed download links. - name: Media description: Generate presigned S3 upload URLs for product/plan images and files. - name: Partner description: Partner integration APIs (organization provisioning, lookup). - name: Charges description: >- One-time payments charged immediately against a customer's default payment method. - name: Refunds description: Full and partial refunds for paid orders. - name: Transactions description: >- Charges, refunds, disputes, and other financial movements for the authenticated organization. - name: Payment Methods description: Saved customer payment methods (cards, etc.). - name: Orders description: Completed and resolved orders for the authenticated organization. - name: Order Events description: Timeline events for a specific order. - name: Webhooks description: Delivery logs for webhook events sent to your configured endpoints. - name: Checkout Sessions description: Merchant-side view of checkout sessions created by customers. - name: Checkout Session Events description: Timeline events for a specific checkout session. paths: /checkout/: post: tags: - Checkout summary: Create a checkout session description: >- Creates a new checkout session for a customer to proceed with a purchase or subscription. operationId: createCheckoutSession requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutSessionRequest' responses: '201': description: Checkout Session Created content: application/json: schema: $ref: '#/components/schemas/CreateCheckoutSessionResponse' example: checkoutUrl: >- https://kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/ checkoutSessionId: cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9 components: schemas: CreateCheckoutSessionRequest: type: object required: - planIdentifier - successUrl - chargePeriod properties: planIdentifier: type: string description: >- The identifier of the specific plan the customer is checking out with. example: plan-pro-monthly successUrl: type: string format: url description: >- The URL to which the user will be redirected after a successful checkout. example: https://kelviq.com/checkout/success chargePeriod: type: string description: The billing cycle for the subscription. enum: - ONE_TIME - MONTHLY - YEARLY - WEEKLY - DAILY - TWENTY_EIGHT_DAYS - THREE_MONTHS - SIX_MONTHS example: MONTHLY customerId: type: string nullable: true description: >- The customerId of the customer initiating the checkout. If omitted, Kelviq creates a new customer and generates a unique customerId. Multiple customer records can share the same email address, but every customerId must be unique. example: cust_789 features: type: array items: $ref: '#/components/schemas/FeatureInput' nullable: true description: >- A list of features and their desired quantities. SDK documentation notes this as '**Required**', but usage may vary based on examples. example: - identifier: seats quantity: 5 ipAddress: type: string nullable: true description: The IP Address of the customer, used for location-based pricing. example: 103.154.35.20 cancelUrl: type: string format: url nullable: true description: >- The URL to which the user will be redirected if the payment is cancelled. example: https://kelviq.com/checkout/cancel plansEnabled: type: string nullable: true description: >- A comma-separated list of plan identifiers to display on the checkout page. example: plan-pro-monthly,plan-pro-yearly currencyCode: type: string nullable: true description: >- The currency code for the checkout session (e.g. 'USD'). Required when customAmount is provided with a server API key. example: USD customAmount: type: number nullable: true description: >- A custom amount to charge for this checkout session. When provided, taxBehavior is required. When using a server API key, currencyCode is also required. example: 2999 taxBehavior: type: string nullable: true description: >- Specifies how taxes are applied to the custom amount. Required when customAmount is provided. INCLUSIVE means tax is included in the amount; EXCLUSIVE means tax is added on top. enum: - INCLUSIVE - EXCLUSIVE example: EXCLUSIVE discountsEnabled: type: boolean nullable: true description: >- Whether discount/coupon code entry is shown on the checkout page. Defaults to `true`. example: false discountCode: type: string nullable: true description: >- A discount/coupon code to pre-apply to the checkout session. The code is applied only if it is active, unexpired, and valid for the selected plan; otherwise the request fails with an error. example: WELCOME20 lockEmail: type: boolean nullable: true description: >- When `true`, the email field on the checkout page is pre-filled and locked so the customer cannot change it. Defaults to `false`. example: true defaultBillingCountry: type: string nullable: true description: >- ISO 3166-1 alpha-2 country code used to pre-fill the billing address country on the checkout page. example: US metadata: type: object additionalProperties: true nullable: true description: >- Arbitrary key-value pairs to attach to the checkout session. The keys are preserved verbatim and the object is returned unchanged on the `checkout.completed` webhook payload's `metadata` field. example: order_ref: ABC-123 source: pricing_page CreateCheckoutSessionResponse: type: object properties: checkoutUrl: type: string format: url description: >- The URL that the customer should be redirected to complete the payment. example: >- https://kelviq.com/checkout/cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9/ checkoutSessionId: type: string description: The unique ID for the created checkout session. example: cs_eeCGdGayc5oTMdGNV5XocfRk6o87K0vlwwCuKeiE7BLU9 FeatureInput: type: object required: - identifier - quantity properties: identifier: type: string description: The unique identifier for the feature. example: seats quantity: type: integer description: The desired quantity for this feature. example: 5 securitySchemes: bearerAuth: type: http scheme: bearer description: >- The Server API Key obtained from the kelviq application. Pass as a Bearer token in the Authorization header. Example: 'Authorization: Bearer __YOUR_API_KEY__' ````