API reference

Checkout

Knox answers these operations with the same requests and responses as Stripe's API. Authenticate with your secret key, Authorization: Bearer sk_test_..., from your server, and send form-encoded bodies. Test mode only: live processing is currently disabled.

Create a Checkout Session

POST/v1/checkout/sessions

Creates a Checkout Session object.

Body parameters

  • adaptive_pricingobject

    Settings for price localization with Adaptive Pricing.

    Show 1 child parameter
    • enabledboolean
  • after_expirationobject

    Configure actions after a Checkout Session has expired. You can't set this parameter if ui_mode is elements.

    Show 1 child parameter
    • recoveryobject
      Show 2 child parameters
      • enabledbooleanRequired
      • allow_promotion_codesboolean
  • allow_promotion_codesboolean

    Enables user redeemable promotion codes.

  • automatic_taxobject

    Settings for automatic tax lookup for this session and resulting payments, invoices, and subscriptions.

    Show 2 child parameters
    • enabledbooleanRequired
    • liabilityobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • account
        • self
      • accountstring
  • billing_address_collectionstring

    Specify whether Checkout should collect the customer's billing address. Defaults to auto.

    Possible values
    • auto
    • required
  • branding_settingsobject

    The branding settings for the Checkout Session. This parameter is not allowed if ui_mode is elements.

    Show 7 child parameters
    • background_colorstring
    • border_stylestring
      Possible values
      • pill
      • rectangular
      • rounded
    • button_colorstring
    • display_namestring
    • font_familystring
      Possible values
      • be_vietnam_pro
      • bitter
      • chakra_petch
      • default
      • hahmlet
      • inconsolata
      • inter
      • lato
      • lora
      • m_plus_1_code
      • montserrat
      • noto_sans
      • noto_sans_jp
      • noto_serif
      • nunito
      • open_sans
      • and 10 more
    • iconobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • file
        • url
      • filestring
      • urlstring
    • logoobject
      Show 3 child parameters
      • typestringRequired
        Possible values
        • file
        • url
      • filestring
      • urlstring
  • cancel_urlstring

    If set, Checkout displays a back button and customers will be directed to this URL if they decide to cancel payment and return to your website. This parameter is not allowed if ui_mode is embedded_page or elements.

  • client_reference_idstring

    A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems.

  • consent_collectionobject

    Configure fields for the Checkout Session to gather active consent from customers.

    Show 3 child parameters
    • payment_method_reuse_agreementobject
      Show 1 child parameter
      • positionstringRequired
        Possible values
        • auto
        • hidden
    • promotionsstring
      Possible values
      • auto
      • none
    • terms_of_servicestring
      Possible values
      • none
      • required
  • currencystring

    Three-letter ISO currency code, in lowercase. Must be a supported currency. Required in setup mode when payment_method_types is not set.

  • custom_fieldsarray of objects

    Collect additional information from your customer using custom fields. Up to 3 fields are supported. You can't set this parameter if ui_mode is custom.

    Show 7 child parameters
    • keystringRequired
    • labelobjectRequired
      Show 2 child parameters
      • customstringRequired
      • typestringRequired
        Possible values
        • custom
    • typestringRequired
      Possible values
      • dropdown
      • numeric
      • text
    • dropdownobject
      Show 2 child parameters
      • optionsarray of objectsRequired

        Child parameters are listed in the OpenAPI document.

      • default_valuestring
    • numericobject
      Show 3 child parameters
      • default_valuestring
      • maximum_lengthinteger
      • minimum_lengthinteger
    • optionalboolean
    • textobject
      Show 3 child parameters
      • default_valuestring
      • maximum_lengthinteger
      • minimum_lengthinteger
  • custom_textobject

    Display additional text for your customers using custom text. You can't set this parameter if ui_mode is custom.

    Show 4 child parameters
    • after_submitobject
      Show 1 child parameter
      • messagestringRequired
    • shipping_addressobject
      Show 1 child parameter
      • messagestringRequired
    • submitobject
      Show 1 child parameter
      • messagestringRequired
    • terms_of_service_acceptanceobject
      Show 1 child parameter
      • messagestringRequired
  • customerstring

    ID of an existing Customer, if one exists. In payment mode, the customer’s most recently saved card payment method will be used to prefill the email, name, card details, and billing address on the Checkout page. In subscription mode, the customer’s default payment method will be used if it’s a card, otherwise the most recently saved card will be used. A valid billing address, billing name and billing email are required on the payment method for Checkout to prefill the customer's card details. If the Customer already has a valid email set, the email will be prefilled and not editable in Checkout. If the Customer does not have a valid email, Checkout will set the email entered during the session on the Customer. If blank for Checkout Sessions in subscription mode or with customer_creation set as always in payment mode, Checkout will create a new Customer object based on information provided during the payment flow. You can set payment_intent_data.setup_future_usage to have Checkout automatically attach the payment method to the Customer you pass in for future reuse.

  • customer_accountstring

    ID of an existing Account, if one exists. Has the same behavior as customer.

  • customer_creationstring

    Configure whether a Checkout Session creates a Customer during Session confirmation. When a Customer is not created, you can still retrieve email, address, and other customer data entered in Checkout with customer_details. Sessions that don't create Customers instead are grouped by guest customers in the Dashboard. Promotion codes limited to first time customers will return invalid for these Sessions. Can only be set in payment and setup mode.

    Possible values
    • always
    • if_required
  • customer_emailstring

    If provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once a session is complete, use the customer field.

  • customer_updateobject

    Controls what fields on Customer can be updated by the Checkout Session. Can only be provided when customer is provided.

    Show 3 child parameters
    • addressstring
      Possible values
      • auto
      • never
    • namestring
      Possible values
      • auto
      • never
    • shippingstring
      Possible values
      • auto
      • never
  • discountsarray of objects

    The coupon or promotion code to apply to this Session. Currently, only up to one may be specified.

    Show 2 child parameters
    • couponstring
    • promotion_codestring
  • excluded_payment_method_typesarray of strings

    A list of the types of payment methods (e.g., card) that should be excluded from this Checkout Session. This should only be used when payment methods for this Checkout Session are managed through the Stripe Dashboard.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • expires_atinteger

    The Epoch time in seconds at which the Checkout Session will expire. It can be anywhere from 30 minutes to 24 hours after Checkout Session creation. By default, this value is 24 hours from creation.

  • integration_identifierstring

    The integration identifier for this Checkout Session. Multiple Checkout Sessions can have the same integration identifier.

  • invoice_creationobject

    Generate a post-purchase Invoice for one-time payments.

    Show 2 child parameters
    • enabledbooleanRequired
    • invoice_dataobject
      Show 7 child parameters
      • account_tax_idsarray of strings
      • custom_fieldsarray of objects

        Child parameters are listed in the OpenAPI document.

      • descriptionstring
      • footerstring
      • issuerobject

        Child parameters are listed in the OpenAPI document.

      • metadataobject
      • rendering_optionsobject

        Child parameters are listed in the OpenAPI document.

  • line_itemsarray of objects

    A list of items the customer is purchasing. Use this parameter to pass one-time or recurring Prices. The parameter is required for payment and subscription mode. For payment mode, there is a maximum of 100 line items, however it is recommended to consolidate line items if there are more than a few dozen. For subscription mode, there is a maximum of 20 line items with recurring Prices and 20 line items with one-time Prices. Line items with one-time Prices will be on the initial invoice only.

    Show 6 child parameters
    • adjustable_quantityobject
      Show 3 child parameters
      • enabledbooleanRequired
      • maximuminteger
      • minimuminteger
    • metadataobject
    • pricestring
    • price_dataobject
      Show 7 child parameters
      • currencystringRequired
      • productstring
      • product_dataobject

        Child parameters are listed in the OpenAPI document.

      • recurringobject

        Child parameters are listed in the OpenAPI document.

      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • quantityinteger
    • tax_ratesarray of strings
  • localestring

    The IETF language tag of the locale Checkout is displayed in. If blank or auto, the browser's locale is used.

    Possible values
    • auto
    • bg
    • cs
    • da
    • de
    • el
    • en
    • en-GB
    • es
    • es-419
    • et
    • fi
    • fil
    • fr
    • fr-CA
    • hr
    • and 25 more
  • managed_paymentsobject

    Settings for Managed Payments for this Checkout Session and resulting PaymentIntents, Invoices, and Subscriptions.

    Show 1 child parameter
    • enabledboolean
  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • modestring

    The mode of the Checkout Session. Pass subscription if the Checkout Session includes at least one recurring item.

    Possible values
    • payment
    • setup
    • subscription
  • name_collectionobject

    Controls name collection settings for the session. You can configure Checkout to collect your customers' business names, individual names, or both. Each name field can be either required or optional. If a Customer is created or provided, the names can be saved to the Customer object as well.

    Show 2 child parameters
    • businessobject
      Show 2 child parameters
      • enabledbooleanRequired
      • optionalboolean
    • individualobject
      Show 2 child parameters
      • enabledbooleanRequired
      • optionalboolean
  • optional_itemsarray of objects

    A list of optional items the customer can add to their order at checkout. Use this parameter to pass one-time or recurring Prices. There is a maximum of 10 optional items allowed on a Checkout Session, and the existing limits on the number of line items allowed on a Checkout Session apply to the combined number of line items and optional items. For payment mode, there is a maximum of 100 combined line items and optional items, however it is recommended to consolidate items if there are more than a few dozen. For subscription mode, there is a maximum of 20 line items and optional items with recurring Prices and 20 line items and optional items with one-time Prices. You can't set this parameter if ui_mode is custom.

    Show 3 child parameters
    • pricestringRequired
    • quantityintegerRequired
    • adjustable_quantityobject
      Show 3 child parameters
      • enabledbooleanRequired
      • maximuminteger
      • minimuminteger
  • origin_contextstring

    Where the user is coming from. This informs the optimizations that are applied to the session. You can't set this parameter if ui_mode is elements.

    Possible values
    • mobile_app
    • web
  • payment_intent_dataobject

    A subset of parameters to be passed to PaymentIntent creation for Checkout Sessions in payment mode.

    Show 12 child parameters
    • application_fee_amountinteger
    • capture_methodstring
      Possible values
      • automatic
      • automatic_async
      • manual
    • descriptionstring
    • metadataobject
    • on_behalf_ofstring
    • receipt_emailstring
    • setup_future_usagestring
      Possible values
      • off_session
      • on_session
    • shippingobject
      Show 5 child parameters
      • addressobjectRequired

        Child parameters are listed in the OpenAPI document.

      • namestringRequired
      • carrierstring
      • phonestring
      • tracking_numberstring
    • statement_descriptorstring
    • statement_descriptor_suffixstring
    • transfer_dataobject
      Show 2 child parameters
      • destinationstringRequired
      • amountinteger
    • transfer_groupstring
  • payment_method_collectionstring

    Specify whether Checkout should collect a payment method. When set to if_required, Checkout will not collect a payment method when the total due for the session is 0. This may occur if the Checkout Session includes a free trial or a discount. Can only be set in subscription mode. Defaults to always. If you'd like information on how to collect a payment method outside of Checkout, read the guide on configuring subscriptions with a free trial.

    Possible values
    • always
    • if_required
  • payment_method_configurationstring

    The ID of the payment method configuration to use with this Checkout session.

  • payment_method_dataobject

    This parameter allows you to set some attributes on the payment method created during a Checkout session.

    Show 1 child parameter
    • allow_redisplaystring
      Possible values
      • always
      • limited
      • unspecified
  • payment_method_optionsobject

    Payment-method-specific configuration.

    Show 49 child parameters
    • acss_debitobject
      Show 5 child parameters
      • currencystring
        Possible values
        • cad
        • usd
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • setup_future_usagestring
        Possible values
        • none
        • off_session
        • on_session
      • target_datestring
      • verification_methodstring
        Possible values
        • automatic
        • instant
        • microdeposits
    • affirmobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
    • afterpay_clearpayobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
    • alipayobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
    • almaobject
      Show 1 child parameter
      • capture_methodstring
        Possible values
        • manual
    • amazon_payobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
        • off_session
    • au_becs_debitobject
      Show 2 child parameters
      • setup_future_usagestring
        Possible values
        • none
      • target_datestring
    • bacs_debitobject
      Show 3 child parameters
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • setup_future_usagestring
        Possible values
        • none
        • off_session
        • on_session
      • target_datestring
    • bancontactobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
    • billieobject
      Show 1 child parameter
      • capture_methodstring
        Possible values
        • manual
    • boletoobject
      Show 2 child parameters
      • expires_after_daysinteger
      • setup_future_usagestring
        Possible values
        • none
        • off_session
        • on_session
    • cardobject
      Show 11 child parameters
      • capture_methodstring
        Possible values
        • manual
      • installmentsobject

        Child parameters are listed in the OpenAPI document.

      • request_extended_authorizationstring
        Possible values
        • if_available
        • never
      • request_incremental_authorizationstring
        Possible values
        • if_available
        • never
      • request_multicapturestring
        Possible values
        • if_available
        • never
      • request_overcapturestring
        Possible values
        • if_available
        • never
      • request_three_d_securestring
        Possible values
        • any
        • automatic
        • challenge
      • restrictionsobject

        Child parameters are listed in the OpenAPI document.

      • setup_future_usagestring
        Possible values
        • off_session
        • on_session
      • statement_descriptor_suffix_kanastring
      • statement_descriptor_suffix_kanjistring
    • cashappobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
        • off_session
        • on_session
    • cryptoobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
    • customer_balanceobject
      Show 3 child parameters
      • bank_transferobject

        Child parameters are listed in the OpenAPI document.

      • funding_typestring
        Possible values
        • bank_transfer
      • setup_future_usagestring
        Possible values
        • none
    • demo_payobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
        • off_session
    • epsobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
    • fpxobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
    • giropayobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
    • grabpayobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
    • idealobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
    • kakao_payobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
        • off_session
    • klarnaobject
      Show 3 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
      • subscriptionsarray of objects

        Child parameters are listed in the OpenAPI document.

    • konbiniobject
      Show 2 child parameters
      • expires_after_daysinteger
      • setup_future_usagestring
        Possible values
        • none
    • kr_cardobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
        • off_session
    • linkobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
        • off_session
    • mobilepayobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
    • multibancoobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
    • naver_payobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
        • off_session
    • oxxoobject
      Show 2 child parameters
      • expires_after_daysinteger
      • setup_future_usagestring
        Possible values
        • none
    • p24object
      Show 2 child parameters
      • setup_future_usagestring
        Possible values
        • none
      • tos_shown_and_acceptedboolean
    • pay_by_bankobject
    • paycoobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
    • paynowobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
    • paypalobject
      Show 5 child parameters
      • capture_methodstring
        Possible values
        • manual
      • preferred_localestring
        Possible values
        • cs-CZ
        • da-DK
        • de-AT
        • de-DE
        • de-LU
        • el-GR
        • en-GB
        • en-US
        • es-ES
        • fi-FI
        • fr-BE
        • fr-FR
        • fr-LU
        • hu-HU
        • it-IT
        • nl-BE
        • and 5 more
      • referencestring
      • risk_correlation_idstring
      • setup_future_usagestring
        Possible values
        • none
        • off_session
    • paytoobject
      Show 2 child parameters
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • setup_future_usagestring
        Possible values
        • none
        • off_session
    • pixobject
      Show 4 child parameters
      • amount_includes_iofstring
        Possible values
        • always
        • never
      • expires_after_secondsinteger
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • setup_future_usagestring
        Possible values
        • none
        • off_session
    • revolut_payobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
        • off_session
    • samsung_payobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
    • satispayobject
      Show 1 child parameter
      • capture_methodstring
        Possible values
        • manual
    • scalapayobject
      Show 1 child parameter
      • capture_methodstring
        Possible values
        • manual
    • sepa_debitobject
      Show 3 child parameters
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • setup_future_usagestring
        Possible values
        • none
        • off_session
        • on_session
      • target_datestring
    • sofortobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
    • sunbitobject
      Show 2 child parameters
      • capture_methodstring
        Possible values
        • manual
      • setup_future_usagestring
        Possible values
        • none
    • swishobject
      Show 1 child parameter
      • referencestring
    • twintobject
      Show 1 child parameter
      • setup_future_usagestring
        Possible values
        • none
        • off_session
    • upiobject
      Show 2 child parameters
      • mandate_optionsobject

        Child parameters are listed in the OpenAPI document.

      • setup_future_usagestring
        Possible values
        • none
        • off_session
        • on_session
    • us_bank_accountobject
      Show 4 child parameters
      • financial_connectionsobject

        Child parameters are listed in the OpenAPI document.

      • setup_future_usagestring
        Possible values
        • none
        • off_session
        • on_session
      • target_datestring
      • verification_methodstring
        Possible values
        • automatic
        • instant
    • wechat_payobject
      Show 3 child parameters
      • clientstringRequired
        Possible values
        • android
        • ios
        • web
      • app_idstring
      • setup_future_usagestring
        Possible values
        • none
  • payment_method_typesarray of strings

    A list of the types of payment methods (e.g., card) this Checkout Session can accept. You can omit this attribute to manage your payment methods from the Stripe Dashboard. See Dynamic Payment Methods for more details. Read more about the supported payment methods and their requirements in our payment method details guide. If multiple payment methods are passed, Checkout will dynamically reorder them to prioritize the most relevant payment methods based on the customer's location and other characteristics.

  • permissionsobject

    This property is used to set up permissions for various actions (e.g., update) on the CheckoutSession object. Can only be set when creating embedded or custom sessions. For specific permissions, please refer to their dedicated subsections, such as permissions.update_shipping_details.

    Show 1 child parameter
    • update_shipping_detailsstring
      Possible values
      • client_only
      • server_only
  • phone_number_collectionobject

    Controls phone number collection settings for the session. We recommend that you review your privacy policy and check with your legal contacts before using this feature. Learn more about collecting phone numbers with Checkout.

    Show 1 child parameter
    • enabledbooleanRequired
  • redirect_on_completionstring

    This parameter applies to ui_mode: embedded_page. Learn more about the redirect behavior of embedded sessions. Defaults to always.

    Possible values
    • always
    • if_required
    • never
  • return_urlstring

    The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site. This parameter is required if ui_mode is embedded_page or elements and redirect-based payment methods are enabled on the session.

  • saved_payment_method_optionsobject

    Controls saved payment method settings for the session. Only available in payment and subscription mode.

    Show 3 child parameters
    • allow_redisplay_filtersarray of strings
    • payment_method_removestring
      Possible values
      • disabled
      • enabled
    • payment_method_savestring
      Possible values
      • disabled
      • enabled
  • setup_intent_dataobject

    A subset of parameters to be passed to SetupIntent creation for Checkout Sessions in setup mode.

    Show 3 child parameters
    • descriptionstring
    • metadataobject
    • on_behalf_ofstring
  • shipping_address_collectionobject

    When set, provides configuration for Checkout to collect a shipping address from a customer.

    Show 1 child parameter
    • allowed_countriesarray of stringsRequired
  • shipping_optionsarray of objects

    The shipping rate options to apply to this Session. Up to a maximum of 5.

    Show 2 child parameters
    • shipping_ratestring
    • shipping_rate_dataobject
      Show 7 child parameters
      • display_namestringRequired
      • delivery_estimateobject

        Child parameters are listed in the OpenAPI document.

      • fixed_amountobject

        Child parameters are listed in the OpenAPI document.

      • metadataobject
      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • tax_codestring
      • typestring
        Possible values
        • fixed_amount
  • submit_typestring

    Describes the type of transaction being performed by Checkout in order to customize relevant text on the page, such as the submit button. submit_type can only be specified on Checkout Sessions in payment or subscription mode. If blank or auto, pay is used. You can't set this parameter if ui_mode is elements.

    Possible values
    • auto
    • book
    • donate
    • pay
    • subscribe
  • subscription_dataobject

    A subset of parameters to be passed to subscription creation for Checkout Sessions in subscription mode.

    Show 15 child parameters
    • application_fee_percentnumber
    • billing_cycle_anchorinteger
    • billing_cycle_anchor_configobject
      Show 5 child parameters
      • day_of_monthintegerRequired
      • hourinteger
      • minuteinteger
      • monthinteger
      • secondinteger
    • billing_modeobject
      Show 2 child parameters
      • typestringRequired
        Possible values
        • classic
        • flexible
      • flexibleobject

        Child parameters are listed in the OpenAPI document.

    • default_tax_ratesarray of strings
    • descriptionstring
    • invoice_settingsobject
      Show 1 child parameter
    • metadataobject
    • on_behalf_ofstring
    • pending_invoice_item_intervalobject
      Show 2 child parameters
      • intervalstringRequired
        Possible values
        • day
        • month
        • week
        • year
      • interval_countinteger
    • proration_behaviorstring
      Possible values
      • create_prorations
      • none
    • transfer_dataobject
      Show 2 child parameters
      • destinationstringRequired
      • amount_percentnumber
    • trial_endinteger
    • trial_period_daysinteger
    • trial_settingsobject
      Show 1 child parameter
  • success_urlstring

    The URL to which Stripe should send customers when payment or setup is complete. This parameter is not allowed if ui_mode is embedded_page or elements. If you'd like to use information from the successful Checkout Session on your page, read the guide on customizing your success page.

  • tax_id_collectionobject

    Controls tax ID collection during checkout.

    Show 2 child parameters
    • enabledbooleanRequired
    • requiredstring
      Possible values
      • if_supported
      • never
  • ui_modestring

    The UI mode of the Session. Defaults to hosted_page.

    Possible values
    • elements
    • embedded_page
    • hosted_page
  • wallet_optionsobject

    Wallet-specific configuration.

    Show 1 child parameter
    • linkobject
      Show 1 child parameter
      • displaystring
        Possible values
        • auto
        • never

