> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create checkout session

> Stripe-style alias for `POST /dev/v1/payments`. Accepts `amount`, `success_url`, `cancel_url`, `customer_email`, and a single `product` descriptor; returns a session shape with `id`, `url`, and `status`. Internally delegates to the payments endpoint, so PSP orchestration, scopes, and webhook behavior are identical; `Idempotency-Key` replay is handled by this endpoint and returns the stored session response. For multi-item checkouts, build the cart on your side and call this endpoint with the aggregated amount.



## OpenAPI

````yaml /openapi.json post /dev/v1/checkout/sessions
openapi: 3.0.3
info:
  title: Shoppex Developer API
  description: Mintlify-compatible Developer API reference for Shoppex.
  version: 1.0.0
  contact:
    name: Shoppex Support
    email: support@shoppex.io
    url: https://shoppex.io
servers:
  - url: https://api.shoppex.io
security:
  - bearerAuth: []
paths:
  /dev/v1/checkout/sessions:
    post:
      tags:
        - Payments
      summary: Create checkout session
      description: >-
        Stripe-style alias for `POST /dev/v1/payments`. Accepts `amount`,
        `success_url`, `cancel_url`, `customer_email`, and a single `product`
        descriptor; returns a session shape with `id`, `url`, and `status`.
        Internally delegates to the payments endpoint, so PSP orchestration,
        scopes, and webhook behavior are identical; `Idempotency-Key` replay is
        handled by this endpoint and returns the stored session response. For
        multi-item checkouts, build the cart on your side and call this endpoint
        with the aggregated amount.
      operationId: postDevV1CheckoutSessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - product
                - amount
                - currency
                - customer_email
              properties:
                product:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 128
                    quantity:
                      type: number
                      minimum: 1
                amount:
                  type: number
                  minimum: 0.01
                currency:
                  type: string
                  minLength: 3
                  maxLength: 3
                customer_email:
                  type: string
                  format: email
                success_url:
                  type: string
                cancel_url:
                  type: string
                metadata:
                  type: object
                gateway:
                  type: string
                gateways:
                  type: array
                  items:
                    type: string
                crypto_gateway:
                  type: string
                confirmations:
                  type: number
                  minimum: 1
                customer_id:
                  type: string
          multipart/form-data:
            schema:
              type: object
              required:
                - product
                - amount
                - currency
                - customer_email
              properties:
                product:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 128
                    quantity:
                      type: number
                      minimum: 1
                amount:
                  type: number
                  minimum: 0.01
                currency:
                  type: string
                  minLength: 3
                  maxLength: 3
                customer_email:
                  type: string
                  format: email
                success_url:
                  type: string
                cancel_url:
                  type: string
                metadata:
                  type: object
                gateway:
                  type: string
                gateways:
                  type: array
                  items:
                    type: string
                crypto_gateway:
                  type: string
                confirmations:
                  type: number
                  minimum: 1
                customer_id:
                  type: string
          text/plain:
            schema:
              type: object
              required:
                - product
                - amount
                - currency
                - customer_email
              properties:
                product:
                  type: object
                  required:
                    - name
                  properties:
                    name:
                      type: string
                      minLength: 1
                      maxLength: 128
                    quantity:
                      type: number
                      minimum: 1
                amount:
                  type: number
                  minimum: 0.01
                currency:
                  type: string
                  minLength: 3
                  maxLength: 3
                customer_email:
                  type: string
                  format: email
                success_url:
                  type: string
                cancel_url:
                  type: string
                metadata:
                  type: object
                gateway:
                  type: string
                gateways:
                  type: array
                  items:
                    type: string
                crypto_gateway:
                  type: string
                confirmations:
                  type: number
                  minimum: 1
                customer_id:
                  type: string
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - id
                      - url
                      - status
                      - amount
                      - currency
                      - customer_email
                      - success_url
                      - cancel_url
                      - created_at
                    properties:
                      id:
                        type: string
                      url:
                        type: string
                      status:
                        type: string
                      amount:
                        type: number
                      currency:
                        type: string
                      customer_email:
                        type: string
                        nullable: true
                      success_url:
                        type: string
                        nullable: true
                      cancel_url:
                        type: string
                        nullable: true
                      expires_at:
                        type: string
                      checkout_url:
                        type: string
                      session_id:
                        type: string
                      created_at:
                        type: number
                      warnings:
                        type: array
                        items:
                          type: object
                          required:
                            - code
                            - field
                            - message
                          properties:
                            code:
                              type: string
                              enum:
                                - subscription_checkout_mismatch
                            field:
                              type: string
                            message:
                              type: string
            multipart/form-data:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - id
                      - url
                      - status
                      - amount
                      - currency
                      - customer_email
                      - success_url
                      - cancel_url
                      - created_at
                    properties:
                      id:
                        type: string
                      url:
                        type: string
                      status:
                        type: string
                      amount:
                        type: number
                      currency:
                        type: string
                      customer_email:
                        type: string
                        nullable: true
                      success_url:
                        type: string
                        nullable: true
                      cancel_url:
                        type: string
                        nullable: true
                      expires_at:
                        type: string
                      checkout_url:
                        type: string
                      session_id:
                        type: string
                      created_at:
                        type: number
                      warnings:
                        type: array
                        items:
                          type: object
                          required:
                            - code
                            - field
                            - message
                          properties:
                            code:
                              type: string
                              enum:
                                - subscription_checkout_mismatch
                            field:
                              type: string
                            message:
                              type: string
            text/plain:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    type: object
                    required:
                      - id
                      - url
                      - status
                      - amount
                      - currency
                      - customer_email
                      - success_url
                      - cancel_url
                      - created_at
                    properties:
                      id:
                        type: string
                      url:
                        type: string
                      status:
                        type: string
                      amount:
                        type: number
                      currency:
                        type: string
                      customer_email:
                        type: string
                        nullable: true
                      success_url:
                        type: string
                        nullable: true
                      cancel_url:
                        type: string
                        nullable: true
                      expires_at:
                        type: string
                      checkout_url:
                        type: string
                      session_id:
                        type: string
                      created_at:
                        type: number
                      warnings:
                        type: array
                        items:
                          type: object
                          required:
                            - code
                            - field
                            - message
                          properties:
                            code:
                              type: string
                              enum:
                                - subscription_checkout_mismatch
                            field:
                              type: string
                            message:
                              type: string
        '400':
          description: Error response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      doc_url:
                        type: string
                      details:
                        type: array
                        items:
                          type: object
                          required:
                            - field
                            - message
                          properties:
                            field:
                              type: string
                            message:
                              type: string
        '401':
          description: Error response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      doc_url:
                        type: string
                      details:
                        type: array
                        items:
                          type: object
                          required:
                            - field
                            - message
                          properties:
                            field:
                              type: string
                            message:
                              type: string
        '403':
          description: Error response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      doc_url:
                        type: string
                      details:
                        type: array
                        items:
                          type: object
                          required:
                            - field
                            - message
                          properties:
                            field:
                              type: string
                            message:
                              type: string
        '422':
          description: Error response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      doc_url:
                        type: string
                      details:
                        type: array
                        items:
                          type: object
                          required:
                            - field
                            - message
                          properties:
                            field:
                              type: string
                            message:
                              type: string
        '429':
          description: Error response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      doc_url:
                        type: string
                      details:
                        type: array
                        items:
                          type: object
                          required:
                            - field
                            - message
                          properties:
                            field:
                              type: string
                            message:
                              type: string
        '500':
          description: Error response
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      doc_url:
                        type: string
                      details:
                        type: array
                        items:
                          type: object
                          required:
                            - field
                            - message
                          properties:
                            field:
                              type: string
                            message:
                              type: string
      deprecated: false
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Use your Shoppex API key in the Authorization header.

````