Skip to main content
Bulk SKU Creation API
curl --request POST \
  --url https://api.pazy.io/v1.0/inventory/skus/bulk

​
Overview

The Bulk SKU Creation API lets you add up to 100 SKUs in a single request. Each SKU can have a name and an optional item code. The item code is especially useful for matching line items in purchase orders to your inventory catalog.

​
Authentication

All requests require an API key in the request headers. Headers: 
Authorization: Api-Key YOUR_API_KEY
Content-Type: application/json

​
Request

Content-Type: application/json

​
Body Parameters

ParameterTypeRequiredDescription
skusarrayYesList of SKUs to create. Minimum 1, maximum 100 items per request

​
SKU Object

Each item in the skus array must contain:
ParameterTypeRequiredDescription
namestringYesDisplay name of the SKU (1–128 characters)
itemCodestringNoItem code for the SKU (1–256 characters)
unitstringNoUnit of measurement, e.g. pcs, kg, litre (max 32 characters)
ratenumberNoDefault unit rate or price for the SKU
hsnSacstringNoHSN or SAC code for GST classification (max 16 characters)
Tip: itemCode is matched case-insensitively against purchase order line items — SKU-001 and sku-001 are treated as the same code.

​
Code Examples

curl -X POST https://api.pazy.io/v1.0/inventory/skus/bulk \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skus": [
      {
        "name": "Office Chair - Ergonomic",
        "itemCode": "FURN-001",
        "unit": "pcs",
        "rate": 5000.00,
        "hsnSac": "9401"
      },
      {
        "name": "Standing Desk",
        "itemCode": "FURN-002",
        "unit": "pcs",
        "rate": 15000.00
      },
      {
        "name": "Laptop Stand"
      }
    ]
  }'

​
Success Response

HTTP Status: 200 OK

​
Response Fields

FieldTypeDescription
okbooleantrue when the request was processed (even if some SKUs failed)
dataobjectSummary of the bulk operation
data.totalnumberTotal number of SKUs submitted
data.successCountnumberNumber of SKUs successfully created
data.failureCountnumberNumber of SKUs that failed to create
data.createdarrayList of successfully created SKUs
data.failedarrayList of SKUs that failed to create

​
Created SKU Object

FieldTypeDescription
namestringDisplay name of the SKU
itemCodestring | nullItem code of the SKU (null if not provided)
unitstring | nullUnit of measurement (null if not provided)
ratenumber | nullDefault unit rate (null if not provided)
hsnSacstring | nullHSN/SAC code (null if not provided)

​
Failed SKU Object

FieldTypeDescription
namestringName of the SKU that failed
itemCodestring | nullItem code of the SKU that failed
errorstringReason for failure

​
Response Example

{
  "ok": true,
  "data": {
    "total": 3,
    "successCount": 3,
    "failureCount": 0,
    "created": [
      {
        "name": "Office Chair - Ergonomic",
        "itemCode": "FURN-001",
        "unit": "pcs",
        "rate": 5000,
        "hsnSac": "9401"
      },
      {
        "name": "Standing Desk",
        "itemCode": "FURN-002",
        "unit": "pcs",
        "rate": 15000,
        "hsnSac": null
      },
      {
        "name": "Laptop Stand",
        "itemCode": null,
        "unit": null,
        "rate": null,
        "hsnSac": null
      }
    ],
    "failed": []
  }
}

​
Partial Success Response

If some SKUs fail (e.g., due to a database constraint), the API still returns 200 OK and reports which succeeded and which failed: 
{
  "ok": true,
  "data": {
    "total": 2,
    "successCount": 1,
    "failureCount": 1,
    "created": [
      {
        "name": "Monitor Stand",
        "itemCode": "DESK-001",
        "unit": null,
        "rate": null,
        "hsnSac": null
      }
    ],
    "failed": [
      {
        "name": "Invalid SKU",
        "itemCode": null,
        "error": "Failed to create SKU"
      }
    ]
  }
}

​
Error Responses

​
Missing Required Fields

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/skus: must NOT have fewer than 1 items"
  }
}

​
Exceeding Maximum Batch Size

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/skus: must NOT have more than 100 items"
  }
}

​
SKU Name Too Long

HTTP Status: 400 Bad Request 
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/skus/0/name: must NOT have more than 128 characters"
  }
}

​
Authentication Errors

HTTP Status: 401 Unauthorized 
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}

​
Permission Errors

HTTP Status: 403 Forbidden 
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}

​
Linking SKUs to Purchase Order Line Items

Once you have created SKUs in your inventory, you can link purchase order line items to them by supplying skuName or skuCode on each line item when creating or updating a purchase order.

​
Matching priority

When both fields are provided, skuCode takes priority over skuName. If the skuCode match fails, the system does not fall back to skuName for the same item — a separate warning is returned.

​
Matching rules

FieldMatch strategy
skuCodeExact match, case-insensitive
skuNameExact match, case-insensitive

​
Purchase order line item with SKU linking

{
  "lineItems": [
    {
      "identifier": "Ergonomic Chair x10",
      "quantity": 10,
      "rate": 5000.00,
      "skuCode": "FURN-001"
    },
    {
      "identifier": "Standing Desk x2",
      "quantity": 2,
      "rate": 15000.00,
      "skuName": "Standing Desk"
    }
  ]
}

​
When a SKU cannot be matched

If a SKU cannot be found, the purchase order is still created and the response includes a skuMatchWarnings array describing which line items could not be linked: 
{
  "ok": true,
  "data": {
    "poId": "po_abc123",
    "skuMatchWarnings": [
      {
        "lineItemIdentifier": "Unknown Item",
        "skuCode": "UNKNOWN-999",
        "message": "SKU with item code \"UNKNOWN-999\" not found in your inventory"
      }
    ]
  }
}
A missing SKU match is a warning, not an error — the purchase order is created successfully regardless.

​
Best Practices

  • Use a consistent, human-readable itemCode scheme (e.g., CATEGORY-NUMBER) so that external systems can reliably match line items
  • Send SKUs in bulk before creating purchase orders to ensure all line items can be matched
  • Keep SKU names unique within your organisation to avoid ambiguity when matching by skuName
  • SKU name is limited to 128 characters — ensure your names stay within this limit
  • Always prefer skuCode over skuName for matching — codes are more stable than display names
  • Populate hsnSac for items subject to GST to ensure correct tax classification downstream
  • Handle skuMatchWarnings in your integration to detect and remediate unmatched line items