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

# Create storefront

> Use this when the user wants to create a new online storefront from scratch.

Creates a storefront from a `StorefrontManifest`. Returns 201 with the full storefront. If the manifest contains more products than the plan allows, returns **207 Multi-Status** with the storefront created (up to plan cap) plus an `errors` array describing the over-cap items.



## OpenAPI

````yaml /openapi.json post /v1/storefronts
openapi: 3.1.0
info:
  title: Marea Alcalina API
  version: 1.0.0
  description: >-
    Operations + retention API for small-business commerce. Bootstrap a digital
    menu (food) or product catalog (retail/services) plus a public hosted
    storefront for a single operator; orders flow through WhatsApp, web
    checkout, or in-person — channel is per-storefront config.


    **Auth**: `Authorization: Bearer mk_<dev|user>_...`


    **Free tier**: 1 storefront, 30 products, no publish.


    **Errors**: every non-2xx response uses the §9.6 envelope, including a
    `nextActions[]` array. Surface those verbatim to your user.


    **Rate limits**: every response carries `X-RateLimit-*` headers. 429s carry
    `Retry-After`.


    **Idempotency**: state-mutating endpoints accept an optional
    `Idempotency-Key` request header; replays within 24h return the original
    response.
  contact:
    name: Marea Alcalina API support
    url: https://developers.mareaalcalina.com
    email: developers@mareaalcalina.com
  termsOfService: https://mareaalcalina.com/terms
  license:
    name: Proprietary
    url: https://mareaalcalina.com/terms
  x-generated-at: '2026-05-15T19:15:00Z'
servers:
  - url: https://api.mareaalcalina.com
    description: Production
  - url: https://api-staging.mareaalcalina.com
    description: Staging
security:
  - BearerAuth: []
  - ApiKeyHeader: []
tags:
  - name: Identity
    description: Inspect the calling key (user or developer).
  - name: Users
    description: Bootstrap, verify, and inspect users created by a developer key.
  - name: Storefronts
    description: Create, update, and publish hosted storefronts.
  - name: Products
    description: Add and update products inside a storefront.
  - name: Webhooks
    description: Register the developer-key destination URL for user-lifecycle events.
paths:
  /v1/storefronts:
    post:
      tags:
        - Storefronts
      summary: Create storefront
      description: >-
        Use this when the user wants to create a new online storefront from
        scratch.


        Creates a storefront from a `StorefrontManifest`. Returns 201 with the
        full storefront. If the manifest contains more products than the plan
        allows, returns **207 Multi-Status** with the storefront created (up to
        plan cap) plus an `errors` array describing the over-cap items.
      operationId: createStorefront
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Optional client-supplied key. Replays of the same key within 24h
            return the original response. Recommended for POSTs that mutate
            billing/inventory.
          schema:
            type: string
            maxLength: 200
            example: idem_b2a9f5b9-3e0c-4a5e-b3c2-7a4ce85a6b21
        - name: Accept-Language
          in: header
          required: false
          description: >-
            BCP-47 locale tag for localized error messages (`es`, `en`, `pt`).
            Defaults to `es`.
          schema:
            type: string
            example: es-MX
      requestBody:
        description: Request body.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StorefrontManifest'
      responses:
        '201':
          description: Resource created.
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontCreateResponse'
        '207':
          description: >-
            Multi-Status — created with partial-failure `errors[]` (over plan
            cap).
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontCreateResponse'
        '400':
          description: Invalid request — Zod validation failed or body malformed.
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Auth failed — missing or invalid API key.
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '402':
          description: Plan limit — the calling user's plan does not permit this action.
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '403':
          description: Forbidden — key scopes do not cover this operation.
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '404':
          description: Not found — leak-less; cross-tenant access also collapses here.
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '409':
          description: Conflict — idempotent retry collided with a different body.
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '410':
          description: Gone — verification code expired (verify endpoint).
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '413':
          description: Payload too large.
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '422':
          description: >-
            Unprocessable entity — semantic precondition failed (empty
            storefront, user not verified, etc).
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '429':
          description: Rate limited — too many requests.
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
            Retry-After:
              description: Seconds the client should wait before retrying.
              schema:
                type: integer
                example: 30
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '500':
          description: Internal error.
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '503':
          description: Service unavailable — downstream Firestore/Auth degraded.
          headers:
            X-RateLimit-Limit:
              description: >-
                Per-minute rate-limit ceiling for the calling key
                (Stripe-compatible).
              schema:
                type: integer
                example: 60
            X-RateLimit-Remaining:
              description: Remaining requests in the current per-minute window.
              schema:
                type: integer
                example: 59
            X-RateLimit-Reset:
              description: >-
                Epoch-seconds timestamp when the per-minute window rolls over
                (Stripe-compatible).
              schema:
                type: integer
                example: 1714867260
            X-Request-Id:
              description: Server-assigned request id. Echo back in support tickets.
              schema:
                type: string
                example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
      security:
        - BearerAuth:
            - catalog:write
