@redotech/redo-api-schema 2.2.423 → 2.2.432

package/lib/openapi.d.ts

@@ -184,6 +184,31 @@ export interface paths {
      */
     get: operations["Invoice list"];
   };
+  "/stores/{storeId}/products/bulk-upload": {
+    /**
+     * Bulk upload products (Beta)
+     * @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.
+     */
+    post: operations["Products bulk upload"];
+  };
   "/stores/{storeId}/returns": {
     /**
      * List Returns
@@ -302,6 +327,279 @@ export interface components {
        */
       state: string;
     };
+    /**
+     * 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;
+    };
+    /**
+     * 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.
@@ -432,6 +730,19 @@ export interface components {
      * @description Custom event to trigger flows with merchant-defined event names and properties.
      */
     "custom-event-request.schema": {
+      /** @description Cart context for product recommendations in triggered emails. If not provided, no cart-aware recommendations will be made. */
+      cart_context?: ({
+        /** @description Items already in the customer's cart. */
+        alreadyInCart: {
+            productId: string;
+            quantity?: number;
+            variantId: string;
+          }[];
+        /** @description The ID of an existing cart to use for recommendations. */
+        existingCartId: string | null;
+        /** @description Product IDs to use as the basis for recommendations. */
+        productIdsForRecommendations: string[];
+      }) | null;
       /** @description Customer email address (one of email or phone is required). */
       email?: string;
       /** @description The name of the custom event (e.g., 'user_registered', 'purchase_completed'). */
@@ -2334,6 +2645,66 @@ export interface operations {
       };
     };
   };
