@redotech/redo-api-schema 2.2.447 → 2.2.476

package/lib/openapi.yaml

@@ -45,6 +45,7 @@ tags:
   - name: Customers
   - name: Invoices
   - name: Merchant Admin
+  - name: Orders
   - name: Products
   - name: Returns
   - name: Storefront
@@ -189,16 +190,28 @@ paths:
         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.
+        Events can include custom properties that are accessible in email and SMS templates,
+        and are persisted for segmentation and historical queries.
 
-        ## Customer Matching
-        The API matches customers by email or phone number. At least one must be provided.
+        ## 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
 
-        If no matching customer is found, the request will fail with a 404 error.
+        At least one identifier must be provided. If no matching customer is found, one will
+        be created automatically. If `customer.id` is provided but not found, the API falls
+        back to email/phone rather than returning 404.
+
+        ## Datetime Formatting
+        All datetime values must be formatted as ISO 8601 (RFC 3339) strings, e.g., `2026-04-02T12:00:00Z`.
+        This applies to `eventTimestamp`, any date-valued properties in `data`, and any date-valued `customFields`.
+        Strings matching this format are automatically detected and indexed as dates for segmentation.
 
         ## Rate Limiting
         This endpoint is rate-limited to 100 requests per second per store.
       operationId: Custom event create
+      x-express-openapi-disable-validation-middleware: true
       parameters:
         - $ref: '#/components/parameters/store-id.param'
       requestBody:
@@ -207,44 +220,173 @@ paths:
             schema:
               $ref: '#/components/schemas/custom-event-request.schema'
             examples:
-              user_registered:
-                summary: User registration event
+              full_example:
+                summary: Every field populated
                 value:
-                  event_name: user_registered
-                  email: customer@example.com
-                  properties:
-                    plan_type: premium
-                    referral_code: FRIEND123
-                    source: mobile_app
-              purchase_milestone:
-                summary: Purchase milestone event
+                  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:
-                  event_name: purchase_milestone_reached
-                  phone: '+12065551234'
-                  properties:
-                    milestone_type: 100th_purchase
-                    total_spent: 5000
-                    vip_tier: gold
+                  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:
-        '200':
+        '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/custom-event-response.schema'
-          description: Event created successfully
+                $ref: '#/components/schemas/error.schema'
+          description: Rate limit exceeded
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Error
+      security:
+        - Bearer: []
+      summary: Create custom event
+      tags:
+        - Custom Events
+  /stores/{storeId}/events/bulk:
+    post:
+      description: |
+        Create multiple custom events in a single request. Accepts up to 100 events per request.
+
+        Each event is validated independently. The response includes per-event results, allowing
+        partial failures — some events may be accepted while others are rejected due to validation
+        errors.
+
+        ## Identity Resolution
+        Each event resolves customers independently using the same priority order as the
+        single-event endpoint:
+        1. `customer.id` — Redo customer ObjectId (highest priority)
+        2. `customer.email` — customer email address
+        3. `customer.phoneNumber` — customer phone number
+
+        At least one identifier must be provided per event. If no matching customer is found,
+        one will be created automatically.
+
+        ## Rate Limiting
+        This endpoint is rate-limited to 100 requests per second per store.
+      operationId: Bulk create custom events
+      x-express-openapi-disable-validation-middleware: true
+      parameters:
+        - $ref: '#/components/parameters/store-id.param'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/bulk-custom-event-request.schema'
+            examples:
+              mixed_events:
+                summary: Bulk event creation with multiple event types
+                value:
+                  events:
+                    - eventName: User Registered
+                      customer:
+                        email: alice@example.com
+                      data:
+                        Plan Type: premium
+                    - eventName: Purchase Completed
+                      customer:
+                        email: bob@example.com
+                      data:
+                        Order Total: 99.99
+                        Item Count: 3
+                      value: 99.99
+                      valueCurrency: USD
+                      uniqueId: order-456
+        required: true
+      responses:
+        '202':
+          description: Bulk request accepted and queued for processing. No response body is returned.
         '400':
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/error.schema'
-          description: Invalid request body or missing required customer identifier
+          description: Invalid request body (e.g., events array missing or exceeds 100 items)
         '404':
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/error.schema'
-          description: Customer not found with provided identifier
+          description: Store not found
         '429':
           content:
             application/json:
@@ -259,7 +401,7 @@ paths:
           description: Error
       security:
         - Bearer: []
-      summary: Create custom event
+      summary: Bulk create custom events
       tags:
         - Custom Events
   /stores/{storeId}/customer-portal:
@@ -620,6 +762,240 @@ paths:
       tags:
         - Merchant Admin
     summary: Merchant admin
+  /stores/{storeId}/orders:
+    description: Orders collection.
+    post:
+      description: Create a new order in the system with line items, customer information, and shipping details.
+      operationId: Order create
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/orders-api-create-order-request.schema'
+        required: true
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-create-order-response.schema'
+          description: Success
+        '400':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Bad Request (validation error)
+        '401':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Unauthorized (invalid or missing API token)
+        '409':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Conflict (duplicate order ID)
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Error
+      security:
+        - Bearer: []
+      summary: Create Order
+      tags:
+        - Orders
+    parameters:
+      - $ref: '#/components/parameters/store-id.param'
+    summary: Orders
+  /stores/{storeId}/orders/{orderId}:
+    description: Single order operations.
+    get:
+      description: Retrieve an existing order from the system, including all fulfillments. The orderId parameter can be either the external order ID you provided when creating the order, or the internal Redo order ID returned from the create order response.
+      operationId: Order get
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-get-order-response.schema'
+          description: Success
+        '401':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Unauthorized (invalid or missing API token)
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Order not found
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Error
+      security:
+        - Bearer: []
+      summary: Get Order
+      tags:
+        - Orders
+    delete:
+      description: Delete an order from the system. The orderId parameter can be either the external order ID you provided when creating the order, or the internal Redo order ID returned from the create order response.
+      operationId: Order delete
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-delete-order-response.schema'
+          description: Success
+        '401':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Unauthorized (invalid or missing API token)
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Order not found
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Error
+      security:
+        - Bearer: []
+      summary: Delete Order
+      tags:
+        - Orders
+    parameters:
+      - $ref: '#/components/parameters/store-id.param'
+      - $ref: '#/components/parameters/order-id.param'
+    summary: Order
+  /stores/{storeId}/orders/{orderId}/fulfillments:
+    description: Order fulfillments collection.
+    post:
+      description: Create a fulfillment for specific line items within an order, including tracking information. The orderId parameter can be either the external order ID you provided when creating the order, or the internal Redo order ID returned from the create order response.
+      operationId: Fulfillment create
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/orders-api-create-fulfillment-request.schema'
+        required: true
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-fulfillment-response.schema'
+          description: Success
+        '400':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Bad Request (validation error)
+        '401':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Unauthorized (invalid or missing API token)
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Order not found
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Error
+      security:
+        - Bearer: []
+      summary: Create Fulfillment
+      tags:
+        - Orders
+    parameters:
+      - $ref: '#/components/parameters/store-id.param'
+      - $ref: '#/components/parameters/order-id.param'
+    summary: Order Fulfillments
+  /stores/{storeId}/orders/{orderId}/fulfillments/{fulfillmentId}/shipment-status:
+    description: Update fulfillment shipment status.
+    post:
+      description: |
+        Post a shipment status update or trigger an automation event for a fulfillment.
+
+        The status field accepts two types of values:
+
+        **Statuses** (e.g., `in_transit`, `delivered`): Real carrier tracking statuses that update the shipment's current status. When you send these, the fulfillment's current status is updated to reflect the new state. Triggers any configured automations for that status.
+
+        **Events** (e.g., `stalled_in_transit`, `delayed`, `arriving_early`): Special event types that trigger automations without changing the current shipment status. The status field remains unchanged, but you can still update estimated delivery date and add tracking history entries. Use these to trigger event-based automations.
+
+        Both statuses and events can update other fields like estimated delivery date and tracking history.
+      operationId: Fulfillment status update
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/orders-api-update-fulfillment-status-request.schema'
+        required: true
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-fulfillment-response.schema'
+          description: Success
+        '400':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Bad Request (validation error)
+        '401':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Unauthorized (invalid or missing API token)
+        '404':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/orders-api-error.schema'
+          description: Fulfillment not found
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Error
+      security:
+        - Bearer: []
+      summary: Update Fulfillment Status
+      tags:
+        - Orders
+    parameters:
+      - $ref: '#/components/parameters/store-id.param'
+      - $ref: '#/components/parameters/order-id.param'
+      - $ref: '#/components/parameters/fulfillment-id.param'
+    summary: Fulfillment Shipment Status
   /stores/{storeId}/products/bulk-upload:
     post:
       description: |
