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
sourceSkuinto 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:
| Field | Why |
|---|---|
vendorId | Resolved from your API key |
storeKey, environment | Resolved from your API key |
| Shopify product or variant IDs | Set by Kennicott Core after publishing |
| Core SKUs | Assigned by Kennicott Core at first commit |
Raw Shopify metafield keys like custom.availablefrom | Use 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
| Error | What happened | Fix |
|---|---|---|
| 401 | Invalid or missing API key | Add x-api-key: YOUR_KEY to every request |
| 403 | Connection is disabled or inactive | Contact your Kennicott Core administrator |
400 UPLOAD_URL_EXPIRED | Upload URL expired before file arrived | Create a new upload job |
409 SOURCE_REVISION_COLLISION | Same revision ID sent with different data | Use a new sourceRevision |
| 429 | Rate limit hit | Wait retryAfterSeconds from the response |
Your credentials
| Auth header | x-api-key: YOUR_API_KEY |
| Key format | grav_conn_<uuid>_<48 hex characters> |
| Key shown | Once, 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
- Product and Inventory Requirements — every field explained
- Import Results and Fixing Errors
- API Reference