Order

Overview

The Order capability provides standardized order lifecycle management. Businesses send webhook events as orders progress through fulfillment, enabling platforms and agents to track status in real-time.

Order Lifecycle

REST API Endpoints

Get Order

GET /orders/{order_id}
Authorization: Bearer {access_token}

Order Response

{
  "order_id": "ord_xyz789",
  "status": "shipped",
  "created_at": "2025-01-14T10:30:00Z",
  "updated_at": "2025-01-15T08:00:00Z",
  "items": [
    {
      "product_id": "SKU-001",
      "name": "Wireless Headphones",
      "quantity": 1,
      "unit_price": 149.99
    }
  ],
  "totals": {
    "subtotal": 149.99,
    "shipping": 9.99,
    "tax": 14.40,
    "total": 174.38
  },
  "shipping_address": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US"
  },
  "tracking": {
    "carrier": "USPS",
    "tracking_number": "9400111899223033005382",
    "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223033005382"
  }
}

List Orders

GET /orders
  ?status=shipped
  &limit=10
  &offset=0
Authorization: Bearer {access_token}

Webhook Events

Businesses send webhook events to registered endpoints as orders progress. All events include a signature for verification.

Event Format

POST https://platform.com/webhooks/ucp
Content-Type: application/json
X-UCP-Signature: sha256=abc123...
X-UCP-Timestamp: 1705312800

{
  "event_id": "evt_abc123",
  "type": "order.shipped",
  "created_at": "2025-01-15T08:00:00Z",
  "data": {
    "order_id": "ord_xyz789",
    "status": "shipped",
    "tracking": {
      "carrier": "USPS",
      "tracking_number": "9400111899223033005382"
    }
  }
}

Event Types

Webhook Signature Verification

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

Webhook Registration

POST /webhooks
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "url": "https://platform.com/webhooks/ucp",
  "events": ["order.created", "order.shipped", "order.delivered"],
  "secret": "whsec_xxx"
}

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

• 1st retry: 1 minute
• 2nd retry: 5 minutes
• 3rd retry: 30 minutes
• 4th retry: 2 hours
• 5th retry: 24 hours

After 5 failed attempts, the webhook is marked as failed and requires manual intervention.

Error Handling

{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order with ID ord_xyz789 was not found"
  }
}

Next Steps

• Learn about Fulfillment Extension for shipping options
• See Platform Integration for webhook implementation
• Explore REST Transport for complete API reference