Linking

Endpoints and scopes

The idea

You reach no merchant’s data without their consent. Consent is given with a link code your system issues and the merchant enters in their AurMap account.

1. Your system asks for a code for one of its branches.
2. You show the code to the merchant as text or a QR in your back office.
3. The merchant scans it from their AurMap account, picks the place, reviews the scopes and approves. Only someone holding the “AurMap and integrations” permission in the merchant’s account can approve.

On the approval screen the merchant sees your verified partner name and logo from the developer dashboard, not the external_location_name you send. That way nobody can pose as another partner. 4. You receive link.created.

A code is valid for 15 minutes and works once.

Scopes

There are seven scopes. The merchant grants customer:contact with a separate consent, to protect customers’ personal data under the Personal Data Protection Law. Ask for it only if your system needs it, such as a loyalty programme that matches customers by number. Before you can ask for it, our team approves your account for it, and the merchant sees the purpose you declared on the approval screen.

Ask only for what you need. The merchant sees the list before approving.

Link level

A place has one menu source. If the merchant links a place that already has another source, we ask them which one stays. A place never has two sources at once.

Issue a link code

POST /link-codes

aurmap POST /v1/link-codes '{"level":"place","external_location_id":"pos-branch-17","external_location_name":"Al Rayhan, Olaya","scopes":["catalog:write","inventory:write","orders:read","orders:write"]}'

201

{
  "code": "7KQ2M9XA",
  "display_code": "7KQ2-M9XA",
  "qr_url": "https://aurmap.com/link/7KQ2M9XA",
  "qr_png_url": "https://partners.aurmap.com/v1/link-codes/7KQ2M9XA/qr.png",
  "status": "pending",
  "expires_at": "2026-10-14T12:15:00Z"
}

Show display_code as it is, or a QR that opens qr_url. The code is 8 letters and digits with no I, L, O or U, so merchants do not mistype it.

const code = await aurmap('POST', '/v1/link-codes', {
  level: 'place',
  external_location_id: 'pos-branch-17',
  external_location_name: 'Al Rayhan, Olaya',
  scopes: ['catalog:write', 'inventory:write', 'orders:read', 'orders:write'],
});
showToMerchant(code.display_code, code.qr_url);

$code = aurmap('POST', '/v1/link-codes', [
    'level' => 'place',
    'external_location_id' => 'pos-branch-17',
    'external_location_name' => 'Al Rayhan, Olaya',
    'scopes' => ['catalog:write', 'inventory:write', 'orders:read', 'orders:write'],
]);

Follow a code

The link.created event is enough. To show the merchant the result right away, ask about the code:

aurmap GET /v1/link-codes/7KQ2M9XA

{ "code": "7KQ2M9XA", "status": "redeemed", "link_id": "lnk_2h6j4n" }

Statuses: pending, redeemed, expired, declined.

The link object

{
  "link_id": "lnk_2h6j4n",
  "mode": "live",
  "level": "place",
  "merchant": { "merchant_id": "mer_5r8k2d", "name": "مطعم الريحان" },
  "place": { "place_id": "plc_9q3w7e", "name": "الريحان - العليا" },
  "external_location_id": "pos-branch-17",
  "scopes": ["catalog:write", "inventory:write", "orders:read", "orders:write"],
  "created_at": "2026-10-14T12:03:11Z",
  "removed_at": null
}

Adding a scope

Issue a new code with every scope you want, old and new. When the merchant approves, the same link is updated and you receive link.updated. No scope is added without the merchant.

Unlinking

• The merchant can remove the link at any time from their account.
• You can remove it with DELETE /links/{link_id}.
• Either way you receive link.removed, with removed_by: merchant, partner or aurmap.

aurmap DELETE /v1/links/lnk_2h6j4n

{ "link_id": "lnk_2h6j4n", "removed_at": "2026-10-20T08:00:00Z", "removed_by": "partner" }

After unlinking:

• Any call on that place answers 410 LINK_REMOVED.
• Your menu leaves the place page within a minute.
• Orders that arrived before the unlink can still be finished for 24 hours, so nothing is stranded in a kitchen.

Common errors