> ## Documentation Index > Fetch the complete documentation index at: https://developers.redo.com/llms.txt > Use this file to discover all available pages before exploring further. # Bulk upload products > 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. ## OpenAPI ````yaml /api-schema/openapi.yaml post /stores/{storeId}/products/bulk-upload openapi: 3.1.0 info: contact: email: engineering-admin@getredo.com name: Redo Engineering description: | ## Endpoints Endpoints are authenticated using the Bearer authorization scheme, using the REDO_API_SECRET. ```txt GET /v2.2/resource HTTP/1.1 Authorization: Bearer 77bb7598b7a972475cc7c7e171ec33af Host: api.getredo.com ``` ## Webhooks Webhooks are authenticated using the Bearer authorization scheme, using a secret supplied by the subscriber. ```txt POST /events HTTP/1.1 Authorization: Bearer subscriberauth123 Host: subscriber.example.com ``` Webhook events are delivered in order for each individual subject (e.g. return). If the response is not a 2xx status code, the event will be retried multiple times before discarding it. title: Redo API version: 2.2.1 servers: - url: https://api.getredo.com/v2.2 security: [] tags: - name: Checkout Buttons - name: Coverage Info - name: Coverage Products - name: Custom Events - name: Customer Portal - name: Customer Subscriptions - name: Customers - name: Inbound Shipments - name: Inventory Items - name: Inventory Levels - name: Invoices - name: Merchant Admin - name: Orders - name: Products - name: Returns - name: Storefront - name: Webhooks paths: /stores/{storeId}/products/bulk-upload: post: tags: - Products summary: 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. 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: [] components: parameters: store-id.param: description: Store ID in: path name: storeId required: true schema: example: 64e5a8a1af49a89df37e4ee7 type: string schemas: 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 error.schema: description: >- Problem details. See [RFC 7807 Section 3](https://datatracker.ietf.org/doc/html/rfc7807#section-3). properties: detail: description: Human-readable description of the problem. title: Detail type: string instance: description: A URI reference that identifies this problem. format: uri-reference type: string title: description: Human-readable summary of the problem type. title: Title type: string type: default: about:blank description: A URI reference that identifies the problem type. format: uri-reference type: string title: Problem details type: object 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-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 securitySchemes: Bearer: scheme: bearer type: http ````