Returns

The checkout.session object.

POST /v1/checkout/sessions
curl -X POST https://api.knoxapi.com/v1/checkout/sessions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "after_expiration": {
    "recovery": {
      "allow_promotion_codes": true,
      "enabled": true,
      "expires_at": null,
      "url": null
    }
  },
  "allow_promotion_codes": null,
  "amount_subtotal": null,
  "amount_total": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "status": null,
    "provider": null
  },
  "billing_address_collection": null,
  "cancel_url": "https://example.com/cancel",
  "client_reference_id": null,
  "client_secret": null,
  "consent": {
    "promotions": null,
    "terms_of_service": null
  },
  "consent_collection": {
    "payment_method_reuse_agreement": {
      "position": "hidden"
    },
    "promotions": null,
    "terms_of_service": null
  },
  "created": 1234567890,
  "currency": null,
  "custom_fields": [],
  "custom_text": {
    "after_submit": {
      "message": "message"
    },
    "shipping_address": {
      "message": "message"
    },
    "submit": {
      "message": "message"
    },
    "terms_of_service_acceptance": {
      "message": "message"
    }
  },
  "customer": null,
  "customer_creation": null,
  "customer_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": "[email protected]",
    "name": null,
    "phone": null,
    "tax_exempt": "none",
    "tax_ids": null,
    "business_name": null,
    "individual_name": null
  },
  "customer_email": null,
  "expires_at": 1234567890,
  "id": "cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY",
  "invoice": null,
  "invoice_creation": {
    "enabled": true,
    "invoice_data": {
      "account_tax_ids": null,
      "custom_fields": null,
      "description": null,
      "footer": null,
      "issuer": {
        "type": "account"
      },
      "metadata": null,
      "rendering_options": {
        "amount_tax_display": null,
        "template": null
      }
    }
  },
  "livemode": false,
  "locale": null,
  "metadata": {},
  "mode": "payment",
  "object": "checkout.session",
  "payment_intent": "pi_1PgafyB7WZ01zgkWSjxsAJo3",
  "payment_link": null,
  "payment_method_collection": null,
  "payment_method_configuration_details": {
    "id": "obj_123",
    "parent": null
  },
  "payment_method_options": {},
  "payment_method_types": [
    "card"
  ],
  "payment_status": "unpaid",
  "phone_number_collection": {
    "enabled": false
  },
  "recovered_from": null,
  "saved_payment_method_options": {
    "allow_redisplay_filters": null,
    "payment_method_remove": null,
    "payment_method_save": null
  },
  "setup_intent": null,
  "shipping_address_collection": {
    "allowed_countries": [
      "SC"
    ]
  },
  "shipping_cost": {
    "amount_subtotal": 1555417355,
    "amount_tax": 1424534716,
    "amount_total": 1117121693,
    "shipping_rate": null
  },
  "shipping_options": [],
  "status": "open",
  "submit_type": null,
  "subscription": null,
  "success_url": "https://example.com/success",
  "total_details": {
    "amount_discount": 406046392,
    "amount_shipping": null,
    "amount_tax": 1424534716
  },
  "ui_mode": null,
  "url": "https://checkout.stripe.com/pay/c/cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY",
  "adaptive_pricing": {
    "enabled": true
  },
  "discounts": null,
  "collected_information": {
    "shipping_details": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "name": "name"
    },
    "business_name": null,
    "individual_name": null
  },
  "permissions": {
    "update_shipping_details": null
  },
  "wallet_options": {},
  "origin_context": null,
  "currency_conversion": {
    "amount_subtotal": 1555417355,
    "amount_total": 1117121693,
    "fx_rate": "291452898",
    "source_currency": "usd"
  },
  "customer_account": null,
  "integration_identifier": null,
  "managed_payments": {
    "enabled": true
  }
}

