@redotech/redo-api-schema/lib/openapi.yaml

Common definitions for Redo API

openapi: 3.1.0
info:
  contact:
    email: engineering-admin@getredo.com
    name: Redo Engineering
  description: |
    ## Endpoints

    Endpoints are authenticated using the Bearer authorization scheme, using the
    REDO_API_SECRET.

    ```txt
    GET /v2.2/resource HTTP/1.1
    Authorization: Bearer 77bb7598b7a972475cc7c7e171ec33af
    Host: api.getredo.com
    ```

    ## Webhooks

    Webhooks are authenticated using the Bearer authorization scheme, using
    a secret supplied by the subscriber.

    ```txt
    POST /events HTTP/1.1
    Authorization: Bearer subscriberauth123
    Host: subscriber.example.com
    ```

    Webhook events are delivered in order for each individual subject (e.g.
    return).

    If the response is not a 2xx status code, the event will be retried multiple
    times before discarding it.
  title: Redo API
  version: 2.2.1
servers:
  - url: https://api.getredo.com/v2.2
tags:
  - name: Checkout Buttons
  - name: Coverage Info
  - name: Coverage Products
  - name: Custom Events
  - name: Customer Portal
  - name: Customer Subscriptions
  - name: Customers
  - name: Inbound Shipments
  - name: Inventory Items
  - name: Inventory Levels
  - name: Invoices
  - name: Merchant Admin
  - name: Orders
  - name: Products
  - name: Returns
  - name: Storefront
  - name: Webhooks
