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.

        Requires the [`customer_events_write`](/docs/api-reference/scopes) scope.
      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.

        Requires the [`customer_events_write`](/docs/api-reference/scopes) scope.
      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. Requires the [`customers_write`](/docs/api-reference/scopes) scope.
      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
            examples:
              full_example:
                summary: All channels and subscription types
                value:
                  sms:
                    phoneNumber: '+15550000000'
                    subscriptions:
                      marketing:
                        subscriptionStatus: subscribed
                        triggerAutomations: true
                        updatedAt: '2026-01-15T10:30:00Z'
                      transactional:
                        subscriptionStatus: subscribed
                        updatedAt: '2026-01-15T10:30:00Z'
                  email:
                    email: jane.doe@example.com
                    subscriptions:
                      marketing:
                        subscriptionStatus: subscribed
                        triggerAutomations: true
                        updatedAt: '2026-01-15T10:30:00Z'
              sms_only:
                summary: SMS marketing and transactional
                value:
                  sms:
                    phoneNumber: '+15550000000'
                    subscriptions:
                      marketing:
                        subscriptionStatus: subscribed
                      transactional:
                        subscriptionStatus: subscribed
              email_only:
                summary: Email marketing only
                value:
                  email:
                    email: jane.doe@example.com
                    subscriptions:
                      marketing:
                        subscriptionStatus: unsubscribed
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/customer-subscription-update-response.schema'
              examples:
                full_example:
                  summary: All channels updated
                  value:
                    success: true
                    message: Customer subscriptions updated successfully
                    updatedSubscriptions:
                      sms:
                        marketing: true
                        transactional: true
                      email:
                        marketing: true
                sms_only:
                  summary: SMS only updated
                  value:
                    success: true
                    message: Customer subscriptions updated successfully
                    updatedSubscriptions:
                      sms:
                        marketing: true
          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.

        Requires the [`customers_read`](/docs/api-reference/scopes) scope.
      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.

        Requires the [`customers_write`](/docs/api-reference/scopes) scope.
      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.
        Requires the [`inbound_shipments_read`](/docs/api-reference/scopes) scope.
      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.
        Requires the [`inbound_shipments_read`](/docs/api-reference/scopes) scope.
      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.
        Requires the [`inventory_read`](/docs/api-reference/scopes) scope.
      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. Requires the [`inventory_read`](/docs/api-reference/scopes) scope.
      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.
        Requires the [`inventory_read`](/docs/api-reference/scopes) scope.
      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.
        Requires the [`inventory_read`](/docs/api-reference/scopes) scope.
      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. Requires the [`invoices_read`](/docs/api-reference/scopes) scope.
      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. Requires the [`invoices_read`](/docs/api-reference/scopes) scope.
      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. Requires the [`invoices_read`](/docs/api-reference/scopes) scope.
      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. Requires the [`orders_write`](/docs/api-reference/scopes) scope.
      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. Requires the [`orders_read`](/docs/api-reference/scopes) scope.
      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. Requires the [`orders_write`](/docs/api-reference/scopes) scope.
      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. Requires the [`orders_write`](/docs/api-reference/scopes) scope.
      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.

        Requires the [`orders_write`](/docs/api-reference/scopes) scope.
      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.

        Requires the [`products_write`](/docs/api-reference/scopes) scope.
      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. Requires the [`returns_read`](/docs/api-reference/scopes) scope.
      operationId: Return get
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  order:
                    $ref: '#/components/schemas/order-read.schema'
                  return:
                    $ref: '#/components/schemas/return-read.schema'
                required:
                  - return
                  - order
                type: object
          description: Success
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Return
      tags:
        - Returns
    parameters:
      - $ref: '#/components/parameters/return-id.param'
    summary: Return
  /returns/{returnId}/comments:
    description: Return comment.
    get:
      description: List return comments. Requires the [`returns_read`](/docs/api-reference/scopes) scope.
      operationId: Return comments get
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  comments:
                    description: Return comments.
                    items:
                      $ref: '#/components/schemas/comment.schema'
                    title: Comments
                    type: array
                required:
                  - comments
                type: object
          description: Success
      summary: List Return Comments
      tags:
        - Returns
    parameters:
      - $ref: '#/components/parameters/return-id.param'
    post:
      description: Create return comment. Requires the [`returns_write`](/docs/api-reference/scopes) scope.
      operationId: Return comment create
      requestBody:
        content:
          application/json:
            schema:
              properties:
                comment:
                  $ref: '#/components/schemas/comment.schema'
              required:
                - comment
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                properties:
                  comment:
                    $ref: '#/components/schemas/comment.schema'
                required:
                  - comment
                type: object
          description: Created
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Create Return Comment
      tags:
        - Returns
    summary: Return comment
  /returns/{returnId}/process:
    description: Process return.
    parameters:
      - $ref: '#/components/parameters/return-id.param'
    post:
      description: |
        **BETA**: This endpoint is in beta and subject to change.

        Trigger processing of a return with specified products.

        Requires the [`returns_write`](/docs/api-reference/scopes) scope.
      operationId: Return process
      requestBody:
        content:
          application/json:
            schema:
              properties:
                customerNotes:
                  description: Notes to send to customer. These can be rejection notes or processing notes.
                  type: string
                products:
                  description: Array of products to process or reject
                  items:
                    properties:
                      _id:
                        description: Product ID found on the return
                        example: 64e4d5e837572a4813b73e41
                        type: string
                      processInput:
                        description: Processing details. You may only have one of reject or processInput.
                        nullable: true
                        properties:
                          newMerchantAdjustment:
                            description: Adjustment amount. This will be the amount that is credited to the customer, overriding the original product value.
                            nullable: true
                            type: number
                          restock:
                            description: Whether to restock the item
                            type: boolean
                        type: object
                      reject:
                        default: false
                        description: Reject this product. You may only have one of reject or processInput.
                        type: boolean
                    required:
                      - _id
                    type: object
                  type: array
              required:
                - products
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  message:
                    description: Status message
                    examples:
                      - Processing triggered successfully
                      - Successfully prepared some products to be processed, once all products are ready, processing will be triggered
                    type: string
                type: object
          description: Processing request completed
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Bad request (e.g., missing products array)
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Process Return
      tags:
        - Returns
    summary: Process return
  /returns/{returnId}/status:
    description: Return status.
    get:
      description: Get return status. Requires the [`returns_read`](/docs/api-reference/scopes) scope.
      operationId: Return status get
      parameters:
        - $ref: '#/components/parameters/return-id.param'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  status:
                    $ref: '#/components/schemas/return-status.schema'
                required:
                  - status
                type: object
          description: Success
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Return Status
      tags:
        - Returns
    put:
      description: |
        Update return status.

        Certain status transitions trigger additional side effects to maintain data consistency:

        - Setting status to **complete** will also mark all return items as complete.
        - Setting status to **open** from **complete** or **rejected** will reopen the return, resetting all processed/rejected items back to open, clearing pending processing info, resetting the expiration date, and marking the return as reopened. **Note:** Reopening a processed return does not reverse any refunds, exchanges, or other actions that were performed during processing.

        Requires the [`returns_write`](/docs/api-reference/scopes) scope.
      operationId: Return status update
      parameters:
        - $ref: '#/components/parameters/return-id.param'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                status:
                  $ref: '#/components/schemas/return-status-update.schema'
              required:
                - status
              type: object
        required: true
      responses:
        '204':
          description: Updated
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Update Return Status
      tags:
        - Returns
    summary: Return status
  /stores/{storeId}/returns:
    description: List of returns for store.
    get:
      description: List returns, sorted by most recent to least recent. Requires the [`returns_read`](/docs/api-reference/scopes) scope.
      operationId: Returns list
      parameters:
        - $ref: '#/components/parameters/page-continue.param'
        - $ref: '#/components/parameters/page-size.param'
        - $ref: '#/components/parameters/updated-at-max.param'
        - $ref: '#/components/parameters/updated-at-min.param'
        - $ref: '#/components/parameters/shopify-order-name'
        - $ref: '#/components/parameters/provider-order-name'
        - $ref: '#/components/parameters/return-status.param'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  orders:
                    items:
                      $ref: '#/components/schemas/order-read.schema'
                    type: array
                  returns:
                    items:
                      $ref: '#/components/schemas/return-read.schema'
                    type: array
                required:
                  - orders
                  - returns
                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 Returns
      tags:
        - Returns
    post:
      description: Create a return for specific order line items. Requires the [`returns_write`](/docs/api-reference/scopes) scope.
      operationId: Return create
      parameters:
        - $ref: '#/components/parameters/idempotency-key.param'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create-return-request.schema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-return-response.schema'
          description: Success (idempotent replay; existing return returned)
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create-return-response.schema'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Invalid request body
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Order not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Conflict
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Create Return
      tags:
        - Returns
    parameters:
      - $ref: '#/components/parameters/store-id.param'
    summary: Returns
  /stores/{storeId}/returns/bulk:
    description: Import returns from external systems.
    post:
      description: |-
        Import externally-created returns into Redo. Use this endpoint when the return originates outside of Redo — a warehouse scan, an ERP, a POS system, or a partner platform.

        Products are referenced by their Redo product ID, obtained from the bulk product upload response. No order is required. Returns are created ready for warehouse intake. Supports up to 100 returns per request with per-item error reporting.
        Requires the [`returns_write`](/docs/api-reference/scopes) scope.
      operationId: Import returns
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/bulk-returns-request.schema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bulk-returns-response.schema'
          description: Batch processed. Check individual results for per-item status. Some items may have succeeded while others failed.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Invalid request body or team not configured for product catalog operations.
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Import Returns
      tags:
        - Returns
    parameters:
      - $ref: '#/components/parameters/store-id.param'
    summary: Import Returns
  /stores/{storeId}/return-tags:
    description: Return tags for a store.
    get:
      description: List every return tag defined for the store. Requires the [`returns_read`](/docs/api-reference/scopes) scope.
      operationId: Return tags list
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  tags:
                    items:
                      $ref: '#/components/schemas/return-tag.schema'
                    type: array
                required:
                  - tags
                type: object
          description: Success
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: List Return Tags
      tags:
        - Returns
    parameters:
      - $ref: '#/components/parameters/store-id.param'
    summary: Return Tags
  /stores/{storeId}/return-tags/{name}:
    delete:
      description: |-
        Delete a return tag. The tag is also stripped from every return and saved view filter that referenced it.
        Requires the [`returns_write`](/docs/api-reference/scopes) scope.
      operationId: Return tag delete
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  success:
                    const: true
                    type: boolean
                required:
                  - success
                type: object
          description: Success
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Invalid request. Returned with type `com.getredo.api:return-tag/invalid-request` when the path `name` is missing.
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Delete Return Tag
      tags:
        - Returns
    description: Return tag.
    put:
      description: |-
        Create a new return tag, update an existing tag's color, or rename a tag. When `newName` is set and differs from the path `name`, the rename cascades to returns and saved view filters.

        Possible 400 problem types:
        - `com.getredo.api:return-tag/rename-precondition-failed` — the source
          tag does not exist, or the target name is already in use.

        - `com.getredo.api:return-tag/invalid-request` — the path `name` is
          missing or the request body is invalid.

        Requires the [`returns_write`](/docs/api-reference/scopes) scope.
      operationId: Return tag upsert
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/return-tag-upsert-request.schema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  tag:
                    $ref: '#/components/schemas/return-tag.schema'
                required:
                  - tag
                type: object
          description: Success
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Rename precondition failed or invalid request
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Upsert Return Tag
      tags:
        - Returns
    parameters:
      - $ref: '#/components/parameters/store-id.param'
      - $ref: '#/components/parameters/return-tag-name.param'
    summary: Return Tag
  /stores/{storeId}/storefront/events:
    post:
      description: Processes events from storefronts using Shopify pixel event schema Requires the [`storefront_events_write`](/docs/api-reference/scopes) scope.
      operationId: Storefront Event
      parameters:
        - $ref: '#/components/parameters/store-id.param'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/storefront-event.schema'
        required: true
      responses:
        '204':
          description: Event processed successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Invalid event payload
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Receive Storefront Events
      tags:
        - Storefront
  /stores/{storeId}/webhooks:
    description: Webhooks.
    get:
      description: List webhooks for store. Requires the [`webhooks_read`](/docs/api-reference/scopes) scope.
      operationId: Webhooks list
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  webhooks:
                    items:
                      $ref: '#/components/schemas/webhook-read.schema'
                    type: array
                required:
                  - webhooks
                type: object
          description: Success
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      summary: List Webhooks
      tags:
        - Webhooks
    parameters:
      - $ref: '#/components/parameters/store-id.param'
    post:
      description: Create webhook for store. Or if webhook already exists with `externalId`, update it. Requires the [`webhooks_write`](/docs/api-reference/scopes) scope.
      operationId: Webhook create
      requestBody:
        content:
          application/json:
            schema:
              properties:
                webhook:
                  $ref: '#/components/schemas/webhook-create.schema'
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  webhook:
                    $ref: '#/components/schemas/webhook-read.schema'
                type: object
          description: Updated
        '201':
          content:
            application/json:
              schema:
                properties:
                  webhook:
                    $ref: '#/components/schemas/webhook-read.schema'
                type: object
          description: Created
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      security:
        - Bearer: []
      summary: Create or Update Webhook
      tags:
        - Webhooks
    summary: Webhooks
  /webhooks/{webhookId}:
    delete:
      description: Delete a webhook. Requires the [`webhooks_write`](/docs/api-reference/scopes) scope.
      operationId: Webhook delete
      parameters:
        - $ref: '#/components/parameters/webhook-id.param'
      responses:
        '204':
          description: Deleted
      security:
        - Bearer: []
      summary: Delete Webhook
      tags:
        - Webhooks
    description: Webhook.
    get:
      description: Get a webhook. Requires the [`webhooks_read`](/docs/api-reference/scopes) scope.
      operationId: Webhook get
      parameters:
        - $ref: '#/components/parameters/webhook-id.param'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  webhook:
                    $ref: '#/components/schemas/webhook-read.schema'
                required:
                  - webhook
                type: object
          description: Success
      summary: Webhook
      tags:
        - Webhooks
    put:
      description: Update a webhook. Requires the [`webhooks_write`](/docs/api-reference/scopes) scope.
      operationId: Webhook update
      parameters:
        - $ref: '#/components/parameters/webhook-id.param'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                webhook:
                  $ref: '#/components/schemas/webhook-update.schema'
              required:
                - webhook
              type: object
        required: true
      responses:
        '204':
          description: Success
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      summary: Update Webhook
      tags:
        - Webhooks
    summary: Webhook
  /webhooks/{webhookId}/replay:
    description: Webhook replay.
    parameters:
      - $ref: '#/components/parameters/webhook-id.param'
    post:
      description: Replay a webhook. Requires the [`webhooks_write`](/docs/api-reference/scopes) scope.
      operationId: Webhook replay
      requestBody:
        content:
          application/json:
            schema:
              properties:
                start:
                  format: date-time
                  type: string
              required:
                - start
              type: object
        required: true
      responses:
        '202':
          description: Success
        default:
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/error.schema'
          description: Error
      summary: Replay Webhook
      tags:
        - Webhooks
    summary: Webhook replay