components:
  schemas:
    StorefrontManifest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        language:
          type: string
          enum:
            - es
            - en
            - pt
        currency:
          type: string
          pattern: ^[A-Z]{3}$
        businessType:
          type: string
        branding:
          $ref: '#/components/schemas/StorefrontBranding'
        schedule:
          $ref: '#/components/schemas/StorefrontSchedule'
        delivery:
          $ref: '#/components/schemas/StorefrontDelivery'
        pickup:
          type:
            - boolean
            - 'null'
        dineIn:
          type:
            - boolean
            - 'null'
        whatsapp:
          type:
            - string
            - 'null'
        biography:
          anyOf:
            - type: object
              properties:
                title:
                  type: string
                description:
                  type: string
              required:
                - title
                - description
            - type: string
              enum:
                - auto
            - type: 'null'
        blocks:
          anyOf:
            - type: string
              enum:
                - auto
            - type: array
              items: {}
            - type: 'null'
        categories:
          type:
            - array
            - 'null'
          items:
            type: object
            properties:
              name:
                type: string
              position:
                type:
                  - integer
                  - 'null'
            required:
              - name
        products:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ProductManifest'
          maxItems: 100
      required:
        - name
        - language
        - currency
        - businessType
      description: >-
        Agent-facing storefront input shape (RFC §6.18.1). Every field is
        PATCHable per §6.18.1.1.
    StorefrontCreateResponse:
      type: object
      properties:
        storefront:
          $ref: '#/components/schemas/StorefrontDto'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/PartialProductError'
      required:
        - storefront
    ApiErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ApiErrorBody'
      required:
        - error
      description: §9.6 uniform error envelope. Every non-2xx response uses this shape.
    StorefrontBranding:
      type:
        - object
        - 'null'
      properties:
        logoUrl:
          anyOf:
            - type: string
              format: uri
            - type: object
              properties:
                fileId:
                  type: string
              required:
                - fileId
            - type: 'null'
        backgroundUrl:
          anyOf:
            - type: string
              format: uri
            - type: object
              properties:
                fileId:
                  type: string
              required:
                - fileId
            - type: string
              enum:
                - auto
            - type: 'null'
        theme:
          anyOf:
            - type: object
              properties:
                primary:
                  type: string
                secondary:
                  type: string
                tertiary:
                  type: string
              required:
                - primary
                - secondary
                - tertiary
            - type: object
              properties:
                preset:
                  type: string
              required:
                - preset
            - type: 'null'
        font:
          type:
            - string
            - 'null'
    StorefrontSchedule:
      type:
        - object
        - 'null'
      properties:
        monday:
          type:
            - object
            - 'null'
          properties:
            open:
              type: string
              pattern: ^\d{2}:\d{2}$
            close:
              type: string
              pattern: ^\d{2}:\d{2}$
            closed:
              type:
                - boolean
                - 'null'
          required:
            - open
            - close
        tuesday:
          type:
            - object
            - 'null'
          properties:
            open:
              type: string
              pattern: ^\d{2}:\d{2}$
            close:
              type: string
              pattern: ^\d{2}:\d{2}$
            closed:
              type:
                - boolean
                - 'null'
          required:
            - open
            - close
        wednesday:
          type:
            - object
            - 'null'
          properties:
            open:
              type: string
              pattern: ^\d{2}:\d{2}$
            close:
              type: string
              pattern: ^\d{2}:\d{2}$
            closed:
              type:
                - boolean
                - 'null'
          required:
            - open
            - close
        thursday:
          type:
            - object
            - 'null'
          properties:
            open:
              type: string
              pattern: ^\d{2}:\d{2}$
            close:
              type: string
              pattern: ^\d{2}:\d{2}$
            closed:
              type:
                - boolean
                - 'null'
          required:
            - open
            - close
        friday:
          type:
            - object
            - 'null'
          properties:
            open:
              type: string
              pattern: ^\d{2}:\d{2}$
            close:
              type: string
              pattern: ^\d{2}:\d{2}$
            closed:
              type:
                - boolean
                - 'null'
          required:
            - open
            - close
        saturday:
          type:
            - object
            - 'null'
          properties:
            open:
              type: string
              pattern: ^\d{2}:\d{2}$
            close:
              type: string
              pattern: ^\d{2}:\d{2}$
            closed:
              type:
                - boolean
                - 'null'
          required:
            - open
            - close
        sunday:
          type:
            - object
            - 'null'
          properties:
            open:
              type: string
              pattern: ^\d{2}:\d{2}$
            close:
              type: string
              pattern: ^\d{2}:\d{2}$
            closed:
              type:
                - boolean
                - 'null'
          required:
            - open
            - close
    StorefrontDelivery:
      type:
        - object
        - 'null'
      properties:
        enabled:
          type: boolean
        type:
          type:
            - string
            - 'null'
          enum:
            - fixed
            - distance
        fixedPrice:
          type:
            - number
            - 'null'
          minimum: 0
        ranges:
          type:
            - array
            - 'null'
          items:
            type: object
            properties:
              fromKm:
                type: number
                minimum: 0
              toKm:
                type: number
                minimum: 0
              price:
                type: number
                minimum: 0
            required:
              - fromKm
              - toKm
              - price
      required:
        - enabled
    ProductManifest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type:
            - string
            - 'null'
        price:
          type: number
          minimum: 0
        salePrice:
          type:
            - number
            - 'null'
          minimum: 0
        category:
          type:
            - string
            - 'null'
        subcategory:
          type:
            - string
            - 'null'
        imageUrl:
          type:
            - string
            - 'null'
          format: uri
        thumbnailUrl:
          type:
            - string
            - 'null'
          format: uri
        sku:
          type:
            - string
            - 'null'
        slug:
          type:
            - string
            - 'null'
        position:
          type:
            - integer
            - 'null'
        cartProduct:
          type:
            - boolean
            - 'null'
        hide:
          type:
            - boolean
            - 'null'
        stock:
          type:
            - integer
            - 'null'
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
        extraProductsCategory:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ExtraProductsCategory'
      required:
        - title
        - price
      description: >-
        Agent-facing product input shape. Mutability rule §6.18.1.1: every field
        PATCHable post-create.
    StorefrontDto:
      type: object
      properties:
        id:
          type: string
          pattern: ^stf_
          example: stf_abc123
        name:
          type: string
        language:
          type: string
          enum:
            - es
            - en
            - pt
        currency:
          type: string
        businessType:
          type:
            - string
            - 'null'
        branding:
          type:
            - object
            - 'null'
          properties:
            logoUrl:
              type:
                - string
                - 'null'
            backgroundUrl:
              type:
                - string
                - 'null'
            theme:
              type:
                - object
                - 'null'
              properties:
                primary:
                  type:
                    - string
                    - 'null'
                secondary:
                  type:
                    - string
                    - 'null'
                tertiary:
                  type:
                    - string
                    - 'null'
              required:
                - primary
                - secondary
                - tertiary
            font:
              type:
                - string
                - 'null'
          required:
            - logoUrl
            - backgroundUrl
            - theme
            - font
        schedule:
          type:
            - object
            - 'null'
          properties:
            monday:
              type:
                - object
                - 'null'
              properties:
                open:
                  type:
                    - string
                    - 'null'
                close:
                  type:
                    - string
                    - 'null'
                closed:
                  type:
                    - boolean
                    - 'null'
              required:
                - open
                - close
                - closed
            tuesday:
              type:
                - object
                - 'null'
              properties:
                open:
                  type:
                    - string
                    - 'null'
                close:
                  type:
                    - string
                    - 'null'
                closed:
                  type:
                    - boolean
                    - 'null'
              required:
                - open
                - close
                - closed
            wednesday:
              type:
                - object
                - 'null'
              properties:
                open:
                  type:
                    - string
                    - 'null'
                close:
                  type:
                    - string
                    - 'null'
                closed:
                  type:
                    - boolean
                    - 'null'
              required:
                - open
                - close
                - closed
            thursday:
              type:
                - object
                - 'null'
              properties:
                open:
                  type:
                    - string
                    - 'null'
                close:
                  type:
                    - string
                    - 'null'
                closed:
                  type:
                    - boolean
                    - 'null'
              required:
                - open
                - close
                - closed
            friday:
              type:
                - object
                - 'null'
              properties:
                open:
                  type:
                    - string
                    - 'null'
                close:
                  type:
                    - string
                    - 'null'
                closed:
                  type:
                    - boolean
                    - 'null'
              required:
                - open
                - close
                - closed
            saturday:
              type:
                - object
                - 'null'
              properties:
                open:
                  type:
                    - string
                    - 'null'
                close:
                  type:
                    - string
                    - 'null'
                closed:
                  type:
                    - boolean
                    - 'null'
              required:
                - open
                - close
                - closed
            sunday:
              type:
                - object
                - 'null'
              properties:
                open:
                  type:
                    - string
                    - 'null'
                close:
                  type:
                    - string
                    - 'null'
                closed:
                  type:
                    - boolean
                    - 'null'
              required:
                - open
                - close
                - closed
          required:
            - monday
            - tuesday
            - wednesday
            - thursday
            - friday
            - saturday
            - sunday
        delivery:
          type:
            - object
            - 'null'
          properties:
            enabled:
              type: boolean
            type:
              type:
                - string
                - 'null'
              enum:
                - fixed
                - distance
            fixedPrice:
              type:
                - number
                - 'null'
            ranges:
              type:
                - array
                - 'null'
              items:
                type: object
                properties:
                  fromKm:
                    type: number
                  toKm:
                    type:
                      - number
                      - 'null'
                  price:
                    type: number
                required:
                  - fromKm
                  - toKm
                  - price
          required:
            - enabled
            - type
            - fixedPrice
            - ranges
        pickup:
          type:
            - boolean
            - 'null'
        dineIn:
          type:
            - boolean
            - 'null'
        whatsapp:
          type:
            - string
            - 'null'
        biography:
          type:
            - object
            - 'null'
          properties:
            title:
              type: string
            description:
              type: string
          required:
            - title
            - description
        categories:
          type:
            - array
            - 'null'
          items:
            type: object
            properties:
              name:
                type: string
              position:
                type:
                  - integer
                  - 'null'
            required:
              - name
              - position
        slug:
          type:
            - string
            - 'null'
        published:
          type:
            - boolean
            - 'null'
        _links:
          $ref: '#/components/schemas/StorefrontLinks'
        createdAt:
          type:
            - string
            - 'null'
        updatedAt:
          type:
            - string
            - 'null'
      required:
        - id
        - name
        - language
        - currency
        - businessType
        - branding
        - schedule
        - delivery
        - pickup
        - dineIn
        - whatsapp
        - biography
        - categories
        - slug
        - published
        - _links
        - createdAt
        - updatedAt
    PartialProductError:
      type: object
      properties:
        type:
          type: string
          enum:
            - plan_limit
        code:
          type: string
          enum:
            - products_over_limit
        message:
          type: string
        param:
          type: string
          enum:
            - products
        doc:
          type: string
        recoverable:
          type: boolean
          enum:
            - true
        recovery:
          type: object
          properties:
            skippedCount:
              type: integer
              minimum: 0
            skippedProducts:
              type: array
              items:
                type: object
                properties:
                  index:
                    type: integer
                    minimum: 0
                  title:
                    type:
                      - string
                      - 'null'
                required:
                  - index
                  - title
            upgrade:
              type: object
              properties:
                currentPlan:
                  type: string
                requiredPlan:
                  type: string
                upgradeUrl:
                  type: string
                previewUrl:
                  type:
                    - string
                    - 'null'
              required:
                - currentPlan
                - requiredPlan
                - upgradeUrl
                - previewUrl
          required:
            - skippedCount
            - skippedProducts
            - upgrade
      required:
        - type
        - code
        - message
        - param
        - doc
        - recoverable
        - recovery
    ApiErrorBody:
      type: object
      properties:
        type:
          type: string
          enum:
            - rate_limited
            - invalid_request
            - auth
            - not_found
            - plan_limit
            - internal
            - conflict
            - idempotency_conflict
            - service_unavailable
            - tos_not_accepted
          description: High-level error category. Agents branch on this.
          example: auth
        code:
          type: string
          description: Stable machine-readable code.
          example: missing_authorization
        message:
          type: string
          description: Human-readable, localized via Accept-Language.
        doc:
          type: string
          description: Link to docs for this error code.
        param:
          type:
            - string
            - 'null'
        requestId:
          type: string
          example: req_30a9358b-70bd-44f3-aa5d-8983b558ad84
        requestLogUrl:
          type: string
        recoverable:
          type: boolean
        retryAfterMs:
          type:
            - integer
            - 'null'
        nextActions:
          type: array
          items:
            $ref: '#/components/schemas/ApiNextAction'
        upgrade:
          $ref: '#/components/schemas/ApiErrorUpgrade'
        requiredScopes:
          type: array
          items:
            type: string
        heldScopes:
          type: array
          items:
            type: string
      required:
        - type
        - code
        - message
        - doc
        - param
        - requestId
        - requestLogUrl
        - recoverable
        - retryAfterMs
        - nextActions
        - upgrade
    ExtraProductsCategory:
      type: object
      properties:
        title:
          type: string
        obligatory:
          type: boolean
        multipleOption:
          type: boolean
        maxOptions:
          type: integer
        minOptions:
          type: integer
        extraProducts:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ExtraProductOption'
      required:
        - title
        - obligatory
        - multipleOption
        - maxOptions
        - minOptions
    StorefrontLinks:
      type: object
      properties:
        previewUrl:
          type:
            - string
            - 'null'
        editUrl:
          type:
            - string
            - 'null'
        publicUrl:
          type:
            - string
            - 'null'
      required:
        - previewUrl
        - editUrl
        - publicUrl
    ApiNextAction:
      type: object
      properties:
        label:
          type: string
          example: Validate the JSON before retrying.
        method:
          type:
            - string
            - 'null'
          example: null
        url:
          type:
            - string
            - 'null'
          example: null
      required:
        - label
        - method
        - url
      description: A concrete action the agent can offer the user.
    ApiErrorUpgrade:
      type:
        - object
        - 'null'
      properties:
        currentPlan:
          type: string
          example: free
        requiredPlan:
          type: string
          example: pro
        upgradeUrl:
          type: string
          example: https://mareaalcalina.com/upgrade?planSource=api
        previewUrl:
          type: string
          description: Optional preview link the agent can surface.
      required:
        - currentPlan
        - requiredPlan
        - upgradeUrl
    ExtraProductOption:
      type: object
      properties:
        title:
          type: string
        price:
          type: number
          minimum: 0
        available:
          type: boolean
        stock:
          type:
            - integer
            - 'null'
      required:
        - title
        - price
        - available
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: mk_dev_* | mk_user_*
      description: >-
        Marea API key. `mk_dev_*` keys are developer-scoped (bootstrap, list
        users, register webhook). `mk_user_*` keys are user-scoped (manage that
        one user's storefronts/products). Scopes: `catalog:read`,
        `catalog:write`, `storefront:publish`, `me:verify`,
        `me:resendVerification`, `developer:bootstrap`, `developer:read`,
        `developer:issueUserKey`, `developer:webhooks`.
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Alternative to `Authorization: Bearer`. Same `mk_*` value. Use only when
        your environment cannot send the `Authorization` header.

````