List all Checkout Sessions

GET/v1/checkout/sessions

Returns a list of Checkout Sessions.

Query parameters

  • createdobject | integer

    Only return Checkout Sessions that were created during the given date interval.

    Show 4 child parameters
    • gtinteger
    • gteinteger
    • ltinteger
    • lteinteger
  • customerstring

    Only return the Checkout Sessions for the Customer specified.

  • customer_accountstring

    Only return the Checkout Sessions for the Account specified.

  • customer_detailsobject

    Only return the Checkout Sessions for the Customer details specified.

    Show 1 child parameter
    • emailstringRequired
  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • payment_intentstring

    Only return the Checkout Session for the PaymentIntent specified.

  • payment_linkstring

    Only return the Checkout Sessions for the Payment Link specified.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

  • statusstring

    Only return the Checkout Sessions matching the given status.

    Possible values
    • complete
    • expired
    • open
  • subscriptionstring

    Only return the Checkout Session for the subscription specified.

Returns

A list of checkout.session objects.

GET /v1/checkout/sessions
curl -G https://api.knoxapi.com/v1/checkout/sessions \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/checkout/sessions",
  "has_more": false,
  "data": [
    {
      "after_expiration": {
        "recovery": {
          "allow_promotion_codes": true,
          "enabled": true,
          "expires_at": null,
          "url": null
        }
      },
      "allow_promotion_codes": null,
      "amount_subtotal": null,
      "amount_total": null,
      "automatic_tax": {
        "enabled": false,
        "liability": {
          "type": "account"
        },
        "status": null,
        "provider": null
      },
      "billing_address_collection": null,
      "cancel_url": "https://example.com/cancel",
      "client_reference_id": null,
      "client_secret": null,
      "consent": {
        "promotions": null,
        "terms_of_service": null
      },
      "consent_collection": {
        "payment_method_reuse_agreement": {
          "position": "hidden"
        },
        "promotions": null,
        "terms_of_service": null
      },
      "created": 1234567890,
      "currency": null,
      "custom_fields": [],
      "custom_text": {
        "after_submit": {
          "message": "message"
        },
        "shipping_address": {
          "message": "message"
        },
        "submit": {
          "message": "message"
        },
        "terms_of_service_acceptance": {
          "message": "message"
        }
      },
      "customer": null,
      "customer_creation": null,
      "customer_details": {
        "address": {
          "city": null,
          "country": null,
          "line1": null,
          "line2": null,
          "postal_code": null,
          "state": null
        },
        "email": "[email protected]",
        "name": null,
        "phone": null,
        "tax_exempt": "none",
        "tax_ids": null,
        "business_name": null,
        "individual_name": null
      },
      "customer_email": null,
      "expires_at": 1234567890,
      "id": "cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY",
      "invoice": null,
      "invoice_creation": {
        "enabled": true,
        "invoice_data": {
          "account_tax_ids": null,
          "custom_fields": null,
          "description": null,
          "footer": null,
          "issuer": {
            "type": "account"
          },
          "metadata": null,
          "rendering_options": {
            "amount_tax_display": null,
            "template": null
          }
        }
      },
      "livemode": false,
      "locale": null,
      "metadata": {},
      "mode": "payment",
      "object": "checkout.session",
      "payment_intent": "pi_1PgafyB7WZ01zgkWSjxsAJo3",
      "payment_link": null,
      "payment_method_collection": null,
      "payment_method_configuration_details": {
        "id": "obj_123",
        "parent": null
      },
      "payment_method_options": {},
      "payment_method_types": [
        "card"
      ],
      "payment_status": "unpaid",
      "phone_number_collection": {
        "enabled": false
      },
      "recovered_from": null,
      "saved_payment_method_options": {
        "allow_redisplay_filters": null,
        "payment_method_remove": null,
        "payment_method_save": null
      },
      "setup_intent": null,
      "shipping_address_collection": {
        "allowed_countries": [
          "SC"
        ]
      },
      "shipping_cost": {
        "amount_subtotal": 1555417355,
        "amount_tax": 1424534716,
        "amount_total": 1117121693,
        "shipping_rate": null
      },
      "shipping_options": [],
      "status": "open",
      "submit_type": null,
      "subscription": null,
      "success_url": "https://example.com/success",
      "total_details": {
        "amount_discount": 406046392,
        "amount_shipping": null,
        "amount_tax": 1424534716
      },
      "ui_mode": null,
      "url": "https://checkout.stripe.com/pay/c/cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY",
      "adaptive_pricing": {
        "enabled": true
      },
      "discounts": null,
      "collected_information": {
        "shipping_details": {
          "address": {
            "city": null,
            "country": null,
            "line1": null,
            "line2": null,
            "postal_code": null,
            "state": null
          },
          "name": "name"
        },
        "business_name": null,
        "individual_name": null
      },
      "permissions": {
        "update_shipping_details": null
      },
      "wallet_options": {},
      "origin_context": null,
      "currency_conversion": {
        "amount_subtotal": 1555417355,
        "amount_total": 1117121693,
        "fx_rate": "291452898",
        "source_currency": "usd"
      },
      "customer_account": null,
      "integration_identifier": null,
      "managed_payments": {
        "enabled": true
      }
    }
  ]
}

