Frequently asked questions

General questions

How do I connect to Track & Trace?

To connect to the Track & Trace API, email us at

I moved an order to the next day, but it's marked as canceled. What's wrong?

When moving an order to a different day, specify the new status.

When uploading routes in Track & Trace, I see is a warning that routes for the date already exist. What to do?

The warning means that routes for this day were added earlier. You need to select the appropriate action to perform with the old and new routes. For more information, see Upload data.

When uploading routes in Track & Trace, I see a warning about duplicate orders. What should I do?

The warning means that there are duplicates in the routes, in other words, orders with duplicate numbers. For more information about actions with duplicates, see Upload data.


How do I pass the OAuth token in the request?

Pass the OAuth token in the Authorization header.

I use the correct OAuth token, but I get a 401 Unauthorized response. What's wrong?

Possible reasons:

  • The OAuth token is expired. If you don't use the token for more than 1 month, it may be revoked.
  • The password for the Yandex ID account was changed.
  • Two-factor authentication was enabled or disabled.
  • You clicked Log out on all devices in the Yandex ID account.
  • You entered a token without adding Auth in the Authorization parameter.
    • Correct: Authorization: Auth your-OAuth-token.
    • Incorrect: Authorization: your-OAuth-token.
For more information about why the token may have been revoked, see Revoke a token.

To continue working, get a new token. The Getting an OAuth token page describes what you need to do.

I lost my OAuth token. How do I restore it?

To restore your OAuth token, follow step 9 of the instructions at Getting an OAuth token. If you restore the token this way, it won't change.

Why do I get a message saying 403 (Company apikey is unknown or banned) or 403 (Company apikey is invalid)?

For the API to work, you need to specify a valid API key under Settings → Company → API key in the routing workspace. You can check that your key is valid or get a new key in the Developer Dashboard for Routing: Planning and Monitoring.

Why am I getting an error message saying 403 Your role doesn't allow to make this request?

This error means that the account in use doesn't have enough permissions to perform the request. The account is identified by the OAuth token that's used in the request.

To resolve the issue, assign the account the Administrator role under Settings → Managers in the routing workspace.

Tracking orders

Why do vehicles on courier tracks jump long distances at once in the routing workspace?
When you view a courier's movement history, their vehicle sometimes moves abruptly along the route as if part of the track wasn't recorded.
Possible cause
While en route, the courier minimizes the Yandex Courier app, and the device drops it from the smartphone RAM.
Add Yandex Courier to the list of exceptions in the smartphone battery optimization settings.
Sample settings on Huawei phones
  • Go to Settings → Battery → App launch.
  • Find the Yandex Courier app and deselect it.
  • In the Manage manually window that opens, make sure that everything is selected.

On different phone models, the settings menu may differ. If you can't find the necessary settings, contact support and we'll do our best to help.

Why do vehicles on courier tracks “jump” long distances off the main route in the routing workspace?
When you view a courier's movement history, their vehicle sometimes deviates abruptly from the route.
Possible cause
The app couldn't get the exact coordinates.
The courier's phone must use a GPS source or a “Device Only” source instead of multiple location sources at once (Wi-Fi, cellular, and GPS).

Order notifications

What types of order notifications are available?

There are two types of notifications about order delivery:

  • The shift_start notification appears when a courier starts moving along the route.
  • The nearby notification appears some time (by default, 30 minutes) before the estimated time of arrival at the delivery point. The estimated arrival time is calculated automatically when the courier moves along the route.

Learn more about getting information about notifications

When does the shift_start notification appear in the system?

The shift_start notification usually appears at the time specified in the route.route_start field if there's information about the location of the courier making the delivery.

If there are no courier coordinates in Track & Trace (for example, the service started receiving them only after the time specified in the route_start field), the notification appears when this data arrives.

If the route.route_start parameter isn't set, the notification appears at the beginning of the earliest time window for all orders. If the mark_route_started_radius is set for the depot, the notification for routes linked to the depot doesn't appear while the courier is within the depot radius.

Why didn't a notification appear in the system?

Possible reasons:

  1. The notification service isn't enabled. To enable it, contact your manager.
  2. The courier didn't log in to the app or choose a route.
  3. The courier started the route after the end of the delivery time window. For example, if the courier starts the route at 10:30, and the delivery window is from 8:00 to 10:00, no order notification appears in the system.
  4. Location data from the GPS tracker wasn't sent to the service. In this case, you'll see that there's no data about the courier's location in the routing workspace.

Contact support