Developer Handover Pack

Developer Handover Pack

Order Processing & Fulfilment

Monitors Shopify for new paid orders via webhook, extracts all line items and their SKUs, and queries Cin7 for current on-hand stock against each SKU. If all SKUs have sufficient stock, the validated order record is passed to the Fulfilment Dispatch Agent. If any SKU is short, the agent sends a Slack alert to the fulfilment channel with the order number, the affected SKU, and the stock shortfall quantity, then halts the order in a held state pending manual review. This agent must handle multi-line orders atomically: a single short SKU holds the entire order, not just that line. Estimated build time: 14 hours. Complexity: Moderate.

// Input
shopify.order {
  order_id: string,
  order_number: string,
  customer.email: string,
  customer.first_name: string,
  customer.last_name: string,
  shipping_address: { address1, address2, city, province, zip, country },
  line_items: [{ sku: string, quantity: integer, price: decimal, title: string }],
  total_price: decimal,
  currency: string
}

// Stock check (per SKU)
cin7.stock_query -> GET /api/v2/inventory?sku={sku}
cin7.stock_response {
  sku: string,
  on_hand_quantity: integer,
  location_id: string
}

// Output (stock confirmed)
validated_order {
  order_id: string,
  order_number: string,
  customer: { email, first_name, last_name },
  shipping_address: { address1, address2, city, province, zip, country },
  line_items: [{ sku, quantity, price, title }],
  total_price: decimal,
  currency: string,
  stock_status: 'confirmed'
}

// Output (stock short - Slack alert payload)
slack.message {
  channel: '#fulfilment-alerts',
  text: 'STOCK HOLD: Order {order_number} held. SKU {sku} has {on_hand_quantity} on hand, {quantity} required.',
  order_id: string,
  held_at: ISO8601 timestamp
}

Receives the validated order record from the Order Intake Agent and executes the full dispatch chain without human input. It creates a draft sales invoice in Xero mapped from Shopify line items, pushes the order to StarShipIt to book the appropriate courier and retrieve the shipping label and tracking number, updates Shopify with the fulfilment status and tracking number, sends a personalised shipping confirmation email to the customer via Gmail using a pre-approved template, and posts a dispatch summary to the Slack fulfilment channel. Each step must complete successfully before the next begins. Any step failure triggers an error log entry and a Slack alert to the fulfilment channel with the step name and error message. Estimated build time: 22 hours. Complexity: Moderate.

// Input
validated_order {
  order_id: string,
  order_number: string,
  customer: { email, first_name, last_name },
  shipping_address: { address1, address2, city, province, zip, country },
  line_items: [{ sku, quantity, price, title }],
  total_price: decimal,
  currency: string,
  stock_status: 'confirmed'
}

// Step 1: Xero invoice creation
xero.invoice_payload {
  Type: 'ACCREC',
  Contact: { EmailAddress: customer.email, Name: '{first_name} {last_name}' },
  LineItems: [{ Description: title, Quantity: quantity, UnitAmount: price, AccountCode: '200' }],
  CurrencyCode: currency,
  Reference: order_number
}
xero.invoice_response -> invoice_id: string

// Step 2: StarShipIt courier booking
starshipit.order_payload {
  reference: order_number,
  destination: { address: address1, suburb: city, state: province, post_code: zip, country: country },
  packages: [{ weight_kg: derived_from_sku_lookup }]
}
starshipit.booking_response {
  tracking_number: string,
  carrier_name: string,
  label_url: string
}

// Step 3: Shopify fulfilment update
shopify.fulfilment_payload {
  order_id: order_id,
  tracking_number: tracking_number,
  tracking_company: carrier_name,
  notify_customer: false
}

// Step 4: Gmail confirmation email
gmail.send_payload {
  to: customer.email,
  subject: 'Your order {order_number} has shipped!',
  body_template: 'shipping_confirmation_v1',
  template_vars: { first_name, order_number, tracking_number, carrier_name }
}

// Output: Slack dispatch notification
slack.message {
  channel: '#fulfilment-dispatched',
  text: 'DISPATCHED: Order {order_number} | {first_name} {last_name} | Courier: {carrier_name} | Tracking: {tracking_number}',
  xero_invoice_id: invoice_id
}

// ============================================================
// ORDER PROCESSING & FULFILMENT - END-TO-END DATA FLOW
// ============================================================