Update a Checkout Session

POST/v1/checkout/sessions/{session}

Updates a Checkout Session object. Related guide: Dynamically update a Checkout Session

Path parameters

  • sessionstringRequired

Body parameters

  • collected_informationobject

    Information about the customer collected within the Checkout Session. Can only be set when updating embedded or custom sessions.

    Show 1 child parameter
    • shipping_detailsobject
      Show 2 child parameters
      • addressobjectRequired

        Child parameters are listed in the OpenAPI document.

      • namestringRequired
  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • line_itemsarray of objects

    A list of items the customer is purchasing. When updating line items, you must retransmit the entire array of line items. To retain an existing line item, specify its id. To update an existing line item, specify its id along with the new values of the fields to update. To add a new line item, specify one of price or price_data and quantity. To remove an existing line item, omit the line item's ID from the retransmitted array. To reorder a line item, specify it at the desired position in the retransmitted array.

    Show 7 child parameters
    • adjustable_quantityobject
      Show 3 child parameters
      • enabledbooleanRequired
      • maximuminteger
      • minimuminteger
    • idstring
    • metadataobject
    • pricestring
    • price_dataobject
      Show 7 child parameters
      • currencystringRequired
      • productstring
      • product_dataobject

        Child parameters are listed in the OpenAPI document.

      • recurringobject

        Child parameters are listed in the OpenAPI document.

      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • unit_amountinteger
      • unit_amount_decimalstring
    • quantityinteger
    • tax_ratesarray of strings
  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • shipping_optionsarray of objects

    The shipping rate options to apply to this Session. Up to a maximum of 5.

    Show 2 child parameters
    • shipping_ratestring
    • shipping_rate_dataobject
      Show 7 child parameters
      • display_namestringRequired
      • delivery_estimateobject

        Child parameters are listed in the OpenAPI document.

      • fixed_amountobject

        Child parameters are listed in the OpenAPI document.

      • metadataobject
      • tax_behaviorstring
        Possible values
        • exclusive
        • inclusive
        • unspecified
      • tax_codestring
      • typestring
        Possible values
        • fixed_amount

