Integration and API Spec

Integration and API Spec

Multichannel Inventory Sync

Acts as the single source of truth for on-hand stock quantities. The automation reads current inventory levels per SKU after every triggering event, and also listens for return confirmations and purchase order receipts originating inside Linnworks.

// Input (webhook payload excerpt)
{ "EventType": "ORDER_UPDATED", "OrderId": "LW-00421",
  "Items": [{ "SKU": "TSHIRT-BLK-M", "Quantity": 2 }] }

// Read call
GET /api/Stock/GetStockLevel
  Body: { "skuList": ["TSHIRT-BLK-M"] }

// Output (stock level response excerpt)
{ "SKU": "TSHIRT-BLK-M", "Available": 48, "Location": "Main Warehouse" }

Receives updated inventory quantities for each affected SKU after the sync calculation. The automation targets the Shopify Inventory API to set the on-hand quantity at the configured location.

// Inventory update call
POST /admin/api/2024-01/inventory_levels/set.json
Headers: { X-Shopify-Access-Token: <SHOPIFY_ACCESS_TOKEN> }
Body: {
  "location_id": "<SHOPIFY_LOCATION_ID>",
  "inventory_item_id": "<resolved_item_id>",
  "available": 46
}

// Success response
HTTP 200 { "inventory_level": { "available": 46 } }

Receives updated quantities via the Amazon Selling Partner API (SP-API) Listings Items API. The automation submits a quantity patch for each affected ASIN/SKU pair. Amazon-side visibility may lag 2 to 5 minutes after submission.

// Token refresh
POST https://api.amazon.com/auth/o2/token
Body: { grant_type: refresh_token, refresh_token: <AMAZON_REFRESH_TOKEN>,
        client_id: <AMAZON_LWA_CLIENT_ID>, client_secret: <AMAZON_LWA_CLIENT_SECRET> }

// Quantity patch
PATCH /listings/2021-08-01/items/<AMAZON_SELLER_ID>/<seller_sku>
  ?marketplaceIds=<AMAZON_MARKETPLACE_ID>
Body: { "productType": "PRODUCT", "patches": [
  { "op": "replace", "path": "/attributes/fulfillment_availability",
    "value": [{ "fulfillment_channel_code": "DEFAULT", "quantity": 46 }] }
] }

Serves two roles: audit log (append one row per sync event) and reference store (reorder thresholds per SKU and the SKU-to-platform-ID mapping table). Both roles use the Google Sheets API v4.

// Append audit row
POST https://sheets.googleapis.com/v4/spreadsheets/<GOOGLE_SPREADSHEET_ID>
     /values/Audit_Log!A:H:append?valueInputOption=USER_ENTERED
Body: { "values": [[
  "2024-06-17T09:14:02Z", "ORDER", "TSHIRT-BLK-M",
  48, 46, "Shopify", "Success", ""
]] }

// Read threshold for SKU
GET https://sheets.googleapis.com/v4/spreadsheets/<GOOGLE_SPREADSHEET_ID>
    /values/Reorder_Thresholds!A:C

Receives structured low-stock alert messages posted by the Reorder Alert and Finance Sync Agent when any SKU quantity falls at or below its configured reorder threshold.

// Post low-stock alert
POST https://slack.com/api/chat.postMessage
Headers: { Authorization: Bearer <SLACK_BOT_TOKEN> }
Body: {
  "channel": "<SLACK_BUYING_CHANNEL_ID>",
  "blocks": [
    { "type": "header", "text": { "type": "plain_text",
        "text": "Low Stock Alert" } },
    { "type": "section", "fields": [
        { "type": "mrkdwn", "text": "*SKU:* TSHIRT-BLK-M" },
        { "type": "mrkdwn", "text": "*Current Qty:* 4" },
        { "type": "mrkdwn", "text": "*Reorder Point:* 10" }
    ] }
  ]
}

Receives an inventory movement journal entry after each confirmed stock sync. The Reorder Alert and Finance Sync Agent posts a manual journal to Xero recording the change in inventory asset value.

// Token refresh
POST https://identity.xero.com/connect/token
Body: { grant_type: refresh_token, refresh_token: <XERO_REFRESH_TOKEN>,
        client_id: <XERO_CLIENT_ID>, client_secret: <XERO_CLIENT_SECRET> }

// Post manual journal
POST https://api.xero.com/api.xro/2.0/ManualJournals
Headers: { Authorization: Bearer <access_token>,
           Xero-tenant-id: <XERO_TENANT_ID> }
Body: {
  "Narration": "Inventory movement: TSHIRT-BLK-M | ORDER | 2024-06-17",
  "JournalLines": [
    { "LineAmount": -4.50, "AccountCode": "630", "Description": "Stock reduction" },
    { "LineAmount":  4.50, "AccountCode": "310", "Description": "COGS" }
  ]
}

// Credential store: complete key list
// (all values stored as encrypted secrets, never hardcoded)

// Linnworks
LINNWORKS_APP_ID
LINNWORKS_APP_SECRET
LINNWORKS_REFRESH_TOKEN
LINNWORKS_LOCATION_ID
LINNWORKS_WEBHOOK_SECRET

// Shopify
SHOPIFY_STORE_URL
SHOPIFY_ACCESS_TOKEN
SHOPIFY_LOCATION_ID
SHOPIFY_WEBHOOK_SECRET

// Amazon Seller Central (SP-API)
AMAZON_LWA_CLIENT_ID
AMAZON_LWA_CLIENT_SECRET
AMAZON_REFRESH_TOKEN
AMAZON_SELLER_ID
AMAZON_MARKETPLACE_ID
AMAZON_ROLE_ARN
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AMAZON_LAST_POLL_TS

// Google Sheets
GOOGLE_SERVICE_ACCOUNT_JSON
GOOGLE_SPREADSHEET_ID
GOOGLE_AUDIT_SHEET_NAME
GOOGLE_THRESHOLD_SHEET_NAME
GOOGLE_SKU_MAP_SHEET_NAME

// Slack
SLACK_BOT_TOKEN
SLACK_BUYING_CHANNEL_ID

// Xero
XERO_CLIENT_ID
XERO_CLIENT_SECRET
XERO_REFRESH_TOKEN
XERO_TENANT_ID
XERO_INVENTORY_ASSET_ACCOUNT_CODE
XERO_COGS_ACCOUNT_CODE