webhooks:
  return:
    post:
      operationId: Webhook return event
      requestBody:
        content:
          application/json:
            example:
              type: created
              at: '2023-08-18T12:00:00Z'
              merchantName: Example Merchant
              return:
                id: 64df65d4c5a4ca3eff4b4e43
                type: return
                status: open
                createdAt: '2023-08-18T12:00:00Z'
                updatedAt: '2023-08-18T12:00:00Z'
                order:
                  id: 64e4da943dd822979a70bd12
                  name: '#1234'
                externalOrderIds:
                  - '1073459971'
                externalReturnIds:
                  - provider: shopify
                    value: '12345'
                shopifyOrderIds:
                  - '1073459971'
                compensationMethods:
                  - refund
                  - store_credit
                  - exchange
                completeWithNoAction: false
                internalCreatedByName: Jordan Manager
                items:
                  - id: 64df65d4c5a4ca3eff4b4e44
                    orderItem:
                      id: 1073459971/0
                      line_item_id: '12345678901234'
                    productId: '8453214567890'
                    variantId: '44567823456789'
                    sku: TSHIRT-BLU-M
                    upc: '012345678905'
                    quantity: 1
                    status: open
                    grade: A
                    outcome: restock
                    greenReturn: false
                    reason: Too big
                    reasonCode: size_too_large
                    reasons:
                      - Too big
                    reasonCodes:
                      - size_too_large
                    customerComment: Runs larger than expected
                    multipleChoiceQuestions:
                      - question: What was wrong with the fit?
                        answer: Too large in the chest
                    shipmentGroupIds:
                      - sg_abc123
                    externalReturnLineItemId: ret_li_12345
                    exchangeItem:
                      product:
                        externalId: '8453214567890'
                        name: Classic T-Shirt
                      variant:
                        externalId: '44567823456790'
                        name: Large / Blue
                      quantity: 1
                    refund:
                      amount:
                        amount: '29.99'
                        currency: USD
                      type: original_payment
                    productValueNoTaxNoAdjustment:
                      amount:
                        amount: '29.99'
                        currency: USD
                source:
                  emailAddress: customer@example.com
                  name:
                    given: Jane
                    surname: Doe
                  mailingAddress:
                    line1: 123 Main St
                    line2: Apt 4B
                    city: San Francisco
                    state: CA
                    postalCode: '94102'
                    country: US
                  phoneNumber: '+14155551234'
                destination:
                  mailingAddress:
                    line1: 500 Warehouse Way
                    line2: ''
                    city: Salt Lake City
                    state: UT
                    postalCode: '84104'
                    country: US
                  phoneNumber: '+18015550100'
                shipment:
                  carrier: USPS
                  status: pre_transit
                  tracker: '9400111202555842761523'
                  trackingUrl: https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111202555842761523
                  postageLabel: https://files.getredo.com/labels/abc123.pdf
                  formLabel: https://files.getredo.com/forms/abc123.pdf
                  shipmentGroupId: sg_abc123
                  itemIds:
                    - 64df65d4c5a4ca3eff4b4e44
                  externalLocationId: loc_warehouse_1
                  estimatedDeliveryDate: '2023-08-22T00:00:00Z'
                shipments:
                  - carrier: USPS
                    status: pre_transit
                    tracker: '9400111202555842761523'
                    trackingUrl: https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111202555842761523
                    postageLabel: https://files.getredo.com/labels/abc123.pdf
                    shipmentGroupId: sg_abc123
                    itemIds:
                      - 64df65d4c5a4ca3eff4b4e44
                dropoffs: []
                giftCards: []
                exchange:
                  itemCount: 1
                  items:
                    - id: 64df65d4c5a4ca3eff4b4e45
                      originalPrice:
                        amount: '34.99'
                        currency: USD
                      price:
                        amount: '29.99'
                        currency: USD
                        tax: '2.40'
                      product:
                        externalId: '8453214567890'
                        name: Classic T-Shirt
                      variant:
                        externalId: '44567823456790'
                        name: Large / Blue
                        sku: TSHIRT-BLU-L
                      quantity: 1
                  order:
                    externalId: shopify-exchange-456
                  provision: deferred
                  totalTax:
                    amount: '2.40'
                    currency: USD
                totals:
                  refund:
                    amount:
                      amount: '0.00'
                      currency: USD
                  exchange:
                    amount:
                      amount: '29.99'
                      currency: USD
                  storeCredit:
                    amount:
                      amount: '0.00'
                      currency: USD
                  charge:
                    amount:
                      amount: '0.00'
                      currency: USD
                tags:
                  - name: VIP customer
                    source: merchant
                notes:
                  - message: Reviewed by support — approved for exchange
              order:
                id: 64e4da943dd822979a70bd12
                externalId: '1073459971'
                name: '#1234'
                customer:
                  emailAddress: customer@example.com
                  name:
                    given: Jane
                    surname: Doe
                  phoneNumber: '+14155551234'
                items:
                  - id: 1073459971/0
                    externalId: '12345678901234'
                    fulfillmentLocationId: loc_warehouse_1
                    product:
                      externalId: '8453214567890'
                      name: Classic T-Shirt
                    variant:
                      externalId: '44567823456789'
                      name: Medium / Blue
                      sku: TSHIRT-BLU-M
                    quantity: 1
                    price:
                      amount: '29.99'
                      currency: USD
                discounts:
                  amount: '0.00'
                  currency: USD
                lineItemsTotal:
                  amount: '29.99'
                  currency: USD
                shippingCost:
                  amount: '5.99'
                  currency: USD
                taxes:
                  amount: '2.40'
                  currency: USD
                total:
                  amount: '38.38'
                  currency: USD
            schema:
              description: Return event
              properties:
                at:
                  description: Event time
                  format: date-time
                  title: At
                  type: string
                merchantName:
                  description: Name of the merchant team that owns this return.
                  title: Merchant Name
                  type: string
                order:
                  $ref: '#/components/schemas/order-read.schema'
                  description: Order for return.
                  title: Order
                return:
                  $ref: '#/components/schemas/return-read.schema'
                  description: Return.
                  title: Return
                type:
                  description: Event type
                  enum:
                    - backfill
                    - created
                    - updated
                  type: string
              type: object
        description: |
          Return event webhook.
        required: true
      responses:
        2XX:
          description: Success. Return a 2xx status code to indicate success.
        default:
          description: Error. The event will be retried multiple times and then discarded.
      security:
        - UserBearer: []
      summary: Return event
      tags:
        - Returns