paths:
  /stores/{storeId}/checkout-buttons-ui:
    description: Generate HTML and CSS for checkout buttons to enable or disable returns coverage.
    get:
      description: Generate rendered HTML and CSS for checkout buttons.
      operationId: Checkout buttons UI
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  css:
                    description: Boilerplate checkout button CSS, plus any merchant configured styles or A/B tests.
                    title: Checkout buttons CSS
                    type: string
                  html:
                    description: Boilerplate checkout button HTML
                    title: Checkout buttons HTML
                    type: string
          description: Success
      summary: Checkout Buttons UI
      tags:
        - Checkout Buttons
    summary: Checkout buttons UI
  /stores/{storeId}/coverage-info:
    description: Navigate to the coverage info page.
    get:
      description: Navigate to the coverage info page.
      operationId: Coverage info navigate
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      responses:
        '302':
          description: Redirect
      summary: Navigate to Coverage Info
      tags:
        - Coverage Info
    summary: Coverage info
  /stores/{storeId}/coverage-products:
    description: Available coverage products.
    post:
      description: Get available coverage products.
      operationId: Coverage products
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                cart:
                  $ref: '#/components/schemas/storefront-cart.schema'
                customer:
                  $ref: '#/components/schemas/storefront-customer.schema'
                products:
                  description: Product information.
                  items:
                    properties:
                      id:
                        description: Identifier of the product.
                        title: ID
                        type: string
                    required:
                      - id
                    type: object
                  deprecated: true
                  title: Products
                  type: array
                variants:
                  description: Variant information.
                  items:
                    properties:
                      height:
                        $ref: '#/components/schemas/length.schema'
                        description: Height of an item.
                        title: Height
                      id:
                        description: Identifier of the variant.
                        title: ID
                        type: string
                      length:
                        $ref: '#/components/schemas/length.schema'
                        description: Length of an item.
                        title: Length
                      title:
                        title: Title
                        type: string
                      weight:
                        $ref: '#/components/schemas/weight.schema'
                        description: Weight of an item.
                        title: Weight
                      width:
                        $ref: '#/components/schemas/length.schema'
                        description: Width of an item.
                        title: Width
                    required:
                      - id
                    type: object
                  deprecated: true
                  title: Variants
                  type: array
              required:
                - cart
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  coverageProducts:
                    description: Coverage products.
                    items:
                      $ref: '#/components/schemas/coverage-product.schema'
                    title: Coverage Products
                    type: array
                required:
                  - coverageProducts
                type: object
          description: Success
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      summary: Coverage Products
      tags:
        - Coverage Products
    summary: Coverage products
  /stores/{storeId}/events:
    post:
      description: |
        Create a custom event to trigger flows with merchant-defined event names and properties.

        Custom events allow merchants to trigger flows based on events from their own systems.
        Events can include custom properties that are accessible in email and SMS templates,
        and are persisted for segmentation and historical queries.

        ## Identity Resolution
        The API resolves customers using the following priority order:
        1. `customer.id` — Redo customer ObjectId (highest priority)
        2. `customer.email` — customer email address
        3. `customer.phoneNumber` — customer phone number

        At least one identifier must be provided. If no matching customer is found, one will
        be created automatically. If `customer.id` is provided but not found, the API falls
        back to email/phone rather than returning 404.

        ## Datetime Formatting
        All datetime values must be formatted as ISO 8601 (RFC 3339) strings, e.g., `2026-04-02T12:00:00Z`.
        This applies to `eventTimestamp`, any date-valued properties in `data`, and any date-valued `customFields`.
        Strings matching this format are automatically detected and indexed as dates for segmentation.

        ## Rate Limiting
        This endpoint is rate-limited to 100 requests per second per store.
      operationId: Custom event create
      x-express-openapi-disable-validation-middleware: true
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/custom-event-request.schema'
            examples:
              full_example:
                summary: Every field populated
                value:
                  eventName: Purchase Milestone Reached
                  customer:
                    id: 665f1a2b3c4d5e6f7a8b9c0d
                    email: stewart@example.com
                    phoneNumber: '+11234567890'
                    firstName: Stewart
                    lastName: Thompson
                    location:
                      street1: 123 Main St
                      street2: Apt 4B
                      city: Seattle
                      state: Washington
                      stateCode: WA
                      postalCode: '98101'
                      country: United States
                      countryCode: US
                      ianaTimeZoneName: America/Los_Angeles
                      latitude: 47.6062
                      longitude: -122.3321
                    customFields:
                      Age at Signup: 25
                      Birthday: '1976-07-04T12:00:00Z'
                      Loyalty Tier: Gold
                      Accepts Marketing: true
                  eventTimestamp: '2026-04-02T12:00:00Z'
                  value: 299.99
                  valueCurrency: USD
                  uniqueId: milestone-test-001
                  data:
                    Milestone Type: 100th_purchase
                    Total Spent: 5000
                    VIP Tier: gold
                    Enrolled At: '2025-01-01T00:00:00Z'
                    Campaign Source: email_drip
                    Last Purchase Date: '2026-03-15T00:00:00Z'
                    $extra:
                      Most Recent Order IDs:
                        - 1
                        - 2
                        - 3
                      Profile Snapshot:
                        tier: gold
                        memberSince: '2024-01-01'
              medium_example:
                summary: Event with customer profile and data
                value:
                  eventName: Order Placed
                  customer:
                    email: stewart@example.com
                    firstName: Stewart
                    lastName: Thompson
                    customFields:
                      Birthday: '1976-07-04T12:00:00Z'
                      Loyalty Tier: Gold
                  value: 149.99
                  valueCurrency: USD
                  data:
                    Order Id: ord_456
                    Item Count: 3
                    Category: apparel
              minimal:
                summary: Required fields only
                value:
                  eventName: Page Viewed
                  customer:
                    email: stewart@example.com
        required: true
      responses:
        '202':
          description: Event accepted and queued for processing. No response body is returned.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Invalid request body or missing required customer identifier
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Store not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Rate limit exceeded
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Create custom event
      tags:
        - Custom Events
  /stores/{storeId}/events/bulk:
    post:
      description: |
        Create multiple custom events in a single request. Accepts up to 100 events per request.

        Each event is validated independently. The response includes per-event results, allowing
        partial failures — some events may be accepted while others are rejected due to validation
        errors.

        ## Identity Resolution
        Each event resolves customers independently using the same priority order as the
        single-event endpoint:
        1. `customer.id` — Redo customer ObjectId (highest priority)
        2. `customer.email` — customer email address
        3. `customer.phoneNumber` — customer phone number

        At least one identifier must be provided per event. If no matching customer is found,
        one will be created automatically.

        ## Rate Limiting
        This endpoint is rate-limited to 100 requests per second per store.
      operationId: Bulk create custom events
      x-express-openapi-disable-validation-middleware: true
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bulk-custom-event-request.schema'
            examples:
              mixed_events:
                summary: Bulk event creation with multiple event types
                value:
                  events:
                    - eventName: User Registered
                      customer:
                        email: alice@example.com
                      data:
                        Plan Type: premium
                    - eventName: Purchase Completed
                      customer:
                        email: bob@example.com
                      data:
                        Order Total: 99.99
                        Item Count: 3
                      value: 99.99
                      valueCurrency: USD
                      uniqueId: order-456
        required: true
      responses:
        '202':
          description: Bulk request accepted and queued for processing. No response body is returned.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Invalid request body (e.g., events array missing or exceeds 100 items)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Store not found
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Rate limit exceeded
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Bulk create custom events
      tags:
        - Custom Events
  /stores/{storeId}/customer-portal:
    description: Navigate to the customer portal.
    get:
      description: Navigate to the customer portal.
      operationId: Customer portal navigate
      parameters:
        - $ref: '#/components/parameters/store-id.param'
        - description: HMAC-SHA256 JWT of {"iss":"<partnerId>","sub":"<storeId>/<customerId>"}
          in: query
          name: token
          schema:
            type: string
        - description: Order ID
          in: query
          name: order_id
          schema:
            type: string
      responses:
        '302':
          description: Redirect
      summary: Navigate to Customer Portal
      tags:
        - Customer Portal
    summary: Customer portal
  /stores/{storeId}/customer-subscriptions:
    description: Update customer subscription preferences for marketing and transactional messages.
    post:
      description: Update customer subscription status for SMS and email marketing and transactional messages. If the customer with that phone number or email does not exist, it will be created.
      operationId: Customer subscriptions update
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                email:
                  $ref: '#/components/schemas/customer-subscription-email.schema'
                sms:
                  $ref: '#/components/schemas/customer-subscription-sms.schema'
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer-subscription-update-response.schema'
          description: Success
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Bad Request
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Internal Server Error
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Update Customer Subscriptions
      tags:
        - Customer Subscriptions
    summary: Customer subscriptions
  /stores/{storeId}/customers:
    description: Manage customer profiles.
    get:
      description: |
        Retrieve a customer profile by email address.

        The response includes the customer's name, contact information, location,
        and any custom fields associated with the profile. Custom fields are returned
        as `{ fieldName: value }` pairs.
      operationId: Customer get
      parameters:
        - $ref: '#/components/parameters/store-id.param'
        - description: Customer email address
          in: query
          name: email
          required: true
          schema:
            format: email
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer-read.schema'
              example:
                id: 67bd4f1a2e3c8d001a5f9b12
                email: jane@example.com
                firstName: Jane
                lastName: Smith
                phoneNumber: '+11234567890'
                location:
                  street1: 123 Main St
                  street2: Suite 12
                  city: Seattle
                  state: Washington
                  stateCode: WA
                  postalCode: '98101'
                  country: United States
                  countryCode: US
                  latitude: 47.6062
                  longitude: -122.3321
                customFields:
                  pricing_plan: com.example.yearly
                  status: Active
                  subscription_source: web
                  loyalty_points: 1250
                  vip_member: true
                createdAt: '2026-02-20T18:30:00.000Z'
                updatedAt: '2026-02-24T12:15:00.000Z'
          description: Customer found
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Missing or invalid email parameter
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: No customer found for that email
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Internal server error
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Get customer by email
      tags:
        - Customers
    put:
      description: |
        Create or update a customer profile. Uses the email address as the upsert
        key — if a customer with that email exists, their profile is updated;
        otherwise, a new customer is created.

        ## Profile fields
        - `firstName` and `lastName` are set directly on the customer. A full
          display name is automatically generated from these fields.
        - `phoneNumber` should be in E.164 format (e.g., `+12345678900`). If the
          number is new, it is added to the customer's contact information.

        ## Location
        Providing `location` sets the customer's current location. Only the fields
        you include are updated.

        ## Custom fields
        Use `customFields` to store arbitrary key-value data on the customer (e.g.,
        `pricing_plan`, `subscription_source`). Values can be strings, numbers, or
        booleans. If a custom field doesn't exist yet, it is created automatically.
      operationId: Customer upsert
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/customer-upsert-request.schema'
            examples:
              create_customer:
                summary: Create a new customer with custom fields
                value:
                  email: jane@example.com
                  firstName: Jane
                  lastName: Smith
                  phoneNumber: '+11234567890'
                  location:
                    street1: 123 Main St
                    street2: Suite 12
                    city: Seattle
                    state: Washington
                    stateCode: WA
                    postalCode: '98101'
                    country: United States
                    countryCode: US
                    latitude: 47.6062
                    longitude: -122.3321
                  customFields:
                    pricing_plan: com.example.yearly
                    status: Active
                    subscription_source: web
                    loyalty_points: 1250
                    vip_member: true
              update_custom_fields:
                summary: Update only custom fields for an existing customer
                value:
                  email: jane@example.com
                  customFields:
                    status: Cancelled
                    cancellation_reason: Too expensive
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer-upsert-response.schema'
              example:
                id: 67bd4f1a2e3c8d001a5f9b12
                email: jane@example.com
                created: false
          description: Existing customer updated
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer-upsert-response.schema'
              example:
                id: 67bd4f1a2e3c8d001a5f9b12
                email: jane@example.com
                created: true
          description: New customer created
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Invalid request body or invalid email address
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Internal server error
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Create or update customer
      tags:
        - Customers
    summary: Customers
  /stores/{storeId}/inbound-shipments:
    description: Inbound shipments for a store.
    get:
      description: List inbound shipments, representing inventory in transit or received at a location. Sorted by most recently updated first.
      operationId: Inbound shipments list
      parameters:
        - $ref: '#/components/parameters/page-continue.param'
        - $ref: '#/components/parameters/page-size.param'
        - $ref: '#/components/parameters/inbound-shipment-status.param'
        - $ref: '#/components/parameters/location-id.param'
        - $ref: '#/components/parameters/created-at-min.param'
        - $ref: '#/components/parameters/created-at-max.param'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  inbound_shipments:
                    items:
                      $ref: '#/components/schemas/inbound-shipment-list.schema'
                    type: array
                required:
                  - inbound_shipments
                type: object
          description: Success
          headers:
            X-Page-Next:
              $ref: '#/components/headers/page-next.header'
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: List Inbound Shipments
      tags:
        - Inbound Shipments
    parameters:
      - $ref: '#/components/parameters/store-id.param'
    summary: Inbound Shipments
  /stores/{storeId}/inbound-shipments/{inboundShipmentId}:
    description: Single inbound shipment.
    get:
      description: Get a single inbound shipment by ID. Returns additional detail fields including purchase orders, transfer orders, files, volume, item discrepancies, and packing modes.
      operationId: Inbound shipment get
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  inbound_shipment:
                    $ref: '#/components/schemas/inbound-shipment-detail.schema'
                required:
                  - inbound_shipment
                type: object
          description: Success
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Inbound shipment not found
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Get Inbound Shipment
      tags:
        - Inbound Shipments
    parameters:
      - $ref: '#/components/parameters/store-id.param'
      - $ref: '#/components/parameters/inbound-shipment-id.param'
    summary: Inbound Shipment
  /stores/{storeId}/inventory-items:
    description: In-stock inventory items for a store.
    get:
      description: List in-stock inventory items. Only items with on-hand quantity greater than zero are returned. Sorted by most recently updated first.
      operationId: Inventory items list
      parameters:
        - $ref: '#/components/parameters/page-continue.param'
        - $ref: '#/components/parameters/page-size.param'
        - $ref: '#/components/parameters/location-id.param'
        - $ref: '#/components/parameters/inventory-item-kind.param'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  inventory_items:
                    items:
                      $ref: '#/components/schemas/inventory-item-list.schema'
                    type: array
                required:
                  - inventory_items
                type: object
          description: Success
          headers:
            X-Page-Next:
              $ref: '#/components/headers/page-next.header'
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: List Inventory Items
      tags:
        - Inventory Items
    parameters:
      - $ref: '#/components/parameters/store-id.param'
    summary: Inventory Items
  /stores/{storeId}/inventory-items/{inventoryItemId}:
    description: Single inventory item.
    get:
      description: Get a single in-stock inventory item by ID.
      operationId: Inventory item get
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  inventory_item:
                    $ref: '#/components/schemas/inventory-item-list.schema'
                required:
                  - inventory_item
                type: object
          description: Success
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Inventory item not found
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Get Inventory Item
      tags:
        - Inventory Items
    parameters:
      - $ref: '#/components/parameters/store-id.param'
      - $ref: '#/components/parameters/inventory-item-id.param'
    summary: Inventory Item
  /stores/{storeId}/inventory-levels:
    description: Inventory levels for a store.
    get:
      description: List inventory levels, representing the aggregate quantity of a product at a specific location. Sorted by most recently updated first.
      operationId: Inventory levels list
      parameters:
        - $ref: '#/components/parameters/page-continue.param'
        - $ref: '#/components/parameters/page-size.param'
        - $ref: '#/components/parameters/location-id.param'
        - $ref: '#/components/parameters/product-id.param'
        - $ref: '#/components/parameters/sku.param'
        - $ref: '#/components/parameters/updated-at-min.param'
        - $ref: '#/components/parameters/updated-at-max.param'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  inventory_levels:
                    items:
                      $ref: '#/components/schemas/inventory-level-list.schema'
                    type: array
                required:
                  - inventory_levels
                type: object
          description: Success
          headers:
            X-Page-Next:
              $ref: '#/components/headers/page-next.header'
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: List Inventory Levels
      tags:
        - Inventory Levels
    parameters:
      - $ref: '#/components/parameters/store-id.param'
    summary: Inventory Levels
  /stores/{storeId}/inventory-levels/{inventoryLevelId}:
    description: Single inventory level.
    get:
      description: Get a single inventory level by ID. Returns additional detail fields including external IDs, creation timestamp, product UPC, and image URL.
      operationId: Inventory level get
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  inventory_level:
                    $ref: '#/components/schemas/inventory-level-detail.schema'
                required:
                  - inventory_level
                type: object
          description: Success
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Inventory level not found
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Get Inventory Level
      tags:
        - Inventory Levels
    parameters:
      - $ref: '#/components/parameters/store-id.param'
      - $ref: '#/components/parameters/inventory-level-id.param'
    summary: Inventory Level
  /invoices/pending/items.csv:
    description: Return invoice CSV file.
    get:
      description: Get an invoice as a CSV.
      operationId: Invoice pending csv get
      responses:
        '200':
          content:
            text/csv:
              schema:
                format: binary
                type: string
          description: Success
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Pending Invoice (CSV)
      tags:
        - Invoices
    summary: Pending invoice
  /invoices/{invoiceId}/items.csv:
    description: Return invoice CSV file.
    get:
      description: Get an invoice as a CSV.
      operationId: Invoice csv get
      parameters:
        - $ref: '#/components/parameters/invoice-id.param'
      responses:
        '200':
          content:
            text/csv:
              schema:
                format: binary
                type: string
          description: Success
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Invoice (CSV)
      tags:
        - Invoices
    summary: Invoice
  /stores/{storeId}/invoices:
    description: Return a list of invoices.
    get:
      description: Get a list of invoices.
      operationId: Invoice list
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  invoices:
                    items:
                      $ref: '#/components/schemas/invoice.schema'
                    type: array
                required:
                  - invoices
                type: object
          description: Success
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: List Invoices
      tags:
        - Invoices
    summary: Invoice
  /stores/{storeId}/admin:
    description: Navigate to the merchant admin page.
    get:
      description: Navigate to the merchant admin page.
      operationId: Merchant admin navigate
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      responses:
        '302':
          description: Redirect
      summary: Navigate to Merchant Admin
      tags:
        - Merchant Admin
    summary: Merchant admin
  /stores/{storeId}/orders:
    description: Orders collection.
    post:
      description: Create a new order in the system with line items, customer information, and shipping details.
      operationId: Order create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/orders-api-create-order-request.schema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-create-order-response.schema'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Bad Request (validation error)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Unauthorized (invalid or missing API token)
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Conflict (duplicate order ID)
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Create Order
      tags:
        - Orders
    parameters:
      - $ref: '#/components/parameters/store-id.param'
    summary: Orders
  /stores/{storeId}/orders/{orderId}:
    description: Single order operations.
    get:
      description: Retrieve an existing order from the system, including all fulfillments. The orderId parameter can be either the external order ID you provided when creating the order, or the internal Redo order ID returned from the create order response.
      operationId: Order get
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-get-order-response.schema'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Unauthorized (invalid or missing API token)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Order not found
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Get Order
      tags:
        - Orders
    delete:
      description: Delete an order from the system. The orderId parameter can be either the external order ID you provided when creating the order, or the internal Redo order ID returned from the create order response.
      operationId: Order delete
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-delete-order-response.schema'
          description: Success
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Unauthorized (invalid or missing API token)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Order not found
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Delete Order
      tags:
        - Orders
    parameters:
      - $ref: '#/components/parameters/store-id.param'
      - $ref: '#/components/parameters/order-id.param'
    summary: Order
  /stores/{storeId}/orders/{orderId}/fulfillments:
    description: Order fulfillments collection.
    post:
      description: Create a fulfillment for specific line items within an order, including tracking information. The orderId parameter can be either the external order ID you provided when creating the order, or the internal Redo order ID returned from the create order response.
      operationId: Fulfillment create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/orders-api-create-fulfillment-request.schema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-fulfillment-response.schema'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Bad Request (validation error)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Unauthorized (invalid or missing API token)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Order not found
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Create Fulfillment
      tags:
        - Orders
    parameters:
      - $ref: '#/components/parameters/store-id.param'
      - $ref: '#/components/parameters/order-id.param'
    summary: Order Fulfillments
  /stores/{storeId}/orders/{orderId}/fulfillments/{fulfillmentId}/shipment-status:
    description: Update fulfillment shipment status.
    post:
      description: |
        Post a shipment status update or trigger an automation event for a fulfillment.

        The status field accepts two types of values:

        **Statuses** (e.g., `in_transit`, `delivered`): Real carrier tracking statuses that update the shipment's current status. When you send these, the fulfillment's current status is updated to reflect the new state. Triggers any configured automations for that status.

        **Events** (e.g., `stalled_in_transit`, `delayed`, `arriving_early`): Special event types that trigger automations without changing the current shipment status. The status field remains unchanged, but you can still update estimated delivery date and add tracking history entries. Use these to trigger event-based automations.

        Both statuses and events can update other fields like estimated delivery date and tracking history.
      operationId: Fulfillment status update
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/orders-api-update-fulfillment-status-request.schema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-fulfillment-response.schema'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Bad Request (validation error)
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Unauthorized (invalid or missing API token)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orders-api-error.schema'
          description: Fulfillment not found
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Update Fulfillment Status
      tags:
        - Orders
    parameters:
      - $ref: '#/components/parameters/store-id.param'
      - $ref: '#/components/parameters/order-id.param'
      - $ref: '#/components/parameters/fulfillment-id.param'
    summary: Fulfillment Shipment Status
  /stores/{storeId}/products/bulk-upload:
    post:
      description: |
        Bulk create or update product families and their variants.

        Submit up to 1,000 product families per request, each containing up to 100 variants.
        Products are processed asynchronously in batches. Only one bulk upload can run per store at a time.

        ## Matching Strategy

        The API uses the following priority to match incoming product families to existing records:

        1. **`product_family_id`** — Redo product family ID (direct lookup)
        2. **`external_id`** — ID from your external system
        3. **SKU** — Matched via variant SKUs

        If no match is found, a new product family is created.

        ## Concurrency

        Only one bulk upload operation can run per store at a time. If a bulk upload is already
        in progress, the request will return a `409 Conflict` error.
      operationId: Products bulk upload
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bulk-product-upload-request.schema'
            examples:
              single_product:
                summary: Single product with one variant
                value:
                  products:
                    - title: Classic T-Shirt
                      description: A comfortable cotton t-shirt
                      vendor: Acme Apparel
                      tags:
                        - apparel
                        - basics
                      kind: SELLABLE
                      variants:
                        - sku: TSHIRT-BLK-M
                          price: 2999
                          currency: USD
                          weight: 200
                          weight_unit: g
              multiple_products_with_options:
                summary: Multiple products with options and images
                value:
                  products:
                    - title: Running Shoes
                      external_id: EXT-SHOES-001
                      options:
                        - name: Size
                          values:
                            - '9'
                            - '10'
                            - '11'
                        - name: Color
                          values:
                            - Black
                            - White
                      images:
                        - url: https://example.com/shoes-main.jpg
                          alt_text: Running shoes front view
                      variants:
                        - sku: SHOE-BLK-9
                          price: 12999
                          currency: USD
                          option_values:
                            - '9'
                            - Black
                        - sku: SHOE-WHT-10
                          price: 12999
                          currency: USD
                          option_values:
                            - '10'
                            - White
                    - title: Athletic Socks
                      variants:
                        - sku: SOCK-WHT-L
                          price: 1499
                          currency: USD
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bulk-product-upload-response.schema'
              examples:
                success:
                  summary: Successful upload
                  value:
                    total_count: 2
                    processed_count: 2
                    error_count: 0
                    results:
                      - status: created
                        product_family_id: 01H5K3EXAMPLE1
                        products:
                          - id: 01H5K3EXAMPLE1A
                            sku: SHOE-BLK-9
                          - id: 01H5K3EXAMPLE1B
                            sku: SHOE-WHT-10
                      - status: updated
                        product_family_id: 01H5K3EXAMPLE2
                        products:
                          - id: 01H5K3EXAMPLE2A
                            sku: SOCK-WHT-L
                partial_failure:
                  summary: Partial failure
                  value:
                    total_count: 2
                    processed_count: 1
                    error_count: 1
                    results:
                      - status: created
                        product_family_id: 01H5K3EXAMPLE3
                        products:
                          - id: 01H5K3EXAMPLE3A
                            sku: TSHIRT-BLK-M
                      - status: error
                        error: Duplicate SKU found in request
          description: Upload completed
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Invalid request body or missing required fields
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: A bulk upload is already in progress for this store
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Bulk upload products
      tags:
        - Products
  /returns/{returnId}:
    description: Return.
    get:
      description: Get return.
      operationId: Return get
      responses:
        '200':
          content:
            application/json:
              schema:
                p