Add Product SKU (v2)

Allows you to create product SKUs in bulk. You can add up to 100 SKUs per request, and the response returns success/failure details for each SKU.

📘

Enabling OU support for product entities

To enable OU support for product entities, you need to create a JIRA ticket and enable the config CONF_OU_LEVEL_PRODUCTS_ENABLED. For more information, see Configuring Organisation Unit (OU) support for product entities.

Endpoint

POST /v2/product/skus

Request Body Parameters

The request body should be a JSON array of SKU objects.

Attributes Object Structure

Each attribute in the attributes array should have:

Response Structure

The endpoint returns a BulkCreateResponse object with the following structure:

Response Fields

Summary Object

ProductSKU Object

Each successfully created SKU returns the following fields:

HTTP Status Codes

The endpoint returns different HTTP status codes based on the operation results:

Validation Rules

📘

Batch and SKU Limits

• Maximum 100 SKUs per request
• Empty requests are rejected
• Each SKU must have a unique sku code within the organization/OU

The endpoint validates each SKU against the following rules. Validations run in parallel for efficiency.

sku (SKU identifier)

• Required field
• Cannot be empty or null
• Must be unique within your organization/OU
• Returns an error if a SKU with the same code already exists
• Returns an error if duplicate SKU codes are found within the same request

ean (barcode)

• Optional field
• Must be unique within your organization/OU if provided
• Returns a warning if duplicate EAN codes are found within the same request
• Returns an error if the EAN already exists in the system

price (product price)

• Optional field
• Must be a valid decimal value if provided

returnableDays (return window)

• Optional field
• Must be a positive integer if provided
• Returns a warning if an invalid value is provided

ouCode (organization unit code)

• Optional field
• If provided, must reference a valid organizational unit
• Returns an error if the ouCode doesn't exist

brandCode, categoryCode, colorCode, styleCode, sizeCode (reference codes)

• Optional fields
• If provided, must reference existing entities in the system
• Returns a warning (non-blocking) if the referenced entity doesn't exist
• The SKU is still created, but without the association

baseSkuCode (parent SKU reference)

• Optional field
• If provided, must reference an existing SKU
• Returns a warning (non-blocking) if the base SKU doesn't exist

attributes (custom attributes)

• Optional field
• Each attribute code must reference an existing product attribute
• Returns a warning if an attribute code doesn't exist
• Returns a warning if an attribute value doesn't exist for the given attribute

📘

Validation Processing Order

1. Fail-fast checks (stop entire batch if fails): Batch empty check and batch size check
2. Field-level validations (run in parallel, mark individual SKUs as invalid): sku, ean, price, returnableDays checks
3. External validations (run in parallel after field checks): ouCode, brandCode, categoryCode, and other reference validations

Request Examples

Example 1: Create Single SKU with Basic Information

[
  {
    "sku": "SHIRT-001",
    "description": "Cotton T-Shirt",
    "price": 29.99
  }
]

Example 2: Create Multiple SKUs with Full Details

[
  {
    "sku": "SHIRT-BLUE-M",
    "ean": "1234567890123",
    "price": 29.99,
    "description": "Blue Cotton T-Shirt",
    "longDescription": "Premium quality cotton t-shirt in blue color",
    "imageUrl": "https://example.com/images/shirt-blue-m.jpg",
    "returnable": true,
    "returnableDays": 30,
    "brandCode": "BRANDX",
    "categoryCode": "APPAREL",
    "colorCode": "BLUE",
    "styleCode": "CASUAL",
    "sizeCode": "M"
  },
  {
    "sku": "SHIRT-RED-L",
    "ean": "1234567890124",
    "price": 29.99,
    "description": "Red Cotton T-Shirt",
    "longDescription": "Premium quality cotton t-shirt in red color",
    "imageUrl": "https://example.com/images/shirt-red-l.jpg",
    "returnable": true,
    "returnableDays": 30,
    "brandCode": "BRANDX",
    "categoryCode": "APPAREL",
    "colorCode": "RED",
    "styleCode": "CASUAL",
    "sizeCode": "L"
  }
]