components:
  securitySchemes:
    Bearer:
      scheme: bearer
      type: http
    UserBearer:
      scheme: bearer
      type: http
  parameters:
    store-id.param:
      description: Store ID
      in: path
      name: storeId
      required: true
      schema:
        example: 64e5a8a1af49a89df37e4ee7
        type: string
    page-continue.param:
      description: Page marker, from X-Page-Next header
      example: 64df700931a04885276c3364
      in: header
      name: X-Page-Continue
      schema:
        type: string
    page-size.param:
      description: Page size, defaults to 20
      example: 20
      in: header
      name: X-Page-Size
      schema:
        maximum: 500
        minimum: 1
        type: integer
    inbound-shipment-status.param:
      description: Filter by shipment status
      example: IN_TRANSIT
      in: query
      name: status
      schema:
        enum:
          - PENDING
          - IN_TRANSIT
          - PARTIALLY_RECEIVED
          - RECEIVED
        type: string
    location-id.param:
      description: Filter by location ID (e.g. `loc_...`)
      example: loc_4d8e1a2b3c
      in: query
      name: location_id
      schema:
        type: string
    created-at-min.param:
      description: Minimum created time, inclusive
      example: '2000-01-01T00:00:00Z'
      in: query
      name: created_at_min
      schema:
        format: date-time
        type: string
    created-at-max.param:
      description: Maximum created time, exclusive
      example: '2026-01-01T00:00:00Z'
      in: query
      name: created_at_max
      schema:
        format: date-time
        type: string
    inbound-shipment-id.param:
      description: Inbound shipment ID
      in: path
      name: inboundShipmentId
      required: true
      schema:
        example: inb_7a3f9c2e1b
        type: string
    inventory-item-kind.param:
      description: Filter by inventory item kind
      example: PRODUCT
      in: query
      name: kind
      schema:
        enum:
          - PRODUCT
          - RETURN
          - UNDECLARED
          - UNKNOWN
        type: string
    inventory-item-id.param:
      description: Inventory item ID
      in: path
      name: inventoryItemId
      required: true
      schema:
        example: ii_5f8e1a2b3c
        type: string
    product-id.param:
      description: Filter by product ID (e.g. `prd_...`)
      example: prd_1a2b3c4d5e
      in: query
      name: product_id
      schema:
        type: string
    sku.param:
      description: Filter by product SKU
      example: TSH-BLK-M
      in: query
      name: sku
      schema:
        type: string
    updated-at-min.param:
      description: Minimum updated time, inclusive
      example: '2000-01-01T00:00:00Z'
      in: query
      name: updated_at_min
      schema:
        format: date-time
        type: string
    updated-at-max.param:
      description: Maximum updated time, exclusive
      example: '2000-02-01T00:00:00Z'
      in: query
      name: updated_at_max
      schema:
        format: date-time
        type: string
    inventory-level-id.param:
      description: Inventory level ID
      in: path
      name: inventoryLevelId
      required: true
      schema:
        example: li_9b2c4d6e8f
        type: string
    invoice-id.param:
      description: Invoice ID
      in: path
      name: invoiceId
      required: true
      schema:
        example: 64e4d5e837572a4813b73e40
        type: string
    order-id.param:
      description: Order ID. Can be either the external order ID provided when creating the order, or the internal Redo order ID.
      in: path
      name: orderId
      required: true
      schema:
        type: string
    fulfillment-id.param:
      description: Unique fulfillment identifier.
      in: path
      name: fulfillmentId
      required: true
      schema:
        type: string
    return-id.param:
      description: Return ID
      in: path
      name: returnId
      required: true
      schema:
        example: 64e4d5e837572a4813b73e40
        type: string
    shopify-order-name:
      description: Shopify specific order name
      in: query
      name: shopify_order_name
      schema:
        example: XYZ1025
        type: string
    provider-order-name:
      description: Provider specific order name
      in: query
      name: provider_order_name
      schema:
        example: XYZ1025
        type: string
    return-status.param:
      description: Filter returns by status
      in: query
      name: status
      schema:
        $ref: '#/components/schemas/return-status.schema'
    idempotency-key.param:
      description: Optional idempotency key for safely retrying create requests.
      in: header
      name: Idempotency-Key
      required: false
      schema:
        type: string
    return-tag-name.param:
      description: Return tag name. Case-sensitive and URL-encoded.
      in: path
      name: name
      required: true
      schema:
        example: Damaged
        type: string
    webhook-id.param:
      description: Webhook ID
      in: path
      name: webhookId
      required: true
      schema:
        example: 64e5a865a58eefeed7f05ea6
        type: string
  schemas:
    money.schema:
      description: Currency amount
      properties:
        amount:
          examples:
            - '50.2'
            - '1.78'
          title: Amount
          type: string
        currency:
          examples:
            - USD
            - EUR
          title: Currency
          type: string
      title: Money
      type: object
    storefront-cart.schema:
      description: Storefront cart.
      properties:
        lineItems:
          description: Line items.
          items:
            properties:
              coupons:
                items:
                  properties:
                    code:
                      type: string
                    discountAmount:
                      $ref: '#/components/schemas/money.schema'
                      description: The amount this coupon discounts in dollars for this line item.
                    id:
                      type: string
                  required:
                    - id
                    - code
                    - discountAmount
                  type: object
                type: array
              id:
                description: Line item ID.
                title: ID
                type: string
              originalPrice:
                $ref: '#/components/schemas/money.schema'
                description: Original price.
                title: Original Price
              priceTotal:
                $ref: '#/components/schemas/money.schema'
                description: Total price.
                title: Price
              product:
                description: Product.
                properties:
                  id:
                    description: Identifier of the product.
                    title: ID
                    type: string
                required:
                  - id
                type: object
              quantity:
                description: Quantity.
                title: Quantity
                type: integer
              variant:
                description: Variant.
                properties:
                  id:
                    description: Identifier of the variant.
                    title: ID
                    type: string
                required:
                  - id
                type: object
            required:
              - id
              - quantity
              - product
              - variant
              - priceTotal
            type: object
          title: Line items
          type: array
        priceTotal:
          $ref: '#/components/schemas/money.schema'
          description: Total price.
          title: Price
      required:
        - lineItems
        - priceTotal
      title: Storefront Cart
      type: object
    storefront-customer.schema:
      description: Storefront customer.
      properties:
        id:
          description: Customer ID.
          title: ID
          type: string
      required:
        - id
      title: Storefront Customer
      type: object
    length.schema:
      description: Length measurement with unit.
      properties:
        unit:
          description: Length unit
          enum:
            - in
            - cm
          examples:
            - in
            - cm
          title: Unit
          type: string
        value:
          description: Numeric length value
          examples:
            - 10.5
            - 30
          minimum: 0
          title: Value
          type: number
      required:
        - value
        - unit
      title: Length
      type: object
    weight.schema:
      description: Weight.
      properties:
        kg:
          description: Weight in kilograms
          examples:
            - 0.021
            - 1.4
          minimum: 0
          title: Kilograms
          type: number
      title: Weight
      type: object
    error.schema:
      description: Problem details. See [RFC 7807 Section 3](https://datatracker.ietf.org/doc/html/rfc7807#section-3).
      properties:
        detail:
          description: Human-readable description of the problem.
          title: Detail
          type: string
        instance:
          description: A URI reference that identifies this problem.
          format: uri-reference
          type: string
        title:
          description: Human-readable summary of the problem type.
          title: Title
          type: string
        type:
          default: about:blank
          description: A URI reference that identifies the problem type.
          format: uri-reference
          type: string
      title: Problem details
      type: object
    coverage-product.schema:
      description: Coverage product.
      properties:
        coverages:
          description: Coverage.
          items:
            properties:
              lineItems:
                items:
                  properties:
                    id:
                      description: Line item ID.
                      title: ID
                      type: string
                  type: object
                type: array
              type:
                enum:
                  - shipping_failure
                  - return_shipping
                title: Coverage
            required:
              - lineItems
              - type
            type: object
          type: array
        id:
          description: Coverage ID.
          title: ID
          type: string
        price:
          $ref: '#/components/schemas/money.schema'
          description: Price.
          title: Price
      required:
        - coverage
        - id
        - price
      title: Coverage product
      type: object
    custom-event-request.schema:
      additionalProperties: true
      description: |
        Custom event to trigger flows with merchant-defined event names and properties.
      properties:
        eventName:
          description: The name of the custom event (e.g., 'User Registered', 'Loyalty Reward Earned').
          type: string
        customer:
          description: |
            Customer identity and profile fields. At least one of `id`, `email`, or `phoneNumber` is required for identity resolution.
          type: object
          additionalProperties: false
          anyOf:
            - required:
                - id
            - required:
                - email
            - required:
                - phoneNumber
          properties:
            id:
              description: Redo customer ObjectId. Used for identity resolution. Takes priority over email and phoneNumber when provided.
              type: string
            email:
              description: Customer email address. Used for identity resolution.
              format: email
              type: string
            phoneNumber:
              description: Customer phone number in E.164 format. Used for identity resolution.
              type: string
            firstName:
              description: Customer first name. Applied with patch semantics — does not erase existing value if omitted.
              type: string
            lastName:
              description: Customer last name. Applied with patch semantics — does not erase existing value if omitted.
              type: string
            location:
              description: Customer location for profile enrichment. All fields are optional.
              type: object
              additionalProperties: false
              properties:
                street1:
                  description: Primary street address.
                  type: string
                street2:
                  description: Secondary address line (apartment, suite, etc.).
                  type: string
                city:
                  description: City name.
                  type: string
                state:
                  description: State or province name.
                  type: string
                stateCode:
                  description: State or province abbreviation (e.g., "CA", "NY").
                  type: string
                postalCode:
                  description: Postal or ZIP code.
                  type: string
                country:
                  description: Country name.
                  type: string
                countryCode:
                  description: ISO 3166-1 alpha-2 country code (e.g., "US", "GB").
                  type: string
                ianaTimeZoneName:
                  description: IANA time zone identifier (e.g., "America/New_York").
                  type: string
                latitude:
                  description: Geographic latitude coordinate.
                  type: number
                longitude:
                  description: Geographic longitude coordinate.
                  type: number
            customFields:
              description: |
                Merchant-defined customer attributes as key-value pairs. Values can be strings, numbers, or booleans. Date values should be passed as ISO 8601 strings (e.g., "2026-04-02T12:00:00Z") and are automatically detected and indexed as dates.
              type: object
              additionalProperties:
                oneOf:
                  - type: string
                  - type: number
                  - type: boolean
        data:
          description: |
            Custom properties for this event (must not exceed 400 properties). The size of the event payload must not exceed 5 MB, and each string cannot be larger than 100 KB. For a full list of data limits on event payloads, see [Limitations](/docs/guides/integrations/custom-events#rate-limits).

            Note any top-level property that is not an object can be used to create segments. The `$extra` property records any non-segmentable values that can be referenced later, e.g., HTML templates are useful on a segment but are not used to create a segment.
          type: object
          additionalProperties:
            description: |
              Segmentable event property. Each key you add becomes available for audience segmentation and automation conditions. Supported types are string, number, boolean, and date (ISO 8601 strings like "2025-01-15T00:00:00Z" are auto-detected as dates). Values of 0, null, and empty string ("") are treated as unset and will not be stored.
            anyOf:
              - type: string
              - type: number
              - type: boolean
          properties:
            $extra:
              description: |
                Non-segmentable metadata bucket. Values inside `$extra` are stored on the event but excluded from segmentation indexes. Unlike top-level data properties, values of 0, null, and empty string are NOT stripped inside `$extra`. Use this for large text, debug info, nested objects, arrays, or any data you want to reference in templates but not segment on.
              type: object
              additionalProperties: true
        eventTimestamp:
          description: ISO 8601 timestamp when the event occurred. Defaults to current time if not provided.
          format: date-time
          type: string
        value:
          description: Monetary or conversion value associated with the event (e.g., purchase amount).
          type: number
        valueCurrency:
          description: ISO 4217 currency code for the value field (e.g., "USD", "EUR").
          type: string
        uniqueId:
          description: |
            Merchant-controlled deduplication key (1-255 characters). If provided, subsequent events with the same uniqueId for the same store are silently deduplicated. Use this for safe retries and at-least-once delivery patterns.
          type: string
      required:
        - eventName
        - customer
      title: Custom Event Request
      type: object
    bulk-custom-event-request.schema:
      additionalProperties: false
      description: Request body for sending multiple custom events in a single request.
      properties:
        events:
          description: Array of custom events to create.
          type: array
          items:
            $ref: '#/components/schemas/custom-event-request.schema'
          maxItems: 100
          minItems: 1
      required:
        - events
      title: Bulk Custom Event Request
      type: object
    customer-subscription-email.schema:
      description: Email subscription updates
      properties:
        email:
          description: Email address
          format: email
          type: string
        subscriptions:
          properties:
            marketing:
              description: Email marketing subscription. Email is always auto-confirmed on subscribe.
              properties:
                subscriptionStatus:
                  description: Subscription status.
                  enum:
                    - subscribed
                    - unsubscribed
                  type: string
                triggerAutomations:
                  default: false
                  description: Whether to trigger automations for this subscription change. Defaults to false.
                  type: boolean
                updatedAt:
                  description: ISO 8601 timestamp. If not provided, defaults to now.
                  format: date-time
                  type: string
              required:
                - subscriptionStatus
              type: object
          type: object
      required:
        - email
        - subscriptions
      type: object
    subscription-status-marketing.schema:
      description: Marketing subscription status
      properties:
        subscriptionStatus:
          description: Subscription status. Use `confirmed` if the customer has already completed double opt-in elsewhere and you are recording that fact.
          enum:
            - subscribed
            - confirmed
            - unsubscribed
          type: string
        triggerAutomations:
          default: false
          description: Whether to trigger automations for this subscription change. Defaults to false.
          type: boolean
        updatedAt:
          description: ISO 8601 timestamp. If not provided, defaults to now.
          format: date-time
          type: string
      required:
        - subscriptionStatus
      title: Subscription Status Marketing
      type: object
    subscription-status-transactional.schema:
      description: Transactional subscription status (order tracking)
      properties:
        subscriptionStatus:
          description: Subscription status. Only subscribed and unsubscribed are supported for transactional.
          enum:
            - subscribed
            - unsubscribed
          type: string
        updatedAt:
          description: ISO 8601 timestamp. If not provided, defaults to now.
          format: date-time
          type: string
      required:
        - subscriptionStatus
      title: Subscription Status Transactional
      type: object
    customer-subscription-sms.schema:
      description: SMS subscription updates
      properties:
        phoneNumber:
          description: Phone number in E.164 format (e.g., +12345678900)
          type: string
        subscriptions:
          properties:
            marketing:
              $ref: '#/components/schemas/subscription-status-marketing.schema'
            transactional:
              $ref: '#/components/schemas/subscription-status-transactional.schema'
          type: object
      required:
        - phoneNumber
        - subscriptions
      type: object
    customer-subscription-update-response.schema:
      description: Customer subscription update response
      properties:
        message:
          description: Human-readable success message
          type: string
        success:
          description: Whether the operation was successful
          type: boolean
        updatedSubscriptions:
          description: Details of which subscriptions were updated
          properties:
            email:
              properties:
                marketing:
                  description: Whether email marketing was updated
                  type: boolean
              type: object
            sms:
              properties:
                marketing:
                  description: Whether SMS marketing was updated
                  type: boolean
                transactional:
                  description: Whether SMS transactional was updated
                  type: boolean
              type: object
          type: object
      required:
        - success
        - message
        - updatedSubscriptions
      type: object
    customer-location.schema:
      description: Customer location information.
      properties:
        street1:
          description: Street address line 1
          type: string
        street2:
          description: Street address line 2
          type: string
        city:
          description: City name
          type: string
        state:
          description: State or province name
          examples:
            - Washington
            - Ontario
          type: string
        stateCode:
          description: State or province abbreviation
          examples:
            - WA
            - 'ON'
          type: string
        postalCode:
          description: Postal or ZIP code
          examples:
            - '12345'
            - K1A 0B1
          type: string
        country:
          description: Country name
          examples:
            - United States
            - Canada
          type: string
        countryCode:
          description: ISO 3166-1 alpha-2 country code
          examples:
            - US
            - CA
          type: string
        ianaTimeZoneName:
          description: IANA time zone identifier
          examples:
            - America/New_York
            - America/Los_Angeles
          type: string
        latitude:
          description: Latitude coordinate
          type: number
        longitude:
          description: Longitude coordinate
          type: number
      title: Customer Location
      type: object
    customer-read.schema:
      description: Customer profile.
      properties:
        id:
          description: Redo customer ID
          examples:
            - 67bd4f1a2e3c8d001a5f9b12
          type: string
        email:
          description: Customer email address
          format: email
          examples:
            - jane@example.com
          type: string
        firstName:
          description: Customer first name
          examples:
            - Jane
          type: string
        lastName:
          description: Customer last name
          examples:
            - Smith
          type: string
        phoneNumber:
          description: Customer phone number in E.164 format
          examples:
            - '+11234567890'
          type: string
        location:
          $ref: '#/components/schemas/customer-location.schema'
        customFields:
          description: Custom field values as key-value pairs, where keys are field names and values can be strings, numbers, or booleans. DATE custom field values are returned as ISO 8601 datetime strings (e.g., "2026-01-15T12:00:00.000Z"), not Date objects.
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
          examples:
            - subscription_source: web
              status: Active
              loyalty_points: 1250
              vip_member: true
              signup_date: '2026-02-24T12:15:00.000Z'
        createdAt:
          description: Timestamp when the customer was created. May be null for older customers created before this field was tracked.
          format: date-time
          title: Created at
          examples:
            - '2026-02-20T18:30:00.000Z'
          type:
            - string
            - 'null'
        updatedAt:
          description: Timestamp when the customer was last updated. May be null for older customers created before this field was tracked.
          format: date-time
          title: Updated at
          examples:
            - '2026-02-24T12:15:00.000Z'
          type:
            - string
            - 'null'
      required:
        - id
        - email
      title: Customer
      type: object
    customer-upsert-request.schema:
      additionalProperties: false
      description: Request body for creating or updating a customer profile. The email address is used as the upsert key.
      properties:
        email:
          description: Customer email address. Used as the upsert key to find or create the customer.
          format: email
          type: string
        firstName:
          description: Customer first name
          type: string
        lastName:
          description: Customer last name
          type: string
        phoneNumber:
          description: Customer phone number in E.164 format (e.g., +12345678900). Appended to the existing phone list if not already present.
          examples:
            - '+12345678900'
          type: string
        location:
          $ref: '#/components/schemas/customer-location.schema'
        customFields:
          description: |-
            Custom field values as key-value pairs. Keys are field names and values can be strings, numbers, or booleans. The field type is determined automatically based on the value:
            - String values → STRING custom field
            - Number values → NUMBER custom field
            - Boolean values → BOOLEAN custom field
            - ISO 8601 datetime strings (e.g., "2026-02-24T12:15:00.000Z") → DATE custom field (auto-detected)

            If a field name does not already have a declaration, one is created automatically. For STRING fields, unique values are tracked as options (used for segment filtering dropdowns). NUMBER, BOOLEAN, and DATE fields do not track options.
          type: object
          additionalProperties:
            oneOf:
              - type: string
              - type: number
              - type: boolean
          example:
            subscription_source: web
            status: Active
            loyalty_points: 1250
            vip_member: true
            signup_date: '2026-02-24T12:15:00.000Z'
      required:
        - email
      title: Customer Upsert Request
      type: object
    customer-upsert-response.schema:
      additionalProperties: false
      description: Response after creating or updating a customer profile.
      properties:
        id:
          description: Redo customer ID
          type: string
        email:
          description: Customer email address
          type: string
        created:
          description: Whether a new customer was created (true) or an existing customer was updated (false).
          type: boolean
      required:
        - id
        - email
        - created
      title: Customer Upsert Response
      type: object
    inbound-shipment-location.schema:
      description: Destination location.
      properties:
        id:
          description: Prefixed location ID (`loc_...`).
          example: loc_4d8e1a2b3c
          type: string
        name:
          description: Location name.
          example: East Coast Warehouse
          type: string
      required:
        - id
        - name
      title: Inbound Shipment Location
      type: object
    inbound-shipment-money.schema:
      description: Monetary amount with currency.
      properties:
        amount:
          description: Decimal amount as a string.
          example: '1250.00'
          type: string
        currency:
          description: ISO 4217 currency code.
          example: USD
          type: string
      required:
        - amount
        - currency
      title: Money
      type: object
    inbound-shipment-product-summary.schema:
      description: Product summary in a shipment item.
      properties:
        id:
          description: Prefixed product ID (`prd_...`).
          example: prd_1a2b3c4d5e
          type: string
        title:
          description: Product title including variant options.
          example: Classic Cotton T-Shirt - Black / M
          type: string
        sku:
          description: Stock keeping unit.
          example: TSH-BLK-M
          nullable: true
          type: string
        image_url:
          description: URL of the product's primary image.
          example: https://cdn.example.com/tshirt-blk-m.jpg
          nullable: true
          type: string
      required:
        - id
        - title
        - sku
      title: Inbound Shipment Product Summary
      type: object
    inbound-shipment-item-list.schema:
      description: Inbound shipment line item (list view).
      properties:
        id:
          description: Prefixed shipment item ID (`isp_...`).
          example: isp_8b2c3d4e5f
          type: string
        product:
          $ref: '#/components/schemas/inbound-shipment-product-summary.schema'
        quantity:
          description: Expected quantity.
          example: 500
          type: integer
        received_quantity:
          description: Quantity received so far.
          example: 0
          type: integer
        damaged_quantity:
          description: Damaged units.
          example: 0
          type: integer
        missing_quantity:
          description: Missing units.
          example: 0
          type: integer
      required:
        - id
        - product
        - quantity
        - received_quantity
        - damaged_quantity
        - missing_quantity
      title: Inbound Shipment Item
      type: object
    inbound-shipment-list.schema:
      description: Inbound shipment (list view).
      properties:
        id:
          description: Prefixed shipment ID (`inb_...`).
          example: inb_7a3f9c2e1b
          type: string
        shipment_id:
          description: Merchant-assigned shipment identifier.
          example: SHIP-2026-0042
          nullable: true
          type: string
        status:
          description: Shipment status.
          enum:
            - PENDING
            - IN_TRANSIT
            - PARTIALLY_RECEIVED
            - RECEIVED
          example: IN_TRANSIT
          type: string
        location:
          $ref: '#/components/schemas/inbound-shipment-location.schema'
        carrier:
          description: Carrier name.
          example: FedEx Freight
          nullable: true
          type: string
        tracking_number:
          description: Tracking number.
          example: '794644790132'
          nullable: true
          type: string
        tracking_url:
          description: Tracking URL.
          example: https://www.fedex.com/fedextrack/?trknbr=794644790132
          nullable: true
          type: string
        estimated_arrival_date:
          description: Expected arrival date (YYYY-MM-DD).
          example: '2026-04-15'
          format: date
          nullable: true
          type: string
        actual_arrival_date:
          description: Actual arrival date (YYYY-MM-DD).
          example: null
          format: date
          nullable: true
          type: string
        freight_type:
          description: Type of freight (e.g. `LTL`, `FTL`, `Parcel`).
          example: LTL
          nullable: true
          type: string
        payment_terms:
          description: Payment terms (e.g. `NET30`, `COD`).
          example: NET30
          nullable: true
          type: string
        freight_cost:
          $ref: '#/components/schemas/inbound-shipment-money.schema'
        duty_cost:
          $ref: '#/components/schemas/inbound-shipment-money.schema'
        items:
          items:
            $ref: '#/components/schemas/inbound-shipment-item-list.schema'
          type: array
        sku_count:
          description: Distinct SKU count.
          example: 2
          type: integer
        item_count:
          description: Total expected unit quantity.
          example: 800
          type: integer
        received_count:
          description: Total received units.
          example: 0
          type: integer
        created_at:
          description: Creation timestamp (ISO 8601).
          example: '2026-03-28T14:30:00Z'
          format: date-time
          type: string
        updated_at:
          description: Last updated timestamp (ISO 8601).
          example: '2026-03-29T09:15:00Z'
          format: date-time
          type: string
      required:
        - id
        - shipment_id
        - status
        - location
        - carrier
        - tracking_number
        - tracking_url
        - estimated_arrival_date
        - actual_arrival_date
        - freight_type
        - payment_terms
        - freight_cost
        - duty_cost
        - items
        - sku_count
        - item_count
        - received_count
        - created_at
        - updated_at
      title: Inbound Shipment
      type: object
    inbound-shipment-product-detail.schema:
      description: Product detail in a shipment item (detail view).
      allOf:
        - $ref: '#/components/schemas/inbound-shipment-product-summary.schema'
        - properties:
            upc:
              description: Universal product code.
              example: '012345678901'
              nullable: true
              type: string
          type: object
      title: Inbound Shipment Product Detail
    inbound-shipment-item-detail.schema:
      description: Inbound shipment line item (detail view).
      allOf:
        - $ref: '#/components/schemas/inbound-shipment-item-list.schema'
        - properties:
            product:
              $ref: '#/components/schemas/inbound-shipment-product-detail.schema'
            discrepancy:
              description: Difference between expected and received quantity.
              example: -150
              type: integer
            packing_mode:
              description: Packing mode (e.g. `individual`).
              example: individual
              type: string
          type: object
      title: Inbound Shipment Item Detail
    inbound-shipment-order-ref.schema:
      description: Reference to a linked purchase order or transfer order.
      properties:
        id:
          description: Prefixed order ID (`po_...` or `trn_...`).
          example: po_5e6f7a8b9c
          type: string
        name:
          description: Order number or name.
          example: PO-2026-0018
          type: string
      required:
        - id
        - name
      title: Order Reference
      type: object
    inbound-shipment-file.schema:
      description: File attached to an inbound shipment.
      properties:
        id:
          description: Prefixed file ID (`isf_...`).
          example: isf_3d4e5f6g7h
          type: string
        title:
          description: File display title.
          example: Packing List.pdf
          type: string
        url:
          description: File URL.
          example: https://storage.example.com/files/packing-list.pdf
          type: string
        content_type:
          description: MIME type.
          example: application/pdf
          type: string
        created_at:
          description: Upload timestamp (ISO 8601).
          example: '2026-03-28T14:35:00Z'
          format: date-time
          type: string
      required:
        - id
        - title
        - url
        - content_type
        - created_at
      title: Inbound Shipment File
      type: object
    inbound-shipment-detail.schema:
      description: Inbound shipment (detail view).
      allOf:
        - $ref: '#/components/schemas/inbound-shipment-list.schema'
        - properties:
            items:
              items:
                $ref: '#/components/schemas/inbound-shipment-item-detail.schema'
              type: array
            custom_volume_cubic_meters:
              description: Custom volume in cubic meters.
              example: 2.4
              nullable: true
              type: number
            purchase_orders:
              description: Linked purchase orders.
              items:
                $ref: '#/components/schemas/inbound-shipment-order-ref.schema'
              type: array
            transfer_orders:
              description: Linked transfer orders.
              items:
                $ref: '#/components/schemas/inbound-shipment-order-ref.schema'
              type: array
            files:
              description: Attached files.
              items:
                $ref: '#/components/schemas/inbound-shipment-file.schema'
              type: array
            damaged_count:
              description: Total damaged units.
              example: 5
              type: integer
            missing_count:
              description: Total missing units.
              example: 0
              type: integer
          required:
            - custom_volume_cubic_meters
            - purchase_orders
            - transfer_orders
            - files
            - damaged_count
            - missing_count
          type: object
      title: Inbound Shipment Detail
    inventory-item-location.schema:
      description: Per-location quantity for an inventory item.
      properties:
        location_id:
          description: Prefixed location ID (`loc_...`).
          example: loc_4d8e1a2b3c
          type: string
        location_name:
          description: Location name.
          example: East Coast Warehouse
          type: string
        quantity:
          description: On-hand quantity at this location.
          example: 120
          type: integer
      required:
        - location_id
        - location_name
        - quantity
      title: Inventory Item Location
      type: object
    inventory-item-list.schema:
      description: Inventory item list entry.
      properties:
        id:
          description: Prefixed inventory item ID (`ii_...`).
          example: ii_5f8e1a2b3c
          type: string
        sku:
          description: Stock keeping unit from the linked product.
          example: TSH-BLK-M
          nullable: true
          type: string
        name:
          description: Product title including variant options.
          example: Classic Cotton T-Shirt - Black / M
          nullable: true
          type: string
        kind:
          description: Inventory item kind.
          enum:
            - PRODUCT
            - RETURN
            - UNDECLARED
            - UNKNOWN
          example: PRODUCT
          type: string
        quantity:
          description: On-hand quantity. When `location_id` is supplied as a query filter, this is the quantity at that location; otherwise it is the total across all locations.
          example: 250
          type: integer
        locations:
          description: Per-location quantities for this inventory item.
          items:
            $ref: '#/components/schemas/inventory-item-location.schema'
          type: array
        created_at:
          description: Creation timestamp (ISO 8601).
          example: '2025-11-01T10:00:00.000Z'
          format: date-time
          type: string
        updated_at:
          description: Last updated timestamp (ISO 8601).
          example: '2026-03-31T18:45:00.000Z'
          format: date-time
          type: string
      required:
        - id
        - sku
        - name
        - kind
        - quantity
        - locations
        - created_at
        - updated_at
      title: Inventory Item
      type: object
    inventory-level-product-summary.schema:
      description: Product summary in an inventory level response.
      properties:
        id:
          description: Prefixed product ID (`prd_...`).
          example: prd_1a2b3c4d5e
          type: string
        title:
          description: Product title including variant options.
          example: Classic Cotton T-Shirt - Black / M
          type: string
        sku:
          description: Stock keeping unit.
          example: TSH-BLK-M
          nullable: true
          type: string
      required:
        - id
        - title
        - sku
      title: Inventory Level Product Summary
      type: object
    inventory-level-location.schema:
      description: Location summary in an inventory level response.
      properties:
        id:
          description: Prefixed location ID (`loc_...`).
          example: loc_4d8e1a2b3c
          type: string
        name:
          description: Location name.
          example: East Coast Warehouse
          type: string
      required:
        - id
        - name
      title: Inventory Level Location
      type: object
    inventory-level-list.schema:
      description: Inventory level list item.
      properties:
        id:
          description: Prefixed inventory level ID (`li_...`).
          example: li_9b2c4d6e8f
          type: string
        product:
          $ref: '#/components/schemas/inventory-level-product-summary.schema'
        location:
          $ref: '#/components/schemas/inventory-level-location.schema'
        quantity:
          description: On-hand quantity.
          example: 1250
          type: integer
        available:
          description: Available quantity (`quantity - committed - reserved`).
          example: 1100
          type: integer
        committed:
          description: Allocated to unfulfilled orders.
          example: 100
          type: integer
        reserved:
          description: Held (damaged, QC, etc.).
          example: 50
          type: integer
        buildable:
          description: Can be assembled from BOM components.
          example: 0
          type: integer
        total_available:
          description: Total available (`available + buildable`).
          example: 1100
          type: integer
        updated_at:
          description: Last updated timestamp (ISO 8601).
          example: '2026-03-31T18:45:00.000Z'
          format: date-time
          type: string
      required:
        - id
        - product
        - location
        - quantity
        - available
        - committed
        - reserved
        - buildable
        - total_available
        - updated_at
      title: Inventory Level
      type: object
    inventory-level-product-detail.schema:
      description: Product detail in an inventory level detail response.
      allOf:
        - $ref: '#/components/schemas/inventory-level-product-summary.schema'
        - properties:
            upc:
              description: Universal product code.
              example: '012345678901'
              nullable: true
              type: string
            image_url:
              description: URL of the product's primary image.
              example: https://cdn.example.com/tshirt-blk-m.jpg
              nullable: true
              type: string
          type: object
      title: Inventory Level Product Detail
    inventory-level-detail.schema:
      description: Inventory level detail.
      allOf:
        - $ref: '#/components/schemas/inventory-level-list.schema'
        - properties:
            product:
              $ref: '#/components/schemas/inventory-level-product-detail.schema'
            external_ids:
              description: External system IDs (e.g. Shopify inventory item GID).
              example:
                shopify: gid://shopify/InventoryItem/12345678
              nullable: true
              type: object
            created_at:
              description: Creation timestamp (ISO 8601).
              example: '2025-11-01T10:00:00.000Z'
              format: date-time
              type: string
          required:
            - external_ids
            - created_at
          type: object
      title: Inventory Level Detail
    invoice.schema:
      description: Schema for an invoice.
      properties:
        charge:
          $ref: '#/components/schemas/money.schema'
          description: The charge that the invoice is for.
        createdAt:
          description: The time the invoice was created.
          format: date-time
          type: string
        id:
          description: The ID of the charge.
          type: string
        status:
          description: The status of the invoice.
          type: string
        store:
          properties:
            id:
              description: The ID of the store.
              type: string
          required:
            - id
          type: object
        updatedAt:
          description: The time the invoice was last updated.
          format: date-time
          type: string
      required:
        - team
        - updatedAt
        - status
        - createdAt
        - charge
      type: object
    orders-api-line-item.schema:
      description: Line item in the order.
      properties:
        id:
          description: Unique identifier for the line item.
          type: string
        productId:
          description: Identifier for the product.
          type: string
        variantId:
          description: Identifier for the product variant.
          type:
            - string
            - 'null'
        title:
          description: Title/name of the product.
          type: string
        sku:
          description: SKU of the product.
          type:
            - string
            - 'null'
        quantity:
          description: Quantity of the product ordered.
          minimum: 1
          maximum: 1000
          type: integer
        price:
          description: Price per unit of the product before discounts, as a decimal amount in the order's currency (e.g. $79.99, not 7999 cents).
          minimum: 0
          type:
            - number
            - 'null'
        imageUrl:
          description: URL to the product image.
          maxLength: 2048
          type:
            - string
            - 'null'
        discount:
          description: Total discount amount applied to this line item, as a decimal amount in the order's currency (e.g. $79.99, not 7999 cents).
          minimum: 0
          type:
            - number
            - 'null'
      required:
        - id
        - productId
        - title
        - quantity
      type: object
    orders-api-customer.schema:
      description: Customer information.
      properties:
        id:
          description: Customer ID from the external system.
          type:
            - string
            - 'null'
        email:
          description: Customer email address.
          type:
            - string
            - 'null'
        phoneNumber:
          description: Customer phone number.
          type:
            - string
            - 'null'
        name:
          description: Customer full name.
          type:
            - string
            - 'null'
        firstName:
          description: Customer first name.
          type:
            - string
            - 'null'
        lastName:
          description: Customer last name.
          type:
            - string
            - 'null'
      type: object
    orders-api-shipping-address.schema:
      description: Shipping address.
      properties:
        address1:
          description: Primary address line.
          type:
            - string
            - 'null'
        address2:
          description: Secondary address line.
          type:
            - string
            - 'null'
        city:
          description: City.
          type:
            - string
            - 'null'
        province:
          description: State or province.
          type:
            - string
            - 'null'
        country:
          description: Country.
          type:
            - string
            - 'null'
        postalCode:
          description: Postal or zip code.
          type:
            - string
            - 'null'
      type: object
    orders-api-shipping.schema:
      description: Shipping information.
      properties:
        method:
          description: Shipping method name.
          type:
            - string
            - 'null'
        cost:
          description: Shipping cost, as a decimal amount in the order's currency (e.g. $79.99, not 7999 cents).
          minimum: 0
          type:
            - number
            - 'null'
        address:
          $ref: '#/components/schemas/orders-api-shipping-address.schema'
      type: object
    orders-api-billing-address.schema:
      description: Billing address.
      properties:
        address1:
          description: Primary address line.
          type:
            - string
            - 'null'
        address2:
          description: Secondary address line.
          type:
            - string
            - 'null'
        city:
          description: City.
          type:
            - string
            - 'null'
        province:
          description: State or province.
          type:
            - string
            - 'null'
        country:
          description: Country.
          type:
            - string
            - 'null'
        postalCode:
          description: Postal or zip code.
          type:
            - string
            - 'null'
      type: object
    orders-api-create-order-request.schema:
      description: Request body for creating an order.
      properties:
        orderId:
          description: Unique identifier for the order.
          type: string
        createdAt:
          description: ISO 8601 date string for when the order was created.
          format: date-time
          type: string
        lineItems:
          description: List of line items in the order.
          items:
            $ref: '#/components/schemas/orders-api-line-item.schema'
          minItems: 1
          type: array
        customer:
          $ref: '#/components/schemas/orders-api-customer.schema'
        shipping:
          $ref: '#/components/schemas/orders-api-shipping.schema'
        totalPrice:
          description: Total order price including tax and shipping, as a decimal amount in the order's currency (e.g. $79.99, not 7999 cents).
          minimum: 0
          type:
            - number
            - 'null'
        subtotalPrice:
          description: Subtotal price excluding tax and shipping, as a decimal amount in the order's currency (e.g. $79.99, not 7999 cents).
          minimum: 0
          type:
            - number
            - 'null'
        totalTax:
          description: Total tax amount, as a decimal amount in the order's currency (e.g. $79.99, not 7999 cents).
          minimum: 0
          type:
            - number
            - 'null'
        totalDiscount:
          description: Total discount amount applied to the order (e.g. coupon codes, promotions), as a decimal amount in the order's currency (e.g. $79.99, not 7999 cents).
          minimum: 0
          type:
            - number
            - 'null'
        billingAddress:
          $ref: '#/components/schemas/orders-api-billing-address.schema'
        tags:
          description: Optional tags associated with the order.
          items:
            type: string
          type:
            - array
            - 'null'
        currencyCode:
          description: Currency code from the ISO 4217 standard (e.g., USD, EUR, GBP).
          type:
            - string
            - 'null'
        locationId:
          description: Optional. Pin this order to a specific fulfillment location. Must be a location id (`loc_...`) returned by `GET /inventory-levels` — either one of your own warehouses or a location at a linked 3PL fulfillment service. When provided, the fulfillment group's origin address is sourced from the location row. Omit to use your team's default origin address.
          example: loc_4d8e1a2b3c
          type:
            - string
            - 'null'
      required:
        - orderId
        - createdAt
        - lineItems
      type: object
    orders-api-create-order-response.schema:
      description: Successful order creation response.
      properties:
        orderId:
          description: Internal Redo order ID.
          type: string
        externalOrderId:
          description: Original external order ID provided in the request.
          type: string
      required:
        - orderId
        - externalOrderId
      type: object
    orders-api-error.schema:
      description: Orders API error response.
      properties:
        error:
          description: Error message describing what went wrong.
          type: string
      required:
        - error
      type: object
    orders-api-fulfillment-line-item.schema:
      description: Fulfilled line item details.
      properties:
        id:
          description: Line item ID that was fulfilled.
          type: string
        quantity:
          description: Quantity fulfilled for this line item.
          minimum: 1
          maximum: 1000
          type: integer
        title:
          description: Title/name of the product.
          type: string
        productId:
          description: Product ID.
          type: string
        variantId:
          description: Product variant ID.
          type:
            - string
            - 'null'
        sku:
          description: SKU of the product.
          type:
            - string
            - 'null'
      required:
        - id
        - quantity
        - title
        - productId
      type: object
    orders-api-tracking-location.schema:
      description: Location information for a tracking event.
      properties:
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        country:
          type:
            - string
            - 'null'
        postalCode:
          type:
            - string
            - 'null'
      type: object
    orders-api-tracking-event.schema:
      description: Tracking event details.
      properties:
        message:
          description: Tracking event message.
          type: string
        status:
          description: Status at this tracking event.
          type: string
        datetime:
          description: ISO 8601 timestamp of the tracking event.
          format: date-time
          type: string
        location:
          $ref: '#/components/schemas/orders-api-tracking-location.schema'
      required:
        - message
        - status
        - datetime
      type: object
    orders-api-fulfillment.schema:
      description: Fulfillment information.
      properties:
        id:
          description: Unique fulfillment ID.
          type: string
        createdAt:
          description: ISO 8601 date string for when the fulfillment was created.
          format: date-time
          type: string
        lineItems:
          description: List of line items in this fulfillment.
          items:
            $ref: '#/components/schemas/orders-api-fulfillment-line-item.schema'
          type: array
        trackingCompany:
          description: Shipping carrier name (e.g., FedEx, UPS).
          type:
            - string
            - 'null'
        trackingNumber:
          description: Tracking number for the shipment.
          type:
            - string
            - 'null'
        status:
          description: Current shipment status.
          enum:
            - pre_transit
            - unknown
            - in_transit
            - out_for_delivery
            - available_for_pickup
            - delivered
            - return_to_sender
            - failure
            - cancelled
            - error
          type: string
        estimatedDeliveryDate:
          description: Carrier's estimated delivery date (YYYY-MM-DD), typically in the destination's local time. Some carriers do not clearly distinguish local vs UTC, so the date may occasionally be off by one day.
          pattern: ^\d{4}-\d{2}-\d{2}$
          type:
            - string
            - 'null'
        deliveredAt:
          description: ISO 8601 timestamp of when the shipment was delivered.
          format: date-time
          type:
            - string
            - 'null'
        trackingHistory:
          description: List of tracking events in chronological order.
          items:
            $ref: '#/components/schemas/orders-api-tracking-event.schema'
          type: array
      required:
        - id
        - createdAt
        - lineItems
        - status
        - trackingHistory
      type: object
    orders-api-get-order-response.schema:
      description: Response for getting an order, including fulfillments.
      allOf:
        - $ref: '#/components/schemas/orders-api-create-order-request.schema'
        - properties:
            fulfillments:
              description: List of fulfillments for this order.
              items:
                $ref: '#/components/schemas/orders-api-fulfillment.schema'
              type: array
          required:
            - fulfillments
          type: object
    orders-api-delete-order-response.schema:
      description: Successful order deletion response.
      properties:
        success:
          description: Indicates successful deletion.
          type: boolean
        orderId:
          description: Internal Redo order ID.
          type: string
        externalOrderId:
          description: External order ID that was deleted.
          type: string
      required:
        - success
        - orderId
        - externalOrderId
      type: object
    orders-api-create-fulfillment-request.schema:
      description: Request body for creating a fulfillment.
      properties:
        fulfillmentId:
          description: Unique identifier for the fulfillment. If not provided, will be auto-generated.
          type: string
        lineItems:
          description: List of line items to fulfill.
          items:
            description: Line item fulfillment details.
            properties:
              id:
                description: Line item ID to fulfill.
                type: string
              quantity:
                description: Quantity to fulfill for this line item.
                minimum: 1
                maximum: 1000
                type: integer
            required:
              - id
              - quantity
            type: object
          minItems: 1
          type: array
        tracking:
          description: Optional tracking information for the shipment.
          properties:
            carrier:
              description: Name of the shipping carrier (e.g., FedEx, UPS, USPS).
              type: string
            code:
              description: Tracking number/code for the shipment.
              type: string
          required:
            - carrier
            - code
          type:
            - object
            - 'null'
        useDummyTracking:
          description: If true, creates a dummy tracker for testing without calling external tracking APIs. Useful for development and testing the fulfillment status update endpoint.
          type: boolean
        initialTracking:
          description: Initial tracking information for the dummy tracker. Only used when useDummyTracking is true. If not specified, defaults to status "pre_transit".
          properties:
            status:
              description: Initial shipment status for the dummy tracker. Only actual statuses are allowed (not automation events).
              enum:
                - pre_transit
                - unknown
                - in_transit
                - out_for_delivery
                - available_for_pickup
                - delivered
                - return_to_sender
                - failure
                - cancelled
                - error
              type: string
            estimatedDeliveryDate:
              description: Estimated delivery date in ISO 8601 format.
              format: date-time
              type:
                - string
                - 'null'
            message:
              description: Tracking event message.
              type:
                - string
                - 'null'
            datetime:
              description: Timestamp of the tracking event in ISO 8601 format.
              format: date-time
              type:
                - string
                - 'null'
            location:
              $ref: '#/components/schemas/orders-api-tracking-location.schema'
          required:
            - status
          type: object
      required:
        - lineItems
      type: object
    orders-api-fulfillment-response.schema:
      description: Successful fulfillment operation response.
      properties:
        success:
          const: true
          type: boolean
        fulfillment:
          $ref: '#/components/schemas/orders-api-fulfillment.schema'
      required:
        - success
        - fulfillment
      type: object
    orders-api-update-fulfillment-status-request.schema:
      description: |
        Request body for updating a fulfillment's tracking status.

        The status field accepts two types of values:
        - **Statuses** (e.g., `in_transit`, `delivered`): Update the shipment's current status and trigger configured automations.
        - **Events** (e.g., `stalled_in_transit`, `delayed`, `arriving_early`): Trigger automations without changing the current shipment status.

        Both can update other fields like estimated delivery date and tracking history.
      properties:
        status:
          description: |
            Shipment status or automation event.

            Statuses update the current shipment status and trigger automations:
            `pre_transit`, `in_transit`, `out_for_delivery`, `available_for_pickup`, `delivered`, `return_to_sender`, `failure`, `cancelled`, `error`.

            Events trigger automations without changing the current status:
            `stalled_in_transit`, `delayed`, `arriving_early`.
          enum:
            - pre_transit
            - in_transit
            - out_for_delivery
            - available_for_pickup
            - delivered
            - return_to_sender
            - failure
            - cancelled
            - error
            - stalled_in_transit
            - delayed
            - arriving_early
          type: string
        estimatedDeliveryDate:
          description: Estimated delivery date in ISO 8601 format.
          format: date-time
          type:
            - string
            - 'null'
        message:
          description: Tracking event message (e.g., "Departed shipping partner facility").
          type:
            - string
            - 'null'
        datetime:
          description: Timestamp of the tracking event in ISO 8601 format.
          format: date-time
          type:
            - string
            - 'null'
        location:
          $ref: '#/components/schemas/orders-api-tracking-location.schema'
      required:
        - status
      type: object
    bulk-product-family-option.schema:
      description: A product option (e.g. Size, Color) with its possible values.
      properties:
        name:
          description: Option name (e.g. "Size", "Color").
          maxLength: 255
          title: Name
          type: string
        values:
          description: Possible values for this option (e.g. ["Small", "Medium", "Large"]).
          items:
            maxLength: 255
            type: string
          title: Values
          type: array
      required:
        - name
        - values
      title: Product Family Option
      type: object
    bulk-product-family-image.schema:
      description: An image associated with a product family or variant.
      properties:
        url:
          description: URL of the image.
          format: uri
          title: URL
          type: string
        alt_text:
          description: Alt text for the image.
          maxLength: 1000
          title: Alt Text
          type: string
      required:
        - url
        - alt_text
      title: Product Family Image
      type: object
    bulk-variant.schema:
      description: A product variant within a product family.
      properties:
        id:
          description: Redo variant ID. Used for matching to an existing variant.
          maxLength: 255
          title: ID
          type: string
        external_id:
          description: Variant ID in your external system. Used for matching if `id` is not provided.
          maxLength: 255
          title: External ID
          type: string
        title:
          description: Variant title (e.g. "Small / Blue").
          maxLength: 500
          title: Title
          type: string
        sku:
          description: Stock keeping unit. Required. Used for matching if neither `id` nor `external_id` are provided.
          maxLength: 255
          minLength: 1
          title: SKU
          type: string
        upc:
          description: Universal product code.
          maxLength: 50
          title: UPC
          type: string
        barcodes:
          description: Additional barcodes for this variant.
          items:
            maxLength: 255
            type: string
          title: Barcodes
          type: array
        price:
          description: Price in the smallest currency unit (e.g. cents for USD).
          minimum: 0
          title: Price
          type: integer
        currency:
          description: Currency code (e.g. "USD").
          maxLength: 10
          title: Currency
          type: string
        weight:
          description: Weight of the variant.
          title: Weight
          type: number
        weight_unit:
          description: Unit of weight measurement.
          enum:
            - g
            - kg
            - lb
            - oz
            - t
          title: Weight Unit
          type: string
        width:
          description: Width of the variant.
          title: Width
          type: number
        length:
          description: Length of the variant.
          title: Length
          type: number
        height:
          description: Height of the variant.
          title: Height
          type: number
        dimension_unit:
          description: Unit of dimension measurement.
          enum:
            - in
            - cm
          title: Dimension Unit
          type: string
        hs_code:
          description: Harmonized System code for customs.
          maxLength: 50
          title: HS Code
          type: string
        origin_country:
          description: Country of origin as an ISO 3166-1 alpha-2 code (e.g. "US").
          pattern: ^[A-Z]{2}$
          title: Origin Country
          type: string
        option_values:
          description: Values for each option defined on the product family, in the same order.
          items:
            maxLength: 255
            type: string
          title: Option Values
          type: array
        images:
          description: Images specific to this variant.
          items:
            $ref: '#/components/schemas/bulk-product-family-image.schema'
          title: Images
          type: array
      required:
        - sku
        - price
        - currency
      title: Bulk Variant
      type: object
    bulk-product-family.schema:
      description: |
        A product family containing one or more variants.

        Matching priority for existing product families:
        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.
      properties:
        product_family_id:
          description: Redo product family ID. Highest-priority match for updating an existing product family.
          maxLength: 255
          title: Product Family ID
          type: string
        external_id:
          description: Product family ID in your external system. Second-priority match.
          maxLength: 255
          title: External ID
          type: string
        title:
          description: Product family title.
          maxLength: 500
          minLength: 1
          title: Title
          type: string
        description:
          description: Product family description.
          maxLength: 5000
          title: Description
          type: string
        vendor:
          description: Vendor or manufacturer name.
          maxLength: 255
          title: Vendor
          type: string
        tags:
          default: []
          description: Tags for categorization.
          items:
            maxLength: 255
            type: string
          title: Tags
          type: array
        kind:
          default: SELLABLE
          description: Whether the product is sellable or non-sellable.
          enum:
            - SELLABLE
            - NON_SELLABLE
          title: Kind
          type: string
        options:
          description: Product options (e.g. Size, Color) with their possible values.
          items:
            $ref: '#/components/schemas/bulk-product-family-option.schema'
          title: Options
          type: array
        images:
          description: Images for the product family.
          items:
            $ref: '#/components/schemas/bulk-product-family-image.schema'
          title: Images
          type: array
        variants:
          description: Product variants. At least 1 and up to 100 per product family.
          items:
            $ref: '#/components/schemas/bulk-variant.schema'
          maxItems: 100
          minItems: 1
          title: Variants
          type: array
      required:
        - title
        - variants
      title: Bulk Product Family
      type: object
    bulk-product-upload-request.schema:
      description: Request body for bulk uploading product families and their variants.
      properties:
        products:
          description: Product families to create or update. Between 1 and 1000 per request.
          items:
            $ref: '#/components/schemas/bulk-product-family.schema'
          maxItems: 1000
          minItems: 1
          title: Products
          type: array
      required:
        - products
      title: Bulk Product Upload Request
      type: object
    bulk-product-upload-response.schema:
      description: Response from a bulk product upload operation.
      properties:
        total_count:
          description: Total number of product families in the request.
          title: Total Count
          type: integer
        processed_count:
          description: Number of product families processed successfully.
          title: Processed Count
          type: integer
        error_count:
          description: Number of product families that failed to process.
          title: Error Count
          type: integer
        results:
          description: Per-product-family results.
          items:
            oneOf:
              - description: A product family that was created or updated successfully.
                properties:
                  status:
                    description: Whether the product family was created or updated.
                    enum:
                      - created
                      - updated
                    title: Status
                    type: string
                  product_family_id:
                    description: Redo product family ID.
                    title: Product Family ID
                    type: string
                  products:
                    description: Variant results within this product family.
                    items:
                      properties:
                        id:
                          description: Redo product ID.
                          title: ID
                          type: string
                        sku:
                          description: Product SKU.
                          title: SKU
                          type: string
                      required:
                        - id
                        - sku
                      type: object
                    title: Products
                    type: array
                required:
                  - status
                  - product_family_id
                  - products
                title: Success Result
                type: object
              - description: A product family that failed to process.
                properties:
                  status:
                    const: error
                    description: Indicates an error occurred.
                    title: Status
                    type: string
                  error:
                    description: Error message describing what went wrong.
                    title: Error
                    type: string
                required:
                  - status
                  - error
                title: Error Result
                type: object
          title: Results
          type: array
      required:
        - total_count
        - processed_count
        - error_count
        - results
      title: Bulk Product Upload Response
      type: object
    person-name.schema:
      description: Person name.
      properties:
        given:
          description: Given name
          examples:
            - John
            - Mary
          type: string
        surname:
          description: Surname
          examples:
            - Smith
            - Brown
          type: string
      required:
        - given
        - surname
      title: Person name
      type: object
    phone-number.schema:
      description: Phone number, in E.164 format
      examples:
        - '+15555555555'
      title: Phone number
      type: string
    product.schema:
      description: Product.
      properties:
        externalId:
          description: Product ID in external system (e.g. shopify).
          title: External ID
          type: string
        name:
          description: Product title
          title: Name
          type: string
      required:
        - name
      title: Product
      type: object
    item-quantity.schema:
      description: Item quantity.
      example: 1
      exclusiveMinimum: 0
      title: Item quantity
      type: number
    product-variant.schema:
      properties:
        externalId:
          title: External ID
          type: string
        name:
          title: Title
          type: string
        sku:
          title: SKU
          type: string
        weight:
          $ref: '#/components/schemas/weight.schema'
          title: Weight
      required:
        - name
      title: Product variant
      type: object
    order-read.schema:
      description: Order.
      properties:
        customer:
          properties:
            emailAddress:
              description: Email address of customer.
              format: email
              title: Email address
              type: string
            name:
              $ref: '#/components/schemas/person-name.schema'
              description: Name of customer.
              title: Name
            phoneNumber:
              $ref: '#/components/schemas/phone-number.schema'
              description: Phone number of customer.
              title: Phone number
          required:
            - name
          type: object
        discounts:
          $ref: '#/components/schemas/money.schema'
          description: The total amount discounted on the order before returns. This includes both order and line level discounts.
          title: Discounts
        externalId:
          description: Shopify ID
          examples:
            - '1073459971'
            - '450789469'
          title: External ID
          type: string
        id:
          description: Order ID
          example: 64e4da943dd822979a70bd12
          title: ID
          type: string
        items:
          items:
            properties:
              externalId:
                example: '123'
                type: string
              fulfillmentLocationId:
                description: ID of the location where the item was be fulfilled.
                example: '123'
                type:
                  - string
                  - 'null'
              id:
                description: Line item ID
                title: ID
                type: string
              price:
                $ref: '#/components/schemas/money.schema'
                title: Price
              product:
                $ref: '#/components/schemas/product.schema'
                title: Product
              quantity:
                $ref: '#/components/schemas/item-quantity.schema'
                title: Quantity
              variant:
                $ref: '#/components/schemas/product-variant.schema'
                title: Variant
            required:
              - id
              - product
              - quantity
              - variant
              - price
              - fulfillmentLocationId
          title: Line items
          type: array
        lineItemsTotal:
          $ref: '#/components/schemas/money.schema'
          description: Total price of all line items before discounts, shipping, and taxes.
          title: Line Items Total
        name:
          description: Shopify name.
          examples:
            - '#123'
          title: Name
          type: string
        shippingCost:
          $ref: '#/components/schemas/money.schema'
          description: The total shipping cost for the order. This includes fees and any related discounts that were refunded.
          title: Shipping Cost
        taxes:
          $ref: '#/components/schemas/money.schema'
          description: Total taxes applied to the order.
          title: Taxes
        total:
          $ref: '#/components/schemas/money.schema'
          description: The total price of the order, before returns. This includes taxes, discounts, and shipping costs.
          title: Total
      required:
        - customer
        - id
        - items
        - name
        - discounts
        - lineItemsTotal
        - shippingCost
        - total
        - taxes
      title: Order
      type: object
    address.schema:
      description: Address.
      properties:
        city:
          description: City name
          examples:
            - Anytown
          title: City
          type: string
        country:
          description: Country code
          examples:
            - US
            - CA
          title: Country
          type: string
        line1:
          description: Line 1
          examples:
            - 123 Main St
          title: Line 1
          type: string
        line2:
          default: ''
          description: Line 2
          examples:
            - ''
          title: Line 2
          type: string
        postalCode:
          description: Postal or ZIP code
          examples:
            - '12345'
          title: Postal code
          type: string
        state:
          description: State or province
          examples:
            - WA
            - Washington
          title: State
          type: string
      required:
        - city
        - country
        - line1
        - state
        - postalCode
      title: Address
      type: object
    exchange-provision.schema:
      enum:
        - instant
        - deferred
      example: deferred
      title: Exchang provision
      type: string
    return-shipment.schema:
      description: Return shipment tracking information
      properties:
        carrier:
          description: Carrier code
          title: Carrier
          type: string
        status:
          description: Status of shipment
          enum:
            - unknown
            - pre_transit
            - in_transit
            - out_for_delivery
            - available_for_pickup
            - cancelled
            - delivered
            - error
            - failure
            - return_to_sender
            - expired
          title: Status
          type: string
        tracker:
          description: Tracking number
          title: Tracker
          type: string
        trackingUrl:
          description: Tracking URL
          title: Tracking URL
          type: string
        postageLabel:
          description: Postage label URL
          title: Postage Label
          type: string
        formLabel:
          description: Form label URL
          title: Form Label
          type: string
        shipmentGroupId:
          description: ID of the shipment group this shipment belongs to
          title: Shipment Group ID
          type: string
        itemIds:
          description: IDs of the return items included in this shipment
          items:
            type: string
          title: Item IDs
          type: array
        externalLocationId:
          description: External location ID for the destination of this shipment
          title: External Location ID
          type: string
        estimatedDeliveryDate:
          description: Estimated delivery date for this shipment
          title: Estimated Delivery Date
          type: string
        deliveredAt:
          description: Date and time this shipment was delivered
          title: Delivered At
          type: string
      title: Return Shipment
      type: object
    return-dropoff.schema:
      description: Dropoff entry for returns using QR-code-based drop-off methods (e.g. BlueYonder/FedEx Easy Returns)
      properties:
        shipmentGroupId:
          description: ID of the shipment group this dropoff belongs to
          title: Shipment Group ID
          type: string
        provider:
          description: Dropoff provider name (e.g. "FedEx Easy Returns", "Virtual")
          title: Provider
          type: string
        qrCode:
          description: Raw QR code data
          title: QR Code
          type: string
        qrCodeUrl:
          description: URL to a rendered QR code image
          title: QR Code URL
          type: string
      required:
        - shipmentGroupId
        - provider
      title: Return Dropoff
      type: object
    return-status.schema:
      description: |
        Return status.

        * open: Return has been approved and is awaiting shipment.
        * in_transit: Return shipment is in transit.
        * delivered: Return shipment has been delivered and awaiting processing.
        * needs_review: Return requires review before further action.
        * in_review: Return is currently being reviewed.
        * complete: The return has been completed successfully.
        * rejected: The return has been rejected.
        * flagged: A problem with return processing requires merchant action.
        * pre_shipment: Return requires pre-shipment merchant authorization.
        * deleted: The return has been deleted (Reset).
      enum:
        - open
        - in_transit
        - delivered
        - needs_review
        - in_review
        - complete
        - rejected
        - flagged
        - pre_shipment
        - deleted
      example: open
      title: Return status
      type: string
    return-type.schema:
      description: |
        Return type.
      enum:
        - claim
        - return
        - warranty
      example: return
      title: Return type
      type: string
    return-read.schema:
      description: Return read.
      properties:
        compensationMethods:
          description: Array of compensation methods available for this return
          items:
            enum:
              - refund
              - store_credit
              - exchange
            type: string
          title: Compensation Methods
          type: array
        completeWithNoAction:
          description: Whether this return can be completed with no action
          title: Complete With No Action
          type: boolean
        createdAt:
          description: Time of creation.
          format: date-time
          title: Created at
          type: string
        destination:
          properties:
            mailingAddress:
              $ref: '#/components/schemas/address.schema'
              description: Mailing address to send the returned items.
              title: Mailing address
            phoneNumber:
              $ref: '#/components/schemas/phone-number.schema'
              description: Phone number of the destination.
              title: Phone number
          type: object
        exchange:
          description: Exchange order
          properties:
            itemCount:
              description: Total quantity of all exchange items
              type: integer
            items:
              items:
                properties:
                  id:
                    title: ID
                    type: string
                  originalPrice:
                    description: Original price for the exchange item without discounts and taxes
                    properties:
                      amount:
                        type: string
                      currency:
                        type: string
                    type: object
                  price:
                    description: Subtotal price for the exchange item including discounts
                    properties:
                      amount:
                        type: string
                      currency:
                        type: string
                      tax:
                        type: string
                    type: object
                  product:
                    $ref: '#/components/schemas/product.schema'
                    title: Product
                  quantity:
                    $ref: '#/components/schemas/item-quantity.schema'
                    title: Quantity
                  variant:
                    $ref: '#/components/schemas/product-variant.schema'
                required:
                  - id
                  - quantity
                  - variant
              title: Line items
              type: array
            order:
              properties:
                externalId:
                  description: ID of external order
                  title: External ID
                  type: string
              type: object
            provision:
              $ref: '#/components/schemas/exchange-provision.schema'
              title: Provision
            totalTax:
              description: Total tax for exchange items
              properties:
                amount:
                  type: string
                currency:
                  type: string
              type: object
          required:
            - items
            - provision
          title: Exchange
          type: object
        externalOrderIds:
          description: Array of external order IDs associated with this return
          items:
            type: string
          title: External Order IDs
          type: array
        externalReturnIds:
          description: Array of external return identifiers associated with this return. For Shopify returns, value is Shopify's numeric return ID as a string, not a Shopify admin URL or gid:// ID.
          examples:
            - - provider: shopify
                value: '12345'
          items:
            properties:
              provider:
                description: External provider that owns this return identifier
                enum:
                  - shopify
                type: string
              value:
                description: Return identifier value from the external provider
                type: string
            required:
              - provider
              - value
            type: object
          title: External Return IDs
          type: array
        giftCards:
          description: Gift card(s) created for return
          items:
            properties:
              amount:
                $ref: '#/components/schemas/money.schema'
                title: Amount
              code:
                description: Gift card 16 digit code.
                title: Code
                type: string
              externalId:
                description: Gift card ID.
                title: ID
                type: string
            required:
              - amount
              - code
              - externalId
            type: object
          title: Gift cards
          type: array
        id:
          description: Return identifier.
          examples:
            - 64df65d4c5a4ca3eff4b4e43
          title: Identifier
          type: string
        internalCreatedByName:
          description: Name of the internal team member who created this return
          title: Internal Created By Name
          type: string
        items:
          description: Return items
          items:
            properties:
              customerComment:
                description: Customer's comment about the return
                type: string
              exchangeItem:
                description: Exchange item details if this return item is being exchanged
                properties:
                  product:
                    properties:
                      externalId:
                        type: string
                      name:
                        type: string
                    type: object
                  quantity:
                    type: integer
                  variant:
                    properties:
                      externalId:
                        type: string
                      name:
                        type: string
                    type: object
                title: Exchange item
                type: object
              grade:
                description: Merchant-assigned grade for the returned item (e.g. condition or quality tier). Null if the merchant has not graded this item.
                title: Grade
                type: string
                nullable: true
              greenReturn:
                description: Whether this is a green return (no physical return required)
                type: boolean
              outcome:
                description: Merchant-assigned processing outcome for the returned item (e.g. restock, dispose). Null if the merchant has not set an outcome for this item.
                title: Outcome
                type: string
                nullable: true
              shipmentGroupIds:
                description: IDs of the shipment groups this return item belongs to
                items:
                  type: string
                title: Shipment Group IDs
                type: array
              id:
                description: Return item ID.
                title: ID
                type: string
              orderItem:
                description: Order line item
                properties:
                  id:
                    description: 'Line item reference ID in format: {orderId}/{lineItemIndex}'
                    title: ID
                    type: string
                  line_item_id:
                    description: Original Shopify line item ID
                    title: Line Item ID
                    type: string
                required:
                  - id
                title: Order item
                type: object
              externalReturnLineItemId:
                description: External return line item ID
                title: External Return Line Item ID
                type: string
              productId:
                description: Product ID
                type: string
              quantity:
                description: Quantity of items being returned
                type: integer
              reason:
                description: Primary return reason
                examples:
                  - Too big
                  - Other
                type: string
              reasonCode:
                description: Return reason code
                type: string
              reasons:
                description: Array of return reasons
                items:
                  type: string
                type: array
              reasonCodes:
                description: Array of return reason codes
                items:
                  type: string
                type: array
              productAdjustment:
                description: Product adjustment details
                type: string
              multipleChoiceQuestions:
                description: Multiple choice questions and answers for this return item
                items:
                  properties:
                    question:
                      description: The question text
                      type: string
                    answer:
                      description: The selected answer
                      type: string
                  required:
                    - question
                    - answer
                  type: object
                type: array
              assessments:
                description: Assessment records for this return item. Only applicable for warranties.
                items:
                  properties:
                    assignedUser:
                      description: User assigned to this assessment
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        firstName:
                          type: string
                        lastName:
                          type: string
                        email:
                          type: string
                      required:
                        - id
                        - name
                        - firstName
                        - lastName
                        - email
                      type: object
                    responses:
                      description: Assessment responses
                      items:
                        discriminator:
                          propertyName: type
                        oneOf:
                          - title: Short Text Response
                            properties:
                              type:
                                const: short_text
                                type: string
                              value:
                                description: Short text response value
                                type: string
                            required:
                              - type
                              - value
                            type: object
                          - title: Long Text Response
                            properties:
                              type:
                                const: long_text
                                type: string
                              value:
                                description: Long text response value
                                type: string
                            required:
                              - type
                              - value
                            type: object
                          - title: Select Response
                            properties:
                              type:
                                const: select
                                type: string
                              value:
                                description: Select response values (array of selected options)
                                items:
                                  type: string
                                type: array
                            required:
                              - type
                              - value
                            type: object
                          - title: Number Response
                            properties:
                              type:
                                const: number
                                type: string
                              value:
                                description: Number response value
                                type: number
                            required:
                              - type
                              - value
                            type: object
                          - title: Boolean Response
                            properties:
                              type:
                                const: boolean
                                type: string
                              value:
                                description: Boolean response value
                                type: boolean
                            required:
                              - type
                              - value
                            type: object
                          - title: File Upload Response
                            properties:
                              type:
                                const: file_upload
                                type: string
                              value:
                                description: File upload response values (array of file URLs or identifiers)
                                items:
                                  type: string
                                type: array
                            required:
                              - type
                              - value
                            type: object
                          - title: Date Response
                            properties:
                              type:
                                const: date
                                type: string
                              value:
                                description: Date response value
                                format: date-time
                                type: string
                            required:
                              - type
                              - value
                            type: object
                      type: array
                  required:
                    - assignedUser
                    - responses
                  type: object
                type: array
              refund:
                description: Refund details
                properties:
                  amount:
                    $ref: '#/components/schemas/money.schema'
                    title: Amount
                  type:
                    description: Refund strategy
                    type: string
                required:
                  - amount
                type: object
              productValueNoTaxNoAdjustment:
                description: Per-product value before taxes and merchant adjustments. Equivalent to the "Product Value (No Tax/Adjustment)" column in the Returns Report.
                properties:
                  amount:
                    $ref: '#/components/schemas/money.schema'
                    title: Amount
                required:
                  - amount
                title: Product value (no tax / no adjustment)
                type: object
              sku:
                description: Product SKU
                type: string
              upc:
                description: Universal Product Code (barcode) snapshotted from the product at return-creation time. Null if no barcode was recorded.
                title: UPC
                type: string
                nullable: true
              status:
                description: Return item status
                type: string
              variantId:
                description: Product variant ID
                type: string
            required:
              - id
              - orderItem
              - quantity
              - reason
            type: object
          type: array
        notes:
          description: Teammembers generated notes and comments on the return
          items:
            properties:
              image:
                description: Optional image URL attached to the note
                title: Image URL
                type: string
              message:
                description: The note text
                title: Message
                type: string
            required:
              - message
            type: object
          title: Notes
          type: array
        order:
          description: Original order.
          properties:
            id:
              description: Redo's internal identifier for the original order created in Redo.
              example: 64e4da943dd822979a70bd12
              title: ID
              type: string
            name:
              description: Order name from the external provider, such as the Shopify order name.
              examples:
                - '#123'
              title: Name
              type: string
          required:
            - id
          title: Order
          type: object
        shipment:
          $ref: '#/components/schemas/return-shipment.schema'
          description: Shipment, if has been made
          title: Shipment
        shipments:
          description: Array of all shipments associated with this return
          items:
            $ref: '#/components/schemas/return-shipment.schema'
          title: Shipments
          type: array
        dropoffs:
          description: Array of QR-code-based dropoff entries for returns using drop-off methods such as BlueYonder/FedEx Easy Returns. Empty for standard label-based returns.
          items:
            $ref: '#/components/schemas/return-dropoff.schema'
          title: Dropoffs
          type: array
        shopifyOrderIds:
          description: Array of Shopify order IDs (deprecated, use externalOrderIds)
          items:
            type: string
          title: Shopify Order IDs
          type: array
        source:
          properties:
            emailAddress:
              description: Email address.
              format: email
              title: Email address
              type: string
            mailingAddress:
              $ref: '#/components/schemas/address.schema'
              description: Mailing address returned items are sent from.
              title: Mailing address
            name:
              $ref: '#/components/schemas/person-name.schema'
              description: Name of returner.
              title: Name
            phoneNumber:
              $ref: '#/components/schemas/phone-number.schema'
              description: Phone number of returner.
              title: Phone number
          required:
            - emailAddress
            - mailingAddress
            - name
            - phoneNumber
          type: object
        status:
          $ref: '#/components/schemas/return-status.schema'
          description: Return status.
          title: Status
        tags:
          description: Tags associated with this return
          items:
            properties:
              name:
                description: The tag's display name
                type: string
              source:
                description: The source of the tag
                type: string
            required:
              - name
              - source
            type: object
          title: Tags
          type: array
        totals:
          description: Calculated totals for the return
          properties:
            charge:
              description: The upsell amount for the exchange order
              properties:
                amount:
                  $ref: '#/components/schemas/money.schema'
              required:
                - amount
              type: object
            exchange:
              description: Total value of new items in exchange
              properties:
                amount:
                  $ref: '#/components/schemas/money.schema'
              required:
                - amount
              type: object
            refund:
              description: Total refund amount excluding shipping
              properties:
                amount:
                  $ref: '#/components/schemas/money.schema'
              required:
                - amount
              type: object
            storeCredit:
              description: Total store credit amount
              properties:
                amount:
                  $ref: '#/components/schemas/money.schema'
              required:
                - amount
              type: object
          required:
            - refund
            - exchange
            - storeCredit
            - charge
          title: Totals
          type: object
        type:
          $ref: '#/components/schemas/return-type.schema'
          description: Return type.
          title: Type
        updatedAt:
          description: Time of last update.
          format: date-time
          title: Updated at
          type: string
      required:
        - createdAt
        - destination
        - giftCards
        - source
        - id
        - order
        - items
        - status
        - updatedAt
      title: Return
      type: object
    comment.schema:
      description: Comment with either message or image.
      examples:
        - message: Item is worn.
        - image: eJxiYAEAAAD//wMAAAYABQ==
      oneOf:
        - additionalProperties: false
          properties:
            image:
              contentEncoding: base64
              description: Base64-encoded image
              title: Image
              type: string
          required:
            - image
          title: Image comment
          type: object
        - additionalProperties: false
          properties:
            message:
              description: Message.
              title: Message
              type: string
          required:
            - message
          title: Message comment
          type: object
      title: Comment
    return-status-update.schema:
      description: |
        Return status.

        * complete: The return has been completed successfully.
        * open: Return has been approved and is awaiting shipment.
        * flagged: A problem with return processing requires merchant action.
        * rejected: The return has been rejected.
        * deleted: The return has been reset.
      enum:
        - complete
        - open
        - flagged
        - rejected
        - deleted
      example: open
      title: Return status
      type: string
    create-return-request.schema:
      type: object
      description: Create return request body.
      properties:
        data:
          type: object
          description: Return information payload.
          properties:
            provider:
              type: string
              description: Ecommerce platform provider.
              examples:
                - shopify
            externalOrderId:
              type: string
              description: External order ID from the ecommerce platform.
            items:
              type: array
              minItems: 1
              description: Items being returned.
              items:
                type: object
                properties:
                  lineItemId:
                    type: string
                    description: External line item ID from the order.
                  quantity:
                    type: integer
                    minimum: 1
                    description: Number of units to return.
                  reason:
                    type: string
                    description: Customer-facing return reason.
                  reasonCode:
                    type: string
                    description: Machine-readable reason code.
                  compensation:
                    type: string
                    enum:
                      - refund
                      - store_credit
                    description: How the customer should be compensated for this item.
                  notes:
                    type: string
                    description: Customer-facing notes for this item.
                required:
                  - lineItemId
                  - quantity
                  - reason
                  - compensation
            shippingAddress:
              type: object
              description: Address the customer is shipping from.
              properties:
                line1:
                  type: string
                line2:
                  type: string
                city:
                  type: string
                state:
                  type: string
                postalCode:
                  type: string
                country:
                  type: string
                  description: ISO 3166-1 alpha-2 country code.
              required:
                - line1
                - city
                - state
                - postalCode
                - country
            label:
              type: object
              description: Optional return label and tracking details.
              properties:
                trackingNumber:
                  type: string
                  description: Carrier tracking number.
                carrier:
                  type: string
                  description: Carrier name.
                trackingUrl:
                  type: string
                  description: Public tracking URL.
                postageLabelUrl:
                  type: string
                  description: Postage label URL.
                formLabelUrl:
                  type: string
                  description: Commercial or form label URL.
                originalShipmentId:
                  type: string
                  description: Provider shipment identifier to reference.
              required:
                - trackingNumber
            notes:
              type: string
              description: Internal merchant-side notes.
          required:
            - provider
            - externalOrderId
            - items
            - shippingAddress
        options:
          type: object
          description: Options controlling side effects of the return creation.
          properties:
            createExternalRMAs:
              type: boolean
              description: Whether to create RMAs with external integrations (e.g. ShipBob). Defaults to false.
              default: false
      required:
        - data
    create-return-response.schema:
      type: object
      description: Create return response body.
      properties:
        return:
          $ref: '#/components/schemas/return-read.schema'
        externalRMAResponses:
          type: array
          items:
            type: object
            properties:
              integrationProvider:
                type: string
                description: Name of the external integration provider.
              success:
                type: boolean
                description: Whether external RMA creation succeeded.
              errorCode:
                type: string
                description: Provider error code when external RMA creation fails.
              errorMessage:
                type: string
                description: Provider error message when external RMA creation fails.
            required:
              - integrationProvider
              - success
      required:
        - return
        - externalRMAResponses
    bulk-returns-request.schema:
      type: object
      description: Import returns request body.
      properties:
        returns:
          type: array
          minItems: 1
          maxItems: 100
          description: Array of returns to import (max 100).
          items:
            type: object
            description: A single return to import.
            properties:
              products:
                type: array
                minItems: 1
                description: Products being returned (at least 1).
                items:
                  type: object
                  properties:
                    productId:
                      type: string
                      description: Redo product ID returned from the bulk product upload response (e.g. `prd_ABC123`).
                    quantity:
                      type: integer
                      minimum: 1
                      description: Number of units to return.
                    sku:
                      type: string
                      description: Override SKU (uses catalog value if omitted).
                    barcode:
                      type: string
                      description: Override barcode (uses catalog value if omitted).
                    productTitle:
                      type: string
                      description: Override product title (uses catalog value if omitted).
                    variantTitle:
                      type: string
                      description: Override variant title (uses catalog value if omitted).
                    reason:
                      type: string
                      description: Return reason.
                    condition:
                      type: string
                      description: Item condition.
                  required:
                    - productId
                    - quantity
              customer:
                type: object
                description: Optional customer information.
                properties:
                  firstName:
                    type: string
                  lastName:
                    type: string
                  email:
                    type: string
                    format: email
              externalReferenceId:
                type: string
                description: Merchant's own return/RMA ID. Stored on the return so it's scannable at warehouse intake.
              trackingNumber:
                type: string
                description: Carrier tracking number for the inbound return shipment.
              carrier:
                type: string
                description: Carrier name for the tracking number (e.g. 'USPS', 'UPS').
              notes:
                type: string
                description: Internal notes.
              idempotencyKey:
                type: string
                description: Idempotency key to prevent duplicate return creation on retry.
              currency:
                type: string
                description: ISO 4217 currency code (defaults to USD).
                examples:
                  - USD
                  - GBP
                  - EUR
              shippingAddress:
                type: object
                description: Customer's shipping address.
                properties:
                  line1:
                    type: string
                    description: Street address line 1.
                  line2:
                    type: string
                    description: Street address line 2.
                  city:
                    type: string
                    description: City.
                  state:
                    type: string
                    description: State or province code.
                  postalCode:
                    type: string
                    description: Postal/ZIP code.
                  country:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                  name:
                    type: string
                    description: Recipient or location name.
                  phone:
                    type: string
                    description: Phone number.
                required:
                  - line1
                  - city
                  - country
              merchantAddress:
                type: object
                description: Merchant return destination address.
                properties:
                  line1:
                    type: string
                    description: Street address line 1.
                  line2:
                    type: string
                    description: Street address line 2.
                  city:
                    type: string
                    description: City.
                  state:
                    type: string
                    description: State or province code.
                  postalCode:
                    type: string
                    description: Postal/ZIP code.
                  country:
                    type: string
                    description: ISO 3166-1 alpha-2 country code.
                  name:
                    type: string
                    description: Recipient or location name.
                  phone:
                    type: string
                    description: Phone number.
                required:
                  - line1
                  - city
                  - country
            required:
              - products
      required:
        - returns
    bulk-returns-response.schema:
      type: object
      description: Bulk external return creation response.
      properties:
        totalCount:
          type: integer
          description: Total number of returns in the request.
        processedCount:
          type: integer
          description: Number of returns successfully created.
        errorCount:
          type: integer
          description: Number of returns that failed.
        results:
          type: array
          description: Per-item results in the same order as the request.
          items:
            oneOf:
              - type: object
                properties:
                  status:
                    type: string
                    enum:
                      - created
                  index:
                    type: integer
                    description: Zero-based index into the request array.
                  returnId:
                    type: string
                    description: ID of the created return.
                required:
                  - status
                  - index
                  - returnId
              - type: object
                properties:
                  status:
                    type: string
                    enum:
                      - error
                  index:
                    type: integer
                    description: Zero-based index into the request array.
                  error:
                    type: string
                    description: Error message.
                required:
                  - status
                  - index
                  - error
            discriminator:
              propertyName: status
      required:
        - totalCount
        - processedCount
        - errorCount
        - results
    pill-theme.schema:
      description: Color theme used to render a tag pill in the UI.
      enum:
        - NORMAL
        - PRIMARY_LIGHT
        - LIGHT_PINK
        - DANGER
        - NEUTRAL_YELLOW
        - SUCCESS
        - NEUTRAL_BLUE
        - PRIMARY
        - SOLID_WHITE
        - SOLID_PINK
        - SOLID_RED
        - SOLID_ORANGE
        - SOLID_YELLOW
        - SOLID_GREEN
        - SOLID_LIGHT_BLUE
        - SOLID_NAVY
        - SOLID_BLACK
        - BRAND
        - GRAY_BLUE
        - WHITE_SUCCESS
        - GRAY_ALTERNATE
        - BRAND_ALTERNATE
        - ERROR_ALTERNATE
        - WARNING_ALTERNATE
        - SUCCESS_ALTERNATE
        - GRAY_BLUE_ALTERNATE
        - BLUE_LIGHT_ALTERNATE
        - BLUE_ALTERNATE
        - INDIGO_ALTERNATE
        - PURPLE_ALTERNATE
        - PINK_ALTERNATE
        - ORANGE_ALTERNATE
        - BLACK_ALTERNATE
        - WHITE_ALTERNATE
        - WHITE_SUCCESS_ALTERNATE
      title: Pill theme
      type: string
    return-tag.schema:
      description: A return tag defined for a store.
      properties:
        name:
          description: The tag's display name. Case-sensitive.
          type: string
        kind:
          const: return
          type: string
        pillTheme:
          $ref: '#/components/schemas/pill-theme.schema'
        source:
          description: Where the tag originated.
          enum:
            - merchant
            - redo
            - flow
          type: string
        numericId:
          description: Stable numeric identifier, if one has been assigned.
          type:
            - number
            - 'null'
      required:
        - name
        - kind
        - pillTheme
        - source
        - numericId
      title: Return tag
      type: object
    return-tag-upsert-request.schema:
      description: Request body for creating, recoloring, or renaming a return tag.
      properties:
        pillTheme:
          $ref: '#/components/schemas/pill-theme.schema'
        newName:
          description: New name for the tag. When set and different from the path `name`, the tag is renamed and the change cascades to returns and saved view filters.
          type: string
      required:
        - pillTheme
      title: Return tag upsert request
      type: object
    storefront-event.schema:
      additionalProperties: true
      description: Shopify pixel event for storefront tracking.
      properties:
        anonymousId:
          description: Anonymous identifier for users without account.
          type: string
        cart:
          description: Cart information.
          type:
            - object
            - 'null'
        cartLine:
          description: Information about specific cart line item.
          type: object
        checkout:
          description: Checkout information.
          type: object
        collection:
          description: Collection information.
          type: object
        customer:
          description: Customer information if available.
          type:
            - object
            - 'null'
        customerEmail:
          description: Customer email if available.
          format: email
          type: string
        customerPhone:
          description: Customer phone if available.
          type: string
        eventId:
          description: Unique identifier for the event.
          type: string
        eventName:
          description: Name of the Shopify pixel event.
          enum:
            - product_added_to_cart
            - product_removed_from_cart
            - product_viewed
            - checkout_started
            - checkout_completed
            - checkout_contact_info_submitted
            - page_viewed
            - collection_viewed
          type: string
        productVariant:
          description: Product variant information.
          type: object
        source:
          description: Source of the event.
          enum:
            - AIMERCE
          type: string
        timestamp:
          description: ISO 8601 timestamp when the event occurred.
          format: date-time
          type: string
        urlWithParams:
          description: Complete page URL with query parameters.
          type: string
        urlWithoutParams:
          description: Page URL without query parameters.
          type: string
      required:
        - eventName
        - eventId
        - timestamp
        - source
      title: Storefront Event
      type: object
    https-callback.schema:
      description: HTTPS callback
      properties:
        auth:
          description: Authorization.
          oneOf:
            - properties:
                bearer:
                  description: Bearer
                  properties:
                    token:
                      description: Token for Bearer authorization.
                      example: abc123
                      format: password
                      title: Token
                      type: string
                  title: Bearer
              title: Bearer authorization
              type: object
            - type: 'null'
          title: Authorization
        url:
          description: HTTPS callback URL.
          example: https://subscriber.example.org/events
          format: uri
          pattern: ^https://
          title: URL
          type: string
      required:
        - auth
        - url
      title: HTTPS callback
      type: object
    webhook-kind.schema:
      description: Webhook kind.
      enum:
        - redo
        - loop
      title: Webhook kind
      type: string
    webhook-topic.schema:
      description: Webhook topic.
      enum:
        - return
      title: Webhook topic
      type: string
    webhook-read.schema:
      description: Webhook read.
      properties:
        callback:
          $ref: '#/components/schemas/https-callback.schema'
          description: HTTPS callback URL to POST events.
          title: Callback
        createdAt:
          description: Time created.
          format: date-time
          title: Created at.
          type: string
        externalId:
          default: null
          description: Optional external identifier.
          title: External ID
          type:
            - string
            - 'null'
        id:
          description: Webhook ID.
          readonly: true
          title: ID
          type: string
        kind:
          $ref: '#/components/schemas/webhook-kind.schema'
          description: Kind.
          title: Kind
        topic:
          $ref: '#/components/schemas/webhook-topic.schema'
          description: Topic.
          title: Topic
        updatedAt:
          description: Last time updated.
          format: date-time
          title: Updated at.
          type: string
      required:
        - callback
        - createdAt
        - externalId id
        - updatedAt
        - topic
      title: Webhook read
      type: object
    webhook-create.schema:
      description: Webhook create.
      properties:
        backfill:
          default: false
          description: Create events for already-existing items
          title: Backfill
          type: boolean
        callback:
          $ref: '#/components/schemas/https-callback.schema'
          description: HTTPS callback to POST events.
          title: HTTPS callback
        externalId:
          default: null
          description: Optional external identifier.
          title: External ID
          type:
            - string
            - 'null'
        kind:
          $ref: '#/components/schemas/webhook-kind.schema'
          description: Kind.
          title: Kind
        topic:
          $ref: '#/components/schemas/webhook-topic.schema'
          description: Topic.
          title: Topic
      required:
        - callback
        - topic
      title: Webhook create
      type: object
    webhook-update.schema:
      description: Webhook update.
      properties:
        callback:
          $ref: '#/components/schemas/https-callback.schema'
          description: HTTPS callback to POST events.
          title: HTTPS callback
        externalId:
          default: null
          description: Optional external identifier.
          title: External ID
          type:
            - string
            - 'null'
      required:
        - callback
      title: Webhook update
      type: object
  headers:
    page-next.header:
      description: Next value for X-Page-Continue, for more results
      schema:
        type: string