Skip to main content

Connect by API

This guide is for vendor teams sending catalog and inventory data to Kennicott Core via API. You don't need to be a large team — if you can run a script or make an HTTP request, you're set.

:::tip Start here, not the API Reference This page is the step-by-step walkthrough — read it first and copy the working script for your language. The API Reference is a lookup table for every endpoint and field, useful once you're already integrated and need exact request/response shapes. :::

What you need:

  • Your API key — shown once in the connection wizard, then stored in your system
  • The base URL — shown in the wizard and in your connection details
  • Any HTTP client (curl, Python requests, Node.js fetch, Postman)

How it works in plain terms​

Your system calls three endpoints in sequence to send a catalog. Kennicott Core stores the upload URL so your file goes directly to secure cloud storage — your API key never touches the file upload step.

1. POST /feed-uploads → get a job ID and a secure upload URL
2. PUT <upload URL> → send your JSON or CSV file directly to storage
3. POST /feed-imports/start → tell Kennicott Core to process it

Then poll once every few seconds until the job reaches a terminal status: AUTO_PROCESSED (clean — nothing needs attention), READY_FOR_REVIEW (something needs to be fixed and resubmitted), COMPLETED/PARTIAL (auto-publish already ran), or FAILED.

For inventory updates, it's a single direct call — no upload step needed.


Authentication​

Add this header to every request:

x-api-key: YOUR_API_KEY

Your key identifies your vendor account, storefront, and environment automatically. You never send your vendor ID or store name separately.

Keep your key in your secrets manager or environment config. Never put it in source code or log files.


Working code examples​

Python​

import requests
import json
import time
import os

CORE_BASE_URL = os.environ["CORE_BASE_URL"]
API_KEY = os.environ["CORE_API_KEY"]

HEADERS = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}


def submit_catalog(products: list[dict]) -> dict:
"""Submit a catalog feed. Returns the completed job result."""

# Step 1 — request an upload slot
job = requests.post(
f"{CORE_BASE_URL}/api/integrations/feed-uploads",
headers=HEADERS,
json={"fileName": "catalog.json", "sourceFormat": "JSON_API"}
).json()

job_id = job["jobId"]
upload_url = job["presignedUploadUrl"]

# Step 2 — upload file directly to storage (no API key needed here)
requests.put(
upload_url,
headers={"Content-Type": "application/json"},
data=json.dumps(products)
)

# Step 3 — start processing
requests.post(
f"{CORE_BASE_URL}/api/integrations/feed-imports/{job_id}/start",
headers=HEADERS,
json={}
)

# Poll until done
while True:
result = requests.get(
f"{CORE_BASE_URL}/api/integrations/feed-imports/{job_id}",
headers=HEADERS
).json()

status = result["status"]
print(f" status: {status}")

if status in ("AUTO_PROCESSED", "READY_FOR_REVIEW", "COMPLETED", "PARTIAL", "FAILED"):
return result

time.sleep(5)


def submit_inventory(items: list[dict], revision: str) -> dict:
"""Send inventory counts. No upload step — direct call."""
from datetime import datetime, timezone

return requests.post(
f"{CORE_BASE_URL}/api/integrations/inventory",
headers=HEADERS,
json={
"sourceRevision": revision,
"sourceUpdatedAt": datetime.now(timezone.utc).isoformat(),
"items": items
}
).json()


# ── Example: submit a two-variant product ────────────────────────────────────

products = [
{
"sourceSku": "ROSE-RED-001",
"productName": "Red Garden Rose",
"productType": "Rose",
"color": "RED",
"grade": "PREMIUM",
"variety": "Red Naomi",
"boxType": "EB",
"unitsPerBox": "5",
"bunchesPerBox": "5",
"stemsPerBunch": "20",
"sellUnit": "Bunch",
"price": "28.50",
"availableFrom": "2026-07-01",
"availableTo": "2026-09-30",
"growerOriginCode": "ECU",
"onHandQuantity": "120"
},
{
# Same sourceSku = same Shopify product, different box size = second variant
"sourceSku": "ROSE-RED-001",
"productName": "Red Garden Rose",
"productType": "Rose",
"color": "RED",
"grade": "PREMIUM",
"variety": "Red Naomi",
"boxType": "HB",
"unitsPerBox": "20",
"bunchesPerBox": "20",
"stemsPerBunch": "20",
"sellUnit": "Bunch",
"price": "98.00",
"availableFrom": "2026-07-01",
"availableTo": "2026-09-30",
"growerOriginCode": "ECU",
"onHandQuantity": "40"
}
]

result = submit_catalog(products)
print(f"Families: {result['familyCount']}, Variants: {result['variantCount']}")


# ── Example: update inventory separately ─────────────────────────────────────

inventory_result = submit_inventory(
items=[
{"sourceSku": "ROSE-RED-001", "vendorVariantCode": "EB-5", "onHandQuantity": 115},
{"sourceSku": "ROSE-RED-001", "vendorVariantCode": "HB-20", "onHandQuantity": 38},
],
revision="my-system-feed-20260703-0600"
)

print(f"Inventory: {inventory_result['applied']} applied")

Node.js​

const CORE_BASE_URL = process.env.CORE_BASE_URL;
const API_KEY = process.env.CORE_API_KEY;

const headers = { "x-api-key": API_KEY, "Content-Type": "application/json" };

