Skip to main content

Locations

A location is a branch, store or warehouse that deliveries start from. It is the unit everything in Alrik is organised around: orders belong to a location, planners plan per location, and tours, vehicles and costs are all counted per location.

Your API key is not a key to everything. It belongs to an integration that may act on a fixed list of locations, and almost every request has to say which of them it means. Almost every 403 you will hit is about naming one that is not on the list — which is why this page is worth reading before the others.

Name locations by your own reference​

Each location has two identifiers:

  • Alrik's numeric id
  • an origin_reference — a string you chose when the location was created

The API is built around the second. You send origin_reference and Alrik resolves it for you, so you never have to store Alrik's ids and your requests read in your own terms:

{
  "origin_order_number": "SO-10432",
  "origin_reference": "wh-stockholm-01"
}
Choose a reference you will never change

Use an identifier your own system already owns — a warehouse code, a store number, a site slug. Every later request depends on it, so pick something that will not be renamed.

Setting up your locations​

There are two ways in, depending on who owns the list of branches.

Alrik set them up for you. This is the common case. Call GET /v1/integration once and map each origin_reference it returns to the matching branch in your system. The same call is the one to reconcile against later if you keep the two lists in sync.

Your system creates them. With the allow_location_creation permission you can create a location yourself, giving it a display name for Connect and the origin_reference you will use from then on. There is no endpoint to rename or remove one, so treat both as permanent.

When a location is rejected​

Naming a location your integration may not act on returns 403 with:

{ "detail": "Invalid location id" }

The message says "id" even when you sent an origin_reference. Read it as this integration may not act on that location, and check for:

  • a typo in origin_reference
  • a location that exists in Alrik but is not attached to this integration
  • no location sent at all

Permissions and locations are checked separately. Holding allow_order_creation does not let you create orders at a location you do not own.

Where locations do not apply​

Two parts of the API are not scoped to a single location:

  • Company orders reads across every location in your company at once, so it needs the integration bound to a company instead.
  • Carrier deliveries identifies each order by the access_token it was dispatched with, so a carrier never names a location.
location_id on order creation

Creating an order also accepts Alrik's numeric location_id when origin_reference is left out. No other endpoint takes it, so prefer origin_reference.