Integration and API Spec

Integration and API Spec

Shipping and Tracking Notification

Primary trigger source. The automation detects order status changes to 'Shipped' with a non-null tracking number, either via webhook push or polling fallback. All tracking data originates here.

// Webhook payload (abbreviated)
{
  "resource_url": "https://ssapi.shipstation.com/shipments?shipmentId=98765432",
  "resource_type": "SHIP_NOTIFY"
}
// Follow-up GET /shipments/{shipmentId} response fields used:
shipmentId          -> internal reference
orderNumber         -> maps to Shopify order_name
trackingNumber      -> carrier tracking number
carrierCode         -> used to build tracking URL
shipDate            -> ISO 8601 date string
// Output passed to Agent 1 internal state:
{ shipmentId, orderNumber, trackingNumber, carrierCode, shipDate }

Used by Agent 1 to fetch the full customer and order record corresponding to the ShipStation order number. Provides customer email, name, and order details for downstream use.

// GET /admin/api/2024-01/orders.json?name={orderNumber}&status=any
// Fields extracted from response orders[0]:
orders[0].name             -> order_number (display)
orders[0].email            -> customer_email
orders[0].shipping_address.first_name -> customer_first_name
orders[0].shipping_address.last_name  -> customer_last_name
orders[0].id               -> shopify_order_id (internal)
// Output assembled by Agent 1:
{
  order_number:       "#1042",
  customer_email:     "jane@example.com",
  customer_first_name: "Jane",
  tracking_number:    "1Z999AA10123456784",
  carrier_code:       "ups",
  tracking_url:       "https://www.ups.com/track?tracknum=1Z999AA10123456784",
  ship_date:          "2024-05-01"
}

Receives the assembled shipment data object from Agent 2 and triggers a pre-built transactional flow. Klaviyo owns the email template design and suppression list management. The automation only calls the event track endpoint.

// POST https://a.klaviyo.com/api/events/
// Headers: Authorization: Klaviyo-API-Key {KLAVIYO_PRIVATE_API_KEY}
//          revision: 2024-02-15
{
  "data": {
    "type": "event",
    "attributes": {
      "metric": { "data": { "type": "metric", "attributes": { "name": "Shipment Tracked" } } },
      "profile": { "data": { "type": "profile", "attributes": { "email": "{customer_email}" } } },
      "properties": {
        "first_name":    "{customer_first_name}",
        "order_number":  "{order_number}",
        "tracking_url":  "{tracking_url}",
        "carrier_name":  "{carrier_name}",
        "ship_date":     "{ship_date}"
      },
      "time": "{iso8601_timestamp}"
    }
  }
}
// Success response: HTTP 202 Accepted
// Failure responses: 400 (bad payload), 429 (rate limited), 5xx (Klaviyo error)

Receives a log record from Agent 2 after each successful or failed notification attempt. Appends one row per shipment event to the fulfilment tracker sheet.

// POST .../values/{SHEETS_TAB_NAME}!A:J:append
// Body (values array, one row):
[
  "{iso8601_timestamp}",
  "{order_number}",
  "{customer_email}",
  "{carrier_name}",
  "{tracking_number}",
  "{tracking_url}",
  "{klaviyo_status}",   // 'sent', 'failed', 'suppressed'
  "{ship_date}",
  "{agent_run_id}",
  "{notes}"            // empty string unless error note applies
]
// Success: HTTP 200 with updatedRange in response body

Receives a daily digest summary from Agent 2 and posts it to the designated fulfilment channel. This is a non-blocking fire-and-forget action; failure here must not halt the core notification workflow.

// POST https://slack.com/api/chat.postMessage
// Headers: Authorization: Bearer {SLACK_BOT_TOKEN}
{
  "channel": "{SLACK_CHANNEL_ID}",
  "blocks": [
    { "type": "header", "text": { "type": "plain_text", "text": "Dispatch Summary" } },
    { "type": "section", "fields": [
      { "type": "mrkdwn", "text": "*Sent:* {sent_count}" },
      { "type": "mrkdwn", "text": "*Failed:* {failed_count}" },
      { "type": "mrkdwn", "text": "*Manual review:* {review_count}" },
      { "type": "mrkdwn", "text": "*Log:* <{sheets_url}|View Google Sheets>" }
    ]}
  ]
}
// Success: HTTP 200, ok: true in response body

// Credential store contents (all values encrypted at rest)

// ShipStation
SHIPSTATION_API_KEY           = "<ShipStation API key>"
SHIPSTATION_API_SECRET        = "<ShipStation API secret>"
SHIPSTATION_WEBHOOK_SECRET    = "<HMAC signing secret from ShipStation webhook settings>"
SHIPSTATION_WEBHOOK_ID        = "<registered webhook ID>"

// Shopify
SHOPIFY_ACCESS_TOKEN          = "<Admin API access token>"
SHOPIFY_STORE_DOMAIN          = "yourcompany.myshopify.com"
SHOPIFY_ORDER_PREFIX          = "#"   // update if custom prefix in use

// Klaviyo
KLAVIYO_PRIVATE_API_KEY       = "<Klaviyo private API key>"
KLAVIYO_FLOW_ID               = "<Klaviyo flow ID for Shipment Tracked trigger>"
KLAVIYO_LIST_ID               = "<seed list ID for integration testing>"

// Google Sheets
GOOGLE_SERVICE_ACCOUNT_JSON   = "<full JSON key file contents>"
SHEETS_SPREADSHEET_ID         = "<Google Sheets document ID from URL>"
SHEETS_TAB_NAME               = "Notification Log"

// Slack
SLACK_BOT_TOKEN               = "xoxb-<bot token>"
SLACK_CHANNEL_ID              = "<target channel ID, not channel name>"
SLACK_WEBHOOK_URL             = "<optional: Incoming Webhook URL>"

// Carrier tracking URL map (JSON object)
CARRIER_TRACKING_URL_MAP      = {
  "ups":         "https://www.ups.com/track?tracknum={tracking_number}",
  "usps":        "https://tools.usps.com/go/TrackConfirmAction?tLabels={tracking_number}",
  "fedex":       "https://www.fedex.com/fedextrack/?trknbr={tracking_number}",
  "dhl_express": "https://www.dhl.com/en/express/tracking.html?AWB={tracking_number}&brand=DHL"
}

// Carrier display name map (JSON object)
CARRIER_NAME_MAP              = {
  "ups":         "UPS",
  "usps":        "USPS",
  "fedex":       "FedEx",
  "dhl_express": "DHL Express"
}