> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexype.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Checkout Session
> Create a new checkout session for a customer with cart items.
The `session_id` returned by this endpoint must be used for all subsequent checkout operations.
Sessions expire after 1 hour of inactivity if not completed. The `country_code` must be in ISO 3166-1 alpha-2 format (e.g. `IN`, `US`).
Each entry in `items` is the full Shopify cart line-item object. Pass it through as-is from the storefront cart — `product_id`, `variant_id`, and `quantity` are the required fields; the rest enrich analytics and display.
## OpenAPI
````yaml POST /session
openapi: 3.0.1
info:
title: FlexyPe Checkout API
description: >-
Public APIs for the FlexyPe checkout system: session creation, OTP-based
authentication, and checkout flow management.
version: 1.0.0
servers:
- url: https://api.flexype.io
security:
- bearerAuth: []
paths:
/session:
post:
tags:
- Checkout
summary: Create Checkout Session
description: >-
Creates a new checkout session for a customer. This endpoint initializes
a shopping session with cart items and sets up the session for checkout
processing. The session is associated with the merchant and tracks the
customer's checkout journey.
Authentication is handled by merchant middleware, which extracts the
merchant from the request `shop_domain`. Sessions expire after 1 hour of
inactivity if not completed.
operationId: createSession
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
type: object
required:
- shop_domain
- country_code
- items
properties:
shop_domain:
type: string
description: Merchant store domain. Must be registered with FlexyPe.
example: your-store.myshopify.com
country_code:
type: string
description: >-
Customer country in ISO 3166-1 alpha-2 format (e.g.
'IN', 'US').
example: IN
items:
type: array
description: >-
Cart items. Must be a non-empty array. Each item is the
full Shopify line-item object.
items:
$ref: '#/components/schemas/LineItem'
fp_id:
type: string
description: FlexyPe visitor/fingerprint ID.
example: 019ed071-5eb5-7058-be68-db99c97a31c6
shopify_s:
type: string
description: Shopify session identifier.
example: f9ab0bb4-b5c5-4972-8858-3c45c6df6e2a
shopify_y:
type: string
description: Shopify Y parameter / fingerprint.
example: cb62239e-bf5d-4cd3-9cac-719072e45672
flexy_trace_s:
type: string
description: FlexyPe trace session ID.
example: 019ed3c2-e442-758f-82ec-5948f1edf94e
flexy_trace_y:
type: string
description: FlexyPe trace fingerprint ID.
example: 019ed071-5eb5-7058-be68-e1a61e387644
redirect_url:
type: string
description: URL to redirect to after checkout.
example: https://my-store.com/cart
analytics:
type: object
description: >-
Marketing/analytics identifiers captured on the
storefront, used for attribution and conversion
tracking.
properties:
fb:
type: object
description: Meta (Facebook) Pixel identifiers.
properties:
fbp:
type: string
description: Meta browser pixel ID (`_fbp` cookie).
example: fb.1.1781613551791.890210081485532160
fbc:
type: string
description: >-
Meta click ID (`_fbc` cookie). Present when the
visit came from a Meta ad.
example: fb.1.1781613551791.IwAR0abcdEfGhIjKlMnOpQr
metadata:
type: object
description: >-
Custom metadata such as UTM parameters and referrer
info.
properties:
utm:
type: array
description: UTM / click-ID name-value pairs.
items:
type: object
properties:
name:
type: string
example: gclid
value:
type: string
example: CjwKCAjw6MPRBhBTEiwAd-7Mr...
orig_referer:
type: string
example: https://www.google.com/
referer_host:
type: string
example: www.google.com
landing_page:
type: string
example: /
attributes:
type: object
description: >-
Free-form Shopify cart attributes as key-value string
pairs. Mirror the storefront cart `attributes`; send
`{}` when none are set.
additionalProperties:
type: string
example:
gift_wrap: 'true'
delivery_date: '2026-06-20'
note:
type: string
description: >-
Customer order note from the storefront cart. Send an
empty string when none.
example: Please deliver after 6 PM
responses:
'200':
description: Session created successfully.
headers:
X-Session-ID:
description: The created session ID.
schema:
type: string
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: SUCCESS
data:
type: object
properties:
session_id:
type: string
format: uuid
description: >-
Session ID. Use this for all subsequent checkout
operations.
example: 5223aec7-bb78-4344-be18-8023eb8f22ae
merchant_id:
type: string
format: uuid
example: 4b4c8bf8-5a7c-4786-9210-418c8bc5c379
'400':
description: Request validation failed or shop domain not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
status: FAILURE
error:
code: error.shop-not-found
message: Shop domain not found in merchant database
components:
schemas:
LineItem:
type: object
description: A Shopify cart line item.
required:
- product_id
- variant_id
- quantity
properties:
product_id:
type: integer
format: int64
description: Shopify product ID.
example: 8948397801608
variant_id:
type: integer
format: int64
description: Shopify variant ID.
example: 46107636203656
quantity:
type: integer
description: Quantity of the variant.
example: 1
properties:
type: object
description: >-
Custom Shopify line-item properties as key-value pairs (e.g.
engraving text, bundle metadata). Empty object when none.
additionalProperties:
type: string
example:
Engraving: John Doe
ErrorResponse:
type: object
properties:
status:
type: string
example: FAILURE
error:
type: object
properties:
code:
type: string
description: Machine-readable error code.
example: error.invalid-request
message:
type: string
description: Human-readable error message.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API key sent as a bearer token (`Bearer `). Generate keys in the
dashboard under Settings → API Keys.
````