@@ -1389,6 +1765,20 @@ components:
       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
@@ -1672,84 +2062,142 @@ components:
       title: Coverage product
       type: object
     custom-event-request.schema:
-      additionalProperties: false
-      description: Custom event to trigger flows with merchant-defined event names and properties.
+      additionalProperties: true
+      description: |
+        Custom event to trigger flows with merchant-defined event names and properties.
       properties:
-        event_name:
-          description: The name of the custom event (e.g., 'user_registered', 'purchase_completed').
-          type: string
-        email:
-          description: Customer email address (one of email or phone is required).
-          type: string
-        phone:
-          description: Customer phone number (one of email or phone is required).
-          type: string
-        properties:
-          description: Custom properties for this event. Access in templates using dot notation (e.g., {{ properties.product_name }}).
-          type: object
-          additionalProperties: true
-        event_timestamp:
-          description: ISO 8601 timestamp when the event occurred. Defaults to current time if not provided.
-          format: date-time
+        eventName:
+          description: The name of the custom event (e.g., 'User Registered', 'Loyalty Reward Earned').
           type: string
-        cart_context:
-          description: Cart context for product recommendations in triggered emails. If not provided, no cart-aware recommendations will be made.
-          nullable: true
+        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:
-            existingCartId:
-              description: The ID of an existing cart to use for recommendations.
+            id:
+              description: Redo customer ObjectId. Used for identity resolution. Takes priority over email and phoneNumber when provided.
               type: string
-              nullable: true
-            productIdsForRecommendations:
-              description: Product IDs to use as the basis for recommendations.
-              type: array
-              items:
-                type: string
-            alreadyInCart:
-              description: Items already in the customer's cart.
-              type: array
-              items:
-                type: object
-                properties:
-                  productId:
-                    type: string
-                  variantId:
-                    type: string
-                  quantity:
-                    type: number
-                required:
-                  - productId
-                  - variantId
-          required:
-            - existingCartId
-            - productIdsForRecommendations
-            - alreadyInCart
-      required:
-        - event_name
-      title: Custom Event Request
-      type: object
-    custom-event-response.schema:
-      additionalProperties: false
-      description: Response after successfully creating a custom event.
-      properties:
-        event_id:
-          description: The unique identifier for the created event.
-          type: string
-        status:
-          description: Status of the event processing.
-          enum:
-            - processed
-          type: string
-        event_name:
-          description: The name of the custom event that was created.
-          type: string
-      required:
-        - event_id
-        - status
-        - event_name
-      title: Custom Event Response
-      type: object
+            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
     subscription-status-marketing.schema:
       description: Marketing subscription status
       properties:
@@ -2079,6 +2527,513 @@ components:
         - 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.
+          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.
+          minimum: 0
+          type:
+            - number
+            - 'null'
+        address:
+          $ref: '#/components/schemas/orders-api-shipping-address.schema'
+      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.
+          minimum: 0
+          type:
+            - number
+            - 'null'
+        subtotalPrice:
+          description: Subtotal price excluding tax and shipping.
+          minimum: 0
+          type:
+            - number
+            - 'null'
+        totalTax:
+          description: Total tax amount.
+          minimum: 0
+          type:
+            - number
+            - 'null'
+        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'
+      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
+        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: