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

# Create a shoppable link

> Create a shoppable Incarts link for a supported retailer intent or custom URL

<Tip>
  This endpoint accepts multiple request shapes for Amazon, Kroger, Walmart, Target, Instacart, and
  custom URLs. Use the **Body** tabs to switch schemas and the **example dropdown** above the code
  panel to load a pre-filled request.
</Tip>


## OpenAPI

````yaml openapi/incarts-public-api.v1.yaml POST /v1/links
openapi: 3.1.0
info:
  title: Incarts API
  version: 1.0.0
  summary: Create shoppable links and QR codes with the Incarts API.
  description: >
    Create shoppable Incarts links and QR codes for retailer, campaign, and
    commerce workflows.
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://incarts-api-qob6vapoca-uc.a.run.app
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Health
    description: Service health checks.
  - name: Links
    description: Link generation and retrieval.
  - name: Retailers
    description: Retailer discovery for link generation.
  - name: QR Codes
    description: QR codes associated with shoppable links.
paths:
  /v1/links:
    post:
      tags:
        - Links
      summary: Create a shoppable link
      description: >
        Creates a shoppable Incarts link for a supported retailer intent or a
        custom URL.


        Validation rules that are enforced by the API:

        - `custom_url` requires `customUrl`.

        - `add_to_cart` supports Walmart smart links plus direct Amazon and
        Target carts.

        - `product_detail` supports Amazon, Instacart, Kroger, Target, and
        Walmart.

        - `shopping_list` requires `retailer=instacart` and
        `options.instacart.shoppingList`.

        - `recipe` requires `retailer=instacart` and `options.instacart.recipe`.
      operationId: createLink
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/CorrelationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLinkRequest'
            examples:
              walmartAddToCart:
                summary: Walmart add-to-cart link with backups
                value:
                  projectId: proj_123
                  name: Summer grilling basket
                  publicName: Shop the grilling list
                  retailer: walmart
                  intent: add_to_cart
                  products:
                    - retailerProductId: '123456789'
                      quantity: 1
                      backupProductIds:
                        - '987654321'
                        - '555555555'
                  fallbackUrl: https://www.walmart.com/
                  options:
                    walmart:
                      allowPdp: true
                      cartMode: auto
                      fallbackMode: items
                      includeStoreId: auto
                  tracking:
                    utm:
                      source: newsletter
                      medium: email
                      campaign: summer-grilling
                    tags:
                      - grilling
                      - q3
              targetProductDetail:
                summary: Target PDP fallback link
                value:
                  projectId: proj_123
                  name: Target cereal PDP fallback
                  retailer: target
                  intent: product_detail
                  products:
                    - retailerProductId: '78025470'
                      backupProductIds:
                        - '87292144'
                  fallbackUrl: https://www.target.com/
                  location:
                    zipCode: '10001'
                  options:
                    target:
                      allowPdp: true
              instacartProductDetail:
                summary: Instacart product detail link for a specific store
                value:
                  projectId: proj_123
                  name: Instacart Walgreens Pepsi PDP
                  retailer: instacart
                  intent: product_detail
                  products:
                    - retailerProductId: '98343'
                      quantity: 1
                  options:
                    instacart:
                      routingMode: specific
                      retailer: walgreens
              instacartShoppingList:
                summary: Instacart shopping list link
                value:
                  projectId: proj_123
                  name: Instacart breakfast list
                  retailer: instacart
                  intent: shopping_list
                  options:
                    instacart:
                      routingMode: specific
                      retailerId: '648'
                      shoppingList:
                        title: Weekend breakfast
                        imageUrl: https://assets.example.com/weekend-breakfast.jpg
                        lineItems:
                          - name: eggs
                            quantity: 1
                            unit: dozen
                            upcs:
                              - '0001111000001'
                            catalogProductId: prod_eggs
                            backupProductIds:
                              - prod_large_brown_eggs
                            backupUpcs:
                              - '0001111000002'
                          - name: whole milk
                            quantity: 1
                            unit: gallon
                            upcs:
                              - '0001111000003'
              instacartRecipe:
                summary: Instacart recipe link
                value:
                  projectId: proj_123
                  name: Instacart tomato toast recipe
                  retailer: instacart
                  intent: recipe
                  options:
                    instacart:
                      routingMode: no_preference
                      recipe:
                        title: Tomato toast
                        author: Incarts
                        imageUrl: https://assets.example.com/tomato-toast.jpg
                        ingredients:
                          - name: tomatoes
                            quantity: 4
                            upcs:
                              - '0001111000004'
                            catalogProductId: prod_tomatoes
                            backupProductIds:
                              - prod_cherry_tomatoes
                            backupUpcs:
                              - '0001111000005'
                          - name: sourdough bread
                            quantity: 1
                            unit: loaf
      responses:
        '201':
          description: Link created.
          headers:
            Location:
              description: Absolute API URL for the created link resource.
              schema:
                type: string
                format: uri
            X-Correlation-ID:
              $ref: '#/components/headers/CorrelationId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkResponse'
              examples:
                created:
                  value:
                    data:
                      id: lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9
                      projectId: proj_123
                      name: Summer grilling basket
                      publicName: Shop the grilling list
                      retailer: walmart
                      intent: add_to_cart
                      status: active
                      shortLink: https://in2carts.com/abc123
                      shortId: abc123
                      qrCode:
                        id: qr_lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9_default
                        linkId: lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9
                        identifier: default
                        name: Default QR code
                        imageUrl: >-
                          https://firebasestorage.googleapis.com/v0/b/incarts.appspot.com/o/qrcodes%2Fexample.png?alt=media
                        encodedUrl: >-
                          https://in2carts.com/qr/qr_lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9_default
                        isDefault: true
                        createdAt: '2026-05-20T07:19:00Z'
                      createdAt: '2026-05-20T07:19:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Stable client-generated key used to safely retry write requests.
      schema:
        type: string
        minLength: 8
        maxLength: 128
      example: link-create-20260520-001
    CorrelationId:
      name: X-Correlation-ID
      in: header
      required: false
      description: >-
        Client-supplied request correlation ID. The API echoes this value when
        provided.
      schema:
        type: string
        minLength: 8
        maxLength: 128
      example: req_01JZ4TCZ7AG9P9W38V4VNQ7W4B
  schemas:
    CreateLinkRequest:
      description: >-
        Request body for creating a shoppable link. Choose the variant that
        matches the retailer and link type you want to create.
      oneOf:
        - $ref: '#/components/schemas/WalmartAddToCartLinkRequest'
        - $ref: '#/components/schemas/TargetProductDetailLinkRequest'
        - $ref: '#/components/schemas/InstacartProductDetailLinkRequest'
        - $ref: '#/components/schemas/InstacartShoppingListLinkRequest'
        - $ref: '#/components/schemas/InstacartRecipeLinkRequest'
        - $ref: '#/components/schemas/DirectRetailerLinkRequest'
        - $ref: '#/components/schemas/CustomUrlLinkRequest'
    LinkResponse:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/LinkResource'
    WalmartAddToCartLinkRequest:
      title: Walmart add-to-cart link
      type: object
      additionalProperties: false
      required:
        - projectId
        - name
        - retailer
        - intent
        - products
      properties:
        projectId:
          type: string
          minLength: 1
          maxLength: 128
          description: Project that owns the link.
          example: proj_123
        name:
          type: string
          minLength: 1
          maxLength: 160
          description: Internal name for the link, shown in your dashboards.
          example: Summer grilling basket
        publicName:
          type: string
          minLength: 1
          maxLength: 160
          description: Optional display name for public surfaces.
          example: Shop the grilling list
        retailer:
          type: string
          enum:
            - walmart
          description: Link provider used for generation.
        intent:
          type: string
          enum:
            - add_to_cart
          description: Creates a Walmart add-to-cart link.
        products:
          type: array
          minItems: 1
          maxItems: 100
          description: Retailer product selections for product and cart style links.
          items:
            $ref: '#/components/schemas/ProductSelection'
        customUrl:
          type: string
          format: uri
          description: Destination URL for `custom_url` links.
          example: https://www.example.com/landing-page
        fallbackUrl:
          type: string
          format: uri
          description: Fallback destination used when a better retailer URL can't be built.
          example: https://www.walmart.com/
        location:
          $ref: '#/components/schemas/RetailerLocation'
        options:
          $ref: '#/components/schemas/WalmartLinkOptionsEnvelope'
        tracking:
          $ref: '#/components/schemas/TrackingOptions'
        metadata:
          $ref: '#/components/schemas/Metadata'
        defaultQrCode:
          $ref: '#/components/schemas/DefaultQrCodeOptions'
    TargetProductDetailLinkRequest:
      title: Target product detail link
      type: object
      additionalProperties: false
      required:
        - projectId
        - name
        - retailer
        - intent
        - products
      properties:
        projectId:
          type: string
          minLength: 1
          maxLength: 128
          description: Project that owns the link.
          example: proj_123
        name:
          type: string
          minLength: 1
          maxLength: 160
          description: Internal name for the link, shown in your dashboards.
          example: Target cereal PDP fallback
        publicName:
          type: string
          minLength: 1
          maxLength: 160
          description: Optional display name for public surfaces.
          example: Shop the cereal
        retailer:
          type: string
          enum:
            - target
          description: Link provider used for generation.
        intent:
          type: string
          enum:
            - product_detail
          description: Creates a Target product detail link.
        products:
          type: array
          minItems: 1
          maxItems: 100
          description: Target product selections for the product detail link.
          items:
            $ref: '#/components/schemas/ProductSelection'
        customUrl:
          type: string
          format: uri
          description: Destination URL for `custom_url` links.
          example: https://www.example.com/landing-page
        fallbackUrl:
          type: string
          format: uri
          description: Fallback destination used when a better retailer URL can't be built.
          example: https://www.target.com/
        location:
          $ref: '#/components/schemas/RetailerLocation'
        options:
          $ref: '#/components/schemas/TargetLinkOptionsEnvelope'
        tracking:
          $ref: '#/components/schemas/TrackingOptions'
        metadata:
          $ref: '#/components/schemas/Metadata'
        defaultQrCode:
          $ref: '#/components/schemas/DefaultQrCodeOptions'
    InstacartProductDetailLinkRequest:
      title: Instacart product detail link
      type: object
      additionalProperties: false
      required:
        - projectId
        - name
        - retailer
        - intent
        - products
      properties:
        projectId:
          type: string
          minLength: 1
          maxLength: 128
          description: Project that owns the link.
          example: proj_123
        name:
          type: string
          minLength: 1
          maxLength: 160
          description: Internal name for the link, shown in your dashboards.
          example: Instacart Walgreens Pepsi PDP
        publicName:
          type: string
          minLength: 1
          maxLength: 160
          description: Optional display name for public surfaces.
          example: Shop Pepsi at Walgreens
        retailer:
          type: string
          enum:
            - instacart
          description: >-
            Use `instacart` for Instacart product detail links, then choose the
            actual store with `options.instacart.retailer`.
        intent:
          type: string
          enum:
            - product_detail
          description: Creates an Instacart product detail link.
        products:
          type: array
          minItems: 1
          maxItems: 1
          description: >-
            Instacart product selection for the product detail link. Use the
            Instacart product ID from the `/products/{id}` path, not a UPC.
          items:
            $ref: '#/components/schemas/ProductSelection'
        customUrl:
          type: string
          format: uri
          description: Destination URL for `custom_url` links.
          example: https://www.example.com/landing-page
        fallbackUrl:
          type: string
          format: uri
          description: Fallback destination used when a better retailer URL can't be built.
          example: https://www.instacart.com/
        location:
          $ref: '#/components/schemas/RetailerLocation'
        options:
          $ref: '#/components/schemas/InstacartLinkOptionsEnvelope'
        tracking:
          $ref: '#/components/schemas/TrackingOptions'
        metadata:
          $ref: '#/components/schemas/Metadata'
        defaultQrCode:
          $ref: '#/components/schemas/DefaultQrCodeOptions'
    InstacartShoppingListLinkRequest:
      title: Instacart shopping list link
      type: object
      additionalProperties: false
      required:
        - projectId
        - name
        - retailer
        - intent
        - options
      properties:
        projectId:
          type: string
          minLength: 1
          maxLength: 128
          description: Project that owns the link.
          example: proj_123
        name:
          type: string
          minLength: 1
          maxLength: 160
          description: Internal name for the link, shown in your dashboards.
          example: Instacart breakfast list
        publicName:
          type: string
          minLength: 1
          maxLength: 160
          description: Optional display name for public surfaces.
          example: Shop the breakfast list
        retailer:
          type: string
          enum:
            - instacart
          description: >-
            Use `instacart` for Instacart shopping list links, then choose the
            exact store with `options.instacart.retailerId` or ordered store
            preferences with `options.instacart.preferredRetailers`.
        intent:
          type: string
          enum:
            - shopping_list
          description: Creates an Instacart shopping list link.
        products:
          type: array
          minItems: 1
          maxItems: 100
          description: Retailer product selections for product and cart style links.
          items:
            $ref: '#/components/schemas/ProductSelection'
        customUrl:
          type: string
          format: uri
          description: Destination URL for `custom_url` links.
          example: https://www.example.com/landing-page
        fallbackUrl:
          type: string
          format: uri
          description: Fallback destination used when a better retailer URL can't be built.
          example: https://www.instacart.com/
        location:
          $ref: '#/components/schemas/RetailerLocation'
        options:
          $ref: '#/components/schemas/InstacartLinkOptionsEnvelope'
        tracking:
          $ref: '#/components/schemas/TrackingOptions'
        metadata:
          $ref: '#/components/schemas/Metadata'
        defaultQrCode:
          $ref: '#/components/schemas/DefaultQrCodeOptions'
    InstacartRecipeLinkRequest:
      title: Instacart recipe link
      type: object
      additionalProperties: false
      required:
        - projectId
        - name
        - retailer
        - intent
        - options
      properties:
        projectId:
          type: string
          minLength: 1
          maxLength: 128
          description: Project that owns the link.
          example: proj_123
        name:
          type: string
          minLength: 1
          maxLength: 160
          description: Internal name for the link, shown in your dashboards.
          example: Instacart tomato toast recipe
        publicName:
          type: string
          minLength: 1
          maxLength: 160
          description: Optional display name for public surfaces.
          example: Shop the recipe
        retailer:
          type: string
          enum:
            - instacart
          description: >-
            Use `instacart` for Instacart recipe links, then choose the exact
            store with `options.instacart.retailerId` or ordered store
            preferences with `options.instacart.preferredRetailers`.
        intent:
          type: string
          enum:
            - recipe
          description: Creates an Instacart recipe link.
        products:
          type: array
          minItems: 1
          maxItems: 100
          description: Retailer product selections for product and cart style links.
          items:
            $ref: '#/components/schemas/ProductSelection'
        customUrl:
          type: string
          format: uri
          description: Destination URL for `custom_url` links.
          example: https://www.example.com/landing-page
        fallbackUrl:
          type: string
          format: uri
          description: Fallback destination used when a better retailer URL can't be built.
          example: https://www.instacart.com/
        location:
          $ref: '#/components/schemas/RetailerLocation'
        options:
          $ref: '#/components/schemas/InstacartLinkOptionsEnvelope'
        tracking:
          $ref: '#/components/schemas/TrackingOptions'
        metadata:
          $ref: '#/components/schemas/Metadata'
        defaultQrCode:
          $ref: '#/components/schemas/DefaultQrCodeOptions'
    DirectRetailerLinkRequest:
      title: Direct retailer link
      type: object
      additionalProperties: false
      required:
        - projectId
        - name
        - retailer
        - intent
        - products
      oneOf:
        - title: Walmart product detail
          properties:
            retailer:
              type: string
              enum:
                - walmart
            intent:
              type: string
              enum:
                - product_detail
            products:
              type: array
              minItems: 1
              maxItems: 1
              items:
                $ref: '#/components/schemas/ProductSelection'
        - title: Target add-to-cart
          properties:
            retailer:
              type: string
              enum:
                - target
            intent:
              type: string
              enum:
                - add_to_cart
        - title: Amazon product detail
          properties:
            retailer:
              type: string
              enum:
                - amazon
            intent:
              type: string
              enum:
                - product_detail
            products:
              type: array
              minItems: 1
              maxItems: 1
              items:
                $ref: '#/components/schemas/ProductSelection'
        - title: Amazon add-to-cart
          properties:
            retailer:
              type: string
              enum:
                - amazon
            intent:
              type: string
              enum:
                - add_to_cart
        - title: Kroger product detail
          properties:
            retailer:
              type: string
              enum:
                - kroger
            intent:
              type: string
              enum:
                - product_detail
            products:
              type: array
              minItems: 1
              maxItems: 1
              items:
                $ref: '#/components/schemas/ProductSelection'
      properties:
        projectId:
          type: string
          minLength: 1
          maxLength: 128
          description: Project that owns the link.
        name:
          type: string
          minLength: 1
          maxLength: 160
          description: Internal name for the link, shown in your dashboards.
        publicName:
          type: string
          minLength: 1
          maxLength: 160
        retailer:
          $ref: '#/components/schemas/Retailer'
        intent:
          $ref: '#/components/schemas/LinkIntent'
        products:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/ProductSelection'
        customUrl:
          type: string
          format: uri
        fallbackUrl:
          type: string
          format: uri
        location:
          $ref: '#/components/schemas/RetailerLocation'
        options:
          $ref: '#/components/schemas/LinkOptions'
        tracking:
          $ref: '#/components/schemas/TrackingOptions'
        metadata:
          $ref: '#/components/schemas/Metadata'
        defaultQrCode:
          $ref: '#/components/schemas/DefaultQrCodeOptions'
    CustomUrlLinkRequest:
      title: Custom URL link
      type: object
      additionalProperties: false
      required:
        - projectId
        - name
        - retailer
        - intent
        - customUrl
      properties:
        projectId:
          type: string
          minLength: 1
          maxLength: 128
          description: Project that owns the link.
          example: proj_123
        name:
          type: string
          minLength: 1
          maxLength: 160
          description: Internal name for the link, shown in your dashboards.
          example: Campaign landing page
        publicName:
          type: string
          minLength: 1
          maxLength: 160
          description: Optional display name for public surfaces.
          example: View the campaign
        retailer:
          type: string
          enum:
            - custom
          description: Use `custom` for direct custom URL links.
        intent:
          type: string
          enum:
            - custom_url
          description: Creates a shoppable Incarts short link for a custom destination URL.
        products:
          type: array
          minItems: 1
          maxItems: 100
          description: Retailer product selections for product and cart style links.
          items:
            $ref: '#/components/schemas/ProductSelection'
        customUrl:
          type: string
          format: uri
          description: Destination URL for `custom_url` links.
          example: https://www.example.com/landing-page
        fallbackUrl:
          type: string
          format: uri
          description: Fallback destination used when a better retailer URL can't be built.
          example: https://www.example.com/
        location:
          $ref: '#/components/schemas/RetailerLocation'
        options:
          $ref: '#/components/schemas/LinkOptions'
        tracking:
          $ref: '#/components/schemas/TrackingOptions'
        metadata:
          $ref: '#/components/schemas/Metadata'
        defaultQrCode:
          $ref: '#/components/schemas/DefaultQrCodeOptions'
    LinkResource:
      type: object
      additionalProperties: false
      required:
        - id
        - projectId
        - name
        - retailer
        - intent
        - status
        - shortLink
        - shortId
        - createdAt
      properties:
        id:
          type: string
          description: Stable identifier for the shoppable link.
          example: lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9
        projectId:
          type: string
          example: proj_123
        name:
          type: string
          example: Summer grilling basket
        publicName:
          type: string
          example: Shop the grilling list
        retailer:
          $ref: '#/components/schemas/Retailer'
        intent:
          $ref: '#/components/schemas/LinkIntent'
        status:
          type: string
          enum:
            - active
            - inactive
        shortLink:
          type: string
          format: uri
          example: https://in2carts.com/abc123
        shortId:
          type: string
          example: abc123
        urlType:
          type: string
          enum:
            - cart
            - pdp
            - long_link
            - custom
            - instacart_list
            - instacart_recipe
          description: Kind of destination the short link points to.
        products:
          type: array
          items:
            $ref: '#/components/schemas/ProductSelection'
        qrCode:
          $ref: '#/components/schemas/QrCodeResource'
          description: Present when best-effort default QR generation succeeds.
        metadata:
          $ref: '#/components/schemas/Metadata'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    ProductSelection:
      type: object
      additionalProperties: false
      required:
        - retailerProductId
      properties:
        retailerProductId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Retailer-native product identifier, such as an Amazon ASIN, Kroger
            product ID, Walmart item ID, Target TCIN, or numeric Instacart
            product ID.
          example: '123456789'
        quantity:
          type: integer
          minimum: 1
          maximum: 999
          default: 1
        backupProductIds:
          type: array
          maxItems: 25
          description: >-
            Ordered backup product IDs to try when the primary product is
            unavailable.
          items:
            type: string
            minLength: 1
            maxLength: 128
          example:
            - '987654321'
            - '555555555'
    RetailerLocation:
      type: object
      additionalProperties: false
      properties:
        zipCode:
          type: string
          minLength: 3
          maxLength: 16
          example: '10001'
        storeId:
          type: string
          minLength: 1
          maxLength: 64
          example: '1234'
    WalmartLinkOptionsEnvelope:
      type: object
      additionalProperties: false
      required:
        - walmart
      properties:
        walmart:
          $ref: '#/components/schemas/WalmartLinkOptions'
    TrackingOptions:
      type: object
      additionalProperties: false
      properties:
        utm:
          $ref: '#/components/schemas/UtmParameters'
        linkValue:
          type: number
          minimum: 0
        tags:
          type: array
          maxItems: 100
          items:
            type: string
            minLength: 1
            maxLength: 80
    Metadata:
      type: object
      additionalProperties: true
      description: >-
        Caller-supplied metadata stored with the resource. Do not put secrets
        here.
      example:
        campaignId: cmp_123
    DefaultQrCodeOptions:
      type: object
      additionalProperties: false
      properties:
        identifier:
          type: string
          pattern: ^[A-Za-z0-9-]{3,64}$
          example: default
        name:
          type: string
          minLength: 1
          maxLength: 120
          example: Default QR code
    TargetLinkOptionsEnvelope:
      type: object
      additionalProperties: false
      required:
        - target
      properties:
        target:
          $ref: '#/components/schemas/TargetLinkOptions'
    InstacartLinkOptionsEnvelope:
      type: object
      additionalProperties: false
      required:
        - instacart
      properties:
        instacart:
          $ref: '#/components/schemas/InstacartLinkOptions'
    Retailer:
      type: string
      enum:
        - amazon
        - kroger
        - walmart
        - target
        - instacart
        - custom
    LinkIntent:
      type: string
      enum:
        - add_to_cart
        - product_detail
        - shopping_list
        - recipe
        - custom_url
    LinkOptions:
      type: object
      additionalProperties: false
      properties:
        walmart:
          $ref: '#/components/schemas/WalmartLinkOptions'
        target:
          $ref: '#/components/schemas/TargetLinkOptions'
        instacart:
          $ref: '#/components/schemas/InstacartLinkOptions'
    QrCodeResource:
      type: object
      additionalProperties: false
      required:
        - id
        - linkId
        - identifier
        - name
        - imageUrl
        - encodedUrl
        - isDefault
        - createdAt
      properties:
        id:
          type: string
          example: qr_lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9_default
        linkId:
          type: string
          example: lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9
        identifier:
          type: string
          pattern: ^[A-Za-z0-9-]{3,64}$
          example: default
        name:
          type: string
          example: Default QR code
        imageUrl:
          type: string
          format: uri
          example: >-
            https://firebasestorage.googleapis.com/v0/b/incarts.appspot.com/o/qrcodes%2Fexample.png?alt=media
        encodedUrl:
          type: string
          format: uri
          example: https://in2carts.com/qr/qr_lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9_default
        isDefault:
          type: boolean
        metadata:
          $ref: '#/components/schemas/Metadata'
        createdAt:
          type: string
          format: date-time
    ErrorObject:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - correlationId
      properties:
        code:
          type: string
          description: Stable machine-readable error code.
          example: validation_failed
        message:
          type: string
          description: Human-readable error summary.
          example: products is required for walmart add_to_cart links.
        correlationId:
          type: string
          example: req_01JZ4TCZ7AG9P9W38V4VNQ7W4B
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetail'
    WalmartLinkOptions:
      type: object
      additionalProperties: false
      properties:
        allowPdp:
          type: boolean
          default: false
          description: >-
            Allow single-item Walmart links to resolve to a product page when
            cart construction is not appropriate.
        cartMode:
          type: string
          enum:
            - auto
            - offers
            - items
          default: auto
        fallbackMode:
          type: string
          enum:
            - offers
            - items
          default: items
        includeStoreId:
          type: string
          enum:
            - never
            - auto
            - always
          default: auto
        preferItemsForWalmart:
          type: boolean
          default: true
        preferOffersForMarketplace:
          type: boolean
          default: false
    UtmParameters:
      type: object
      additionalProperties: false
      properties:
        source:
          type: string
          maxLength: 120
        medium:
          type: string
          maxLength: 120
        campaign:
          type: string
          maxLength: 120
        term:
          type: string
          maxLength: 120
        content:
          type: string
          maxLength: 120
    TargetLinkOptions:
      type: object
      additionalProperties: false
      properties:
        allowPdp:
          type: boolean
          default: true
          description: >-
            Target v1 links resolve to product detail pages or fallback URLs,
            not add-to-cart URLs.
    InstacartLinkOptions:
      type: object
      additionalProperties: false
      properties:
        routingMode:
          type: string
          enum:
            - specific
            - preferred
            - no_preference
          default: no_preference
        retailer:
          type: string
          description: >-
            Instacart store slug. For product detail links, Incarts appends this
            as `retailerSlug={retailer}` when `routingMode=specific`. Shopping
            list and recipe links use `retailerId` instead. This is not the
            top-level `retailer` provider field.
          example: walgreens
        retailerId:
          type: string
          minLength: 1
          description: >-
            Instacart retailer id for exact store selection on shopping list and
            recipe links when `routingMode=specific`. Product detail links use
            `retailerSlug`, so send the store slug in `retailer` for PDP
            routing.
          example: '648'
        preferredRetailers:
          type: array
          description: >-
            Ordered Instacart store slugs when `routingMode=preferred`. Use
            `retailerId` for exact shopping list or recipe store routing with
            `routingMode=specific`.
          items:
            type: string
          example:
            - kroger
            - aldi
        shoppingList:
          $ref: '#/components/schemas/InstacartShoppingList'
        recipe:
          $ref: '#/components/schemas/InstacartRecipe'
    ErrorDetail:
      type: object
      additionalProperties: false
      required:
        - field
        - message
      properties:
        field:
          type: string
          example: products
        message:
          type: string
          example: At least one product is required.
    InstacartShoppingList:
      type: object
      additionalProperties: false
      required:
        - title
        - lineItems
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 160
        imageUrl:
          type: string
          format: uri
        instructions:
          type: string
          maxLength: 4000
        lineItems:
          type: array
          minItems: 1
          maxItems: 200
          items:
            $ref: '#/components/schemas/InstacartLineItem'
    InstacartRecipe:
      type: object
      additionalProperties: false
      required:
        - title
        - ingredients
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 160
        imageUrl:
          type: string
          format: uri
        author:
          type: string
          maxLength: 160
        servings:
          type: integer
          minimum: 1
        cookingTimeMinutes:
          type: integer
          minimum: 0
        instructions:
          type: array
          items:
            type: string
        expiresInDays:
          type: integer
          minimum: 1
          maximum: 365
        ingredients:
          type: array
          minItems: 1
          maxItems: 200
          items:
            $ref: '#/components/schemas/InstacartRecipeIngredient'
        landingPageConfiguration:
          type: object
          additionalProperties: false
          properties:
            partnerLinkbackUrl:
              type: string
              format: uri
            enablePantryItems:
              type: boolean
    InstacartLineItem:
      type: object
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        quantity:
          type: number
          minimum: 0
          default: 1
        unit:
          type: string
          maxLength: 64
          example: each
        upcs:
          type: array
          items:
            type: string
          example:
            - '0001111000001'
          description: >-
            UPCs that help Instacart match this item. Include primary and
            acceptable backup UPCs when you want Instacart to consider
            alternates.
        catalogProductId:
          type: string
          minLength: 1
          maxLength: 128
          description: >-
            Optional Incarts catalog product ID for dashboard metadata. This is
            not sent to Instacart Connect.
          example: prod_eggs
        backupProductIds:
          type: array
          maxItems: 25
          description: >-
            Optional Incarts catalog product IDs to preserve as backup choices
            for this item. To influence Instacart matching, also include the
            backup UPCs in `backupUpcs` or `upcs`.
          items:
            type: string
            minLength: 1
            maxLength: 128
          example:
            - prod_large_brown_eggs
        backupUpcs:
          type: array
          maxItems: 25
          description: >-
            UPCs for backup choices. The API merges these into the Instacart
            `upcs` field and preserves them on the link record for dashboard
            editing.
          items:
            type: string
            minLength: 1
            maxLength: 64
          example:
            - '0001111000002'
        displayText:
          type: string
          maxLength: 200
        measurements:
          type: array
          items:
            $ref: '#/components/schemas/InstacartMeasurement'
        filters:
          $ref: '#/components/schemas/InstacartFilters'
    InstacartRecipeIngredient:
      allOf:
        - $ref: '#/components/schemas/InstacartLineItem'
    InstacartMeasurement:
      type: object
      additionalProperties: false
      properties:
        quantity:
          type: number
          minimum: 0
        unit:
          type: string
          maxLength: 64
    InstacartFilters:
      type: object
      additionalProperties: false
      properties:
        brandFilters:
          type: array
          items:
            type: string
        healthFilters:
          type: array
          items:
            type: string
          example:
            - ORGANIC
            - GLUTEN_FREE
  headers:
    CorrelationId:
      description: >-
        Request correlation ID generated by the API or echoed from
        `X-Correlation-ID`.
      schema:
        type: string
      example: req_01JZ4TCZ7AG9P9W38V4VNQ7W4B
  responses:
    BadRequest:
      description: Request body, path, or header is malformed.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: API key is missing or invalid.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        API key is valid but does not have access to the requested project or
        scope.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: >-
        Idempotency conflict, duplicate identifier, or conflicting resource
        state.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnprocessableEntity:
      description: >-
        Request is syntactically valid but violates business rules or retailer
        capabilities.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unsupportedCapability:
              value:
                error:
                  code: unsupported_retailer_intent
                  message: Kroger add-to-cart links are not supported.
                  correlationId: req_01JZ4TCZ7AG9P9W38V4VNQ7W4B
    TooManyRequests:
      description: Rate limit exceeded.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Unexpected server error.
      headers:
        X-Correlation-ID:
          $ref: '#/components/headers/CorrelationId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Incarts-API-Key

````