Returns

The checkout.session object.

POST /v1/checkout/sessions/{session}
curl https://api.knoxapi.com/v1/checkout/sessions/cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  -d "metadata[order_id]=6735"
Response
{
  "after_expiration": {
    "recovery": {
      "allow_promotion_codes": true,
      "enabled": true,
      "expires_at": null,
      "url": null
    }
  },
  "allow_promotion_codes": null,
  "amount_subtotal": null,
  "amount_total": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "status": null,
    "provider": null
  },
  "billing_address_collection": null,
  "cancel_url": "https://example.com/cancel",
  "client_reference_id": null,
  "client_secret": null,
  "consent": {
    "promotions": null,
    "terms_of_service": null
  },
  "consent_collection": {
    "payment_method_reuse_agreement": {
      "position": "hidden"
    },
    "promotions": null,
    "terms_of_service": null
  },
  "created": 1234567890,
  "currency": null,
  "custom_fields": [],
  "custom_text": {
    "after_submit": {
      "message": "message"
    },
    "shipping_address": {
      "message": "message"
    },
    "submit": {
      "message": "message"
    },
    "terms_of_service_acceptance": {
      "message": "message"
    }
  },
  "customer": null,
  "customer_creation": null,
  "customer_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": "[email protected]",
    "name": null,
    "phone": null,
    "tax_exempt": "none",
    "tax_ids": null,
    "business_name": null,
    "individual_name": null
  },
  "customer_email": null,
  "expires_at": 1234567890,
  "id": "cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY",
  "invoice": null,
  "invoice_creation": {
    "enabled": true,
    "invoice_data": {
      "account_tax_ids": null,
      "custom_fields": null,
      "description": null,
      "footer": null,
      "issuer": {
        "type": "account"
      },
      "metadata": null,
      "rendering_options": {
        "amount_tax_display": null,
        "template": null
      }
    }
  },
  "livemode": false,
  "locale": null,
  "metadata": {},
  "mode": "payment",
  "object": "checkout.session",
  "payment_intent": "pi_1PgafyB7WZ01zgkWSjxsAJo3",
  "payment_link": null,
  "payment_method_collection": null,
  "payment_method_configuration_details": {
    "id": "obj_123",
    "parent": null
  },
  "payment_method_options": {},
  "payment_method_types": [
    "card"
  ],
  "payment_status": "unpaid",
  "phone_number_collection": {
    "enabled": false
  },
  "recovered_from": null,
  "saved_payment_method_options": {
    "allow_redisplay_filters": null,
    "payment_method_remove": null,
    "payment_method_save": null
  },
  "setup_intent": null,
  "shipping_address_collection": {
    "allowed_countries": [
      "SC"
    ]
  },
  "shipping_cost": {
    "amount_subtotal": 1555417355,
    "amount_tax": 1424534716,
    "amount_total": 1117121693,
    "shipping_rate": null
  },
  "shipping_options": [],
  "status": "open",
  "submit_type": null,
  "subscription": null,
  "success_url": "https://example.com/success",
  "total_details": {
    "amount_discount": 406046392,
    "amount_shipping": null,
    "amount_tax": 1424534716
  },
  "ui_mode": null,
  "url": "https://checkout.stripe.com/pay/c/cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY",
  "adaptive_pricing": {
    "enabled": true
  },
  "discounts": null,
  "collected_information": {
    "shipping_details": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "name": "name"
    },
    "business_name": null,
    "individual_name": null
  },
  "permissions": {
    "update_shipping_details": null
  },
  "wallet_options": {},
  "origin_context": null,
  "currency_conversion": {
    "amount_subtotal": 1555417355,
    "amount_total": 1117121693,
    "fx_rate": "291452898",
    "source_currency": "usd"
  },
  "customer_account": null,
  "integration_identifier": null,
  "managed_payments": {
    "enabled": true
  }
}

