Developer Handover Pack

Developer Handover Pack

Multichannel Inventory Sync

Watches all connected sales channels and the warehouse system for any stock-changing event, including new orders on Shopify and Amazon Seller Central, confirmed returns processed through Linnworks, and purchase order receipts marked as received. On each event, the agent queries Linnworks for the current on-hand quantity of every affected SKU, applies the order delta, return credit, or inbound receipt, and produces a validated new quantity per SKU. If any calculated quantity falls below zero, the agent halts the update for that SKU and raises an anomaly flag for human review instead. Valid quantities are pushed simultaneously to the Shopify Inventory API and the Amazon Listings API. A timestamped audit row is then appended to the master Google Sheet covering SKU, event type, previous quantity, and new quantity. This agent replaces all eight manual steps that previously consumed up to 160 minutes per cycle and was the primary source of stock drift, oversells, and delayed returns restocking. Estimated build time: 28 hours. Complexity: Complex.

// Input
event_type: 'order' | 'return' | 'po_receipt'
source_channel: 'shopify' | 'amazon' | 'linnworks'
sku_id: string
quantity_delta: integer  // negative for orders, positive for returns and receipts
order_id: string         // reference for audit log
linnworks_stock_on_hand: integer  // pulled from Linnworks API after trigger

// Calculation
new_quantity = linnworks_stock_on_hand + quantity_delta
if new_quantity < 0: raise anomaly_flag, halt channel updates for this SKU

// Output (valid quantity only)
shopify_inventory_update: { inventory_item_id, location_id, available: new_quantity }
amazon_listings_update: { seller_sku, quantity: new_quantity, fulfillment_latency: 1 }
google_sheets_row: { timestamp, sku_id, event_type, source_channel, prev_quantity, new_quantity, order_id }

// On anomaly
anomaly_record: { sku_id, calculated_quantity: new_quantity, trigger_event: event_type, flagged_at: timestamp }
human_review_required: true

Triggers immediately after the Stock Level Sync Agent completes a quantity update for one or more SKUs. The agent reads the new quantity for each updated SKU from the Google Sheets audit log and compares it against the reorder threshold defined for that SKU in a reference tab of the same sheet. If the new quantity is at or below the threshold, it composes a structured Slack alert and posts it to the buying team channel, including SKU name, current quantity, and reorder point. Regardless of whether a threshold is breached, the agent posts a stock movement journal entry to Xero for every qualifying stock-change event, keeping the finance record current without end-of-week manual reconciliation. This agent replaces steps 9, 10, and 11, eliminating 55 minutes of manual work per cycle and the finance reconciliation delay. Estimated build time: 18 hours. Complexity: Moderate.

// Input (from Sync Agent completion or Google Sheets read)
sku_id: string
new_quantity: integer
event_type: 'order' | 'return' | 'po_receipt'
quantity_delta: integer
timestamp: ISO8601 string
reorder_threshold: integer  // read from Sheets reference tab by sku_id lookup
unit_cost: number           // read from Sheets reference tab for Xero journal value

// Decision
if new_quantity <= reorder_threshold: fire Slack alert

// Output: Slack alert (conditional)
slack_message: {
  channel: '#buying-team',
  text: 'Low stock alert: [SKU name] is at [new_quantity] units (reorder point: [reorder_threshold]). Please raise a PO.'
}

// Output: Xero journal entry (always)
xero_manual_journal: {
  narration: 'Inventory movement: [sku_id] | [event_type] | [timestamp]',
  journal_lines: [
    { account_code: '630', description: 'Inventory asset adjustment', line_amount: quantity_delta * unit_cost },
    { account_code: '310', description: 'COGS offset', line_amount: -(quantity_delta * unit_cost) }
  ]
}

// ─── TRIGGER ───────────────────────────────────────────────────────────────
// Source: Shopify order webhook, Amazon SP-API order feed, or Linnworks event
//
incoming_event {
  event_type:      'order' | 'return' | 'po_receipt'
  source_channel:  'shopify' | 'amazon' | 'linnworks'
  sku_id:          string          // e.g. 'SKU-00142'
  quantity_delta:  integer         // e.g. -2 for a 2-unit order, +1 for a return
  order_id:        string          // Shopify order ID, Amazon order ID, or LW PO ref
  event_timestamp: ISO8601 string
}

// ─── STOCK LEVEL SYNC AGENT: Step 1 — Pull current stock from Linnworks ──
// GET /api/v1/stock/items?sku={sku_id}
linnworks_response {
  sku_id:               string
  stock_item_id:        string    // Linnworks internal GUID
  stock_on_hand:        integer   // e.g. 47
  location_id:          string    // warehouse location GUID
  bin_rack:             string
}

