Skip to main content

Subscriptions

A subscription tells the service which shipment to track and by which identifier. Once subscribed, the shipment is polled against the relevant carrier and any events are stored against the subscription.

Subscribing is step 4 of the flow: carrier credentials come first, plus a webhook if you want push delivery.

Creating a subscription​

POST /subscription/equipment
x-api-key: <your-api-key>
Content-Type: application/json

{
  "scacCode": "ABCU",
  "containerNumber": "ABCU1234567",
  "bookingNumber": "BN12345",
  "billNumber": "BL12345",
  "subscriptionReference": "REF12345"
}

Only scacCode (the carrier's four-letter SCAC code) is required; provide whichever of containerNumber, bookingNumber, or billNumber you have. A subscriptionReference is optional but recommended: it's your own identifier, returned unchanged in webhook payloads and in GET /subscription/{id}, so you can correlate events back to your own records instead of parsing carrier references.

A successful call returns your reference back:

{
  "message": "Successfully Subscribed",
  "subscriptionReference": "REF12345",
  "dateOfRequest": "2023-06-15T10:30:00Z"
}

See Create Equipment Subscription.

Pulling tracking data​

If you haven't set up a webhook, or just want the current state on demand, pull it back through the subscription itself:

  • GET /subscription/equipment?bookingNumber=... / ?billNumber=...: tracking data for the subscriptions matching a booking number or bill of lading.
  • GET /subscription/{subscription_id}: a single subscription by its reference.
  • GET /subscriptions: every subscription on your account, with optional subscriptionStatus and referencePrefix filters and opt-in pagination (limit / nextToken) for large accounts.

See Get Equipment Subscriptions and List Subscriptions.

Closing a subscription​

DELETE /subscription/{subscription_id} soft-closes a subscription: polling stops (once no other open subscription shares the same shipment) but the record is retained for audit and doesn't block re-subscribing the same shipment later. See Close a Subscription.