Retrieve a Checkout Session

GET/v1/checkout/sessions/{session}

Retrieves a Checkout Session object.

Path parameters

  • sessionstringRequired

Query parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The checkout.session object.

GET /v1/checkout/sessions/{session}
curl https://api.knoxapi.com/v1/checkout/sessions/cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "after_expiration": {
    "recovery": {
      "allow_promotion_codes": true,
      "enabled": true,
      "expires_at": null,
      "url": null
    }
  },
  "allow_promotion_codes": null,
  "amount_subtotal": null,
  "amount_total": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "status": null,
    "provider": null
  },
  "billing_address_collection": null,
  "cancel_url": "https://example.com/cancel",
  "client_reference_id": null,
  "client_secret": null,
  "consent": {
    "promotions": null,
    "terms_of_service": null
  },
  "consent_collection": {
    "payment_method_reuse_agreement": {
      "position": "hidden"
    },
    "promotions": null,
    "terms_of_service": null
  },
  "created": 1234567890,
  "currency": null,
  "custom_fields": [],
  "custom_text": {
    "after_submit": {
      "message": "message"
    },
    "shipping_address": {
      "message": "message"
    },
    "submit": {
      "message": "message"
    },
    "terms_of_service_acceptance": {
      "message": "message"
    }
  },
  "customer": null,
  "customer_creation": null,
  "customer_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": "[email protected]",
    "name": null,
    "phone": null,
    "tax_exempt": "none",
    "tax_ids": null,
    "business_name": null,
    "individual_name": null
  },
  "customer_email": null,
  "expires_at": 1234567890,
  "id": "cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY",
  "invoice": null,
  "invoice_creation": {
    "enabled": true,
    "invoice_data": {
      "account_tax_ids": null,
      "custom_fields": null,
      "description": null,
      "footer": null,
      "issuer": {
        "type": "account"
      },
      "metadata": null,
      "rendering_options": {
        "amount_tax_display": null,
        "template": null
      }
    }
  },
  "livemode": false,
  "locale": null,
  "metadata": {},
  "mode": "payment",
  "object": "checkout.session",
  "payment_intent": "pi_1PgafyB7WZ01zgkWSjxsAJo3",
  "payment_link": null,
  "payment_method_collection": null,
  "payment_method_configuration_details": {
    "id": "obj_123",
    "parent": null
  },
  "payment_method_options": {},
  "payment_method_types": [
    "card"
  ],
  "payment_status": "unpaid",
  "phone_number_collection": {
    "enabled": false
  },
  "recovered_from": null,
  "saved_payment_method_options": {
    "allow_redisplay_filters": null,
    "payment_method_remove": null,
    "payment_method_save": null
  },
  "setup_intent": null,
  "shipping_address_collection": {
    "allowed_countries": [
      "SC"
    ]
  },
  "shipping_cost": {
    "amount_subtotal": 1555417355,
    "amount_tax": 1424534716,
    "amount_total": 1117121693,
    "shipping_rate": null
  },
  "shipping_options": [],
  "status": "open",
  "submit_type": null,
  "subscription": null,
  "success_url": "https://example.com/success",
  "total_details": {
    "amount_discount": 406046392,
    "amount_shipping": null,
    "amount_tax": 1424534716
  },
  "ui_mode": null,
  "url": "https://checkout.stripe.com/pay/c/cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY",
  "adaptive_pricing": {
    "enabled": true
  },
  "discounts": null,
  "collected_information": {
    "shipping_details": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "name": "name"
    },
    "business_name": null,
    "individual_name": null
  },
  "permissions": {
    "update_shipping_details": null
  },
  "wallet_options": {},
  "origin_context": null,
  "currency_conversion": {
    "amount_subtotal": 1555417355,
    "amount_total": 1117121693,
    "fx_rate": "291452898",
    "source_currency": "usd"
  },
  "customer_account": null,
  "integration_identifier": null,
  "managed_payments": {
    "enabled": true
  }
}

