API Endpoint Reference
Public API endpoint reference
Quick Summary: Find the Public API route, method, and response pattern for client account operations.
Base URL
Use the URL displayed with the token for your environment. The production Developers page displays an issued Production Token with its matching production URL. Sandbox does not display a production token. If no production token has been issued, contact your Account Manager through a secure channel.
Production and sandbox tokens work only in their matching environment. See API Overview for credential setup.
| Mount | Base path | List pagination |
|---|---|---|
| Canonical | /api/v2/ |
Cursor pagination on supported lists |
| Alias | /api/v3/ |
Page-number pagination by default |
| Legacy alias | /api/v1/ |
Page-number pagination by default |
The three mounts expose the same routes. The generated API reference uses v2 examples. On a cursor-aware list, add cursor_pagination=1 to request cursor mode from an alias.
Send the token on protected requests:
Authorization: Token YOUR_API_TOKEN
Accept: application/json
A token can read only its own client's records. GET /client/ is a simple authenticated connection test.
Page-number lists accept page and limit. The default page size is 50, and limit can go up to 500. Cursor responses provide next and previous links.
Orders
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /orders/ |
List orders |
| POST | /orders/ |
Create an order |
| GET | /orders/{id}/ |
Retrieve an order |
| PUT/PATCH | /orders/{id}/ |
Update an order |
| POST | /orders/action/ |
Run a bulk action |
| POST | /orders/{id}/action/{action_name}/ |
Run an order action |
| POST | /orders/label/ |
Start the order and label flow |
| GET | /orders/export/ |
Start an export and return its task ID |
| POST | /orders/sales_order_stats/ |
Return order statistics |
| GET | /orders/{id}/rates/ |
Deprecated rates route |
The order action route accepts an order ID or tracking number in {id}. Read actions from the order response before calling an action. The deprecated rates route returns a deprecation message. Use POST /rates/ for a new calculation.
Return orders
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /orders/returns/ |
List return orders |
| POST | /orders/returns/ |
Create a return order |
| GET | /orders/returns/{id}/ |
Retrieve a return order |
| PUT/PATCH | /orders/returns/{id}/ |
Update a return order |
| POST | /orders/returns/action/ |
Run a bulk return action |
Labels and shipments
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /orders/create_master_shipment/ |
Create a master shipment |
| GET | /orders/create_master_shipment/results/ |
Retrieve a result with order_id |
| POST | /orders/pickup_master_shipments/ |
Request a master shipment pickup |
The master shipment result route requires the order_id query parameter. The pickup request takes the relevant order IDs in its payload.
Products
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /products/ |
List products |
| POST | /products/ |
Create a product |
| GET | /products/{id}/ |
Retrieve a product |
| PUT/PATCH | /products/{id}/ |
Update a product |
| GET | /products/stocks/ |
List products with stock entries |
The product detail route supports read and update methods. It does not expose DELETE.
Stock levels
GET /products/stocks/ returns each product with its warehouses_stock entries. Values are read when the request is served. Sum qty_total_available across a product's entries for its account-wide available quantity.
| Field | Meaning |
|---|---|
three_pl_id, three_pl_name |
The location that owns the stock entry |
qty |
Recorded stock quantity |
qty_on_hand |
Quantity physically on hand |
quarantine_qty |
Quantity held in quarantine |
pending_return_qty |
Quantity expected from returns not yet received |
qty_reserved |
Quantity committed to unfulfilled orders |
qty_total_available |
qty minus qty_reserved |
The response uses qty_reserved for committed quantity. It does not include a committed field.
Item groups
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /item_groups/ |
List item groups |
| POST | /item_groups/ |
Create an item group |
| GET | /item_groups/{id}/ |
Retrieve an item group |
| PUT/PATCH | /item_groups/{id}/ |
Update an item group |
| DELETE | /item_groups/{id}/ |
Delete an editable item group |
Return items
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /return_items/ |
List return items |
| GET | /return_items/{id}/ |
Retrieve a return item |
| POST | /return_items/action/ |
Run a bulk return-item action |
| GET | /return_items/return-item-conditions/ |
List return conditions |
| POST | /return_items/return-item-conditions/ |
Create a return condition |
| GET | /return_items/return-item-conditions/{id}/ |
Retrieve a return condition |
| PUT/PATCH | /return_items/return-item-conditions/{id}/ |
Update a return condition |
| DELETE | /return_items/return-item-conditions/{id}/ |
Deactivate a return condition |
| GET | /return_items/return-item-conditions/available-options/ |
List available condition options |
The condition routes use the literal path segment return-item-conditions. They do not use /conditions/.
ASN (Advance Shipping Notices)
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /asn/ |
List ASNs |
| POST | /asn/ |
Create an ASN |
| GET | /asn/{id}/ |
Retrieve an ASN |
| PUT/PATCH | /asn/{id}/ |
Update an ASN |
| DELETE | /asn/{id}/ |
Delete a draft ASN |
| POST | /asn/{id}/action/{action_name}/ |
Run an ASN action |
An ASN can be deleted only while it is a draft. Read actions from the ASN response before calling an action.
Tracking
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /track/{tracking_number} |
Retrieve order or client tracking events |
| GET | /fic_track/{tracking_number} |
Retrieve FIC order tracking events |
| POST | /track/ |
Create a client tracking event |
The plain tracking route returns an empty object when no matching event exists. The /fic_track/ route returns a validation error when its order tracking record does not exist.
Rates
| Method | Endpoint | Authentication | Purpose |
|---|---|---|---|
| POST | /rates/ |
Token | Calculate rates for the authenticated account |
| POST | /rates/public/ |
None | Calculate rates without account credentials |
Shipping options
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /shipping_option/ |
List shipping options |
| POST | /shipping_option/ |
Create a shipping option |
| GET | /shipping_option/{id}/ |
Retrieve a shipping option |
| PUT/PATCH | /shipping_option/{id}/ |
Update a shipping option |
Couriers
| Method | Endpoint | Authentication | Purpose |
|---|---|---|---|
| GET | /couriers/ |
Token | List couriers available to the account |
| GET | /couriers/groups/ |
Token | List available courier groups |
| GET | /couriers/public_list/ |
None | List public couriers |
| GET | /couriers/groups/public_list/ |
None | List public courier groups |
The unauthenticated routes use public_list, not public.
Warehouses
| Method | Endpoint | Authentication | Purpose |
|---|---|---|---|
| GET | /warehouses/ |
Token | List account warehouses |
| GET | /warehouses/{id}/ |
Token | Retrieve an account warehouse |
| GET | /warehouses/public_list |
None | List public warehouses |
Addresses
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /address/ |
List addresses |
| POST | /address/ |
Create an address |
| GET | /address/{id} |
Retrieve an address |
| PUT/PATCH | /address/{id} |
Update an address |
| DELETE | /address/{id} |
Delete an address |
Specialized addresses
| Address type | Collection | Detail |
|---|---|---|
| Exporter | /address/exporter_address/ |
/address/exporter_address/{id} |
| Importer | /address/importer_address/ |
/address/importer_address/{id} |
| Customs broker | /address/customs_broker_address/ |
/address/customs_broker_address/{id} |
| Client location | /address/client_location_address/ |
/address/client_location_address/{id}/ |
Collection routes allow GET and POST. Detail routes allow GET, PUT, PATCH, and DELETE. Copy the trailing slash shown for each route.
Countries, HS codes, and shipping zones
| Method | Endpoint | Authentication | Purpose |
|---|---|---|---|
| GET | /countries/ |
Token | List countries |
| GET | /countries/public |
None | List countries publicly |
| GET | /hs_codes/ |
Token | List HS codes |
| GET | /hs_codes/{id}/ |
Token | Retrieve an HS code |
| GET | /hs_codes/public/ |
None | List HS codes publicly |
| GET | /hs_codes/public/check/ |
None | Check a code without client context |
| GET | /shipping_zones/ |
Token | List shipping zones |
The anonymous HS-code check returns exists_harmonized_code: false because it has no client context.
Webhooks
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /webhooks/ |
List subscriptions |
| POST | /webhooks/ |
Create a subscription |
| GET | /webhooks/{id}/ |
Retrieve a subscription |
| PUT/PATCH | /webhooks/{id}/ |
Update a subscription |
| DELETE | /webhooks/{id}/ |
Delete a subscription |
| POST | /webhooks/trigger/ |
Trigger a sandbox test event |
The trigger route exists only in sandbox. Subscription callback URLs must use HTTPS.
Available webhook topics
| Resource | Topics |
|---|---|
| Order | order/created, order/updated, order/fulfilled, order/approved, order/generated_labels, order/picked, order/packed, order/canceled, order/incomplete, order/tracking_status_changed |
| Tracking | tracking/client_tracking_status_changed, tracking/client_tracking_events_updated, tracking/order_tracking_events_updated |
| ASN | asn/created, asn/updated, asn/sent_to_3pl, asn/in_review, asn/on_hold, asn/approved, asn/canceled, asn/rejected, asn/accepted |
| Product | product/created, product/updated |
| Return order | return_order/received, return_order/created, return_order/updated |
Webhook delivery
Deliveries are HTTP POST requests with a Webhook-Topic header. The callback must answer with a 2xx status within 30 seconds . Redirects fail delivery.
Failed deliveries use exponential backoff up to the configured topic limit. Most topics allow up to 8 retries. Selected high-volume topics allow up to 4 retries .
The subscription owner receives a warning after 1 day of failures. The subscription is disabled after 5 days of failures .
The failure window starts on the first failed delivery. A successful delivery clears it.
After a subscription is disabled
Events that fire while a subscription is disabled are not stored or replayed. Fix the callback first, then enable it with PATCH /webhooks/{id}/ and "is_active": true.
Enabling the subscription does not reset the failure window. A failed delivery can disable it again. Confirm the state with is_active in GET /webhooks/.
To find records missed during the outage, use the list routes with their update windows. Orders and ASNs accept update_date_from and update_date_to. Return items accept updated_from and updated_to.
Bulk upload
| Method | Endpoint | Purpose |
|---|---|---|
| PUT | /upload/{filename}/ |
Upload a multipart file and return its URL |
Send the file in the multipart field named file. The API validates the extension and maximum file size.
Async tasks
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /tasks/{task_id}/ |
Get task status, progress, and download link |
| GET | /tasks/{task_id}/progress/ |
Get detailed progress |
| POST | /tasks/{task_id}/stop/ |
Request cancellation |
The task routes serve export tasks owned by the caller. Order export returns the task ID. Other task types and other users' tasks return 404.
Client info
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /client/ |
Return the authenticated account |
Documents
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /documents/pallets/ |
List pallet documents |
| GET | /documents/pallets/{id}/ |
Retrieve a pallet document |
| POST | /documents/pallets/{id}/start_generating/ |
Start pallet generation |
Pallet generation requires at least one order with tracking, courier support for pallets, and one courier across the pallet orders. A pallet already in generation cannot start again.
External order data
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /external_orders/ |
Create external order data |
| PUT | /external_orders/{id}/ |
Replace external order data |
| DELETE | /external_orders/{id}/ |
Delete external order data |
These routes create, replace, or remove external order data. They do not provide list, retrieve, or PATCH routes.
Embedded app requests
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /embedded/context/ |
Retrieve app context |
| GET | /embedded/orders/ |
List eligible orders |
| GET | /embedded/tracking/ |
Retrieve order tracking |
| POST | /embedded/create_rma_order/ |
Create an RMA return |
| GET | /embedded/labels/{floship_so_number}/ |
Retrieve order labels |
| GET | /embedded/drop_off_location/ |
List nearby drop-off locations |
Embedded routes use an active app token instead of a Developers token. The app token can also be restricted to its registered domains. See Embedded Forms for the form workflow.
Rate limits
The Public API limits concurrent authenticated requests per client across all web processes. The configured maximum is 5; current platform capacity can produce a lower limit .
Some endpoints also enforce a request rate. A throttled request returns 429 Too Many Requests with a Retry-After header. Wait for that interval and avoid retrying a burst in parallel.
Use webhooks for event delivery, follow next links instead of guessing offsets, and cache values that change infrequently.
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
401 on every protected request |
The token is missing, invalid, or from the other environment | Send Authorization: Token YOUR_TOKEN and use the production or sandbox token for the matching environment |
403 for a valid token |
The requested action is unavailable for the account or record | Confirm the endpoint and action in the generated reference, then ask the account administrator or support to review access |
404 for a route copied from this page |
The plural form, route name, or trailing slash differs | Use the exact path shown, including /orders/label/, /orders/sales_order_stats/, and /address/{id} |
| Webhook is not called | The callback is not HTTPS, returns outside 2xx, redirects, or the subscription is disabled |
Fix the endpoint and confirm is_active with GET /webhooks/{id}/ |
| Webhooks are missing after an outage | Events fired while the subscription was disabled are not replayed | Enable the subscription and reconcile records with the list routes and update windows |
Task route returns 404 |
The task belongs to another user or is not an export task | Check the task ID and use the token that started the export |
429 Too Many Requests |
A request rate or per-client concurrency limit was reached | Read Retry-After, reduce parallel calls, and retry after the stated delay |
Related Documentation
- API Overview: authentication and developer setup
- Developers: token management
- Public API reference: request, pagination, and error conventions
- Product and Order Field Limits: field lengths and values
- Embedded Forms: app token and RMA form flows
- Troubleshooting: integration diagnosis