Documentation

Public API

The Public API connects your systems to orders, inventory, returns, tracking, and webhooks. It accepts JSON over HTTPS and uses client-scoped tokens.

Open Public API reference

Get started

  1. Open the user menu in your production portal and choose Developers.
  2. If you have no token yet, choose Get Access.
  3. Copy Production Token and its displayed URL for production requests.
  4. If available, use Sandbox Token and its displayed URL for testing.
  5. Send the token with every request in the Authorization header.
curl "<API_URL>/orders/" \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Accept: application/json"

Production Token appears only in the production portal when a token has been issued. It is not shown in the sandbox portal.

If Production Token is missing in production, ask your Account Manager to arrange access securely. If you cannot see Developers, ask your account administrator for access.

The API is mounted at /api/v1/, /api/v2/, and /api/v3/. The generated reference documents version 2 paths.

Authentication

Send the token as Authorization: Token YOUR_TOKEN.

A token can read only its own client's data. Production and sandbox tokens work only in their matching environment. An embedded app uses an app token, and its registered domains may also be checked.

A missing or invalid token returns HTTP 401 with a detail message.

What the API covers

  • Create and update orders, run order actions, and run bulk actions.
  • Create return orders, then restock, quarantine, forward, or dispose return items.
  • Create and update products and item groups. Look up customs records such as HS codes.
  • Create and update ASNs, then run ASN actions.
  • Read tracking events, couriers, countries, warehouses, shipping options, shipping zones, and rates.
  • Create labels, export orders, generate pallet documents, and follow async tasks.
  • Register webhooks for order, tracking, ASN, product, and return order events.
  • Manage exporter, importer, client location, and customs broker addresses.

Endpoint reference

Paths below omit the version segment. For example, /orders/ is available at /api/v3/orders/.

Group Endpoints
Orders /orders/, /orders/{id}/, /orders/action/, /orders/{id}/action/{action_name}/, /orders/label/, /orders/export/, /orders/sales_order_stats/
Return orders /orders/returns/, /orders/returns/{id}/, /orders/returns/action/
Return items /return_items/, /return_items/{id}/, /return_items/action/, /return_items/return-item-conditions/, /return_items/return-item-conditions/available-options/
Products /products/, /products/{id}/, /products/stocks/, /item_groups/, /item_groups/{id}/
ASN /asn/, /asn/{id}/, /asn/{id}/action/{action_name}/
Tracking /track/, /track/{tracking_number}, /fic_track/{tracking_number}
Shipping and rates /shipping_option/, /shipping_option/{id}/, /couriers/, /couriers/groups/, /countries/, /rates/, /warehouses/, /shipping_zones/
Customs /hs_codes/
Webhooks /webhooks/, /webhooks/{id}/
Addresses /address/, /address/{id}, /address/exporter_address/, /address/importer_address/, /address/client_location_address/, /address/customs_broker_address/
Embedded /embedded/context/, /embedded/orders/, /embedded/tracking/, /embedded/drop_off_location/, /embedded/create_rma_order/, /embedded/labels/{floship_so_number}/
Tasks and documents /tasks/{task_id}/, /tasks/{task_id}/progress/, /tasks/{task_id}/stop/, /documents/pallets/, /documents/pallets/{id}/start_generating/
Client and uploads /client/, /upload/{filename}/

Use the exact path in the table; some detail routes omit the trailing slash. Call OPTIONS on an order endpoint to see its filters, writable fields, and allowed bulk actions.

The per-order /orders/{id}/rates/ route is deprecated. Use the rates calculator at /rates/.

These endpoints accept requests without a token:

Endpoint Returns
/countries/public Country list
/couriers/public_list/ Courier list
/couriers/groups/public_list/ Courier group list
/warehouses/public_list Warehouse list
/hs_codes/public/ HS code lookup
/rates/public/ Rate estimate

Pagination differs by endpoint. Order, product, ASN, courier, warehouse, and shipping option lists use the cursor-aware paginator. Other lists can return page numbers or a different shape.

For those cursor-aware lists, cursor mode applies on /api/v2/, when a request sets cursor_pagination, or when the environment enables FORCE_V2_PUBLIC_API. The server helper need_cursor_pagination adds cursor mode for a few internal order paths. Follow the returned next link instead of building a page number.

On those lists, meta=results returns rows without a total count, and meta=count returns a count with no rows. Both modes keep page-number pagination.

limit sets the page size, up to 500 items.

?search= on /orders/ and /orders/export/ searches order number, customer reference, item summary, and tracking number. It is a full-text search, so use structured filters for exact matches. On /orders/, exact email search uses the shipping address when vector search is off.

Errors and limits

Status Meaning
400 Request validation failed. Read the returned field errors.
401 A protected endpoint rejected a missing or invalid token for this environment.
429 A rate or concurrency limit was reached. Wait for the Retry-After time.

Authenticated endpoints limit concurrent requests per client. Some endpoints also limit request rate per token. The generated reference lists the configured limits.

An order's errors field records validation messages. It does not describe an HTTP 400 response.

Field limits

Every supplied address may include company, phone and email; all three are optional and may be blank or null. Omit the whole address to retain its stored values.

Parcel-forwarding orders can use source_address without preregistering a client location. Omit warehouse_id and client_location_address_id for that custom origin. Choose FW custom origin in the reference's Request samples for a complete request.

A customer reference stores up to 255 characters . A Create Label request accepts up to 35 characters .

SKU and barcode checks depend on your account settings. See the generated schema for each endpoint.

See Field limits for product and order field limits.

Related Articles