Expire a Checkout Session

POST/v1/checkout/sessions/{session}/expire

A Checkout Session can be expired when it is in one of these statuses: open After it expires, a customer can’t complete a Checkout Session and customers loading the Checkout Session see a message saying the Checkout Session is expired.

Path parameters

  • sessionstringRequired

Body parameters

  • expandarray of strings

    Specifies which fields in the response should be expanded.

Returns

The checkout.session object.

POST /v1/checkout/sessions/{session}/expire
curl -X POST https://api.knoxapi.com/v1/checkout/sessions/cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY/expire \
  -H "Authorization: Bearer $KNOX_SECRET_KEY"
Response
{
  "after_expiration": {
    "recovery": {
      "allow_promotion_codes": true,
      "enabled": true,
      "expires_at": null,
      "url": null
    }
  },
  "allow_promotion_codes": null,
  "amount_subtotal": null,
  "amount_total": null,
  "automatic_tax": {
    "enabled": false,
    "liability": {
      "type": "account"
    },
    "status": null,
    "provider": null
  },
  "billing_address_collection": null,
  "cancel_url": "https://example.com/cancel",
  "client_reference_id": null,
  "client_secret": null,
  "consent": {
    "promotions": null,
    "terms_of_service": null
  },
  "consent_collection": {
    "payment_method_reuse_agreement": {
      "position": "hidden"
    },
    "promotions": null,
    "terms_of_service": null
  },
  "created": 1234567890,
  "currency": null,
  "custom_fields": [],
  "custom_text": {
    "after_submit": {
      "message": "message"
    },
    "shipping_address": {
      "message": "message"
    },
    "submit": {
      "message": "message"
    },
    "terms_of_service_acceptance": {
      "message": "message"
    }
  },
  "customer": null,
  "customer_creation": null,
  "customer_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,
      "state": null
    },
    "email": "[email protected]",
    "name": null,
    "phone": null,
    "tax_exempt": "none",
    "tax_ids": null,
    "business_name": null,
    "individual_name": null
  },
  "customer_email": null,
  "expires_at": 1234567890,
  "id": "cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY",
  "invoice": null,
  "invoice_creation": {
    "enabled": true,
    "invoice_data": {
      "account_tax_ids": null,
      "custom_fields": null,
      "description": null,
      "footer": null,
      "issuer": {
        "type": "account"
      },
      "metadata": null,
      "rendering_options": {
        "amount_tax_display": null,
        "template": null
      }
    }
  },
  "livemode": false,
  "locale": null,
  "metadata": {},
  "mode": "payment",
  "object": "checkout.session",
  "payment_intent": "pi_1PgafyB7WZ01zgkWSjxsAJo3",
  "payment_link": null,
  "payment_method_collection": null,
  "payment_method_configuration_details": {
    "id": "obj_123",
    "parent": null
  },
  "payment_method_options": {},
  "payment_method_types": [
    "card"
  ],
  "payment_status": "unpaid",
  "phone_number_collection": {
    "enabled": false
  },
  "recovered_from": null,
  "saved_payment_method_options": {
    "allow_redisplay_filters": null,
    "payment_method_remove": null,
    "payment_method_save": null
  },
  "setup_intent": null,
  "shipping_address_collection": {
    "allowed_countries": [
      "SC"
    ]
  },
  "shipping_cost": {
    "amount_subtotal": 1555417355,
    "amount_tax": 1424534716,
    "amount_total": 1117121693,
    "shipping_rate": null
  },
  "shipping_options": [],
  "status": "open",
  "submit_type": null,
  "subscription": null,
  "success_url": "https://example.com/success",
  "total_details": {
    "amount_discount": 406046392,
    "amount_shipping": null,
    "amount_tax": 1424534716
  },
  "ui_mode": null,
  "url": "https://checkout.stripe.com/pay/c/cs_test_a1YS1URlnyQCN5fUUduORoQ7Pw41PJqDWkIVQCpJPqkfIhd6tVY8XB1OLY",
  "adaptive_pricing": {
    "enabled": true
  },
  "discounts": null,
  "collected_information": {
    "shipping_details": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "name": "name"
    },
    "business_name": null,
    "individual_name": null
  },
  "permissions": {
    "update_shipping_details": null
  },
  "wallet_options": {},
  "origin_context": null,
  "currency_conversion": {
    "amount_subtotal": 1555417355,
    "amount_total": 1117121693,
    "fx_rate": "291452898",
    "source_currency": "usd"
  },
  "customer_account": null,
  "integration_identifier": null,
  "managed_payments": {
    "enabled": true
  }
}