// ─── STOCK LEVEL SYNC AGENT: Step 2 — Calculate new quantity ────────────
new_quantity = linnworks_response.stock_on_hand + incoming_event.quantity_delta
// e.g. 47 + (-2) = 45

// ─── DECISION: Quantity valid? ───────────────────────────────────────────
if new_quantity < 0:
  anomaly_record {
    sku_id:               incoming_event.sku_id
    calculated_quantity:  new_quantity
    trigger_event:        incoming_event.event_type
    source_channel:       incoming_event.source_channel
    order_id:             incoming_event.order_id
    flagged_at:           ISO8601 timestamp
  }
  // Post anomaly alert to Slack #fulfilment-alerts
  // Halt all channel updates for this SKU — do NOT continue
  STOP

// ─── STOCK LEVEL SYNC AGENT: Step 3 — Update Shopify ───────────────────
// POST /admin/api/2024-01/inventory_levels/set.json
shopify_request {
  inventory_item_id: string    // from Shopify product variant lookup by sku_id
  location_id:       string    // Shopify fulfilment location ID
  available:         new_quantity
}
shopify_response {
  inventory_level.available: integer  // confirmed new quantity
  updated_at:                ISO8601 string
}

// ─── STOCK LEVEL SYNC AGENT: Step 4 — Update Amazon Seller Central ──────
// PUT /listings/2021-08-01/items/{sellerId}/{sku_id}
amazon_request {
  seller_sku:           incoming_event.sku_id
  quantity:             new_quantity
  fulfillment_latency:  1   // days
}
amazon_response {
  status:               'ACCEPTED' | 'INVALID'
  submission_id:        string
}
// Note: Amazon listing visibility lags 2-5 min after ACCEPTED status

// ─── STOCK LEVEL SYNC AGENT: Step 5 — Write audit row to Google Sheets ──
// POST spreadsheets/{sheet_id}/values/{range}:append
sheets_row {
  timestamp:      ISO8601 string
  sku_id:         string
  event_type:     incoming_event.event_type
  source_channel: incoming_event.source_channel
  prev_quantity:  linnworks_response.stock_on_hand
  new_quantity:   new_quantity
  order_id:       incoming_event.order_id
  shopify_status: 'updated' | 'skipped'
  amazon_status:  amazon_response.status
}

// ─── AGENT HANDOFF: Stock Level Sync Agent -> Reorder Alert and Finance Sync Agent
//     Handoff payload is the completed sheets_row plus reorder_threshold lookup

// ─── REORDER ALERT AND FINANCE SYNC AGENT: Step 6 — Read threshold ──────
// GET spreadsheets/{sheet_id}/values/thresholds!A:D
threshold_lookup {
  sku_id:           string
  reorder_threshold: integer   // e.g. 10
  unit_cost:         number    // e.g. 8.50
  sku_name:          string    // human-readable label for Slack message
}

// ─── REORDER ALERT AND FINANCE SYNC AGENT: Step 7 — Conditional Slack alert
if new_quantity <= threshold_lookup.reorder_threshold:
  // POST https://slack.com/api/chat.postMessage
  slack_payload {
    channel: env.BUYING_TEAM_CHANNEL_ID
    text:    'Low stock: {sku_name} | Current: {new_quantity} units | Reorder point: {reorder_threshold} | Ref: {order_id}'
    blocks:  [ rich_text_block with SKU detail and Sheet deep-link ]
  }

// ─── REORDER ALERT AND FINANCE SYNC AGENT: Step 8 — Post to Xero ────────
// POST https://api.xero.com/api.xro/2.0/ManualJournals
xero_payload {
  narration: 'Inventory movement: {sku_id} | {event_type} | {ISO8601 timestamp}'
  journal_lines: [
    {
      account_code:  '630',           // Inventory Asset
      description:   'Stock adjustment: {sku_id}',
      line_amount:   quantity_delta * threshold_lookup.unit_cost
    },
    {
      account_code:  '310',           // COGS
      description:   'COGS offset: {sku_id}',
      line_amount:   -(quantity_delta * threshold_lookup.unit_cost)
    }
  ]
}
xero_response {
  manual_journal_id: UUID
  status:            'DRAFT' | 'POSTED'
}

// ─── END OF FLOW ─────────────────────────────────────────────────────────
// All updates complete. Audit row in Google Sheets serves as the single
// reconciliation record linking event_type, channel, quantity, and Xero ref.