Example 3: Create SKU with Custom Attributes

[
  {
    "sku": "LAPTOP-001",
    "description": "Gaming Laptop",
    "price": 1299.99,
    "brandCode": "TECHCORP",
    "categoryCode": "ELECTRONICS",
    "attributes": [
      {
        "code": "processor",
        "value": "Intel i7"
      },
      {
        "code": "ram",
        "value": "16GB"
      },
      {
        "code": "storage",
        "value": "512GB SSD"
      }
    ]
  }
]

Example 4: Create SKU with Base SKU Reference

[
  {
    "sku": "SHIRT-VARIANT-001",
    "description": "T-Shirt Variant",
    "price": 34.99,
    "baseSkuCode": "SHIRT-BASE-001"
  }
]

Example 5: Create SKU with OU Scope

[
  {
    "sku": "STORE-EXCLUSIVE-001",
    "description": "Store Exclusive Product",
    "price": 49.99,
    "ouCode": "STORE_NORTH"
  }
]

Response Examples

Example 1: Full Success (201 Created)

{
  "created": [
    {
      "id": 10001,
      "orgId": 100,
      "ouId": -1,
      "code": "SHIRT-001",
      "ean": null,
      "price": 29.99,
      "description": "Cotton T-Shirt",
      "longDescription": null,
      "imageUrl": null,
      "returnable": false,
      "returnableDays": null
    }
  ],
  "summary": {
    "totalRequested": 1,
    "successCount": 1,
    "failureCount": 0
  },
  "warnings": [],
  "errors": []
}

Example 2: Partial Success with Warnings (207 Multi-Status)

{
  "created": [
    {
      "id": 10002,
      "orgId": 100,
      "ouId": -1,
      "code": "SHIRT-BLUE-M",
      "ean": "1234567890123",
      "price": 29.99,
      "description": "Blue Cotton T-Shirt",
      "longDescription": "Premium quality cotton t-shirt in blue color",
      "imageUrl": "https://example.com/images/shirt-blue-m.jpg",
      "returnable": true,
      "returnableDays": 30,
      "brand": {
        "id": 5,
        "code": "BRANDX",
        "name": "Brand X"
      },
      "category": {
        "id": 10,
        "code": "APPAREL",
        "name": "Apparel"
      }
    }
  ],
  "summary": {
    "totalRequested": 2,
    "successCount": 1,
    "failureCount": 1
  },
  "warnings": [
    {
      "code": "WARN_COLOR_NOT_FOUND",
      "message": "Color with code 'INVALID_COLOR' not found"
    }
  ],
  "errors": [
    {
      "code": "ERR_SKU_ALREADY_EXISTS",
      "message": "SKU with code 'SHIRT-RED-L' already exists"
    }
  ]
}

Example 3: Full Failure (400 Bad Request)

{
  "created": [],
  "summary": {
    "totalRequested": 2,
    "successCount": 0,
    "failureCount": 2
  },
  "warnings": [],
  "errors": [
    {
      "code": "ERR_SKU_EMPTY",
      "message": "SKU code cannot be empty"
    },
    {
      "code": "ERR_SKU_DUPLICATE_IN_REQUEST",
      "message": "Duplicate SKU codes found in request"
    }
  ]
}

Common Error Scenarios

Empty SKU Code

If you attempt to create a SKU without a SKU code:

{
  "code": "ERR_SKU_EMPTY",
  "message": "SKU code cannot be empty"
}

Duplicate SKU Code (Already Exists)

If you attempt to create a SKU with a code that already exists:

{
  "code": "ERR_SKU_ALREADY_EXISTS",
  "message": "SKU with code 'SHIRT-001' already exists"
}

Duplicate SKU Code in Request

If the request contains multiple SKUs with the same code:

