---
title: "Create a new session"
method: POST
path: "/v2/session"
tags: ["Session"]
---

# Create a new session

`POST /v2/session`

Initiate a Sezzle session with shopper order details, redirect links, and capture and tokenization settings.
A session must carry an order, tokenize a customer, or both. Omit the order and set customer.tokenize to true for standalone tokenization, which returns tokenize.approval_url instead of an order.

## Request body

- SessionRequest
  - `cancel_url` object — The HTTP request information used to redirect the customer in the case of a cancellation. Required for sessions that include an order and use redirect checkout. Optional for standalone tokenization sessions, which have no order to cancel — supply it only if you want a separate destination for customers who decline.
    - `href` string, required — The URL used when redirecting a customer upon order cancellation
    - `method` string — The HTTP request method used when redirecting a customer. Currently only the GET method is supported. If omitted, will default to GET.
  - `complete_url` object, required — The HTTP request information used to redirect the customer upon completion of the session. Required for sessions that include an order and use redirect checkout, and for any session that tokenizes a customer — including standalone tokenization, where it is the destination the customer returns to after approving.
    - `href` string, required — The URL used when redirecting a customer upon order completion
    - `method` string — The HTTP request method used when redirecting a customer. Currently only the GET method is supported. If omitted, will default to GET.
  - `customer` object — Customer details for this session. To optimize checkout and boost conversion, it is recommended to include as much customer information as possible.
    - `first_name` string — The customer's first name
    - `last_name` string — The customer's last name
    - `email` string — The customer's email address
    - `phone` string — The customer's phone number
    - `billing_address` AddressV2
      - `name` string — The name on the address
      - `street` string — The street and number of the address
      - `street2` string — The apt or unit
      - `city` string — The city
      - `state` string — The 2 character state code
      - `postal_code` string — The postal delivery code
      - `country_code` string — The 2 character country code
      - `phone` string — The phone number at the delivery location
    - `shipping_address` AddressV2
      - `name` string — The name on the address
      - `street` string — The street and number of the address
      - `street2` string — The apt or unit
      - `city` string — The city
      - `state` string — The 2 character state code
      - `postal_code` string — The postal delivery code
      - `country_code` string — The 2 character country code
      - `phone` string — The phone number at the delivery location
    - `dob` string, YYYY-MM-DD — The customer's date of birth in YYYY-MM-DD format (parameter is input only)
    - `tokenize` boolean — Tokenizing a customer allows you to authorize future transactions on their behalf. If omitted, will default to false. To create an order and tokenize a customer in a single session, set customer.tokenize to true and provide an order object. The user will be prompted to accept tokenization during checkout. To tokenize a customer without a purchase (standalone tokenization), set customer.tokenize to true and omit the order object. The response returns tokenize.approval_url to redirect the customer to. Standalone tokenization is enabled per merchant — contact your account manager.
    - `recurring` boolean — Indicates whether the tokenization is part of a recurring subscription. true - The token is associated with a subscription and will be reused for future charges. false - The token is for a one-time use, such as Pre-order or Single Tokenization.
    - `recurring_metadata` object
      - `name` string — The name of the subscription plan associated with the recurring tokenization. This field provides context for the recurring charge agreement and can be shown in checkout
  - `order` object — Order ID, amount, and capture intent. Order details optional.
    - `intent` 'AUTH' | 'CAPTURE', required — - Use CAPTURE if payment should be captured immediately upon shopper authorization - Use AUTH if there is any post-authorization validation needed prior to capture, such as inventory validation or regulatory requirements, or if merchant policy is to charge the payment method at time of shipment - Submit a capture request via the API or your Merchant Dashboard before the authorization expires. - The authorization expiration window can be set from 30 minutes up to 7 days in your Merchant Dashboard Settings. - If not specified, the value will default to CAPTURE
    - `reference_id` string, required — The checkout or cart ID from the merchant, currently used for tracking only (must contain only alphanumeric characters, dashes (-), and underscores (_))
    - `order_amount` Price, required
      - `amount_in_cents` integer, required — The amount in cents
      - `currency` string, required — The 3 character currency code as defined by ISO 4217
    - `description` string, required — Your description for this order
    - `metadata` object — Object for any custom data you want to submit with the checkout. You are not limited to the key-value pairs shown in the example, and you may use any key-value pairs you like
      - `any` string — Custom metadata field
    - `items` LineItem[] — The items being purchased
      - `name` string — The name of the item
      - `sku` string — The sku identifier
      - `quantity` integer — The quantity purchased
      - `price` Price
        - `amount_in_cents` integer, required — The amount in cents
        - `currency` string, required — The 3 character currency code as defined by ISO 4217
      - `category_path` string — The category path where the product is located. Use `>` only as the category delimiter, not as part of a product or category name. Example: Camping Gear & Supplies > Tents & Shelters.
      - `brand` string — The products brand name as customers would recognize. Examples: Nike, Kelty, Brooks, Carhartt, Columbia
      - `image_url` string — The fully qualified URL that shows the image
      - `product_url` string — The fully qualified URL that links directly to the product being purchased
      - `global_trade_item_number` string — The products Global Trade Item Number (GTIN). Common types include UPC, ISBN, EAN. Exclude dashes and spaces.
      - `manufacturer_part_number` string — The products Manufacturer Part Number (MPN) which together with brand can uniquely identify a product.
    - `requires_shipping_info` boolean — Flag to indicate if you would like us to collect shipping information for this checkout from the customer. If omitted, defaults to false. Required for express checkout flow if express_checkout_type is single-step or multi-step.
    - `discounts` Discount[] — The discounts applied to this order. Must be included in total
      - `name` string — The description of the discount
      - `amount` Price
        - `amount_in_cents` integer, required — The amount in cents
        - `currency` string, required — The 3 character currency code as defined by ISO 4217
    - `tax_amount` Price
      - `amount_in_cents` integer, required — The amount in cents
      - `currency` string, required — The 3 character currency code as defined by ISO 4217
    - `shipping_amount` Price
      - `amount_in_cents` integer, required — The amount in cents
      - `currency` string, required — The 3 character currency code as defined by ISO 4217
    - `checkout_mode` 'iframe' | 'popup' | 'redirect' — The mode for the order checkout. Defaults to redirect if not provided. If iframe or popup is provided, then the cancel and complete URLs must include the origin of the parent window.
    - `send_checkout_url` Notification
      - `to_sms_phone` string — The SMS phone number of the notification
      - `to_email` string — The email address of the notification
      - `language` 'en' | 'fr-CA' — The 2-character ISO 639 langauge code of the notification. Acceptable values are en and fr-CA. Will default to English if not provided.
    - `locale` 'en-US' | 'en-CA' | 'fr-CA' — Localizes the checkout. Accepted values are en-US (English, United States), en-CA (English, Canada) and fr-CA (French, Canada). Defaults to en-US if not provided.
    - `checkout_financing_options` InstallmentPlan[] — The financing options of the checkout. Only one option can be included.
  - `express_checkout_type` 'single-step' | 'multi-step' | 'no-shipping' — - single-step: only one shipping method exists, or only use default shipping method for Sezzle express checkout flow - multi-step: allow the user to select from merchant-supported shipping methods - no-shipping: purchase contains no shippable items and shopper does not have option to select, such as digital download or buy online pick up in store (BOPIS).