Retrieve a Checkout Session's line items

GET/v1/checkout/sessions/{session}/line_items

When retrieving a Checkout Session, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Path parameters

  • sessionstringRequired

Query parameters

  • ending_beforestring

    A cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.

  • expandarray of strings

    Specifies which fields in the response should be expanded.

  • limitinteger

    A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

  • starting_afterstring

    A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.

Returns

A list of item objects.

GET /v1/checkout/sessions/{session}/line_items
curl -G https://api.knoxapi.com/v1/checkout/sessions/session_123/line_items \
  -H "Authorization: Bearer $KNOX_SECRET_KEY" \
  --data-urlencode limit=3
Response
{
  "object": "list",
  "url": "/v1/checkout/sessions",
  "has_more": false,
  "data": [
    {
      "amount_discount": 0,
      "amount_subtotal": 0,
      "amount_tax": 0,
      "amount_total": 0,
      "currency": "usd",
      "description": "T-shirt",
      "id": "li_1Pgc73B7WZ01zgkWx8kcmZPK",
      "object": "item",
      "price": {
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1721948530,
        "currency": "usd",
        "custom_unit_amount": {
          "maximum": null,
          "minimum": null,
          "preset": null
        },
        "id": "price_1PgafmB7WZ01zgkW02Hf9z6c",
        "livemode": false,
        "lookup_key": null,
        "metadata": {},
        "nickname": null,
        "object": "price",
        "product": "prod_QXg1hqf4jFNsqG",
        "recurring": {
          "interval": "month",
          "interval_count": 797691627,
          "meter": null,
          "trial_period_days": null,
          "usage_type": "licensed"
        },
        "tax_behavior": "unspecified",
        "tiers_mode": null,
        "transform_quantity": {
          "divide_by": 1592560163,
          "round": "down"
        },
        "type": "one_time",
        "unit_amount": 1000,
        "unit_amount_decimal": "1000"
      },
      "quantity": 1,
      "metadata": null,
      "adjustable_quantity": {
        "enabled": true,
        "maximum": null,
        "minimum": null
      }
    }
  ]
}

Operations and schemas come from the pinned Stripe OpenAPI specification (MIT); response examples from its fixtures. Nested object definitions and enums are in the complete specification.