Create checkout session
Create an ‘open’ checkout session to start a purchase.
Contract modes:
- Plan-based: set contract.is_plan_based = true and provide plan_id, currency, start_date.
- Product-based: set contract.is_plan_based = false and provide currency, start_date, and phases with pricings.
Customer modes:
- Customer-based: provide customer_id of an existing customer.
- Guest: set guest_checkout = true and provide customer details and business_entity_id.
Validation notes:
- currency must be ISO-4217 and match the contract currency if provided.
- success_url, cancel_url, pending_url must be fully qualified URLs.
- idempotency_key allows safe retries without duplicates.
Response: returns the created session (status ‘open’) and pricing estimates following EstimationResponseSchema. See the examples for plan-based and product-based requests and responses.
Documentation Index
Fetch the complete documentation index at: https://docs2.zenskar.com/llms.txt
Use this file to discover all available pages before exploring further.
Authorizations
Body
Schema for creating a new checkout session
This schema defines all the information needed to create a new checkout session, including contract details, customer information, session configuration, and experience options.
Contract data for checkout session. Can be either plan-based or product-based. Required field.
- CheckoutContractSchemaPlanBased
- CheckoutContractSchemaProductBased
{
"currency": "USD",
"is_plan_based": true,
"plan_id": "123e4567-e89b-12d3-a456-426614174000",
"start_date": "2023-01-01T00:00:00"
}ID of an existing customer. Required for non-guest checkout flows. Must be a valid UUID of an existing customer.
Flag indicating if this is a guest checkout flow. When true, customer_id is not required, but customer data and business_entity_id must be provided.
Customer data for guest checkout or to override existing customer details. Required when guest_checkout is true.
ID of the business entity. Required when guest_checkout is true. Must be a valid UUID of an existing business entity.
Timestamp when this checkout session expires. If not provided, system defaults will apply. Format: ISO 8601 datetime.
Unique key for idempotent requests. Allows safe retries of checkout session creation without creating duplicates.
ID for cross-service request tracing. Useful for debugging and tracking request flows across services.
Display currency for the checkout session. Must be a valid ISO 4217 currency code (e.g., 'USD', 'EUR'). If provided, must match the contract currency.
URL to redirect customers after successful checkout. Should be a valid, fully-qualified URL.
1 - 2083URL to redirect customers after cancellation. Should be a valid, fully-qualified URL.
1 - 2083URL to redirect customers when payment is pending. Should be a valid, fully-qualified URL.
1 - 2083UTM and attribution data for marketing tracking. Helps track the source of the checkout session.
Arbitrary key-value storage for additional data. Can be used to store metadata or integration-specific information.
Response
Successfully created checkout session
Schema for checkout session response
This schema defines the response format for checkout session operations, including all session details, status information, and associated data.
Unique identifier for the checkout session
Current status of the checkout session (open, processing, completed, closed, cancelled)
open, processing, completed, closed, cancelled Current status of the payment (not_started, pending, paid, failed, no_payment_required)
not_started, pending, paid, failed, no_payment_required Contract data associated with this checkout session
Indicates if this was a guest checkout flow
ID of the associated contract, if one has been created
ID of the execution process for this checkout session
Timestamp when the checkout session was confirmed
Timestamp when the payment was received
External payment intent ID from the payment provider
Calculated price estimates for the contract as EstimationResponseSchema (estimation_id, current_invoice, future_invoices, amount_due, credit_notes)
ID of the customer associated with this checkout session
ID of the business entity associated with this checkout session
Customer data snapshot at the time of checkout
Timestamp when this checkout session expires
Timestamp of the last activity on this checkout session
Timestamp when the checkout session was completed
Idempotency key used when creating this checkout session
Correlation ID for cross-service tracking
Display currency for the checkout session
URL to redirect customers after successful checkout
URL to redirect customers after cancellation
URL to redirect customers when payment is pending
UTM and attribution data for marketing tracking
Arbitrary key-value storage for additional data