## Response `201`

Successful Operation

- object
  - `uuid` string — The unique identifier for this response
  - `links` Link[] — Available API links prefilled with UUID with accompanying method
    - `href` string, required — The fully qualified URL for the API endpoint
    - `rel` 'self' | 'capture' | 'checkout' | 'create' | 'customer' | 'list' | 'order' | 'preapprove' | 'refund' | 'release' | 'session' — The relationship type indicating the purpose of this link (e.g., 'self' for the current resource, 'create' for creating a new resource, 'list' for listing resources)
    - `method` 'GET' | 'POST' | 'PATCH' | 'DELETE' — The HTTP method to use when calling this API endpoint
  - `order` SessionOrderResponse
    - `uuid` string — Unique identifier for this order
    - `intent` 'AUTH' | 'CAPTURE' — - Use CAPTURE if payment should be captured immediately upon shopper authorization - Use AUTH if there is any post-authorization validation needed prior to capture, such as inventory validation or regulatory requirements, or if merchant policy is to charge the payment method at time of shipment - Submit a capture request via the API or your Merchant Dashboard before the authorization expires. - The authorization expiration window can be set from 30 minutes up to 7 days in your Merchant Dashboard Settings. - If not specified, the value will default to CAPTURE
    - `checkout_url` string — The URL to which the shopper should be directed to complete their order with Sezzle
    - `links` Link[] — Available API links prefilled with UUID with accompanying method
      - `href` string, required — The fully qualified URL for the API endpoint
      - `rel` 'self' | 'capture' | 'checkout' | 'create' | 'customer' | 'list' | 'order' | 'preapprove' | 'refund' | 'release' | 'session' — The relationship type indicating the purpose of this link (e.g., 'self' for the current resource, 'create' for creating a new resource, 'list' for listing resources)
      - `method` 'GET' | 'POST' | 'PATCH' | 'DELETE' — The HTTP method to use when calling this API endpoint
  - `tokenize` SessionTokenResponse
    - `token` string — This token represents the merchant request to tokenize a customer. This token can only be used one time. Once a user accepts/denies tokenization, this token and its approval URL will be obsolete.
    - `expiration` string, date-time — The expiration of the request token in ISO 8601 date/time format.
    - `approval_url` string — The URL for the user to accept tokenization. This URL does not create an order and the customer is not charged; it is only used for tokenizing a customer. Returned only for standalone tokenization — a session with customer.tokenize set to true and no order object — and only for merchants who have standalone tokenization enabled. It is omitted for sessions that include an order, where the customer authorizes tokenization during checkout instead. The URL expires 30 minutes after the session is created, which is sooner than the expiration field above. Create the session at the moment the customer clicks to authorize.

## Other responses

- `400` — Invalid request
- `401` — Unauthorized. Returned for any failed bearer or basic auth, including expired bearer tokens.
- `404` — The specified resource was not found
- `422` — Unable to process the request entity

## Changes

- **2026-08-12** `878c32abbb37` — 1 info
  - the request property `cancel_url` became optional

[Change history](https://skmtc.dev/sezzle/apis/sezzle-api-v2/changes/v2/session/post.md)

---

[API](https://skmtc.dev/sezzle/apis/sezzle-api-v2.md) · [All operations](https://skmtc.dev/sezzle/apis/sezzle-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sezzle/sezzle-api-v2/revisions/878c32abbb37/schema)