Skip to main content

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:

FieldRequiredDescription
fileNameYesFilename for reference
sourceFormatNo (default: CSV)CSV or JSON_API
profileIdNoSpecific 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:

FieldDescription
statusCurrent job status (see below)
totalRowsTotal rows in your file
acceptedRowsRows that passed validation
skippedRowsBlank or unsupported rows
familyCountNumber of product families detected
variantCountTotal variants
validReadyRowsRows with all required publish fields
validStagedRowsRows staged but missing publish fields
needsEnrichmentRowsRows missing required staging fields
errorRowsRows with validation errors
previewSummary.families[]First 50 families with coreSkus

Job statuses:

StatusMeaning
QUEUEDJob created, not yet started
UPLOADINGAwaiting S3 upload
PARSINGReading the file
VALIDATINGValidating rows
AUTO_PROCESSEDEverything committed cleanly — nothing needs your admin's attention
READY_FOR_REVIEWAt least one row has an error or conflict that needs to be fixed and resent
COMMITTINGAdmin is committing families (portal-uploaded jobs only)
COMPLETEDAll families committed, and published if auto-publish is on
PARTIALSome families committed/published, some skipped
FAILEDProcessing 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:

FieldRequiredDescription
coreSkuYesAssigned variant SKU from previewSummary.families[].coreSkus
fieldsYesObject 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:

FieldRequiredDescription
sourceRevisionYesStable batch identifier from your system. Prevents duplicate processing on retry.
sourceUpdatedAtYesISO 8601 timestamp of when the count was taken in your system.
itemsYesArray of inventory items. Maximum 500 per request.

Item fields:

FieldRequiredDescription
sourceSkuYesYour product code. Must match an existing Kennicott Core product.
onHandQuantityYesCurrent physical count. Non-negative whole number.
vendorVariantCodeRequired when multiple variants existFormat: {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:

CodeMeaning
APPLIEDCount accepted and applied
NO_CHANGESubmitted count equals current on-hand
REJECTED_STALEsourceUpdatedAt is older than the last accepted count
HELD_BY_OVERRIDEAdmin override active — count stored but not applied
REJECTED_NOT_AUTHORITATIVEAccount not configured for API inventory
UNKNOWN_VARIANTsourceSku not found in your catalog
AMBIGUOUS_VARIANTsourceSku has multiple variants but vendorVariantCode was not provided

Error responses​

HTTP StatusMeaning
200Success
201Created
400Bad request — missing required field or invalid value
401Missing or invalid API key
403Valid key but connection lacks required capability, or connection is disabled
404Job or resource not found
500Internal 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 '{}'

Next step​

→ Import Results and Fixing Errors → Support