@redotech/redo-api-schema/lib/openapi.d.ts

Common definitions for Redo API

/**
 * This file was auto-generated by openapi-typescript.
 * Do not make direct changes to the file.
 */


/** OneOf type helpers */
type Without<T, U> = { [P in Exclude<keyof T, keyof U>]?: never };
type XOR<T, U> = (T | U) extends object ? (Without<T, U> & U) | (Without<U, T> & T) : T | U;
type OneOf<T extends any[]> = T extends [infer Only] ? Only : T extends [infer A, infer B, ...infer Rest] ? OneOf<[XOR<A, B>, ...Rest]> : never;

export interface paths {
  "/invoices/{invoiceId}/items.csv": {
    /**
     * Invoice (CSV)
     * @description Get an invoice as a CSV. Requires the [`invoices_read`](/docs/api-reference/scopes) scope.
     */
    get: operations["Invoice csv get"];
  };
  "/invoices/pending/items.csv": {
    /**
     * Pending Invoice (CSV)
     * @description Get an invoice as a CSV. Requires the [`invoices_read`](/docs/api-reference/scopes) scope.
     */
    get: operations["Invoice pending csv get"];
  };
  "/returns/{returnId}": {
    /**
     * Return
     * @description Get return. Requires the [`returns_read`](/docs/api-reference/scopes) scope.
     */
    get: operations["Return get"];
    parameters: {
      path: {
        returnId: components["parameters"]["return-id.param"];
      };
    };
  };
  "/returns/{returnId}/comments": {
    /**
     * List Return Comments
     * @description List return comments. Requires the [`returns_read`](/docs/api-reference/scopes) scope.
     */
    get: operations["Return comments get"];
    /**
     * Create Return Comment
     * @description Create return comment. Requires the [`returns_write`](/docs/api-reference/scopes) scope.
     */
    post: operations["Return comment create"];
    parameters: {
      path: {
        returnId: components["parameters"]["return-id.param"];
      };
    };
  };
  "/returns/{returnId}/process": {
    /**
     * Process Return
     * @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.
     */
    post: operations["Return process"];
    parameters: {
      path: {
        returnId: components["parameters"]["return-id.param"];
      };
    };
  };
  "/returns/{returnId}/status": {
    /**
     * Return Status
     * @description Get return status. Requires the [`returns_read`](/docs/api-reference/scopes) scope.
     */
    get: operations["Return status get"];
    /**
     * Update Return Status
     * @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.
     */
    put: operations["Return status update"];
  };
  "/stores/{storeId}/admin": {
    /**
     * Navigate to Merchant Admin
     * @description Navigate to the merchant admin page.
     */
    get: operations["Merchant admin navigate"];
  };
  "/stores/{storeId}/checkout-buttons-ui": {
    /**
     * Checkout Buttons UI
     * @description Generate rendered HTML and CSS for checkout buttons.
     */
    get: operations["Checkout buttons UI"];
  };
  "/stores/{storeId}/coverage-info": {
    /**
     * Navigate to Coverage Info
     * @description Navigate to the coverage info page.
     */
    get: operations["Coverage info navigate"];
  };
  "/stores/{storeId}/coverage-products": {
    /**
     * Coverage Products
     * @description Get available coverage products.
     */
    post: operations["Coverage products"];
  };
  "/stores/{storeId}/customer-portal": {
    /**
     * Navigate to Customer Portal
     * @description Navigate to the customer portal.
     */
    get: operations["Customer portal navigate"];
  };
  "/stores/{storeId}/customer-subscriptions": {
    /**
     * Update Customer Subscriptions
     * @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.
     */
    post: operations["Customer subscriptions update"];
  };
  "/stores/{storeId}/customers": {
    /**
     * Get customer by email
     * @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.
     */
    get: operations["Customer get"];
    /**
     * Create or update customer
     * @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.
     */
    put: operations["Customer upsert"];
  };
  "/stores/{storeId}/events": {
    /**
     * Create custom event
     * @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.
     */
    post: operations["Custom event create"];
  };
  "/stores/{storeId}/events/bulk": {
    /**
     * Bulk create custom events
     * @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.
     */
    post: operations["Bulk create custom events"];
  };
  "/stores/{storeId}/inbound-shipments": {
    /**
     * List Inbound Shipments
     * @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.
     */
    get: operations["Inbound shipments list"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
      };
    };
  };
  "/stores/{storeId}/inbound-shipments/{inboundShipmentId}": {
    /**
     * Get Inbound Shipment
     * @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.
     */
    get: operations["Inbound shipment get"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
        inboundShipmentId: components["parameters"]["inbound-shipment-id.param"];
      };
    };
  };
  "/stores/{storeId}/inventory-items": {
    /**
     * List Inventory Items
     * @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.
     */
    get: operations["Inventory items list"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
      };
    };
  };
  "/stores/{storeId}/inventory-items/{inventoryItemId}": {
    /**
     * Get Inventory Item
     * @description Get a single in-stock inventory item by ID. Requires the [`inventory_read`](/docs/api-reference/scopes) scope.
     */
    get: operations["Inventory item get"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
        inventoryItemId: components["parameters"]["inventory-item-id.param"];
      };
    };
  };
  "/stores/{storeId}/inventory-levels": {
    /**
     * List Inventory Levels
     * @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.
     */
    get: operations["Inventory levels list"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
      };
    };
  };
  "/stores/{storeId}/inventory-levels/{inventoryLevelId}": {
    /**
     * Get Inventory Level
     * @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.
     */
    get: operations["Inventory level get"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
        inventoryLevelId: components["parameters"]["inventory-level-id.param"];
      };
    };
  };
  "/stores/{storeId}/invoices": {
    /**
     * List Invoices
     * @description Get a list of invoices. Requires the [`invoices_read`](/docs/api-reference/scopes) scope.
     */
    get: operations["Invoice list"];
  };
  "/stores/{storeId}/orders": {
    /**
     * Create Order
     * @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.
     */
    post: operations["Order create"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
      };
    };
  };
  "/stores/{storeId}/orders/{orderId}": {
    /**
     * Get Order
     * @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.
     */
    get: operations["Order get"];
    /**
     * Delete Order
     * @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.
     */
    delete: operations["Order delete"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
        orderId: components["parameters"]["order-id.param"];
      };
    };
  };
  "/stores/{storeId}/orders/{orderId}/fulfillments": {
    /**
     * Create Fulfillment
     * @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.
     */
    post: operations["Fulfillment create"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
        orderId: components["parameters"]["order-id.param"];
      };
    };
  };
  "/stores/{storeId}/orders/{orderId}/fulfillments/{fulfillmentId}/shipment-status": {
    /**
     * Update Fulfillment Status
     * @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.
     */
    post: operations["Fulfillment status update"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
        orderId: components["parameters"]["order-id.param"];
        fulfillmentId: components["parameters"]["fulfillment-id.param"];
      };
    };
  };
  "/stores/{storeId}/products/bulk-upload": {
    /**
     * Bulk upload products
     * @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.
     */
    post: operations["Products bulk upload"];
  };
  "/stores/{storeId}/return-tags": {
    /**
     * List Return Tags
     * @description List every return tag defined for the store. Requires the [`returns_read`](/docs/api-reference/scopes) scope.
     */
    get: operations["Return tags list"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
      };
    };
  };
  "/stores/{storeId}/return-tags/{name}": {
    /**
     * Upsert Return Tag
     * @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.
     */
    put: operations["Return tag upsert"];
    /**
     * Delete Return Tag
     * @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.
     */
    delete: operations["Return tag delete"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
        name: components["parameters"]["return-tag-name.param"];
      };
    };
  };
  "/stores/{storeId}/returns": {
    /**
     * List Returns
     * @description List returns, sorted by most recent to least recent. Requires the [`returns_read`](/docs/api-reference/scopes) scope.
     */
    get: operations["Returns list"];
    /**
     * Create Return
     * @description Create a return for specific order line items. Requires the [`returns_write`](/docs/api-reference/scopes) scope.
     */
    post: operations["Return create"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
      };
    };
  };
  "/stores/{storeId}/returns/bulk": {
    /**
     * Import Returns
     * @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.
     */
    post: operations["Import returns"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
      };
    };
  };
  "/stores/{storeId}/storefront/events": {
    /**
     * Receive Storefront Events
     * @description Processes events from storefronts using Shopify pixel event schema Requires the [`storefront_events_write`](/docs/api-reference/scopes) scope.
     */
    post: operations["Storefront Event"];
  };
  "/stores/{storeId}/webhooks": {
    /**
     * List Webhooks
     * @description List webhooks for store. Requires the [`webhooks_read`](/docs/api-reference/scopes) scope.
     */
    get: operations["Webhooks list"];
    /**
     * Create or Update Webhook
     * @description Create webhook for store. Or if webhook already exists with `externalId`, update it. Requires the [`webhooks_write`](/docs/api-reference/scopes) scope.
     */
    post: operations["Webhook create"];
    parameters: {
      path: {
        storeId: components["parameters"]["store-id.param"];
      };
    };
  };
  "/webhooks/{webhookId}": {
    /**
     * Webhook
     * @description Get a webhook. Requires the [`webhooks_read`](/docs/api-reference/scopes) scope.
     */
    get: operations["Webhook get"];
    /**
     * Update Webhook
     * @description Update a webhook. Requires the [`webhooks_write`](/docs/api-reference/scopes) scope.
     */
    put: operations["Webhook update"];
    /**
     * Delete Webhook
     * @description Delete a webhook. Requires the [`webhooks_write`](/docs/api-reference/scopes) scope.
     */
    delete: operations["Webhook delete"];
  };
  "/webhooks/{webhookId}/replay": {
    /**
     * Replay Webhook
     * @description Replay a webhook. Requires the [`webhooks_write`](/docs/api-reference/scopes) scope.
     */
    post: operations["Webhook replay"];
    parameters: {
      path: {
        webhookId: components["parameters"]["webhook-id.param"];
      };
    };
  };
}