{
  "code": "ERR_SKU_DUPLICATE_IN_REQUEST",
  "message": "Duplicate SKU codes found in request"
}

Batch Size Exceeded

If the request contains more than 100 SKUs:

{
  "code": "ERR_SKU_BATCH_SIZE_EXCEEDED",
  "message": "Batch size cannot exceed 100 SKUs"
}

Empty Batch

If the request contains an empty array:

{
  "code": "ERR_SKU_BATCH_EMPTY",
  "message": "Request body cannot be empty"
}

Base SKU Not Found (Error)

If the referenced base SKU doesn't exist and is required:

{
  "code": "ERR_BASE_SKU_NOT_FOUND",
  "message": "Base SKU with code 'INVALID_BASE' not found"
}

Duplicate Inventory Item

If the SKU and EAN combination already exists:

{
  "code": "ERR_DUPLICATE_INVENTORY_ITEM",
  "message": "Inventory item with this SKU and EAN already exists"
}

Common Warning Scenarios

Warnings are non-blocking issues that allow the SKU to be created, but indicate potential problems with referenced entities.

Brand Not Found

{
  "code": "WARN_BRAND_NOT_FOUND",
  "message": "Brand with code 'INVALID_BRAND' not found"
}

Category Not Found

{
  "code": "WARN_CATEGORY_NOT_FOUND",
  "message": "Category with code 'INVALID_CATEGORY' not found"
}

Color Not Found

{
  "code": "WARN_COLOR_NOT_FOUND",
  "message": "Color with code 'INVALID_COLOR' not found"
}

Style Not Found

{
  "code": "WARN_STYLE_NOT_FOUND",
  "message": "Style with code 'INVALID_STYLE' not found"
}

Size Not Found

{
  "code": "WARN_SIZE_NOT_FOUND",
  "message": "Size with code 'INVALID_SIZE' not found"
}

Duplicate EAN in Request

{
  "code": "WARN_EAN_DUPLICATE_IN_REQUEST",
  "message": "Duplicate EAN codes found in request"
}

Duplicate SKU in Request (Warning)

{
  "code": "WARN_SKU_DUPLICATE_IN_REQUEST",
  "message": "Duplicate SKU codes found in request"
}

Base SKU Not Found (Warning)

{
  "code": "WARN_BASE_SKU_NOT_FOUND",
  "message": "Base SKU with code 'INVALID_BASE' not found"
}

Attribute Not Found

{
  "code": "WARN_ATTRIBUTE_NOT_FOUND",
  "message": "Attribute with code 'invalid_attr' not found"
}

Attribute Value Not Found

{
  "code": "WARN_ATTRIBUTE_VALUE_NOT_FOUND",
  "message": "Attribute value not found for attribute 'material'"
}

Invalid Returnable Days

{
  "code": "WARN_RETURNABLE_DAYS_INVALID",
  "message": "Invalid returnable days value"
}

Important Notes

📘

Organization Unit Support

The ouCode parameter is only applicable if OU (Organization Unit) support for product inventory is enabled for your organization. If OU support is not enabled, SKUs are created at the organization level regardless of the ouCode value.

🚧

Reference Validation Warnings

When you provide reference codes (brandCode, categoryCode, colorCode, etc.) that don't exist in the system, the API returns warnings but still creates the SKU. The SKU will be created without those associations. This allows for flexible SKU creation workflows where referenced entities might not be set up yet.

👍

Parallel Validation

The endpoint validates SKUs in parallel for improved performance. However, certain batch-level checks (like batch size and empty batch) apply to the entire request. If these fail, no SKUs are created even if individual SKUs are valid.

📘

EAN Uniqueness

EAN codes must be unique within your organization/OU. If you attempt to create a SKU with an EAN that already exists, the request will fail for that SKU.

See Also

• Get Product SKUs - Retrieve existing SKUs
• Add Product - Create a single product
• Product API Response Codes - Complete list of error and warning codes