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

# Create checkout session

> Create a new checkout session.

Checkout sessions are hosted checkout forms your shoppers can use to complete their purchases.



## OpenAPI

````yaml https://app.stainless.com/api/spec/documented/checkout-intents/openapi.documented.yml post /api/v1/betas/checkout-sessions
openapi: 3.0.0
info:
  title: Universal Checkout API
  version: 1.0.5
  description: >-
    Turn any product URL into a completed checkout. Instantly retrieve price,
    tax, and shipping for any product, and let users buy without ever leaving
    your native AI experience.


    View the [Rye API docs](https://docs.rye.com).
  termsOfService: https://rye.com/terms-of-service
  license:
    name: UNLICENSED
  contact:
    name: Rye
    email: dev@rye.com
    url: https://docs.rye.com
servers:
  - url: https://staging.api.rye.com
security: []
paths:
  /api/v1/betas/checkout-sessions:
    post:
      tags:
        - Betas
      summary: Create checkout session
      description: >-
        Create a new checkout session.


        Checkout sessions are hosted checkout forms your shoppers can use to
        complete their purchases.
      operationId: Create
      parameters: []
      requestBody:
        description: The request body containing the checkout session parameters
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutSessionPostParams'
              description: ''
      responses:
        '200':
          description: Checkout session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSession'
        '401':
          description: Authentication Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeError'
      security:
        - bearerAuth:
            - checkout_intents:write
      x-codeSamples:
        - lang: JavaScript
          source: |-
            import CheckoutIntents from 'checkout-intents';

            const client = new CheckoutIntents({
              apiKey: process.env['CHECKOUT_INTENTS_API_KEY'], // This is the default and can be omitted
            });

            const checkoutSession = await client.betas.checkoutSessions.create({
              productUrl: 'https://www.amazon.com/dp/B0DFC9MT8Q',
              quantity: 1,
            });

            console.log(checkoutSession.url);
        - lang: Python
          source: |-
            import os
            from checkout_intents import CheckoutIntents

            client = CheckoutIntents(
                api_key=os.environ.get("CHECKOUT_INTENTS_API_KEY"),  # This is the default and can be omitted
            )
            checkout_session = client.betas.checkout_sessions.create(
                product_url="https://www.amazon.com/dp/B0DFC9MT8Q",
                quantity=1,
            )
            print(checkout_session.url)
        - lang: Java
          source: >-
            package com.rye.example;


            import com.rye.client.CheckoutIntentsClient;

            import com.rye.client.okhttp.CheckoutIntentsOkHttpClient;

            import com.rye.models.betas.CheckoutSession;

            import
            com.rye.models.betas.checkoutsessions.CheckoutSessionCreateParams;


            public final class Main {
                private Main() {}

                public static void main(String[] args) {
                    CheckoutIntentsClient client = CheckoutIntentsOkHttpClient.fromEnv();

                    CheckoutSessionCreateParams params = CheckoutSessionCreateParams.builder()
                        .productUrl("https://www.amazon.com/dp/B0DFC9MT8Q")
                        .quantity(1)
                        .build();
                    CheckoutSession checkoutSession = client.betas().checkoutSessions().create(params);
                }
            }
        - lang: cURL
          source: |-
            curl https://staging.api.rye.com/api/v1/betas/checkout-sessions \
                -H 'Content-Type: application/json' \
                -H "Authorization: Bearer $CHECKOUT_INTENTS_API_KEY" \
                -d '{
                      "productUrl": "https://www.amazon.com/dp/B0DFC9MT8Q",
                      "quantity": 1
                    }'