// TRIGGER
// Shopify fires order.paid webhook on new paid order
SHOPIFY.WEBHOOK -> order.paid {
  order_id,
  order_number,
  customer.email,
  customer.first_name,
  customer.last_name,
  shipping_address.address1,
  shipping_address.address2,
  shipping_address.city,
  shipping_address.province,
  shipping_address.zip,
  shipping_address.country,
  line_items[].sku,
  line_items[].quantity,
  line_items[].price,
  line_items[].title,
  total_price,
  currency
}

// ============================================================
// AGENT HANDOFF 1: Shopify -> Order Intake Agent
// ============================================================

// ORDER INTAKE AGENT: Dedupe check
CHECK supabase.held_orders WHERE order_id = order_id
CHECK active_pipeline WHERE order_id = order_id
  -> IF FOUND: skip (duplicate webhook)
  -> IF NOT FOUND: proceed

// ORDER INTAKE AGENT: Stock check loop (per SKU)
FOR EACH line_item IN order.line_items:
  CIN7.GET /api/v2/inventory?sku={line_item.sku} -> {
    sku,
    on_hand_quantity,
    location_id
  }
  IF on_hand_quantity < line_item.quantity:
    short_skus.APPEND { sku, on_hand_quantity, required: line_item.quantity }

// ORDER INTAKE AGENT: Route decision
IF short_skus.length > 0:
  // Stock short path
  SLACK.POST #fulfilment-alerts {
    text: 'STOCK HOLD: Order {order_number} | Short SKUs: {short_skus}',
    held_at: ISO8601_timestamp
  }
  SUPABASE.INSERT held_orders { order_id, order_number, short_skus, held_at }
  STOP // human review required

ELSE:
  // Stock confirmed path - build validated_order payload
  validated_order = {
    order_id, order_number,
    customer: { email, first_name, last_name },
    shipping_address: { address1, address2, city, province, zip, country },
    line_items: [{ sku, quantity, price, title, weight_kg }],
    total_price, currency,
    stock_status: 'confirmed'
  }

// ============================================================
// AGENT HANDOFF 2: Order Intake Agent -> Fulfilment Dispatch Agent
// ============================================================

// FULFILMENT DISPATCH AGENT: Step 1 - Xero invoice
XERO.POST /api.xro/2.0/Invoices {
  Type: 'ACCREC',
  Contact.EmailAddress: customer.email,
  Contact.Name: '{first_name} {last_name}',
  LineItems[].Description: line_item.title,
  LineItems[].Quantity: line_item.quantity,
  LineItems[].UnitAmount: line_item.price,
  LineItems[].AccountCode: '200',
  CurrencyCode: currency,
  Reference: order_number
} -> { invoice_id }

// FULFILMENT DISPATCH AGENT: Step 2 - StarShipIt booking
STARSHIPIT.POST /orders {
  reference: order_number,
  destination.address: shipping_address.address1,
  destination.suburb: shipping_address.city,
  destination.state: shipping_address.province,
  destination.post_code: shipping_address.zip,
  destination.country: shipping_address.country,
  packages[].weight_kg: line_item.weight_kg (or default fallback)
} -> {
  tracking_number,
  carrier_name,
  label_url
}

// FULFILMENT DISPATCH AGENT: Step 3 - Shopify fulfilment update
SHOPIFY.POST /orders/{order_id}/fulfillments {
  tracking_number: tracking_number,
  tracking_company: carrier_name,
  notify_customer: false
}

// FULFILMENT DISPATCH AGENT: Step 4 - Gmail customer email
GMAIL.SEND {
  to: customer.email,
  subject: 'Your order {order_number} has shipped!',
  template: 'shipping_confirmation_v1',
  vars: { first_name, order_number, tracking_number, carrier_name }
}

// FULFILMENT DISPATCH AGENT: Step 5 - Slack dispatch notification
SLACK.POST #fulfilment-dispatched {
  text: 'DISPATCHED: Order {order_number} | {first_name} {last_name} | {carrier_name} | {tracking_number}',
  xero_invoice_id: invoice_id
}

// ============================================================
// ERROR PATH (any step in dispatch chain)
// ============================================================
ON FAILURE AT step {step_name}:
  SUPABASE.INSERT dispatch_errors {
    order_id, order_number, failed_step: step_name,
    error_message: error.message,
    timestamp: ISO8601_timestamp
  }
  SLACK.POST #fulfilment-alerts {
    text: 'ERROR: Order {order_number} failed at {step_name}. Details logged.',
    timestamp: ISO8601_timestamp
  }
  STOP // do not proceed to subsequent steps