> ## Documentation Index > Fetch the complete documentation index at: https://docs.sezzle.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a session > Initiate a Sezzle session with shopper order details, redirect links, and capture and tokenization settings ## OpenAPI ````yaml post /v2/session openapi: 3.1.0 info: title: Sezzle API v2 description: >- This Sezzle API is for merchants who want to accept Sezzle as a payment option termsOfService: https://legal.sezzle.com version: 2.0.0 x-logo: url: https://media.sezzle.com/branding/2.0/png/Logo_WhiteWordmark_500x126.png backgroundColor: '#392558' servers: - url: https://sandbox.gateway.sezzle.com description: development server, usa, ca - url: https://gateway.sezzle.com description: production server, usa, ca security: - Bearer: [] externalDocs: description: Sezzle API guides and tutorials url: https://docs.sezzle.com/sezzle-integration paths: /v2/session: post: tags: - Session summary: Create a new session description: >- Initiate a Sezzle session with shopper order details, redirect links, and capture and tokenization settings operationId: HandleNewSession requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SessionRequest' example: cancel_url: href: https://example.com/cart method: GET complete_url: href: https://example.com/ord_12345/complete method: GET customer: email: john.doe@sezzle.com first_name: John last_name: Doe phone: '5555045294' dob: '1990-02-25' billing_address: name: John Doe street: 123 W Lake St street2: Unit 104 city: Minneapolis state: MN postal_code: '55408' country_code: US phone_number: '5555045294' shipping_address: name: John Doe street: 123 W Lake St street2: Unit 104 city: Minneapolis state: MN postal_code: '55408' country_code: US phone_number: '5555045294' order: intent: CAPTURE reference_id: ord_12345 description: 'sezzle-store - #12749253509255' items: - name: widget sku: sku123456 quantity: 1 price: amount_in_cents: 1000 currency: USD discounts: - name: 20% off amount: amount_in_cents: 1000 currency: USD metadata: location_id: '123' store_name: Downtown Minneapolis store_manager: Jane Doe shipping_amount: amount_in_cents: 1000 currency: USD tax_amount: amount_in_cents: 1000 currency: USD order_amount: amount_in_cents: 10000 currency: USD responses: '201': description: Successful Operation content: application/json: schema: allOf: - $ref: '#/components/schemas/Response' - type: object properties: order: $ref: '#/components/schemas/SessionOrderResponse' description: Order metadata required for checkout tokenize: $ref: '#/components/schemas/SessionTokenResponse' description: >- This is included in the response when starting a customer tokenization session. example: uuid: fadbc642-05a4-4e38-9e74-80e325623af9 links: - href: >- https://gateway.sezzle.com/v2/session/fadbc642-05a4-4e38-9e74-80e325623af9 method: GET rel: self order: uuid: 12a34bc5-6de7-890f-g123-4hi1238jk902 checkout_url: >- https://checkout.sezzle.com/?id=12a34bc5-6de7-890f-g123-4hi1238jk902 intent: CAPTURE links: - href: >- https://gateway.sezzle.com/v2/order/12a34bc5-6de7-890f-g123-4hi1238jk902 method: GET rel: self - href: >- https://gateway.sezzle.com/v2/order/12a34bc5-6de7-890f-g123-4hi1238jk902 method: PATCH rel: self - href: >- https://gateway.sezzle.com/v2/order/12a34bc5-6de7-890f-g123-4hi1238jk902/release method: POST rel: release - href: >- https://gateway.sezzle.com/v2/order/12a34bc5-6de7-890f-g123-4hi1238jk902/capture method: POST rel: capture - href: >- https://gateway.sezzle.com/v2/order/12a34bc5-6de7-890f-g123-4hi1238jk902/refund method: POST rel: refund '400': $ref: '#/components/responses/BadRequestV2' example: code: bad request message: cannot unmarshal string into order.items.quantity location: order.items.quantity '401': $ref: '#/components/responses/UnauthorizedV2' example: code: unauthorized message: authorization not accepted '404': $ref: '#/components/responses/NotFoundV2' example: code: record_not_found message: not found '422': $ref: '#/components/responses/UnprocessableV2' example: code: invalid message: UnprocessableV2 entity components: schemas: SessionRequest: type: object required: - cancel_url - complete_url properties: cancel_url: required: - href type: object properties: href: type: string description: The URL used when redirecting a customer upon order cancellation method: type: string description: >- The HTTP request method used when redirecting a customer. Currently only the GET method is supported. If omitted, will default to GET. description: >- The HTTP request information used to redirect the customer in the case of a cancellation complete_url: required: - href type: object properties: href: type: string description: The URL used when redirecting a customer upon order completion method: type: string description: >- The HTTP request method used when redirecting a customer. Currently only the GET method is supported. If omitted, will default to GET. description: >- The HTTP request information used to redirect the customer upon completion of the session customer: allOf: - $ref: '#/components/schemas/Customer' - type: object properties: shipping_address: $ref: '#/components/schemas/AddressV2' description: > The customer's shipping address. Merchants enrolled in Sezzle's Long Term Lending program (as well as general integrations) must send a Customer object that includes, at a minimum, a complete and valid shipping_address object. Post office box (i.e., P. O. Box) addresses are not accepted for this purpose. For more details, please contact your account manager. dob: type: string format: YYYY-MM-DD description: >- The customer's date of birth in YYYY-MM-DD format (parameter is input only) tokenize: type: boolean description: > 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. recurring: type: boolean description: > 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: type: object properties: name: type: string description: > 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 description: >- Customer details for this session. To optimize checkout and boost conversion, it is recommended to include as much customer information as possible. order: description: | Order ID, amount, and capture intent. Order details optional. allOf: - $ref: '#/components/schemas/OrderBasic' - $ref: '#/components/schemas/OrderDetail' - $ref: '#/components/schemas/OrderCheckout' required: - intent - reference_id - description - order_amount Response: type: object properties: uuid: type: string description: The unique identifier for this response links: type: array description: Available API links prefilled with UUID with accompanying method items: $ref: '#/components/schemas/Link' SessionOrderResponse: type: object properties: uuid: type: string description: Unique identifier for this order intent: $ref: '#/components/schemas/Intent' checkout_url: type: string description: >- The URL to which the shopper should be directed to complete their order with Sezzle links: type: array description: Available API links prefilled with UUID with accompanying method items: $ref: '#/components/schemas/Link' SessionTokenResponse: type: object properties: token: type: string description: >- 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: type: string format: date-time description: The expiration of the request token in ISO 8601 date/time format. approval_url: type: string description: >- The URL for the user to accept tokenization. This URL does not create an order, it is only used for tokenizing a customer. Customer: allOf: - $ref: '#/components/schemas/CheckoutRequestCustomer' - type: object properties: billing_address: $ref: '#/components/schemas/AddressV2' description: The customer's billing address AddressV2: allOf: - $ref: '#/components/schemas/Address' - type: object properties: phone: type: string description: The phone number at the delivery location OrderBasic: type: object properties: intent: $ref: '#/components/schemas/Intent' reference_id: type: string description: >- The checkout or cart ID from the merchant, currently used for tracking only (must contain only alphanumeric characters, dashes (-), and underscores (_)) order_amount: $ref: '#/components/schemas/Price' description: >- A Price object containing the total amount in cents of the order, which must be at least 100 which is $1.00. Please note your merchant configuration might have a higher minimum. OrderDetail: type: object properties: description: type: string description: Your description for this order metadata: type: object description: >- 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 properties: any: type: string description: Custom metadata field items: type: array description: The items being purchased items: $ref: '#/components/schemas/LineItem' OrderCheckout: type: object properties: requires_shipping_info: type: boolean description: >- Flag to indicate if you would like us to collect shipping information for this checkout from the customer. If omitted, defaults to false. discounts: type: array description: The discounts applied to this order. Must be included in total items: $ref: '#/components/schemas/Discount' tax_amount: $ref: '#/components/schemas/Price' description: The taxes applied to this order. Must be included in the total shipping_amount: $ref: '#/components/schemas/Price' description: >- The shipping fees applied to this order. Must be included in the total checkout_mode: $ref: '#/components/schemas/CheckoutMode' send_checkout_url: $ref: '#/components/schemas/Notification' description: A Notification object for sending checkout URL to the customer locale: $ref: '#/components/schemas/Locale' checkout_financing_options: type: array description: >- The financing options of the checkout. Only one option can be included. items: $ref: '#/components/schemas/InstallmentPlan' Link: type: object required: - href properties: href: type: string description: The fully qualified URL for the API endpoint rel: type: string description: >- 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) enum: - self - capture - checkout - create - customer - list - order - preapprove - refund - release - session method: type: string description: The HTTP method to use when calling this API endpoint enum: - GET - POST - PATCH - DELETE Intent: type: string description: > If your checkout flow requires the user to confirm their checkout on your site after being approved by Sezzle, use AUTH as your intent. If you prefer the checkout be captured immediately, use CAPTURE. 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. enum: - AUTH - CAPTURE ErrorV2: type: object properties: code: type: string description: The general error type message: type: string description: A more specific error message, if available location: type: string description: Where the error occurred debug_uuid: type: string description: The unique identifier assigned to this error for troubleshooting CheckoutRequestCustomer: type: object properties: first_name: type: string description: The customer's first name last_name: type: string description: The customer's last name email: type: string description: The customer's email address phone: type: string description: The customer's phone number Address: type: object properties: name: type: string description: The name on the address street: type: string description: The street and number of the address street2: type: string description: The apt or unit city: type: string description: The city state: type: string description: The 2 character state code postal_code: type: string description: The postal delivery code country_code: type: string description: The 2 character country code Price: allOf: - $ref: '#/components/schemas/PriceBase' - type: object required: - amount_in_cents - currency LineItem: description: >- Merchants who are in the Sports & Hobbies or Hunting & Fishing categories must define a category_path for each item in the order. Please talk with your account manager for further details. allOf: - $ref: '#/components/schemas/LineItemBasic' - type: object properties: name: type: string description: The name of the item sku: type: string description: The sku identifier quantity: type: integer description: The quantity purchased price: $ref: '#/components/schemas/Price' description: The price of the product before tax and discounts brand: type: string description: >- The products brand name as customers would recognize. Examples: Nike, Kelty, Brooks, Carhartt, Columbia image_url: type: string description: The fully qualified URL that shows the image product_url: type: string description: >- The fully qualified URL that links directly to the product being purchased global_trade_item_number: type: string description: >- The products Global Trade Item Number (GTIN). Common types include UPC, ISBN, EAN. Exclude dashes and spaces. manufacturer_part_number: type: string description: >- The products Manufacturer Part Number (MPN) which together with brand can uniquely identify a product. Discount: type: object properties: name: type: string description: The description of the discount amount: $ref: '#/components/schemas/Price' description: A price object CheckoutMode: type: string description: >- 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. enum: - iframe - popup - redirect Notification: type: object properties: to_sms_phone: type: string description: The SMS phone number of the notification to_email: type: string description: The email address of the notification language: $ref: '#/components/schemas/Language' Locale: type: string description: >- 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. enum: - en-US - en-CA - fr-CA InstallmentPlan: type: string description: | *currently not supported, defaults to 4-pay-biweekly* enum: - 4-pay-biweekly - 4-pay-monthly - 6-pay-monthly PriceBase: type: object properties: amount_in_cents: type: integer description: The amount in cents currency: type: string description: The 3 character currency code as defined by ISO 4217 LineItemBasic: type: object description: >- Merchants who are in the Sports & Hobbies or Hunting & Fishing categories must define a category_path for each item in the order. Please talk with your account manager for further details. properties: name: type: string description: The name of the item sku: type: string description: The sku identifier quantity: type: integer description: The quantity purchased price: $ref: '#/components/schemas/Price' description: The price of the product before tax and discounts category_path: type: string description: >- 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. Language: type: string description: >- The 2-character ISO 639 langauge code of the notification. Acceptable values are en and fr-CA. Will default to English if not provided. enum: - en - fr-CA responses: BadRequestV2: description: Invalid request content: application/json: schema: type: array items: $ref: '#/components/schemas/ErrorV2' example: - code: bad_request message: bad request UnauthorizedV2: description: >- Unauthorized. Returned for any failed bearer or basic auth, including expired bearer tokens. content: application/json: schema: type: array items: $ref: '#/components/schemas/ErrorV2' example: - code: unauthorized message: authorization not accepted NotFoundV2: description: The specified resource was not found content: application/json: schema: type: array items: $ref: '#/components/schemas/ErrorV2' example: - code: record_not_found message: not found UnprocessableV2: description: Unable to process the request entity content: application/json: schema: type: array items: $ref: '#/components/schemas/ErrorV2' example: - code: invalid message: Unprocessable entity securitySchemes: Bearer: type: apiKey name: Authorization in: header description: >- The authentication token generated from providing API Keys to Sezzle Gateway ````