async function submitCatalog(products) {
// 1. Request upload slot
const { jobId, presignedUploadUrl } = await fetch(
`${CORE_BASE_URL}/api/integrations/feed-uploads`,
{
method: "POST",
headers,
body: JSON.stringify({
fileName: "catalog.json",
sourceFormat: "JSON_API",
}),
},
).then((r) => r.json());

// 2. Upload to storage — no API key needed for this step
await fetch(presignedUploadUrl, {
method: "PUT",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(products),
});

// 3. Start processing
await fetch(
`${CORE_BASE_URL}/api/integrations/feed-imports/${jobId}/start`,
{ method: "POST", headers, body: "{}" },
);

// 4. Poll until complete
while (true) {
const result = await fetch(
`${CORE_BASE_URL}/api/integrations/feed-imports/${jobId}`,
{ headers },
).then((r) => r.json());

if (
["AUTO_PROCESSED", "READY_FOR_REVIEW", "COMPLETED", "PARTIAL", "FAILED"].includes(
result.status,
)
) {
return result;
}

await new Promise((r) => setTimeout(r, 5000));
}
}

async function submitInventory(items, revision) {
return fetch(`${CORE_BASE_URL}/api/integrations/inventory`, {
method: "POST",
headers,
body: JSON.stringify({
sourceRevision: revision,
sourceUpdatedAt: new Date().toISOString(),
items,
}),
}).then((r) => r.json());
}

// Usage
const result = await submitCatalog([
{
sourceSku: "ROSE-RED-001",
productName: "Red Garden Rose",
boxType: "EB",
unitsPerBox: "5",
sellUnit: "Bunch",
price: "28.50",
availableFrom: "2026-07-01",
},
]);

console.log(`${result.familyCount} families, ${result.variantCount} variants`);

Shell (one-liner for testing)​

# Step 1 — get upload slot
JOB=$(curl -s -X POST "$CORE_BASE_URL/api/integrations/feed-uploads" \
-H "x-api-key: $CORE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"fileName":"catalog.json","sourceFormat":"JSON_API"}')

JOB_ID=$(echo $JOB | python3 -c "import sys,json; print(json.load(sys.stdin)['jobId'])")
UPLOAD_URL=$(echo $JOB | python3 -c "import sys,json; print(json.load(sys.stdin)['presignedUploadUrl'])")

# Step 2 — upload file
curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: application/json" --data-binary @catalog.json

# Step 3 — start + poll
curl -s -X POST "$CORE_BASE_URL/api/integrations/feed-imports/$JOB_ID/start" \
-H "x-api-key: $CORE_API_KEY" -H "Content-Type: application/json" -d '{}'

curl -s "$CORE_BASE_URL/api/integrations/feed-imports/$JOB_ID" \
-H "x-api-key: $CORE_API_KEY" | python3 -m json.tool

Verify your connection first​

Before sending any data, confirm your key works:

curl -X POST $CORE_BASE_URL/api/integrations/test \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'

Expected response:

{
"success": true,
"connection": {
"vendorId": "your-vendor-id",
"storefrontId": "directbloom",
"environment": "DEV",
"status": "ACTIVE"
}
}

What Kennicott Core does automatically​

You send your product data. Kennicott Core handles the rest:

  • Groups rows with the same sourceSku into one Shopify product family
  • Assigns a stable internal SKU to each package variant
  • Builds the Pack Size Shopify option from your box type and unit count — "EB · 5 Bunches", "HB · 20 Bunches"
  • Maps product fields to approved Shopify metafields — color, grade, variety, box type, stems per bunch, grower origin, and more
  • Holds package specification changes for review before updating Shopify
  • Applies your shipping lead time to availability dates at publish time

What not to send​

Never include these in your payloads — Kennicott Core rejects them:

FieldWhy
vendorIdResolved from your API key
storeKey, environmentResolved from your API key
Shopify product or variant IDsSet by Kennicott Core after publishing
Core SKUsAssigned by Kennicott Core at first commit
Raw Shopify metafield keys like custom.availablefromUse Kennicott Core canonical field names

Inventory updates​

Same API key, direct call — no upload step:

submit_inventory(
items=[
{"sourceSku": "ROSE-RED-001", "vendorVariantCode": "EB-5", "onHandQuantity": 115},
{"sourceSku": "ROSE-RED-001", "vendorVariantCode": "HB-20", "onHandQuantity": 38},
],
revision="my-feed-20260703-0600"
)

vendorVariantCode is "{boxType}-{unitsPerBox}". Required when a product has more than one box type — otherwise Kennicott Core doesn't know which variant to update.


Upload URL expiration​

The upload URL in step 2 expires in 15 minutes. If it expires before you upload, create a new job and try again. Your integration code should run all three steps back to back.


sourceRevision and safe retries​

Include a sourceRevision in every inventory call — a unique ID from your system for that batch:

{
"sourceRevision": "my-erp-export-20260703-0600",
"sourceUpdatedAt": "2026-07-03T06:00:00Z",
"items": [...]
}
  • Same revision + same data → NO_CHANGE — safe to retry any number of times
  • Same revision + different data → SOURCE_REVISION_COLLISION — use a new revision ID

Common errors​

ErrorWhat happenedFix
401Invalid or missing API keyAdd x-api-key: YOUR_KEY to every request
403Connection is disabled or inactiveContact your Kennicott Core administrator
400 UPLOAD_URL_EXPIREDUpload URL expired before file arrivedCreate a new upload job
409 SOURCE_REVISION_COLLISIONSame revision ID sent with different dataUse a new sourceRevision
429Rate limit hitWait retryAfterSeconds from the response

Your credentials​

Auth headerx-api-key: YOUR_API_KEY
Key formatgrav_conn_<uuid>_<48 hex characters>
Key shownOnce, in the connection wizard

Your key is shown once when generated. Store it immediately. If lost, your Kennicott Core administrator can rotate it — the old key stops working when rotated.

A separate PROD key is issued after your DEV integration is reviewed and approved.


Next steps​