components:
  schemas:
    CheckoutSessionPostParams:
      allOf:
        - $ref: '#/components/schemas/Omit_CheckoutIntentPostParams.buyer_'
        - properties:
            layout:
              type: string
              enum:
                - default
                - wizard
              description: >-
                Optional layout for the checkout UI (e.g. "wizard"). Defaults to
                the standard layout.
            buyer:
              $ref: '#/components/schemas/Partial_Buyer_'
              description: >-
                Optional buyer information, used to pre-fill the checkout form
                with the buyer's information.
          type: object
      description: Post body for creating a checkout session.
    CheckoutSession:
      properties:
        url:
          type: string
          description: >-
            URL to send your user to for checkout. This URL is valid for 4
            hours.
      required:
        - url
      type: object
      description: >-
        A checkout session represents a hosted checkout form that shoppers can
        use to complete their purchases.


        Checkout sessions provide a pre-built UI for collecting payment and
        shipping information, allowing you to quickly integrate checkout
        functionality without building your own forms.
    AuthenticationError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
        - name
        - message
      type: object
      additionalProperties: false
    ValidateError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
        status:
          type: number
          format: double
        fields:
          $ref: '#/components/schemas/FieldErrors'
      required:
        - name
        - message
        - status
        - fields
      type: object
      additionalProperties: false
    RuntimeError:
      properties:
        name:
          type: string
        message:
          type: string
        stack:
          type: string
      required:
        - name
        - message
      type: object
      additionalProperties: false
    Omit_CheckoutIntentPostParams.buyer_:
      $ref: >-
        #/components/schemas/Pick_CheckoutIntentPostParams.Exclude_keyofCheckoutIntentPostParams.buyer__
      description: Construct a type with the properties of T except for those in type K.
    Partial_Buyer_:
      properties:
        firstName:
          type: string
          example: John
          maxLength: 255
        lastName:
          type: string
          example: Doe
          maxLength: 255
        email:
          type: string
          example: john.doe@example.com
        phone:
          type: string
          example: '1234567890'
        address1:
          type: string
          example: 123 Main St
          maxLength: 255
        address2:
          type: string
          example: Apt 1
          maxLength: 255
        city:
          type: string
          example: New York
          maxLength: 255
        province:
          type: string
          example: NY
          maxLength: 255
        country:
          type: string
          example: US
        postalCode:
          type: string
          example: '10001'
          maxLength: 255
      type: object
      description: Make all properties in T optional
    FieldErrors:
      properties: {}
      type: object
      additionalProperties:
        properties:
          value: {}
          message:
            type: string
        required:
          - message
        type: object
    Pick_CheckoutIntentPostParams.Exclude_keyofCheckoutIntentPostParams.buyer__:
      properties:
        productUrl:
          type: string
          example: https://www.amazon.com/dp/B0DFC9MT8Q
        quantity:
          type: integer
          format: int32
          example: 1
          minimum: 0
        variantSelections:
          items:
            $ref: '#/components/schemas/VariantSelection'
          type: array
        promoCodes:
          items:
            type: string
          type: array
          maxItems: 16
        constraints:
          $ref: '#/components/schemas/CheckoutConstraints'
        discoverPromoCodes:
          type: boolean
      required:
        - productUrl
        - quantity
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    VariantSelection:
      properties:
        value:
          anyOf:
            - type: string
            - type: number
              format: double
          example: Small, Red, XS, L, etc.
          maxLength: 60
        label:
          type: string
          example: Size, Color, etc.
          maxLength: 30
      required:
        - value
        - label
      type: object
    CheckoutConstraints:
      properties:
        offerRetrievalEffort:
          $ref: '#/components/schemas/OfferRetrievalEffort'
          example: max
        maxShippingPrice:
          type: integer
          format: int32
          example: 500
          minimum: 0
        maxTotalPrice:
          type: integer
          format: int32
          example: 100000
          minimum: 0
      type: object
    OfferRetrievalEffort:
      type: string
      enum:
        - max
        - low
      description: >-
        Controls how much effort the system should spend retrieving an offer.

        - 'max': Full effort including AI agent fallback (slower, higher success
        rate)

        - 'low': Fast API-only retrieval, fails if API unavailable (faster,
        lower success rate)


        Default: 'max'
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Rye API key

````