Track Fulfillments

Fulfillments represent the shipping and delivery information for orders.

Full API Reference

Response examples are simplified. See the complete endpoint documentation for the full response schema.

Get Fulfillments by Order

Use the dedicated endpoint to get all fulfillments for a specific order:

TypeScript

const response = await fetch(
  `https://na1-prod.okcapsule.app/v2/orders/${orderId}/fulfillments`,
  {
    headers: { Authorization: `Bearer ${access_token}` },
  }
);

const { fulfillments } = await response.json();

cURL

curl -X GET "https://na1-prod.okcapsule.app/v2/orders/{orderId}/fulfillments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Fulfillment Details

TypeScript

const response = await fetch(
  `https://na1-prod.okcapsule.app/v2/fulfillments/${fulfillmentId}`,
  {
    headers: { Authorization: `Bearer ${access_token}` },
  }
);

const { fulfillment } = await response.json();

cURL

curl -X GET https://na1-prod.okcapsule.app/v2/fulfillments/{fulfillmentId} \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "fulfillment": {
    "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "order_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "consumer_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "status_id": "shipped-status-uuid",
    "delivery_date": "2024-01-20T14:30:00Z",
    "pickup_date": "2024-01-18T09:00:00Z",
    "tracking_info": {
      "shipping_carrier": "FedEx",
      "shipping_method": "Ground",
      "tracking_number": "123456789012",
      "tracking_url": "https://www.fedex.com/fedextrack/?trknbr=123456789012"
    },
    "shipment_order_id": "SO-12345",
    "shipment_order_number": "1234567890",
    "label_url": "https://okc-labels-bucket.s3.amazonaws.com/...",
    "shipping_net_charge": 12.5,
    "weight": 2.5,
    "created_at": "2024-01-17T10:00:00Z",
    "updated_at": "2024-01-18T09:00:00Z",
    "order_lines": [
      {
        "id": "orderline-uuid",
        "name": "Monthly Pack"
      }
    ]
  }
}

List Fulfillments

TypeScript

const response = await fetch(
  "https://na1-prod.okcapsule.app/v2/fulfillments?limit=20",
  {
    headers: { Authorization: `Bearer ${access_token}` },
  }
);

const { fulfillments } = await response.json();

cURL

curl -X GET "https://na1-prod.okcapsule.app/v2/fulfillments?limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Query Parameters

Parameter	Description
limit	Number of results (default: 20)
cursor	Pagination cursor
order_id	Filter by order ID

Tracking Information

The tracking_info object contains:

Field	Description
shipping_carrier	Carrier name (FedEx, UPS, USPS, etc.)
shipping_method	Service level
tracking_number	Carrier tracking number
tracking_url	Direct link to carrier tracking page

Fulfillment Dates

Field	Description
pickup_date	When the package was picked up by carrier
delivery_date	When the package was delivered

Shipping Label

The label_url field provides a pre-signed S3 URL to download the shipping label.

Label URL Expiration

The label_url is a pre-signed URL that expires after 15 minutes. Request a fresh fulfillment if you need a new label URL.

Best Practices

Store Tracking Info

Cache tracking numbers and URLs in your system to reduce API calls and provide faster customer support.