Register Shipment Tracking

POST 
/api/shipment-trackings/register

Manual Track this shipment trigger from an entity detail page. Resolves the entity, creates a pending shipment_trackings row via the manager, and kicks off a background job so the row gets pushed to 17TRACK promptly.

Authorization

Any valid API token can call this endpoint — no specific scope required. Manage tokens.

Required Fields:

• trackable_type — friendly slug. One of: sales_order_fulfillment, inbound_shipment, warehouse_transfer_shipment, rma, vendor_credit_shipment
• trackable_id — integer, min 1. The PK of the trackable entity.

Responses:

• 201 Created — pending tracking row created (carrier event data not yet hydrated; the register job will fill it on the next tick)
• 404 Not Found — trackable entity does not exist
• 422 Unprocessable Entity with code: not_connected — no active 17TRACK instance
• 422 Unprocessable Entity with code: register_skipped — entity has an empty tracking number, OR auto-track is disabled for this entity type

This manual action bypasses the auto_track_channels sales-channel scoping — an explicit request to track one shipment always registers it, even if its channel is excluded from automatic tracking.

Request

Responses

201

Created

Response Headers

Content-Type

401

Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.

403

Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.

422

Unprocessable Entity

Response Headers

Content-Type

429

Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.