Developer: API tokens, webhooks and the guide — Help

Settings › Developer lets your own software read and update orders, payments and delivery status, and be told the moment something changes.

Settings › Developer is for connecting your own software (an accounts program, a warehouse system, a website of your own) to Order Tracker. It has three parts: API tokens (the key your software uses to ask), Webhooks (Order Tracker tells your server when something happens) and the Reference (every call and event, with examples). You need the Developer permission (owners have it) and a plan that includes Developer tools.

TipNot a developer? Send your developer the Guide (PDF) button at the top of the page. It has everything they need, and nothing secret is in it.

Make a token

Open API tokens and press Create token.
Name it after what will use it (for example Accounts software). One token for each program means you can see what each one does and cancel one without breaking the others.
Choose what it may do: Read only, Orders & payments, Everything, or tick the boxes yourself. A token can only do what you tick, and you can only hand out what your own permissions allow.
Choose when it stops working (a year by default) and, if you like, the internet addresses it may be used from.
Copy the token when it appears. It is shown once: Order Tracker keeps only a fingerprint of it. If you lose it, make a new one.

NoteA token is like a password. Use it only from your own server, never in a web page or a phone app, and never write it in an address. If it leaks, press Revoke on its row: it stops working at once. Advanced › Developer settings › Revoke all stops every token if you do not know which one leaked.

Make a first call

The Start here tab shows your API address and a ready example in curl, PHP, Python and Node.js. Replace YOUR_TOKEN with your token. A good answer starts with "ok": true. Every call a token makes is listed in Advanced › Activity with the time, the answer and where it came from.

Webhooks: be told, instead of asking

Open Webhooks and press Add endpoint.
Enter a name and the address of your server. It must start with https:// and be reachable from the internet.
Choose the events (new order, payment recorded, parcel status changed, claim created...), or all of them.
If your server asks callers to sign in, choose how: a bearer token, a user name and password, or a header of your choice, and enter the secret. It is stored encrypted and never shown again; leave it empty when editing to keep it.
Copy the signing secret. Your server uses it to check that a message really comes from Order Tracker (the exact code is on the page, in PHP, Node.js and Python). You can show it again, or make a new one, with Signing secret.
Press Send test. You see what your server answered, and the message is in the log.

Messages shows every message sent to an endpoint: when, which event, whether your server accepted it, how many tries, and (when you open one) exactly what was sent and what your server said. Send again sends a message once more by hand.

If your server does not answer, Order Tracker tries again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours, then marks the message Failed. A message can therefore arrive twice, and not always in order: your server should remember the event ids it has handled.

TipThe first try of a message is sent as soon as the event happens. The retries are sent by the store's background job (cron), so make sure it runs: the Start here tab warns you if it has not. See the install notes, Cron.

Settings (in Advanced)

Since v97 the call log (Activity) and Developer settings are the two parts of the last tab, Advanced; the old ?tab=activity and ?tab=settings addresses still open them.

Allow API calls - the master switch for all tokens. Webhooks keep working when it is off.
Calls allowed per minute - for each token. Over the limit a call is answered with 429 and told how long to wait.
Keep the call log and finished messages for - 3 to 90 days; older lines are deleted for you.
Try again when your server does not answer - on by default; without it a message is tried once.
Pause an endpoint after this many failures in a row - so a dead server is not called all day. A paused endpoint gets nothing until you switch it on again, and nothing is lost: the failed messages can be sent again from the log.
Email the store owners when an endpoint is paused - so a broken server is noticed.

Sending orders into Order Tracker

The API reads and updates orders; it does not create them. To push orders in from a shop Order Tracker has no connection for, add a Custom store channel in Settings › Sales channels. Its address and secret are shown on the Start here tab, and the format is in the Reference.

When something does not work

401 - the token is missing, wrong, revoked or ended. Make a new one.
403 insufficient_scope - the token may not do this. Edit it and tick the scope the Reference names for that call.
403 ip_not_allowed - the token has an address list and the call came from another address.
403 plan_required - your plan does not include Developer tools.
429 - too many calls in a minute. Wait for the number of seconds in Retry-After.
Webhook says "Failing" - open Messages and then the failed message: it shows what your server answered. Common causes: the address is not https://, the certificate is not valid, the server takes longer than the time set for the endpoint, or it answers with a redirect.