Skip to main content
The TMS external IDs endpoint lets an external TMS write its identifier back to Vectrix after a shipment or order has been processed. 
POST /api/integrations/tms/external-ids
Authorization: Bearer <workos-m2m-access-token>
Content-Type: application/json
The bearer token must be a WorkOS Connect machine-to-machine access token for the same WorkOS organization as the target shipment or order.

​
Request

Write to a shipment by Convex ID: 
{
  "level": "shipment",
  "shipmentId": "j97...",
  "tmsId": "TMS-123",
  "state": "linked"
}
Write to a shipment by project and shipment code: 
{
  "level": "shipment",
  "projectId": "j57...",
  "shipmentCode": "SHP-123",
  "tmsId": "TMS-123",
  "state": "linked"
}
Write to an order: 
{
  "level": "order",
  "orderId": "j98...",
  "tmsId": "TMS-ORDER-123",
  "state": "unlinked"
}
state accepts linked or unlinked.

​
Behavior

  • level: "shipment" stores the value in shipments.externalIds.tms_id and updates that shipment’s status.
  • level: "order" stores the value in orders.externalIds.tms_id and updates all non-deleted shipments in that order to the requested status.
  • Order-level TMS IDs are not copied down to child shipment externalIds.
  • The order overview can display the external ID column from either shipment-level or order-level values through the display menu.

​
Authentication

The route is public in the SvelteKit auth hook and authenticates itself with the WorkOS M2M bearer token. The server verifies issuer, audience, allowed client ID, required scope, and token organization before it writes to Convex. Required environment variables:
VariablePurpose
WORKOS_TMS_EXTERNAL_IDS_JWKS_URLJWKS endpoint used to verify M2M JWT signatures.
WORKOS_TMS_EXTERNAL_IDS_ISSUERExpected token issuer.
WORKOS_TMS_EXTERNAL_IDS_AUDIENCEExpected token audience.
WORKOS_TMS_EXTERNAL_IDS_ALLOWED_CLIENT_IDAllowed WorkOS M2M client ID.
WORKOS_TMS_EXTERNAL_IDS_REQUIRED_SCOPERequired token scope. Defaults to tms:external_ids:write.