Skip to main content

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​

IdentifierWho sets itUsed for
sourceSkuYouGroups rows into one Shopify product
vendorVariantCodeYou (optional)Inventory update disambiguation
Assigned variant SKU (e.g. KNC-000123456)Kennicott CoreOrders, 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​

FieldDescriptionExample
sourceSkuYour stable product code. All rows with the same code = one Shopify product.ROSE-RED-001
productNameProduct display name (also accepted as commonName)Red Garden Rose
boxTypeBox type code. Identifies the variant within a family.EB, HB, QB, CB
sellUnitUnit of saleBunch, Stem, Box

Required before Shopify publish​

FieldDescriptionFormat
priceSelling price per packageDecimal string: "28.50"
availableFromStart of availability windowYYYY-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.

FieldDescriptionExample
unitsPerBoxTotal sellable units per box"5", "20"
bunchesPerBoxBunches per box"5", "20"
stemsPerBunchStems per bunch"20", "25"
totalUnitsPerBoxTotal stems per box"100", "400"
packPack count (usually same as bunchesPerBox)"5"

Product fields (optional)​

FieldDescriptionExample
productTypeFlower typeRose, Alstroemeria, Lily
colorColorRED, WHITE, ASSORTED
gradeQuality gradePREMIUM, SELECT, SUPER SELECT
varietyCultivar nameRed Naomi, Freedom, Bodega
categoryCategory codeCut Flowers, ALSTROEMERIA
growerOriginCodeOrigin location codeECU, MIA, BOG
availableToEnd of availability window"2026-09-30"
imageUrlProduct image URLhttps://example.com/rose.jpg
vendorProductCodeYour internal product codeROSE-RED-001

Inline inventory (optional)​

FieldDescriptionExample
onHandQuantityCurrent on-hand count for this variant"120"
inventoryAsOfWhen 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​

CodeMeaning
APPLIEDBalance updated
NO_CHANGEBalance already matches — safe to retry with same revision
REJECTED_STALEsourceUpdatedAt is older than last accepted snapshot
HELD_BY_OVERRIDEManual override is active — count held for review
UNKNOWN_VARIANTsourceSku not found in committed products
AMBIGUOUS_VARIANTMultiple 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​

FieldWhy
vendorIdResolved from your API key
storeKey, environmentResolved from your API key
shopifyProductId, shopifyVariantIdSet by Kennicott Core after publishing
Core SKUAssigned by Kennicott Core at first commit
Raw Shopify metafield keys (custom.availablefrom, etc.)Use Kennicott Core canonical field names

Next steps​


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​

IdentifierWho assigns itPurpose
sourceSkuYouGroups rows into one product family
vendorVariantCodeYou (optional)Distinguishes variants in inventory updates
Core SKU (KNC-000123456)Kennicott CoreStable 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.

FieldDescriptionExample
sourceSkuYour stable product code. All rows with the same code become one Shopify product.ROSE-RED-GARDEN
productNameProduct display name (also accepted as commonName)Red Garden Rose
boxTypeBox type code. Identifies the variant within a family.EB, HB, QB, CB
sellUnitUnit of saleBunch, Stem, Box

Required before Shopify publish​

In addition to the staging fields:

FieldDescriptionFormat
priceSelling price per packageDecimal string: "28.50"
availableFromStart of availability windowYYYY-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​

FieldDescriptionExample
unitsPerBoxTotal sellable units per box"5", "20"
bunchesPerBoxBunches per box"5", "20"
stemsPerBunchStems per bunch"20", "25"
totalUnitsPerBoxTotal stems per box"100", "400"
packPack count (same as bunchesPerBox in most cases)"5"

Optional product fields​

FieldDescriptionExample
productTypeProduct categoryRose, Alstroemeria, Lily
colorColorRED, WHITE, ASSORTED
gradeQuality gradePREMIUM, SELECT, SUPER SELECT
varietyCultivar nameRed Naomi, Freedom, Bodega
categoryCategory codeCut Flowers, ALSTROEMERIA
growerOriginCodeOrigin location codeECU, MIA, BOG
availableToEnd of availability window"2026-09-30"
imageUrlProduct image URLhttps://example.com/rose.jpg
vendorProductCodeYour internal product codeROSE-RED-001

Inline inventory (optional)​

Include quantity data directly in your catalog rows. Kennicott Core applies inventory after committing each variant.

FieldDescriptionExample
onHandQuantityCurrent on-hand count for this variant"120"
inventoryAsOfWhen 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​

FieldRequiredDescriptionExample
sourceRevisionYesUnique ID for this batch from your system"my-feed-20260701-001"
sourceUpdatedAtYesWhen this count was taken in your system (ISO 8601)"2026-07-01T06:00:00Z"
itemsYesArray of inventory rows, max 500—
sourceSkuYesYour product code, must match a committed product"ROSE-RED-GARDEN"
vendorVariantCodeRequired when multi-variantFormat: {boxType}-{unitsPerBox}. Required if sourceSku has more than one box type."EB-5", "HB-20"
onHandQuantityYesCurrent physical count, non-negative whole number120

If a sourceSku has multiple variants and you omit vendorVariantCode, the item returns AMBIGUOUS_VARIANT and is not applied.

Inventory result codes​

CodeMeaning
APPLIEDInventory movement written, balance updated
NO_CHANGECurrent balance already matches the submitted count
REJECTED_STALEsourceUpdatedAt is older than the last accepted snapshot — not applied
HELD_BY_OVERRIDEA manual override is active for this variant — count held for review
UNKNOWN_VARIANTsourceSku not found in your committed products
AMBIGUOUS_VARIANTMultiple 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​

FieldWhy
vendorIdResolved from your API key
storeKey, environmentResolved from your API key
shopifyProductId, shopifyVariantIdSet by Kennicott Core after publishing
Core SKU (e.g. KNC-000123456)Assigned by Kennicott Core at first commit
Any Shopify GIDManaged by Kennicott Core
Raw Shopify metafield keys (custom.availablefrom, etc.)Use Kennicott Core canonical field names

Next steps​