Integration and API Spec

Integration and API Spec

Order Processing and Fulfilment

Acts as the automation trigger (incoming paid order webhook) and as a write target for fulfilment status and tracking number. Used by Agent 1 for order ingestion and Agent 2 for marking the order fulfilled.

// Inbound webhook payload (key fields consumed)
order.id                  -> internal order_id
order.order_number        -> human-readable reference
order.line_items[]        -> sku, quantity, title, price
order.shipping_address    -> name, address1, address2, city, zip, country_code, phone
order.customer.email      -> recipient address for Gmail step
order.customer.first_name -> personalisation token in email template
order.total_price         -> invoice total passed to Xero
// Write back (Agent 2)
POST /orders/{order_id}/fulfillments -> fulfillment.tracking_number, fulfillment.tracking_url, fulfillment.tracking_company

Queried by Agent 1 to confirm on-hand stock for each SKU in the incoming order. Cin7 does not require a write operation in this automation; stock deduction occurs automatically via Cin7's own Shopify integration or is handled by the existing Cin7 workflow. If no native sync exists, a manual deduction step remains with the coordinator.

// GET /api/v1/stock?where=SKU='{sku}'&fields=onHand,available
// Response fields consumed
product.sku               -> matched against order line_items[].sku
product.available         -> compared against line_items[].quantity
// Output to orchestration layer
stock_check_result        -> 'pass' if all SKUs sufficient, 'fail' with shortfall_detail[] if not

Agent 2 creates a sales invoice in Xero immediately after Agent 1 confirms stock availability. Line items, totals, and customer data are mapped from the Shopify order payload. No manual re-entry is required.

// POST /api.xro/2.0/Invoices
// Request fields mapped from Shopify payload
Contact.EmailAddress      <- order.customer.email
Contact.Name              <- order.shipping_address.name
LineItems[].Description   <- line_items[].title
LineItems[].Quantity      <- line_items[].quantity
LineItems[].UnitAmount    <- line_items[].price
LineItems[].AccountCode   <- XERO_SALES_ACCOUNT_CODE
LineItems[].TaxType       <- XERO_TAX_TYPE
Reference                 <- order.order_number
// Response fields stored
invoice.InvoiceID         -> logged to run record for audit

Agent 2 pushes the validated order to StarShipIt to book the appropriate courier service, generate the shipping label, and retrieve the tracking number. Courier selection is rule-based within StarShipIt and must be configured before go-live.

// POST /api/orders
// Request fields mapped from Shopify payload
order.order_date          <- order webhook received_at timestamp
order.reference           <- order.order_number
order.destination.name    <- order.shipping_address.name
order.destination.address <- order.shipping_address.address1 + address2
order.destination.suburb  <- order.shipping_address.city
order.destination.postcode<- order.shipping_address.zip
order.destination.country <- order.shipping_address.country_code
order.destination.phone   <- order.shipping_address.phone
order.products[].sku      <- line_items[].sku
order.products[].qty      <- line_items[].quantity
// GET /api/orders/{order_id}/labels -> label binary (PDF or ZPL)
// GET /api/orders/{order_id}        -> shipment.tracking_number, shipment.carrier_name
tracking_number           -> passed to Shopify fulfillment and Gmail template
carrier_name              -> passed to Gmail template

Agent 2 sends a personalised shipping confirmation email to the customer after the tracking number has been retrieved from StarShipIt. A pre-approved template is used; no freeform composition occurs at runtime.

// POST https://gmail.googleapis.com/gmail/v1/users/me/messages/send
// MIME message constructed at runtime
To                        <- order.customer.email
From                      <- GMAIL_SENDER_ADDRESS
Subject                   <- 'Your order {{order_number}} has shipped'
Body (HTML)               <- GMAIL_TEMPLATE_ID rendered with:
  {{customer_first_name}} <- order.customer.first_name
  {{order_number}}        <- order.order_number
  {{tracking_number}}     <- starshipit.tracking_number
  {{carrier_name}}        <- starshipit.carrier_name
  {{tracking_url}}        <- starshipit.tracking_url

Used by Agent 1 to send a stock-shortfall alert to the fulfilment team when one or more SKUs cannot be fulfilled. Used by Agent 2 to post a dispatch confirmation after the order is fully processed. Both messages use a Slack Bot Token.

// Agent 1: Stock shortfall alert
POST https://slack.com/api/chat.postMessage
channel                   <- SLACK_ALERT_CHANNEL_ID
text                      <- ':warning: Stock shortfall on order {{order_number}}'
blocks[].shortfall_detail <- sku, ordered_qty, available_qty for each failing SKU

// Agent 2: Dispatch confirmation
POST https://slack.com/api/chat.postMessage
channel                   <- SLACK_DISPATCH_CHANNEL_ID
text                      <- ':white_check_mark: Dispatched: Order {{order_number}} | {{customer_name}} | {{carrier_name}} | {{tracking_number}}'

// Credential store: Order Processing and Fulfilment automation
// All values are environment references. No plaintext secrets in workflow code.

SHOPIFY_STORE_DOMAIN          // e.g. yourstore.myshopify.com
SHOPIFY_ACCESS_TOKEN          // Private App or Custom App OAuth token
SHOPIFY_WEBHOOK_SECRET        // Shared secret for HMAC-SHA256 validation
SHOPIFY_LOCATION_ID           // Fulfilment location ID (resolved at build time)

CIN7_ACCOUNT_ID               // Cin7 account identifier for Basic Auth
CIN7_API_KEY                  // Cin7 API key for Basic Auth
CIN7_BRANCH_ID                // Target branch/warehouse ID for stock lookup

XERO_CLIENT_ID                // OAuth 2.0 application client ID
XERO_CLIENT_SECRET            // OAuth 2.0 application client secret
XERO_REFRESH_TOKEN            // Long-lived refresh token; auto-rotated on use
XERO_TENANT_ID                // Xero organisation (tenant) ID
XERO_SALES_ACCOUNT_CODE       // Chart of accounts code for sales revenue (e.g. 200)
XERO_TAX_TYPE                 // Tax type string (e.g. OUTPUT, NONE)

STARSHIPIT_API_KEY            // StarShipIt API subscription key (header-based)
STARSHIPIT_DEFAULT_CARRIER    // Fallback carrier code if rules do not match

GMAIL_REFRESH_TOKEN           // Google OAuth 2.0 refresh token for sending account
GMAIL_SENDER_ADDRESS          // Verified sending email address
GMAIL_TEMPLATE_ID             // Internal reference to the parameterised HTML template

SLACK_BOT_TOKEN               // Slack App Bot Token (xoxb-...)
SLACK_ALERT_CHANNEL_ID        // Channel ID for stock shortfall and error alerts
SLACK_DISPATCH_CHANNEL_ID     // Channel ID for dispatch confirmations and run summaries