export interface webhooks {
  "return": {
    /** Return event */
    post: operations["Webhook return event"];
  };
}

export interface components {
  schemas: {
    /**
     * Address
     * @description Address.
     */
    "address.schema": {
      /**
       * City
       * @description City name
       */
      city: string;
      /**
       * Country
       * @description Country code
       */
      country: string;
      /**
       * Line 1
       * @description Line 1
       */
      line1: string;
      /**
       * Line 2
       * @description Line 2
       * @default
       */
      line2?: string;
      /**
       * Postal code
       * @description Postal or ZIP code
       */
      postalCode: string;
      /**
       * State
       * @description State or province
       */
      state: string;
    };
    /**
     * Bulk Custom Event Request
     * @description Request body for sending multiple custom events in a single request.
     */
    "bulk-custom-event-request.schema": {
      /** @description Array of custom events to create. */
      events: components["schemas"]["custom-event-request.schema"][];
    };
    /**
     * Product Family Image
     * @description An image associated with a product family or variant.
     */
    "bulk-product-family-image.schema": {
      /**
       * Alt Text
       * @description Alt text for the image.
       */
      alt_text: string;
      /**
       * URL
       * Format: uri
       * @description URL of the image.
       */
      url: string;
    };
    /**
     * Product Family Option
     * @description A product option (e.g. Size, Color) with its possible values.
     */
    "bulk-product-family-option.schema": {
      /**
       * Name
       * @description Option name (e.g. "Size", "Color").
       */
      name: string;
      /**
       * Values
       * @description Possible values for this option (e.g. ["Small", "Medium", "Large"]).
       */
      values: string[];
    };
    /**
     * Bulk Product Family
     * @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.
     */
    "bulk-product-family.schema": {
      /**
       * Description
       * @description Product family description.
       */
      description?: string;
      /**
       * External ID
       * @description Product family ID in your external system. Second-priority match.
       */
      external_id?: string;
      /**
       * Images
       * @description Images for the product family.
       */
      images?: components["schemas"]["bulk-product-family-image.schema"][];
      /**
       * Kind
       * @description Whether the product is sellable or non-sellable.
       * @default SELLABLE
       * @enum {string}
       */
      kind?: "SELLABLE" | "NON_SELLABLE";
      /**
       * Options
       * @description Product options (e.g. Size, Color) with their possible values.
       */
      options?: components["schemas"]["bulk-product-family-option.schema"][];
      /**
       * Product Family ID
       * @description Redo product family ID. Highest-priority match for updating an existing product family.
       */
      product_family_id?: string;
      /**
       * Tags
       * @description Tags for categorization.
       * @default []
       */
      tags?: string[];
      /**
       * Title
       * @description Product family title.
       */
      title: string;
      /**
       * Variants
       * @description Product variants. At least 1 and up to 100 per product family.
       */
      variants: components["schemas"]["bulk-variant.schema"][];
      /**
       * Vendor
       * @description Vendor or manufacturer name.
       */
      vendor?: string;
    };
    /**
     * Bulk Product Upload Request
     * @description Request body for bulk uploading product families and their variants.
     */
    "bulk-product-upload-request.schema": {
      /**
       * Products
       * @description Product families to create or update. Between 1 and 1000 per request.
       */
      products: components["schemas"]["bulk-product-family.schema"][];
    };
    /**
     * Bulk Product Upload Response
     * @description Response from a bulk product upload operation.
     */
    "bulk-product-upload-response.schema": {
      /**
       * Error Count
       * @description Number of product families that failed to process.
       */
      error_count: number;
      /**
       * Processed Count
       * @description Number of product families processed successfully.
       */
      processed_count: number;
      /**
       * Results
       * @description Per-product-family results.
       */
      results: (OneOf<[{
          /**
           * Product Family ID
           * @description Redo product family ID.
           */
          product_family_id: string;
          /**
           * Products
           * @description Variant results within this product family.
           */
          products: {
              /**
               * ID
               * @description Redo product ID.
               */
              id: string;
              /**
               * SKU
               * @description Product SKU.
               */
              sku: string;
            }[];
          /**
           * Status
           * @description Whether the product family was created or updated.
           * @enum {string}
           */
          status: "created" | "updated";
        }, {
          /**
           * Error
           * @description Error message describing what went wrong.
           */
          error: string;
          /**
           * Status
           * @description Indicates an error occurred.
           * @constant
           */
          status: "error";
        }]>)[];
      /**
       * Total Count
       * @description Total number of product families in the request.
       */
      total_count: number;
    };
    /** @description Import returns request body. */
    "bulk-returns-request.schema": {
      /** @description Array of returns to import (max 100). */
      returns: {
          /** @description Carrier name for the tracking number (e.g. 'USPS', 'UPS'). */
          carrier?: string;
          /** @description ISO 4217 currency code (defaults to USD). */
          currency?: string;
          /** @description Optional customer information. */
          customer?: {
            /** Format: email */
            email?: string;
            firstName?: string;
            lastName?: string;
          };
          /** @description Merchant's own return/RMA ID. Stored on the return so it's scannable at warehouse intake. */
          externalReferenceId?: string;
          /** @description Idempotency key to prevent duplicate return creation on retry. */
          idempotencyKey?: string;
          /** @description Merchant return destination address. */
          merchantAddress?: {
            /** @description City. */
            city: string;
            /** @description ISO 3166-1 alpha-2 country code. */
            country: string;
            /** @description Street address line 1. */
            line1: string;
            /** @description Street address line 2. */
            line2?: string;
            /** @description Recipient or location name. */
            name?: string;
            /** @description Phone number. */
            phone?: string;
            /** @description Postal/ZIP code. */
            postalCode?: string;
            /** @description State or province code. */
            state?: string;
          };
          /** @description Internal notes. */
          notes?: string;
          /** @description Products being returned (at least 1). */
          products: {
              /** @description Override barcode (uses catalog value if omitted). */
              barcode?: string;
              /** @description Item condition. */
              condition?: string;
              /** @description Redo product ID returned from the bulk product upload response (e.g. `prd_ABC123`). */
              productId: string;
              /** @description Override product title (uses catalog value if omitted). */
              productTitle?: string;
              /** @description Number of units to return. */
              quantity: number;
              /** @description Return reason. */
              reason?: string;
              /** @description Override SKU (uses catalog value if omitted). */
              sku?: string;
              /** @description Override variant title (uses catalog value if omitted). */
              variantTitle?: string;
            }[];
          /** @description Customer's shipping address. */
          shippingAddress?: {
            /** @description City. */
            city: string;
            /** @description ISO 3166-1 alpha-2 country code. */
            country: string;
            /** @description Street address line 1. */
            line1: string;
            /** @description Street address line 2. */
            line2?: string;
            /** @description Recipient or location name. */
            name?: string;
            /** @description Phone number. */
            phone?: string;
            /** @description Postal/ZIP code. */
            postalCode?: string;
            /** @description State or province code. */
            state?: string;
          };
          /** @description Carrier tracking number for the inbound return shipment. */
          trackingNumber?: string;
        }[];
    };
    /** @description Bulk external return creation response. */
    "bulk-returns-response.schema": {
      /** @description Number of returns that failed. */
      errorCount: number;
      /** @description Number of returns successfully created. */
      processedCount: number;
      /** @description Per-item results in the same order as the request. */
      results: ({
          /** @description Zero-based index into the request array. */
          index: number;
          /** @description ID of the created return. */
          returnId: string;
          /** @enum {string} */
          status: "created";
        } | {
          /** @description Error message. */
          error: string;
          /** @description Zero-based index into the request array. */
          index: number;
          /** @enum {string} */
          status: "error";
        })[];
      /** @description Total number of returns in the request. */
      totalCount: number;
    };
    /**
     * Bulk Variant
     * @description A product variant within a product family.
     */
    "bulk-variant.schema": {
      /**
       * Barcodes
       * @description Additional barcodes for this variant.
       */
      barcodes?: string[];
      /**
       * Currency
       * @description Currency code (e.g. "USD").
       */
      currency: string;
      /**
       * Dimension Unit
       * @description Unit of dimension measurement.
       * @enum {string}
       */
      dimension_unit?: "in" | "cm";
      /**
       * External ID
       * @description Variant ID in your external system. Used for matching if `id` is not provided.
       */
      external_id?: string;
      /**
       * Height
       * @description Height of the variant.
       */
      height?: number;
      /**
       * HS Code
       * @description Harmonized System code for customs.
       */
      hs_code?: string;
      /**
       * ID
       * @description Redo variant ID. Used for matching to an existing variant.
       */
      id?: string;
      /**
       * Images
       * @description Images specific to this variant.
       */
      images?: components["schemas"]["bulk-product-family-image.schema"][];
      /**
       * Length
       * @description Length of the variant.
       */
      length?: number;
      /**
       * Option Values
       * @description Values for each option defined on the product family, in the same order.
       */
      option_values?: string[];
      /**
       * Origin Country
       * @description Country of origin as an ISO 3166-1 alpha-2 code (e.g. "US").
       */
      origin_country?: string;
      /**
       * Price
       * @description Price in the smallest currency unit (e.g. cents for USD).
       */
      price: number;
      /**
       * SKU
       * @description Stock keeping unit. Required. Used for matching if neither `id` nor `external_id` are provided.
       */
      sku: string;
      /**
       * Title
       * @description Variant title (e.g. "Small / Blue").
       */
      title?: string;
      /**
       * UPC
       * @description Universal product code.
       */
      upc?: string;
      /**
       * Weight
       * @description Weight of the variant.
       */
      weight?: number;
      /**
       * Weight Unit
       * @description Unit of weight measurement.
       * @enum {string}
       */
      weight_unit?: "g" | "kg" | "lb" | "oz" | "t";
      /**
       * Width
       * @description Width of the variant.
       */
      width?: number;
    };
    /**
     * Comment
     * @description Comment with either message or image.
     */
    "comment.schema": OneOf<[{
      /**
       * Image
       * @description Base64-encoded image
       */
      image: string;
    }, {
      /**
       * Message
       * @description Message.
       */
      message: string;
    }]>;
    /**
     * Coverage product
     * @description Coverage product.
     */
    "coverage-product.schema": {
      /** @description Coverage. */
      coverages?: ({
          lineItems: {
              /**
               * ID
               * @description Line item ID.
               */
              id?: string;
            }[];
          /**
           * Coverage
           * @enum {unknown}
           */
          type: "shipping_failure" | "return_shipping";
        })[];
      /**
       * ID
       * @description Coverage ID.
       */
      id: string;
      /**
       * Price
       * @description Price.
       */
      price: components["schemas"]["money.schema"];
    };
    /** @description Create return request body. */
    "create-return-request.schema": {
      /** @description Return information payload. */
      data: {
        /** @description External order ID from the ecommerce platform. */
        externalOrderId: string;
        /** @description Items being returned. */
        items: ({
            /**
             * @description How the customer should be compensated for this item.
             * @enum {string}
             */
            compensation: "refund" | "store_credit";
            /** @description External line item ID from the order. */
            lineItemId: string;
            /** @description Customer-facing notes for this item. */
            notes?: string;
            /** @description Number of units to return. */
            quantity: number;
            /** @description Customer-facing return reason. */
            reason: string;
            /** @description Machine-readable reason code. */
            reasonCode?: string;
          })[];
        /** @description Optional return label and tracking details. */
        label?: {
          /** @description Carrier name. */
          carrier?: string;
          /** @description Commercial or form label URL. */
          formLabelUrl?: string;
          /** @description Provider shipment identifier to reference. */
          originalShipmentId?: string;
          /** @description Postage label URL. */
          postageLabelUrl?: string;
          /** @description Carrier tracking number. */
          trackingNumber: string;
          /** @description Public tracking URL. */
          trackingUrl?: string;
        };
        /** @description Internal merchant-side notes. */
        notes?: string;
        /** @description Ecommerce platform provider. */
        provider: string;
        /** @description Address the customer is shipping from. */
        shippingAddress: {
          city: string;
          /** @description ISO 3166-1 alpha-2 country code. */
          country: string;
          line1: string;
          line2?: string;
          postalCode: string;
          state: string;
        };
      };
      /** @description Options controlling side effects of the return creation. */
      options?: {
        /**
         * @description Whether to create RMAs with external integrations (e.g. ShipBob). Defaults to false.
         * @default false
         */
        createExternalRMAs?: boolean;
      };
    };
    /** @description Create return response body. */
    "create-return-response.schema": {
      externalRMAResponses: {
          /** @description Provider error code when external RMA creation fails. */
          errorCode?: string;
          /** @description Provider error message when external RMA creation fails. */
          errorMessage?: string;
          /** @description Name of the external integration provider. */
          integrationProvider: string;
          /** @description Whether external RMA creation succeeded. */
          success: boolean;
        }[];
      return: components["schemas"]["return-read.schema"];
    };
    /**
     * Custom Event Request
     * @description Custom event to trigger flows with merchant-defined event names and properties.
     */
    "custom-event-request.schema": {
      /** @description Customer identity and profile fields. At least one of `id`, `email`, or `phoneNumber` is required for identity resolution. */
      customer: {
        /** @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. */
        customFields?: {
          [key: string]: string | number | boolean;
        };
        /**
         * Format: email
         * @description Customer email address. Used for identity resolution.
         */
        email?: string;
        /** @description Customer first name. Applied with patch semantics — does not erase existing value if omitted. */
        firstName?: string;
        /** @description Redo customer ObjectId. Used for identity resolution. Takes priority over email and phoneNumber when provided. */
        id?: string;
        /** @description Customer last name. Applied with patch semantics — does not erase existing value if omitted. */
        lastName?: string;
        /** @description Customer location for profile enrichment. All fields are optional. */
        location?: {
          /** @description City name. */
          city?: string;
          /** @description Country name. */
          country?: string;
          /** @description ISO 3166-1 alpha-2 country code (e.g., "US", "GB"). */
          countryCode?: string;
          /** @description IANA time zone identifier (e.g., "America/New_York"). */
          ianaTimeZoneName?: string;
          /** @description Geographic latitude coordinate. */
          latitude?: number;
          /** @description Geographic longitude coordinate. */
          longitude?: number;
          /** @description Postal or ZIP code. */
          postalCode?: string;
          /** @description State or province name. */
          state?: string;
          /** @description State or province abbreviation (e.g., "CA", "NY"). */
          stateCode?: string;
          /** @description Primary street address. */
          street1?: string;
          /** @description Secondary address line (apartment, suite, etc.). */
          street2?: string;
        };
        /** @description Customer phone number in E.164 format. Used for identity resolution. */
        phoneNumber?: string;
      };
      /**
       * @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.
       */
      data?: {
        /** @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. */
        $extra?: {
          [key: string]: unknown;
        };
        [key: string]: (string | number | boolean) | undefined;
      };
      /** @description The name of the custom event (e.g., 'User Registered', 'Loyalty Reward Earned'). */
      eventName: string;
      /**
       * Format: date-time
       * @description ISO 8601 timestamp when the event occurred. Defaults to current time if not provided.
       */
      eventTimestamp?: string;
      /** @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. */
      uniqueId?: string;
      /** @description Monetary or conversion value associated with the event (e.g., purchase amount). */
      value?: number;
      /** @description ISO 4217 currency code for the value field (e.g., "USD", "EUR"). */
      valueCurrency?: string;
      [key: string]: unknown;
    };
    /**
     * Customer Location
     * @description Customer location information.
     */
    "customer-location.schema": {
      /** @description City name */
      city?: string;
      /** @description Country name */
      country?: string;
      /** @description ISO 3166-1 alpha-2 country code */
      countryCode?: string;
      /** @description IANA time zone identifier */
      ianaTimeZoneName?: string;
      /** @description Latitude coordinate */
      latitude?: number;
      /** @description Longitude coordinate */
      longitude?: number;
      /** @description Postal or ZIP code */
      postalCode?: string;
      /** @description State or province name */
      state?: string;
      /** @description State or province abbreviation */
      stateCode?: string;
      /** @description Street address line 1 */
      street1?: string;
      /** @description Street address line 2 */
      street2?: string;
    };
    /**
     * Customer
     * @description Customer profile.
     */
    "customer-read.schema": {
      /**
       * Created at
       * Format: date-time
       * @description Timestamp when the customer was created. May be null for older customers created before this field was tracked.
       */
      createdAt?: string | null;
      /** @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. */
      customFields?: {
        [key: string]: string | number | boolean;
      };
      /**
       * Format: email
       * @description Customer email address
       */
      email: string;
      /** @description Customer first name */
      firstName?: string;
      /** @description Redo customer ID */
      id: string;
      /** @description Customer last name */
      lastName?: string;
      location?: components["schemas"]["customer-location.schema"];
      /** @description Customer phone number in E.164 format */
      phoneNumber?: string;
      /**
       * Updated at
       * Format: date-time
       * @description Timestamp when the customer was last updated. May be null for older customers created before this field was tracked.
       */
      updatedAt?: string | null;
    };
    /** @description Email subscription updates */
    "customer-subscription-email.schema": {
      /**
       * Format: email
       * @description Email address
       */
      email: string;
      subscriptions: {
        /** @description Email marketing subscription. Email is always auto-confirmed on subscribe. */
        marketing?: {
          /**
           * @description Subscription status.
           * @enum {string}
           */
          subscriptionStatus: "subscribed" | "unsubscribed";
          /**
           * @description Whether to trigger automations for this subscription change. Defaults to false.
           * @default false
           */
          triggerAutomations?: boolean;
          /**
           * Format: date-time
           * @description ISO 8601 timestamp. If not provided, defaults to now.
           */
          updatedAt?: string;
        };
      };
    };
    /** @description SMS subscription updates */
    "customer-subscription-sms.schema": {
      /** @description Phone number in E.164 format (e.g., +12345678900) */
      phoneNumber: string;
      subscriptions: {
        marketing?: components["schemas"]["subscription-status-marketing.schema"];
        transactional?: components["schemas"]["subscription-status-transactional.schema"];
      };
    };
    /** @description Customer subscription update response */
    "customer-subscription-update-response.schema": {
      /** @description Human-readable success message */
      message: string;
      /** @description Whether the operation was successful */
      success: boolean;
      /** @description Details of which subscriptions were updated */
      updatedSubscriptions: {
        email?: {
          /** @description Whether email marketing was updated */
          marketing?: boolean;
        };
        sms?: {
          /** @description Whether SMS marketing was updated */
          marketing?: boolean;
          /** @description Whether SMS transactional was updated */
          transactional?: boolean;
        };
      };
    };
    /**
     * Customer Upsert Request
     * @description Request body for creating or updating a customer profile. The email address is used as the upsert key.
     */
    "customer-upsert-request.schema": {
      /**
       * @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.
       * @example {
       *   "subscription_source": "web",
       *   "status": "Active",
       *   "loyalty_points": 1250,
       *   "vip_member": true,
       *   "signup_date": "2026-02-24T12:15:00.000Z"
       * }
       */
      customFields?: {
        [key: string]: string | number | boolean;
      };
      /**
       * Format: email
       * @description Customer email address. Used as the upsert key to find or create the customer.
       */
      email: string;
      /** @description Customer first name */
      firstName?: string;
      /** @description Customer last name */
      lastName?: string;
      location?: components["schemas"]["customer-location.schema"];
      /** @description Customer phone number in E.164 format (e.g., +12345678900). Appended to the existing phone list if not already present. */
      phoneNumber?: string;
    };
    /**
     * Customer Upsert Response
     * @description Response after creating or updating a customer profile.
     */
    "customer-upsert-response.schema": {
      /** @description Whether a new customer was created (true) or an existing customer was updated (false)