Skip to main content

​
Items

An “item” is a bundle that groups a parent Item with one or more Item Variants and ownership-specific records. The external API lets you create platform item bundles.
You can only create platform item bundles via the API. Phantom item bundles exist (for phantom suppliers) but are not creatable externally.

​
Item bundle structure

Parent Item

The parent resource that holds core fields (name, handle, type, status). Variants are attached to this Item.

Ownership layer

Platform Item is an extension of the Item that stores ownership/diverged fields. It shares the same ID as the parent Item. Phantom item extensions exist but are not creatable via the external API.

Variants (the real meat)

Variants hold pricing, cost, SKU/barcode, dimensions, and more. Every item must have at least one variant — a single-variant item typically uses a variant named “Default” (similar to Shopify’s model).

​
What happens when you create an item

Creating an item via the API orchestrates resources in this order:
1

Parent Item is created

Defines the container and core metadata for the item. Variants will attach to this parent Item.
2

Platform Item is created

Ownership-specific extension record for your supplier business that uses the same ID as the parent Item.
3

Variants are created

One or more variants are attached to the parent Item. At least one is required.

​
Relationship map

Supplier (you)
└─ Item (parent, itm_...)
   ├─ Platform Item (extension, same id as Item)
   └─ Variants (one or more)

​
Authentication

Include the following headers in every request:
  • X-Business-ID: Your business identifier
  • X-API-Key: Your API key

​
Create an Item

Creates a platform item bundle with a parent Item and one or more Variants. Endpoint: POST /api/v1/items 
curl -X POST "https://integrations.polinate.ai/api/v1/items" \
  -H "X-Business-ID: {{businessId}}" \
  -H "X-API-Key: {{apiKey}}" \
  -H "Content-Type: application/json" \
  -d '{
    "item": {
      "name": "Widget",
      "handle": "widget-1",
      "type": "OTHER",
      "status": "ACTIVE"
    },
    "variants": [
      {
        "variantName": "Default",
        "currency": "AUD",
        "price": 12.34,
        "cost": 8.5
      }
    ]
  }'

​
Response Structure

The API returns:
  • success: Always true on successful creation
  • id: The created item ID (used for GET/PATCH operations)
  • variantIds: Array of created variant IDs in the same order as submitted
Variant ID ordering: The variantIds array matches the order of variants in your request body. This allows you to map your input variants to their database IDs.For example, if you submit:
"variants": [
  { "variantName": "Small", ... },
  { "variantName": "Medium", ... },
  { "variantName": "Large", ... }
]
The response will be:
{
  "id": "itm_123",
  "variantIds": ["var_small_id", "var_medium_id", "var_large_id"]
}
Where variantIds[0] = Small, variantIds[1] = Medium, variantIds[2] = Large.
This operation is idempotent when you provide an Idempotency-Key. Repeating the same key returns the original result.

​
Notes

  • Provide at least one variant in variants.
  • Use Idempotency-Key header for safe retries on POST requests.
  • The variantIds array preserves submission order for easy mapping to your input data.