Checkout sessions
Create secure, hosted payment pages that handle one-time purchases and subscriptions using Checkout Sessions.
Quickstart
Choose the fastest way to create a checkout session based on your setup.
Using the dashboard (no-code)
Create and share a checkout session directly from the PaymentKit dashboard:
Configure session details
Configure the following session details:
- Customer (optional): Select an existing customer
- Expires In (Hours): Set expiration time (default: 24 hours)
- Success URL: URL to redirect customers after successful payment
- Return URL: URL to redirect customers if they cancel
- Line Items: Add one or more prices with quantities. Each line item consists of a price (linked to a product) and a quantity.
Using the API
Create a checkout session programmatically:
The response includes a CheckoutSession object with an id and secure_token. Use the secure_token to construct the hosted checkout page URL and redirect the customer to begin checkout.
How checkout sessions work
Customizing checkout
Pre-fill customer information
Link the checkout session to an existing customer:
Apply a promotion code
Apply a promotion code to the checkout session:
Or apply a coupon directly by ID:
Redirect URLs
Configure where customers go after checkout:
Include the checkout session ID to verify the result: https://yoursite.com/success?session_id={CHECKOUT_SESSION_ID}
Session expiration
Checkout sessions expire after 24 hours by default. You can configure a custom expiration time using expires_in_hours:
Skip the customer's credit balance
When the checkout’s customer (the session’s customer_id, or an existing customer matched by email) holds a credit balance, the balance is applied to the invoice at checkout and the customer pays the remainder. Set apply_customer_balance to false to leave the credit untouched for a later purchase, for example when a promo code should not stack with a referral credit. The customer then pays the full amount after any coupon. Only credit is skipped: if the customer owes you money (a negative balance), it is handled exactly as on a session without this flag.
The flag is fixed when the session is created. An update request that sends it returns a 422 error; create a new session to change it. It only affects the invoice created from this session: a subscription started from it applies the balance to its renewals as usual. With a free trial, the session’s invoice is $0 and the first paid invoice comes after the trial, so that invoice applies the balance. The session and its invoice both report the value as apply_customer_balance.
Attach custom fields
Attach custom fields for internal tracking:
Custom fields are included in webhooks and retrievable from the API when expand=custom_fields is specified.
Free trials
A checkout that includes a recurring price with a free trial creates the subscription in trialing state. The first invoice is $0, the card is saved, and the first charge happens when the trial ends.
By default the session uses the trial set on the price (Free trial for N days in the product catalog). When several line items carry a trial, the shortest one applies. A basket that also holds a one-time price (a setup fee, say) takes no trial by default, because a trial makes the whole first invoice $0 and that one-time line would never be charged — send free_trial_days explicitly if you want it anyway. Set free_trial_days to use a different length, or 0 to skip the trial for this session:
The response reports the trial the session will apply in free_trial_days (null when there is none). Adding a line item to the session works the trial out again with the same rules, so adding a setup fee removes a default trial. A free_trial_days you sent on create still applies. A trial needs at least one recurring price and is not available in setup mode. With cascade pricing only the first tier sets the trial length, because the fallback tiers are decline fallbacks. A trialing checkout stays $0 on whichever tier pays for it, as long as that tier has a recurring price. A tier with only one-time prices creates no subscription, so it is charged in full. A fallback tier that holds a one-time price also stops the default trial, for the same reason as a one-time line in the first tier.
Pass parameters to the subscription
Use params_for_sub to pass parameters to the subscription created by the checkout session. Currently supports custom_fields, which are validated against subscription custom field definitions (not checkout session ones).
After the checkout completes, these custom fields appear on the created subscription and are retrievable via the API with expand=custom_fields.
Configure processor route
Override the default processor route for card checkout:
Cascade pricing
Configure fallback pricing tiers for cascade pricing. If the primary tier fails, the system automatically tries the next tier:
- Always verify payments using the API or webhooks.
- Use webhooks for fulfillment instead of redirects.
- Handle expired sessions by creating a new session when needed.
- Pre-fill customer details to reduce friction and improve conversion.