API Reference
Reference for all vendor-accessible API endpoints. These are the endpoints your system can call using your API key.
:::tip New to the API? Start with Connect by API instead — it walks through the full flow with a working script you can copy and run. Come back to this page once you need the exact fields for a specific endpoint. :::
All requests require:
x-api-key: CORE_API_KEY
Replace CORE_BASE_URL with the base URL your Kennicott Core administrator provided.
Feed import responses and enrichment requests use coreSku. Use the assigned
value returned by Kennicott Core; do not construct one from a product name or
code.
Connection
Verify connection
POST CORE_BASE_URL/api/integrations/test
Verifies your API key and returns safe connection metadata.
Request body: {} (empty)
Response:
{
"success": true,
"message": "Connection test successful",
"connection": {
"connectionId": "conn_...",
"vendorId": "your-vendor-id",
"storefrontId": "directbloom",
"environment": "DEV",
"connectionType": "VENDOR_INBOUND_API",
"status": "ACTIVE",
"capabilities": ["PRODUCT_CREATE", "PRODUCT_UPDATE", "CONNECTION_TEST"]
}
}
Get setup guide
GET CORE_BASE_URL/api/integrations/setup-guide
Returns your environment-specific setup information including available endpoints, curl examples, and a setup checklist.
Response: Configuration object with apiBaseUrl, capabilities, endpoints[], setupChecklist[].
Catalog feed
Create upload job
POST CORE_BASE_URL/api/integrations/feed-uploads
Capability required: PRODUCT_CREATE or PRODUCT_UPDATE
Request body:
| Field | Required | Description |
|---|---|---|
fileName | Yes | Filename for reference |
sourceFormat | No (default: CSV) | CSV or JSON_API |
profileId | No | Specific profile ID; uses your active profile if omitted |
Response:
{
"jobId": "JOB_ID",
"presignedUploadUrl": "https://s3.amazonaws.com/...",
"s3Key": "feed-uploads/.../catalog.json",
"expiresInSeconds": 900,
"profileId": "...",
"vendorId": "your-vendor-id",
"storefrontId": "directbloom",
"environment": "DEV"
}
Upload catalog file to S3
PUT PRESIGNED_UPLOAD_URL
Content-Type: application/json (for JSON_API)
Content-Type: text/csv (for CSV)
Upload directly to S3 using the presigned URL. No API key needed for this step.
For JSON_API: body is a JSON array of product rows.
For CSV: body is the raw CSV file content.
Start processing
POST CORE_BASE_URL/api/integrations/feed-imports/JOB_ID/start
Capability required: PRODUCT_CREATE or PRODUCT_UPDATE
Request body: {} (empty)
Response:
{
"jobId": "JOB_ID",
"started": true,
"status": "PARSING"
}
Poll job status
GET CORE_BASE_URL/api/integrations/feed-imports/JOB_ID
Capability required: PRODUCT_CREATE or PRODUCT_UPDATE
Response fields:
| Field | Description |
|---|---|
status | Current job status (see below) |
totalRows | Total rows in your file |
acceptedRows | Rows that passed validation |
skippedRows | Blank or unsupported rows |
familyCount | Number of product families detected |
variantCount | Total variants |
validReadyRows | Rows with all required publish fields |
validStagedRows | Rows staged but missing publish fields |
needsEnrichmentRows | Rows missing required staging fields |
errorRows | Rows with validation errors |
previewSummary.families[] | First 50 families with coreSkus |
Job statuses:
| Status | Meaning |
|---|---|
QUEUED | Job created, not yet started |
UPLOADING | Awaiting S3 upload |
PARSING | Reading the file |
VALIDATING | Validating rows |
AUTO_PROCESSED | Everything committed cleanly — nothing needs your admin's attention |
READY_FOR_REVIEW | At least one row has an error or conflict that needs to be fixed and resent |
COMMITTING | Admin is committing families (portal-uploaded jobs only) |
COMPLETED | All families committed, and published if auto-publish is on |
PARTIAL | Some families committed/published, some skipped |
FAILED | Processing failed — check errorMessage |
AUTO_PROCESSED and READY_FOR_REVIEW are both terminal poll targets for API
connections — a valid batch resolves to AUTO_PROCESSED (or straight to COMPLETED/
PARTIAL if auto-publish is on), while READY_FOR_REVIEW only happens when something
in the batch actually needs to be fixed. Families that are staged but missing a price
or availability date are not an error — they still land on AUTO_PROCESSED and can be
completed later via the enrich endpoint.
Enrich a variant
POST CORE_BASE_URL/api/integrations/feed-imports/JOB_ID/enrich
Capability required: PRODUCT_UPDATE
Adds missing fields (price, availability) to a staged variant.
Request body:
| Field | Required | Description |
|---|---|---|
coreSku | Yes | Assigned variant SKU from previewSummary.families[].coreSkus |
fields | Yes | Object with fields to update |
Enrichable fields: price, availableFrom, availableTo, status, and other optional product fields.
Request example:
{
"coreSku": "KNC-000123456",
"fields": {
"price": "18.50",
"availableFrom": "2026-07-01",
"availableTo": "2026-09-30"
}
}
Response:
{
"updated": true,
"coreSku": "KNC-000123456"
}
Publish job to Shopify
POST CORE_BASE_URL/api/integrations/feed-imports/JOB_ID/publish
Capability required: PRODUCT_CREATE or PRODUCT_UPDATE
Publishes all committed variants from the job to Shopify. Variants missing required publish fields are skipped with a reason.
Request body: {} (empty)
Response:
{
"success": true,
"jobId": "JOB_ID",
"familiesPublished": 1,
"variantsPublished": 2,
"errors": [],
"results": [
{
"sourceSku": "ALST-ASST-001",
"success": true,
"shopifyProductGid": "gid://shopify/Product/...",
"variantsPublished": 2,
"errors": []
}
]
}
Calling publish again on the same job updates existing Shopify products — it does not create duplicates.
Validate a product payload
POST CORE_BASE_URL/api/integrations/validate/product
Capability required: PRODUCT_CREATE or PRODUCT_UPDATE
Validates a single product payload and returns the normalized result with warnings and errors. Does not save anything.
Request body: Any product fields.
Response:
{
"success": true,
"normalized": { "sku": "...", "productName": "...", ... },
"warnings": [],
"errors": []
}
Inventory
Submit on-hand inventory counts
POST CORE_BASE_URL/api/integrations/inventory
Capability required: INVENTORY_UPDATE
Submits a physical on-hand count snapshot. Kennicott Core calculates the delta and updates balances.
Request body:
| Field | Required | Description |
|---|---|---|
sourceRevision | Yes | Stable batch identifier from your system. Prevents duplicate processing on retry. |
sourceUpdatedAt | Yes | ISO 8601 timestamp of when the count was taken in your system. |
items | Yes | Array of inventory items. Maximum 500 per request. |
Item fields:
| Field | Required | Description |
|---|---|---|
sourceSku | Yes | Your product code. Must match an existing Kennicott Core product. |
onHandQuantity | Yes | Current physical count. Non-negative whole number. |
vendorVariantCode | Required when multiple variants exist | Format: {boxType}-{bunchesPerBox}. Example: EB-4, HB-18. |
Response:
{
"success": true,
"processed": 2,
"applied": 2,
"noChange": 0,
"rejected": 0,
"sourceRevision": "my-system-feed-20260701-001",
"results": [
{
"sourceSku": "ALST-ASST-001",
"vendorVariantCode": "EB-4",
"result": "APPLIED",
"coreSku": "KNC-000123456",
"onHandBefore": 60,
"onHandAfter": 80,
"deltaApplied": 20
}
]
}
Per-item result codes:
| Code | Meaning |
|---|---|
APPLIED | Count accepted and applied |
NO_CHANGE | Submitted count equals current on-hand |
REJECTED_STALE | sourceUpdatedAt is older than the last accepted count |
HELD_BY_OVERRIDE | Admin override active — count stored but not applied |
REJECTED_NOT_AUTHORITATIVE | Account not configured for API inventory |
UNKNOWN_VARIANT | sourceSku not found in your catalog |
AMBIGUOUS_VARIANT | sourceSku has multiple variants but vendorVariantCode was not provided |
Error responses
| HTTP Status | Meaning |
|---|---|
200 | Success |
201 | Created |
400 | Bad request — missing required field or invalid value |
401 | Missing or invalid API key |
403 | Valid key but connection lacks required capability, or connection is disabled |
404 | Job or resource not found |
500 | Internal error — contact Kennicott Core support |
Complete working scripts
Python
#!/usr/bin/env python3
"""
Kennicott Core Vendor API — minimal working example
Replace the three variables at the top. Requires Python 3.8+ and requests.
pip install requests
"""
import time, json, requests
CORE_BASE_URL = "https://YOUR_BASE_URL"
CORE_API_KEY = "YOUR_API_KEY"
headers = {"x-api-key": CORE_API_KEY, "Content-Type": "application/json"}
# 1. Test connection
r = requests.post(f"{CORE_BASE_URL}/api/integrations/test", headers=headers, json={})
r.raise_for_status()
print("Connected:", r.json()["connection"]["environment"])
# 2. Create upload job
r = requests.post(f"{CORE_BASE_URL}/api/integrations/feed-uploads", headers=headers,
json={"fileName": "catalog.json", "sourceFormat": "JSON_API"})
r.raise_for_status()
resp = r.json()
job_id, upload_url = resp["jobId"], resp["presignedUploadUrl"]
# 3. Upload catalog (no API key on S3 PUT)
catalog = [
{"sourceSku": "ALST-ASST-001", "productName": "Alstroemeria Assorted",
"boxType": "EB", "unitsPerBox": "4", "bunchesPerBox": "4",
"stemsPerBunch": "10", "sellUnit": "Bunch",
"price": "18.50", "availableFrom": "2026-07-01", "availableTo": "2026-09-30"},
{"sourceSku": "ALST-ASST-001", "productName": "Alstroemeria Assorted",
"boxType": "HB", "unitsPerBox": "18", "bunchesPerBox": "18",
"stemsPerBunch": "10", "sellUnit": "Bunch",
"price": "72.00", "availableFrom": "2026-07-01", "availableTo": "2026-09-30"},
]
requests.put(upload_url, headers={"Content-Type": "application/json"}, json=catalog).raise_for_status()
# 4. Start processing
requests.post(f"{CORE_BASE_URL}/api/integrations/feed-imports/{job_id}/start",
headers=headers, json={}).raise_for_status()
# 5. Poll until done (AUTO_PROCESSED = clean, READY_FOR_REVIEW = needs a fix,
# COMPLETED/PARTIAL = already published via auto-publish)
for _ in range(12):
time.sleep(5)
r = requests.get(f"{CORE_BASE_URL}/api/integrations/feed-imports/{job_id}", headers=headers)
status = r.json()
if status["status"] in ("AUTO_PROCESSED", "READY_FOR_REVIEW", "COMPLETED", "PARTIAL", "FAILED"):
print(f"{status['status']}: {status['familyCount']} families, {status['variantCount']} variants")
break
# 6. Publish (skip this if status is already COMPLETED/PARTIAL — that means
# auto-publish already ran for this vendor)
if status["status"] in ("AUTO_PROCESSED", "READY_FOR_REVIEW"):
r = requests.post(f"{CORE_BASE_URL}/api/integrations/feed-imports/{job_id}/publish",
headers=headers, json={})
result = r.json()
print(f"Published: {result['variantsPublished']} variants")
Shell (curl)
#!/bin/bash
CORE_BASE_URL="https://YOUR_BASE_URL"
CORE_API_KEY="YOUR_API_KEY"
# 1. Test
curl -sf -X POST "$CORE_BASE_URL/api/integrations/test" \
-H "x-api-key: $CORE_API_KEY" -H "Content-Type: application/json" -d '{}'
# 2. Create job
RESP=$(curl -sf -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=$(echo "$RESP" | python3 -c "import sys,json;print(json.load(sys.stdin)['jobId'])")
URL=$(echo "$RESP" | python3 -c "import sys,json;print(json.load(sys.stdin)['presignedUploadUrl'])")
# 3. Upload (no API key on S3 PUT)
curl -sf -X PUT "$URL" -H "Content-Type: application/json" -d '[
{"sourceSku":"ALST-ASST-001","productName":"Alstroemeria Assorted","boxType":"EB","sellUnit":"Bunch","unitsPerBox":"4","bunchesPerBox":"4","stemsPerBunch":"10","price":"18.50","availableFrom":"2026-07-01"},
{"sourceSku":"ALST-ASST-001","productName":"Alstroemeria Assorted","boxType":"HB","sellUnit":"Bunch","unitsPerBox":"18","bunchesPerBox":"18","stemsPerBunch":"10","price":"72.00","availableFrom":"2026-07-01"}
]'
# 4. Start
curl -sf -X POST "$CORE_BASE_URL/api/integrations/feed-imports/$JOB/start" \
-H "x-api-key: $CORE_API_KEY" -H "Content-Type: application/json" -d '{}'
# 5. Poll (run this command until status is AUTO_PROCESSED, READY_FOR_REVIEW,
# COMPLETED, PARTIAL, or FAILED)
curl -sf "$CORE_BASE_URL/api/integrations/feed-imports/$JOB" -H "x-api-key: $CORE_API_KEY"
# 6. Publish — only needed if status came back AUTO_PROCESSED or
# READY_FOR_REVIEW. If it's already COMPLETED/PARTIAL, auto-publish
# already ran for this vendor and there's nothing left to do.
curl -sf -X POST "$CORE_BASE_URL/api/integrations/feed-imports/$JOB/publish" \
-H "x-api-key: $CORE_API_KEY" -H "Content-Type: application/json" -d '{}'