+  /**
+   * Bulk upload products (Beta)
+   * @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.
+   */
+  "Products bulk upload": {
+    parameters: {
+      path: {
+        storeId: components["parameters"]["store-id.param"];
+      };
+    };
+    requestBody: {
+      content: {
+        "application/json": components["schemas"]["bulk-product-upload-request.schema"];
+      };
+    };
+    responses: {
+      /** @description Upload completed */
+      200: {
+        content: {
+          "application/json": components["schemas"]["bulk-product-upload-response.schema"];
+        };
+      };
+      /** @description Invalid request body or missing required fields */
+      400: {
+        content: {
+          "application/json": components["schemas"]["error.schema"];
+        };
+      };
+      /** @description A bulk upload is already in progress for this store */
+      409: {
+        content: {
+          "application/json": components["schemas"]["error.schema"];
+        };
+      };
+      /** @description Error */
+      default: {
+        content: {
+          "application/problem+json": components["schemas"]["error.schema"];
+        };
+      };
+    };
+  };
   /**
    * List Returns
    * @description List returns, sorted by most recent to least recent.

package/lib/openapi.yaml

@@ -45,6 +45,7 @@ tags:
   - name: Customers
   - name: Invoices
   - name: Merchant Admin
+  - name: Products
   - name: Returns
   - name: Storefront
   - name: Webhooks
@@ -619,6 +620,156 @@ paths:
       tags:
         - Merchant Admin
     summary: Merchant admin
+  /stores/{storeId}/products/bulk-upload:
+    post:
+      description: |
+        Bulk create or update product families and their variants.
+
+        Submit up to 1,000 product families per request, each containing up to 100 variants.
+        Products are processed asynchronously in batches. Only one bulk upload can run per store at a time.
+
+        ## Matching Strategy
+
+        The API uses the following priority to match incoming product families to existing records:
+
+        1. **`product_family_id`** — Redo product family ID (direct lookup)
+        2. **`external_id`** — ID from your external system
+        3. **SKU** — Matched via variant SKUs
+
+        If no match is found, a new product family is created.
+
+        ## Concurrency
+
+        Only one bulk upload operation can run per store at a time. If a bulk upload is already
+        in progress, the request will return a `409 Conflict` error.
+      operationId: Products bulk upload
+      parameters:
+        - $ref: '#/components/parameters/store-id.param'
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/bulk-product-upload-request.schema'
+            examples:
+              single_product:
+                summary: Single product with one variant
+                value:
+                  products:
+                    - title: Classic T-Shirt
+                      description: A comfortable cotton t-shirt
+                      vendor: Acme Apparel
+                      tags:
+                        - apparel
+                        - basics
+                      kind: SELLABLE
+                      variants:
+                        - sku: TSHIRT-BLK-M
+                          price: 2999
+                          currency: USD
+                          weight: 200
+                          weight_unit: g
+              multiple_products_with_options:
+                summary: Multiple products with options and images
+                value:
+                  products:
+                    - title: Running Shoes
+                      external_id: EXT-SHOES-001
+                      options:
+                        - name: Size
+                          values:
+                            - '9'
+                            - '10'
+                            - '11'
+                        - name: Color
+                          values:
+                            - Black
+                            - White
+                      images:
+                        - url: https://example.com/shoes-main.jpg
+                          alt_text: Running shoes front view
+                      variants:
+                        - sku: SHOE-BLK-9
+                          price: 12999
+                          currency: USD
+                          option_values:
+                            - '9'
+                            - Black
+                        - sku: SHOE-WHT-10
+                          price: 12999
+                          currency: USD
+                          option_values:
+                            - '10'
+                            - White
+                    - title: Athletic Socks
+                      variants:
+                        - sku: SOCK-WHT-L
+                          price: 1499
+                          currency: USD
+        required: true
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/bulk-product-upload-response.schema'
+              examples:
+                success:
+                  summary: Successful upload
+                  value:
+                    total_count: 2
+                    processed_count: 2
+                    error_count: 0
+                    results:
+                      - status: created
+                        product_family_id: 01H5K3EXAMPLE1
+                        products:
+                          - id: 01H5K3EXAMPLE1A
+                            sku: SHOE-BLK-9
+                          - id: 01H5K3EXAMPLE1B
+                            sku: SHOE-WHT-10
+                      - status: updated
+                        product_family_id: 01H5K3EXAMPLE2
+                        products:
+                          - id: 01H5K3EXAMPLE2A
+                            sku: SOCK-WHT-L
+                partial_failure:
+                  summary: Partial failure
+                  value:
+                    total_count: 2
+                    processed_count: 1
+                    error_count: 1
+                    results:
+                      - status: created
+                        product_family_id: 01H5K3EXAMPLE3
+                        products:
+                          - id: 01H5K3EXAMPLE3A
+                            sku: TSHIRT-BLK-M
+                      - status: error
+                        error: Duplicate SKU found in request
+          description: Upload completed
+        '400':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Invalid request body or missing required fields
+        '409':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: A bulk upload is already in progress for this store
+        default:
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/error.schema'
+          description: Error
+      security:
+        - Bearer: []
+      summary: Bulk upload products (Beta)
+      tags:
+        - Products
   /returns/{returnId}:
     description: Return.
     get:
@@ -1541,6 +1692,39 @@ components:
           description: ISO 8601 timestamp when the event occurred. Defaults to current time if not provided.
           format: date-time
           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
+          type: object
+          properties:
+            existingCartId:
+              description: The ID of an existing cart to use for recommendations.
+              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
@@ -1884,6 +2068,325 @@ components:
         - createdAt
         - charge
       type: object
+    bulk-product-family-option.schema:
+      description: A product option (e.g. Size, Color) with its possible values.
+      properties:
+        name:
+          description: Option name (e.g. "Size", "Color").
+          maxLength: 255
+          title: Name
+          type: string
+        values:
+          description: Possible values for this option (e.g. ["Small", "Medium", "Large"]).
+          items:
+            maxLength: 255
+            type: string
+          title: Values
+          type: array
+      required:
+        - name
+        - values
+      title: Product Family Option
+      type: object
+    bulk-product-family-image.schema:
+      description: An image associated with a product family or variant.
+      properties:
+        url:
+          description: URL of the image.
+          format: uri
+          title: URL
+          type: string
+        alt_text:
+          description: Alt text for the image.
+          maxLength: 1000
+          title: Alt Text
+          type: string
+      required:
+        - url
+        - alt_text
+      title: Product Family Image
+      type: object
+    bulk-variant.schema:
+      description: A product variant within a product family.
+      properties:
+        id:
+          description: Redo variant ID. Used for matching to an existing variant.
+          maxLength: 255
+          title: ID
+          type: string
+        external_id:
+          description: Variant ID in your external system. Used for matching if `id` is not provided.
+          maxLength: 255
+          title: External ID
+          type: string
+        title:
+          description: Variant title (e.g. "Small / Blue").
+          maxLength: 500
+          title: Title
+          type: string
+        sku:
+          description: Stock keeping unit. Required. Used for matching if neither `id` nor `external_id` are provided.
+          maxLength: 255
+          minLength: 1
+          title: SKU
+          type: string
+        upc:
+          description: Universal product code.
+          maxLength: 50
+          title: UPC
+          type: string
+        barcodes:
+          description: Additional barcodes for this variant.
+          items:
+            maxLength: 255
+            type: string
+          title: Barcodes
+          type: array
+        price:
+          description: Price in the smallest currency unit (e.g. cents for USD).
+          minimum: 0
+          title: Price
+          type: integer
+        currency:
+          description: Currency code (e.g. "USD").
+          maxLength: 10
+          title: Currency
+          type: string
+        weight:
+          description: Weight of the variant.
+          title: Weight
+          type: number
+        weight_unit:
+          description: Unit of weight measurement.
+          enum:
+            - g
+            - kg
+            - lb
+            - oz
+            - t
+          title: Weight Unit
+          type: string
+        width:
+          description: Width of the variant.
+          title: Width
+          type: number
+        length:
+          description: Length of the variant.
+          title: Length
+          type: number
+        height:
+          description: Height of the variant.
+          title: Height
+          type: number
+        dimension_unit:
+          description: Unit of dimension measurement.
+          enum:
+            - in
+            - cm
+          title: Dimension Unit
+          type: string
+        hs_code:
+          description: Harmonized System code for customs.
+          maxLength: 50
+          title: HS Code
+          type: string
+        origin_country:
+          description: Country of origin as an ISO 3166-1 alpha-2 code (e.g. "US").
+          pattern: ^[A-Z]{2}$
+          title: Origin Country
+          type: string
+        option_values:
+          description: Values for each option defined on the product family, in the same order.
+          items:
+            maxLength: 255
+            type: string
+          title: Option Values
+          type: array
+        images:
+          description: Images specific to this variant.
+          items:
+            $ref: '#/components/schemas/bulk-product-family-image.schema'
+          title: Images
+          type: array
+      required:
+        - sku
+        - price
+        - currency
+      title: Bulk Variant
+      type: object
+    bulk-product-family.schema:
+      description: |
+        A product family containing one or more variants.
+
+        Matching priority for existing product families:
+        1. `product_family_id` — Redo product family ID (direct lookup)
+        2. `external_id` — ID from your external system
+        3. SKU — Matched via variant SKUs
+        If no match is found, a new product family is created.
+      properties:
+        product_family_id:
+          description: Redo product family ID. Highest-priority match for updating an existing product family.
+          maxLength: 255
+          title: Product Family ID
+          type: string
+        external_id:
+          description: Product family ID in your external system. Second-priority match.
+          maxLength: 255
+          title: External ID
+          type: string
+        title:
+          description: Product family title.
+          maxLength: 500
+          minLength: 1
+          title: Title
+          type: string
+        description:
+          description: Product family description.
+          maxLength: 5000
+          title: Description
+          type: string
+        vendor:
+          description: Vendor or manufacturer name.
+          maxLength: 255
+          title: Vendor
+          type: string
+        tags:
+          default: []
+          description: Tags for categorization.
+          items:
+            maxLength: 255
+            type: string
+          title: Tags
+          type: array
+        kind:
+          default: SELLABLE
+          description: Whether the product is sellable or non-sellable.
+          enum:
+            - SELLABLE
+            - NON_SELLABLE
+          title: Kind
+          type: string
+        options:
+          description: Product options (e.g. Size, Color) with their possible values.
+          items:
+            $ref: '#/components/schemas/bulk-product-family-option.schema'
+          title: Options
+          type: array
+        images:
+          description: Images for the product family.
+          items:
+            $ref: '#/components/schemas/bulk-product-family-image.schema'
+          title: Images
+          type: array
+        variants:
+          description: Product variants. At least 1 and up to 100 per product family.
+          items:
+            $ref: '#/components/schemas/bulk-variant.schema'
+          maxItems: 100
+          minItems: 1
+          title: Variants
+          type: array
+      required:
+        - title
+        - variants
+      title: Bulk Product Family
+      type: object
+    bulk-product-upload-request.schema:
+      description: Request body for bulk uploading product families and their variants.
+      properties:
+        products:
+          description: Product families to create or update. Between 1 and 1000 per request.
+          items:
+            $ref: '#/components/schemas/bulk-product-family.schema'
+          maxItems: 1000
+          minItems: 1
+          title: Products
+          type: array
+      required:
+        - products
+      title: Bulk Product Upload Request
+      type: object
+    bulk-product-upload-response.schema:
+      description: Response from a bulk product upload operation.
+      properties:
+        total_count:
+          description: Total number of product families in the request.
+          title: Total Count
+          type: integer
+        processed_count:
+          description: Number of product families processed successfully.
+          title: Processed Count
+          type: integer
+        error_count:
+          description: Number of product families that failed to process.
+          title: Error Count
+          type: integer
+        results:
+          description: Per-product-family results.
+          items:
+            oneOf:
+              - description: A product family that was created or updated successfully.
+                properties:
+                  status:
+                    description: Whether the product family was created or updated.
+                    enum:
+                      - created
+                      - updated
+                    title: Status
+                    type: string
+                  product_family_id:
+                    description: Redo product family ID.
+                    title: Product Family ID
+                    type: string
+                  products:
+                    description: Variant results within this product family.
+                    items:
+                      properties:
+                        id:
+                          description: Redo product ID.
+                          title: ID
+                          type: string
+                        sku:
+                          description: Product SKU.
+                          title: SKU
+                          type: string
+                      required:
+                        - id
+                        - sku
+                      type: object
+                    title: Products
+                    type: array
+                required:
+                  - status
+                  - product_family_id
+                  - products
+                title: Success Result
+                type: object
+              - description: A product family that failed to process.
+                properties:
+                  status:
+                    const: error
+                    description: Indicates an error occurred.
+                    title: Status
+                    type: string
+                  error:
+                    description: Error message describing what went wrong.
+                    title: Error
+                    type: string
+                required:
+                  - status
+                  - error
+                title: Error Result
+                type: object
+          title: Results
+          type: array
+      required:
+        - total_count
+        - processed_count
+        - error_count
+        - results
+      title: Bulk Product Upload Response
+      type: object
     person-name.schema:
       description: Person name.
       properties:

package/package.json

@@ -31,5 +31,5 @@
       ]
     }
   },
-  "version": "2.2.423"
+  "version": "2.2.432"
 }