Product and Inventory Requirements
This is the field reference for sending fresh and floral catalog data to Kennicott Core. Every API example and CSV template is based on these fields.
How Kennicott Core organizes your products
Product family — one flower or product concept. Becomes one Shopify product listing.
Variant — a specific package size within that product family. Becomes one Shopify variant with a Pack Size option.
To create multiple variants, submit multiple rows with the same sourceSku — one row per box type.
Example — one product, four box sizes:
Red Garden Rose (sourceSku: ROSE-RED-001)
├── EB · 5 Bunches → Shopify variant, Pack Size "EB · 5 Bunches"
├── HB · 20 Bunches → Shopify variant, Pack Size "HB · 20 Bunches"
├── QB · 10 Bunches → Shopify variant, Pack Size "QB · 10 Bunches"
└── CB · 3 Bunches → Shopify variant, Pack Size "CB · 3 Bunches"
Identifiers: yours vs Kennicott Core's
| Identifier | Who sets it | Used for |
|---|---|---|
sourceSku | You | Groups rows into one Shopify product |
vendorVariantCode | You (optional) | Inventory update disambiguation |
Assigned variant SKU (e.g. KNC-000123456) | Kennicott Core | Orders, inventory, fulfillment — internal only |
Do not include assigned variant SKUs or Shopify IDs in catalog submission payloads. Kennicott Core assigns and manages these. The enrich endpoint uses the returned coreSku to identify a staged variant.
Minimal example — single-variant product
One product, one box size, ready to publish:
[
{
"sourceSku": "ROSE-RED-001",
"productName": "Red Garden Rose",
"boxType": "EB",
"sellUnit": "Bunch",
"price": "28.50",
"availableFrom": "2026-07-01"
}
]
Full example — four variants with all fields
[
{
"sourceSku": "ROSE-RED-001",
"productName": "Red Garden Rose",
"productType": "Rose",
"color": "RED",
"grade": "PREMIUM",
"variety": "Red Naomi",
"category": "Cut Flowers",
"growerOriginCode": "ECU",
"boxType": "EB",
"unitsPerBox": "5",
"bunchesPerBox": "5",
"stemsPerBunch": "20",
"totalUnitsPerBox": "100",
"sellUnit": "Bunch",
"pack": "5",
"price": "28.50",
"availableFrom": "2026-07-01",
"availableTo": "2026-09-30",
"onHandQuantity": "120",
"inventoryAsOf": "2026-07-01T08:00:00Z"
},
{
"sourceSku": "ROSE-RED-001",
"productName": "Red Garden Rose",
"productType": "Rose",
"color": "RED",
"grade": "PREMIUM",
"variety": "Red Naomi",
"category": "Cut Flowers",
"growerOriginCode": "ECU",
"boxType": "HB",
"unitsPerBox": "20",
"bunchesPerBox": "20",
"stemsPerBunch": "20",
"totalUnitsPerBox": "400",
"sellUnit": "Bunch",
"pack": "20",
"price": "98.00",
"availableFrom": "2026-07-01",
"availableTo": "2026-09-30",
"onHandQuantity": "40",
"inventoryAsOf": "2026-07-01T08:00:00Z"
},
{
"sourceSku": "ROSE-RED-001",
"productName": "Red Garden Rose",
"productType": "Rose",
"color": "RED",
"grade": "PREMIUM",
"variety": "Red Naomi",
"category": "Cut Flowers",
"growerOriginCode": "ECU",
"boxType": "QB",
"unitsPerBox": "10",
"bunchesPerBox": "10",
"stemsPerBunch": "20",
"totalUnitsPerBox": "200",
"sellUnit": "Bunch",
"pack": "10",
"price": "52.00",
"availableFrom": "2026-07-01",
"availableTo": "2026-09-30",
"onHandQuantity": "75",
"inventoryAsOf": "2026-07-01T08:00:00Z"
},
{
"sourceSku": "ROSE-RED-001",
"productName": "Red Garden Rose",
"productType": "Rose",
"color": "RED",
"grade": "PREMIUM",
"variety": "Red Naomi",
"category": "Cut Flowers",
"growerOriginCode": "ECU",
"boxType": "CB",
"unitsPerBox": "3",
"bunchesPerBox": "3",
"stemsPerBunch": "20",
"totalUnitsPerBox": "60",
"sellUnit": "Bunch",
"pack": "3",
"price": "18.00",
"availableFrom": "2026-07-01",
"availableTo": "2026-09-30",
"onHandQuantity": "200",
"inventoryAsOf": "2026-07-01T08:00:00Z"
}
]
Equivalent CSV
The same four variants as a CSV file. Download the CSV template from the connection wizard (Step 5) with headers pre-filled.
sourceSku,productName,productType,color,grade,variety,category,growerOriginCode,boxType,unitsPerBox,bunchesPerBox,stemsPerBunch,totalUnitsPerBox,pack,sellUnit,price,availableFrom,availableTo,imageUrl,onHandQuantity,inventoryAsOf
ROSE-RED-001,Red Garden Rose,Rose,RED,PREMIUM,Red Naomi,Cut Flowers,ECU,EB,5,5,20,100,5,Bunch,28.50,2026-07-01,2026-09-30,,120,2026-07-01T08:00:00Z
ROSE-RED-001,Red Garden Rose,Rose,RED,PREMIUM,Red Naomi,Cut Flowers,ECU,HB,20,20,20,400,20,Bunch,98.00,2026-07-01,2026-09-30,,40,2026-07-01T08:00:00Z
ROSE-RED-001,Red Garden Rose,Rose,RED,PREMIUM,Red Naomi,Cut Flowers,ECU,QB,10,10,20,200,10,Bunch,52.00,2026-07-01,2026-09-30,,75,2026-07-01T08:00:00Z
ROSE-RED-001,Red Garden Rose,Rose,RED,PREMIUM,Red Naomi,Cut Flowers,ECU,CB,3,3,20,60,3,Bunch,18.00,2026-07-01,2026-09-30,,200,2026-07-01T08:00:00Z
JSON and CSV produce identical results in Kennicott Core — same family, same variants, same Pack Size option, same metafields.
Field reference
Required to stage
| Field | Description | Example |
|---|---|---|
sourceSku | Your stable product code. All rows with the same code = one Shopify product. | ROSE-RED-001 |
productName | Product display name (also accepted as commonName) | Red Garden Rose |
boxType | Box type code. Identifies the variant within a family. | EB, HB, QB, CB |
sellUnit | Unit of sale | Bunch, Stem, Box |
Required before Shopify publish
| Field | Description | Format |
|---|---|---|
price | Selling price per package | Decimal string: "28.50" |
availableFrom | Start of availability window | YYYY-MM-DD: "2026-07-01" |
You can submit without price and dates — add them later via the enrich endpoint or in the portal before publishing.
Do not pre-adjust dates for lead time. Enter your actual availability dates. Kennicott Core adds your shipping lead time at publish time automatically.
Package fields (optional but recommended)
| Field | Description | Example |
|---|---|---|
unitsPerBox | Total sellable units per box | "5", "20" |
bunchesPerBox | Bunches per box | "5", "20" |
stemsPerBunch | Stems per bunch | "20", "25" |
totalUnitsPerBox | Total stems per box | "100", "400" |
pack | Pack count (usually same as bunchesPerBox) | "5" |
Product fields (optional)
| Field | Description | Example |
|---|---|---|
productType | Flower type | Rose, Alstroemeria, Lily |
color | Color | RED, WHITE, ASSORTED |
grade | Quality grade | PREMIUM, SELECT, SUPER SELECT |
variety | Cultivar name | Red Naomi, Freedom, Bodega |
category | Category code | Cut Flowers, ALSTROEMERIA |
growerOriginCode | Origin location code | ECU, MIA, BOG |
availableTo | End of availability window | "2026-09-30" |
imageUrl | Product image URL | https://example.com/rose.jpg |
vendorProductCode | Your internal product code | ROSE-RED-001 |
Inline inventory (optional)
| Field | Description | Example |
|---|---|---|
onHandQuantity | Current on-hand count for this variant | "120" |
inventoryAsOf | When this count was taken (ISO 8601) | "2026-07-01T08:00:00Z" |
Inventory-only updates
Send on-hand counts directly using the same API key. No catalog job or upload step needed.
{
"sourceRevision": "my-feed-20260703-0600",
"sourceUpdatedAt": "2026-07-03T06:00:00Z",
"items": [
{
"sourceSku": "ROSE-RED-001",
"vendorVariantCode": "EB-5",
"onHandQuantity": 120
},
{
"sourceSku": "ROSE-RED-001",
"vendorVariantCode": "HB-20",
"onHandQuantity": 40
}
]
}
vendorVariantCode format is "{boxType}-{unitsPerBox}" — e.g. "EB-5", "HB-20". Required when a product has more than one box type, otherwise Kennicott Core can't tell which variant to update.
Inventory result codes
| Code | Meaning |
|---|---|
APPLIED | Balance updated |
NO_CHANGE | Balance already matches — safe to retry with same revision |
REJECTED_STALE | sourceUpdatedAt is older than last accepted snapshot |
HELD_BY_OVERRIDE | Manual override is active — count held for review |
UNKNOWN_VARIANT | sourceSku not found in committed products |
AMBIGUOUS_VARIANT | Multiple variants match — add vendorVariantCode |
Package change behavior
If you submit a row where boxType, unitsPerBox, or sellUnit differs from what is already published, Kennicott Core holds the change for admin review. The Shopify variant is not updated until approved.
This protects against accidental mutations to live product listings.
Fields Kennicott Core manages — never send these
| Field | Why |
|---|---|
vendorId | Resolved from your API key |
storeKey, environment | Resolved from your API key |
shopifyProductId, shopifyVariantId | Set by Kennicott Core after publishing |
| Core SKU | Assigned by Kennicott Core at first commit |
Raw Shopify metafield keys (custom.availablefrom, etc.) | Use Kennicott Core canonical field names |
Next steps
- Connect by API — integration guide with Python, Node.js, and shell examples
- Import Results and Fixing Errors
- API Reference
How Kennicott Core organizes your products
Product family — one flower or product concept. Becomes one Shopify product listing.
Variant — a specific package size within that product family. Becomes one Shopify variant with a Pack Size option.
Example:
Red Garden Rose (sourceSku: ROSE-RED-GARDEN)
├── EB · 5 Bunches → Shopify variant, Pack Size: "EB · 5 Bunches"
├── HB · 20 Bunches → Shopify variant, Pack Size: "HB · 20 Bunches"
├── QB · 10 Bunches → Shopify variant, Pack Size: "QB · 10 Bunches"
└── CB · 3 Bunches → Shopify variant, Pack Size: "CB · 3 Bunches"
To create multiple variants, submit multiple rows with the same sourceSku — one row per box type.
Identifiers: yours vs Kennicott Core's
| Identifier | Who assigns it | Purpose |
|---|---|---|
sourceSku | You | Groups rows into one product family |
vendorVariantCode | You (optional) | Distinguishes variants in inventory updates |
Core SKU (KNC-000123456) | Kennicott Core | Stable internal ID for orders, inventory, fulfillment |
Never send Core SKUs or Shopify IDs in your payloads. Kennicott Core assigns and manages these.
Catalog feed format
Your catalog is a JSON array. Each element is one product row. Multiple rows with the same sourceSku become one product family with multiple variants.
Minimal single-variant example
One product, one box type:
[
{
"sourceSku": "ROSE-RED-GARDEN",
"productName": "Red Garden Rose",
"boxType": "EB",
"sellUnit": "Bunch",
"price": "28.50",
"availableFrom": "2026-07-01"
}
]
Full multi-variant example with all fields
Same product, four box types, full package details and inline inventory:
[
{
"sourceSku": "ROSE-RED-GARDEN",
"productName": "Red Garden Rose",
"productType": "Rose",
"color": "RED",
"grade": "PREMIUM",
"variety": "Red Naomi",
"category": "Cut Flowers",
"growerOriginCode": "ECU",
"boxType": "EB",
"unitsPerBox": "5",
"bunchesPerBox": "5",
"stemsPerBunch": "20",
"totalUnitsPerBox": "100",
"sellUnit": "Bunch",
"pack": "5",
"price": "28.50",
"availableFrom": "2026-07-01",
"availableTo": "2026-09-30",
"onHandQuantity": "120",
"inventoryAsOf": "2026-07-01T08:00:00Z"
},
{
"sourceSku": "ROSE-RED-GARDEN",
"productName": "Red Garden Rose",
"productType": "Rose",
"color": "RED",
"grade": "PREMIUM",
"variety": "Red Naomi",
"category": "Cut Flowers",
"growerOriginCode": "ECU",
"boxType": "HB",
"unitsPerBox": "20",
"bunchesPerBox": "20",
"stemsPerBunch": "20",
"totalUnitsPerBox": "400",
"sellUnit": "Bunch",
"pack": "20",
"price": "98.00",
"availableFrom": "2026-07-01",
"availableTo": "2026-09-30",
"onHandQuantity": "40",
"inventoryAsOf": "2026-07-01T08:00:00Z"
}
]
Catalog field reference
Required to stage
These four fields are the minimum required for Kennicott Core to accept and store your product.
| Field | Description | Example |
|---|---|---|
sourceSku | Your stable product code. All rows with the same code become one Shopify product. | ROSE-RED-GARDEN |
productName | Product display name (also accepted as commonName) | Red Garden Rose |
boxType | Box type code. Identifies the variant within a family. | EB, HB, QB, CB |
sellUnit | Unit of sale | Bunch, Stem, Box |
Required before Shopify publish
In addition to the staging fields:
| Field | Description | Format |
|---|---|---|
price | Selling price per package | Decimal string: "28.50" |
availableFrom | Start of availability window | YYYY-MM-DD: "2026-07-01" |
You can submit your catalog without price and dates and add them later through the enrich endpoint or in the portal before publishing.
Do not pre-adjust dates for shipping lead time. Enter your actual product availability dates. Kennicott Core adds your vendor shipping lead time automatically at publish time.
Optional package fields
| Field | Description | Example |
|---|---|---|
unitsPerBox | Total sellable units per box | "5", "20" |
bunchesPerBox | Bunches per box | "5", "20" |
stemsPerBunch | Stems per bunch | "20", "25" |
totalUnitsPerBox | Total stems per box | "100", "400" |
pack | Pack count (same as bunchesPerBox in most cases) | "5" |
Optional product fields
| Field | Description | Example |
|---|---|---|
productType | Product category | Rose, Alstroemeria, Lily |
color | Color | RED, WHITE, ASSORTED |
grade | Quality grade | PREMIUM, SELECT, SUPER SELECT |
variety | Cultivar name | Red Naomi, Freedom, Bodega |
category | Category code | Cut Flowers, ALSTROEMERIA |
growerOriginCode | Origin location code | ECU, MIA, BOG |
availableTo | End of availability window | "2026-09-30" |
imageUrl | Product image URL | https://example.com/rose.jpg |
vendorProductCode | Your internal product code | ROSE-RED-001 |
Inline inventory (optional)
Include quantity data directly in your catalog rows. Kennicott Core applies inventory after committing each variant.
| Field | Description | Example |
|---|---|---|
onHandQuantity | Current on-hand count for this variant | "120" |
inventoryAsOf | When this count was taken (ISO 8601) | "2026-07-01T08:00:00Z" |
If the variant is new and not yet committed, inline inventory is held until catalog approval completes.
Inventory-only updates
Send on-hand counts directly without a catalog feed. Uses the same API key.
{
"sourceRevision": "your-system-feed-20260701-001",
"sourceUpdatedAt": "2026-07-01T06:00:00Z",
"items": [
{
"sourceSku": "ROSE-RED-GARDEN",
"vendorVariantCode": "EB-5",
"onHandQuantity": 120
},
{
"sourceSku": "ROSE-RED-GARDEN",
"vendorVariantCode": "HB-20",
"onHandQuantity": 40
}
]
}
Inventory field reference
| Field | Required | Description | Example |
|---|---|---|---|
sourceRevision | Yes | Unique ID for this batch from your system | "my-feed-20260701-001" |
sourceUpdatedAt | Yes | When this count was taken in your system (ISO 8601) | "2026-07-01T06:00:00Z" |
items | Yes | Array of inventory rows, max 500 | — |
sourceSku | Yes | Your product code, must match a committed product | "ROSE-RED-GARDEN" |
vendorVariantCode | Required when multi-variant | Format: {boxType}-{unitsPerBox}. Required if sourceSku has more than one box type. | "EB-5", "HB-20" |
onHandQuantity | Yes | Current physical count, non-negative whole number | 120 |
If a sourceSku has multiple variants and you omit vendorVariantCode, the item returns AMBIGUOUS_VARIANT and is not applied.
Inventory result codes
| Code | Meaning |
|---|---|
APPLIED | Inventory movement written, balance updated |
NO_CHANGE | Current balance already matches the submitted count |
REJECTED_STALE | sourceUpdatedAt is older than the last accepted snapshot — not applied |
HELD_BY_OVERRIDE | A manual override is active for this variant — count held for review |
UNKNOWN_VARIANT | sourceSku not found in your committed products |
AMBIGUOUS_VARIANT | Multiple variants match this sourceSku — provide vendorVariantCode |
Package change behavior
If you submit a product row where boxType, unitsPerBox, or sellUnit differs from what is already published in Shopify, Kennicott Core routes the change for admin review instead of applying it immediately.
This prevents accidental mutations to live Shopify variants when a vendor renames or reconfigures a box type.
The Core SKU for that variant does not change. The existing Shopify option label is not updated until an administrator approves the change.
Fields Kennicott Core manages — never send these
| Field | Why |
|---|---|
vendorId | Resolved from your API key |
storeKey, environment | Resolved from your API key |
shopifyProductId, shopifyVariantId | Set by Kennicott Core after publishing |
Core SKU (e.g. KNC-000123456) | Assigned by Kennicott Core at first commit |
| Any Shopify GID | Managed by Kennicott Core |
Raw Shopify metafield keys (custom.availablefrom, etc.) | Use Kennicott Core canonical field names |
Next steps
- Connect by API — step-by-step integration guide
- Import Results and Fixing Errors
- API Reference