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

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Crear checkout

> Crea un nuevo checkout personalizado como clon publicado del checkout predeterminado de la cuenta

> [!NOTE]
>
> Esta API está en **Beta**. Los endpoints y los esquemas pueden cambiar sin previo aviso.

El nuevo checkout nace **`PUBLISHED`** como un clon del predeterminado de la cuenta: se copian los métodos de pago (incluidos los cambios de ícono y nombre y los conjuntos de condiciones de campos obligatorios); la configuración general y el estilo heredan la base de la cuenta hasta la primera [Publicación](https://docs.y.uno/es/reference/checkout-builder/publish-checkout-configuration.md) del checkout. Nunca se crea como el checkout predeterminado de la cuenta.

El `id` de nivel superior de la respuesta es el `checkout_code` que usan los endpoints [Obtener](https://docs.y.uno/es/reference/checkout-builder/fetch-checkout-configuration.md), [Publicar](https://docs.y.uno/es/reference/checkout-builder/publish-checkout-configuration.md) y [Gestionar ciclo de vida del checkout](https://docs.y.uno/es/reference/checkout-builder/manage-checkout-lifecycle.md).

`name` es obligatorio, no puede estar en blanco y debe ser único por cuenta; un duplicado se rechaza con `409`. Si la cuenta no tiene un checkout predeterminado del cual clonar, la solicitud se rechaza con `404`.


## OpenAPI

````yaml openapi/es/checkout-builder/create-checkout.json POST /checkouts
openapi: 3.1.0
info:
  title: checkout-builder
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - publicApiKey: []
    privateSecretKey: []
    accountCode: []
paths:
  /checkouts:
    post:
      summary: Create Checkout
      description: >-
        Crea un nuevo checkout personalizado como un clon publicado del checkout
        predeterminado de la cuenta: los métodos de pago (incluidos los
        reemplazos de ícono y nombre y los conjuntos de condiciones de campos
        obligatorios) se copian del predeterminado; la configuración general y
        los estilos heredan la base de la cuenta hasta la primera publicación
        del checkout. El nuevo checkout nace con el estado PUBLISHED y nunca es
        el predeterminado de la cuenta. El identificador se expone como el `id`
        de nivel superior.
      operationId: create-checkout
      parameters:
        - name: X-Idempotency-Key
          in: header
          description: >-
            Clave opcional del cliente, de hasta 64 caracteres. Se aplica con el
            mejor esfuerzo; si se reenvía la misma clave, no se garantiza que se
            elimine la duplicación.
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: >-
                    Nombre del checkout. Obligatorio, no puede estar en blanco y
                    debe ser único por cuenta (un nombre duplicado se rechaza
                    con 409).
                description:
                  type: string
                  description: Descripción opcional de texto libre.
            examples:
              Name only:
                value:
                  name: Promo Checkout
              Name and description:
                value:
                  name: Promo Checkout
                  description: Seasonal promo storefront
      responses:
        '201':
          description: >-
            El checkout creado. Nace PUBLISHED como un clon del predeterminado
            de la cuenta; `is_default` siempre es false al crearlo. Usa `id`
            como checkout_code en los demás endpoints de Checkout Builder.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutMutationResponse'
              examples:
                Created:
                  value:
                    id: 0b28ff66-15f1-44c1-8d1e-bd1fefbc0a19
                    name: Promo Checkout
                    description: Seasonal promo storefront
                    is_default: false
                    is_active: true
                    created_at: '2026-07-17T10:02:33.000Z'
        '400':
          description: >-
            Falta `name` o está en blanco, o el cuerpo JSON tiene un formato
            incorrecto.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
              examples:
                Missing name:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - name is required
        '401':
          description: >-
            No autenticado, o la cuenta no está en la lista de acceso permitido
            de la beta.
          content:
            application/json:
              examples:
                Unauthorized:
                  value:
                    code: NOT_AUTHENTICATED
                    messages:
                      - Not authenticated
        '404':
          description: La cuenta no tiene un checkout predeterminado que clonar.
          content:
            application/json:
              examples:
                No default checkout:
                  value:
                    code: DEFAULT_CHECKOUT_NOT_FOUND
                    messages:
                      - >-
                        No default Custom Checkout found for account:
                        78163a7c-c63c-4fdd-b72b-d5f77093a927
        '409':
          description: Ya existe un checkout con el mismo nombre para la cuenta.
          content:
            application/json:
              examples:
                Duplicate name:
                  value:
                    code: DUPLICATE_CHECKOUT_NAME
                    messages:
                      - >-
                        A Custom Checkout with name 'Promo Checkout' already
                        exists for this account
components:
  schemas:
    CheckoutMutationResponse:
      type: object
      properties:
        id:
          type: string
          description: >-
            Identificador del checkout (UUID). Úsalo como checkout_code en los
            endpoints de consulta, publicación y ciclo de vida.
        name:
          type: string
          description: Nombre del checkout.
        description:
          type: string
          description: Descripción del checkout.
        is_default:
          type: boolean
          description: >-
            Indica si este checkout es el predeterminado de la cuenta. Un
            checkout recién creado nunca es el predeterminado.
        is_active:
          type: boolean
          description: Indica si el checkout está activo (atendiendo tráfico).
        created_at:
          type: string
          format: date-time
          description: Marca de tiempo de creación (ISO-8601).
  securitySchemes:
    publicApiKey:
      type: apiKey
      in: header
      name: PUBLIC-API-KEY
      description: >-
        Clave de API pública del comercio. Se encuentra en el Dashboard de Yuno
        → Settings → API Keys.
    privateSecretKey:
      type: apiKey
      in: header
      name: PRIVATE-SECRET-KEY
      description: >-
        Clave secreta privada del comercio, asociada a la clave pública. Nunca
        la incluyas en código del lado del cliente.
    accountCode:
      type: apiKey
      in: header
      name: X-Account-Code
      description: >-
        UUID del ámbito de la cuenta del comercio para la solicitud. El tenant
        se resuelve únicamente a partir de este encabezado.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.