> ## 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.
# Retrieve a checkout session
> Returns a single checkout session by ID, including the order, subscription, and payment method it produced (if any).
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 get /checkout/sessions/{session_id}/
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/sessions/{session_id}/:
get:
tags:
- Checkout Sessions
summary: Retrieve a checkout session
description: >-
Returns a single checkout session by ID, including the order,
subscription, and payment method it produced (if any).
operationId: retrieveCheckoutSession
parameters:
- name: session_id
in: path
required: true
description: The checkout session ID.
schema:
type: string
example: cs_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2
responses:
'200':
description: The checkout session.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutSessionDetailResponse'
'401':
description: Unauthorized — missing or invalid API key.
'404':
description: No checkout session with that ID for the authenticated organization.
components:
schemas:
CheckoutSessionDetailResponse:
type: object
description: >-
A single checkout session, with the order/subscription/payment method it
produced.
allOf:
- $ref: '#/components/schemas/CheckoutSessionResponse'
- type: object
properties:
order:
$ref: '#/components/schemas/CheckoutSessionOrder'
nullable: true
description: '`null` until an order has been created from this session.'
subscription:
$ref: '#/components/schemas/CheckoutSessionSubscription'
nullable: true
description: '`null` if the order has no linked subscription.'
paymentMethod:
$ref: '#/components/schemas/OrderPaymentMethod'
CheckoutSessionResponse:
type: object
description: A checkout session. Returned by the list endpoint.
properties:
id:
type: string
description: Checkout session ID.
example: cs_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2
customer:
$ref: '#/components/schemas/OrderCustomer'
product:
$ref: '#/components/schemas/Product'
billingAddress:
$ref: '#/components/schemas/BillingAddress'
discountCode:
type: string
nullable: true
example: null
taxId:
type: string
nullable: true
example: null
currency:
type: string
nullable: true
example: usd
currencySymbol:
type: string
example: $
status:
type: string
description: 'Typical values: `open`, `processing`, `success`, `expired`.'
example: open
createdOn:
type: string
format: date-time
example: '2026-07-29T10:30:00Z'
selectedData:
type: object
description: Selected plan/addons for this session.
additionalProperties: true
offeringData:
type: object
description: Snapshot of the product/plan offering shown at checkout.
additionalProperties: true
data:
type: object
additionalProperties: true
customFieldsData:
type: object
description: Customer-submitted responses to custom checkout fields.
additionalProperties: true
metadata:
type: object
description: Customer-supplied metadata passed at checkout session creation.
additionalProperties: true
customization:
type: object
description: >-
Customer-supplied checkout UI customization passed at session
creation.
additionalProperties: true
trialPeriod:
type: integer
description: Trial period length in days.
example: 0
CheckoutSessionOrder:
type: object
description: The first order created from this checkout session.
properties:
id:
type: string
example: ORD-20260729103000-AB3K9
status:
type: string
enum:
- PENDING
- COMPLETE
- FAILED
- REFUNDED
- PARTIAL_REFUND
- CANCELLED
- FRAUDULENT
example: COMPLETE
paidAt:
type: string
format: date-time
nullable: true
example: '2026-07-29T10:31:12Z'
createdOn:
type: string
format: date-time
example: '2026-07-29T10:30:55Z'
billingType:
type: string
enum:
- ONE_TIME
- SUBSCRIPTION
nullable: true
example: SUBSCRIPTION
isTrial:
type: boolean
example: false
amountSubtotal:
type: string
description: >-
Decimal amount, serialized as a string (e.g. `"261.00"`), not a JSON
number.
nullable: true
example: '261.00'
amountDiscount:
type: string
description: Decimal amount, serialized as a string, not a JSON number.
example: '0.00'
amountTax:
type: string
description: Decimal amount, serialized as a string, not a JSON number.
nullable: true
example: '0.00'
amountTotal:
type: string
description: Decimal amount, serialized as a string, not a JSON number.
nullable: true
example: '261.00'
saleCurrency:
type: string
example: USD
saleCurrencySymbol:
type: string
example: $
invoiceId:
type: string
nullable: true
example: INV-20260729103000-XZ7Q1
CheckoutSessionSubscription:
type: object
description: The subscription created from this checkout session's order, if any.
properties:
id:
type: string
format: uuid
example: 09d706ca-58f3-4fb2-818f-5b8623d67e6e
recurrence:
type: string
nullable: true
example: month
billingPeriodStartTime:
type: string
format: date-time
nullable: true
example: '2026-07-29T10:31:12Z'
billingPeriodEndTime:
type: string
format: date-time
nullable: true
example: '2026-08-29T10:31:12Z'
startDate:
type: string
format: date
example: '2026-07-29'
endDate:
type: string
format: date
nullable: true
example: null
status:
type: string
example: active
amount:
type: string
description: >-
Decimal amount, serialized as a string (e.g. `"261.00"`), not a JSON
number.
nullable: true
example: '261.00'
currency:
type: string
nullable: true
example: usd
trialDaysRemaining:
type: integer
example: 0
billingType:
type: string
enum:
- ONE_TIME
- SUBSCRIPTION
example: SUBSCRIPTION
recurrenceUnit:
type: integer
nullable: true
example: 1
recurrenceType:
type: string
nullable: true
example: MONTH
OrderPaymentMethod:
type: object
nullable: true
description: >-
The payment method used for the order's first successful transaction.
`null` if no successful transaction exists yet.
properties:
paymentMethodType:
type: string
example: card
paymentMethodName:
type: string
nullable: true
example: visa
last4:
type: string
nullable: true
example: '4242'
OrderCustomer:
type: object
properties:
customerId:
type: string
example: testuser
name:
type: string
nullable: true
example: Jane Smith
email:
type: string
format: email
nullable: true
example: jane@example.com
Product:
type: object
description: >-
A product in the catalog. Each product can have multiple plans, images
and files.
properties:
id:
type: string
format: uuid
readOnly: true
example: 0d65f7c0-7e91-4f56-9b32-13a9a6a7c1de
identifier:
type: string
description: >-
Human-readable, URL-safe slug. Auto-generated from `name` if omitted
on create.
example: pro-suite
name:
type: string
example: Pro Suite
description:
type: string
example: Premium tools for growing teams.
taxCode:
type: string
description: Tax code for the product. Must be one of the supported values.
enum:
- saas
- saas_business
- software
- videocontent
- informationservice
- ebook
- digitalgraphic
- videogame
- eservice
- training
example: saas
createdBy:
type: string
readOnly: true
description: Display name of the user who created the product.
example: Jane Smith
modifiedOn:
type: string
format: date-time
readOnly: true
example: '2025-04-12T08:21:14.910Z'
images:
type: array
readOnly: true
items:
$ref: '#/components/schemas/ProductImage'
BillingAddress:
type: object
nullable: true
description: The billing address of the customer.
properties:
country:
type: string
description: The country code (e.g., ISO 3166-1 alpha-2).
example: IN
line1:
type: string
description: Address line 1.
example: 123 Main Street
line2:
type: string
nullable: true
description: Address line 2.
example: Apt 4B
postalCode:
type: string
description: The postal or ZIP code.
example: '560001'
city:
type: string
description: The city name.
example: Bangalore
state:
type: string
description: The state or province.
example: Karnataka
ProductImage:
type: object
description: An image asset attached to a product.
properties:
id:
type: string
format: uuid
readOnly: true
description: Unique identifier for the image.
example: 1f7e1b54-7c6f-4d7e-9a4f-2c9c2d8b9d31
name:
type: string
nullable: true
description: Original filename or display name.
example: hero-banner.png
image:
type: string
readOnly: true
description: Storage key / URL for the image asset.
example: media/.../products///hero-banner.png
ordering:
type: integer
description: Position of the image in the gallery.
example: 0
thumbnail:
type: boolean
description: If `true`, this image is used as the product thumbnail.
example: true
enabled:
type: boolean
description: If `true`, the image is shown publicly.
example: true
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__'
````