Armada Armada API v2

Branches

A branch is a pickup location — the place a driver goes to collect the package. Most merchants register their kitchens, stores, or warehouses as branches and then reference them by id on every delivery. Branches are also used by Armada for reporting, so keeping them clean and specific pays off.

When to create a branch vs use location_format

The v2 API supports two origin shapes on a delivery. Choosing between them:

  • Create a branch for recurring pickup locations — your kitchens, your warehouse bays. Once registered, every order just carries origin.branch_id. The branch shows up in reports, dispatcher heuristics improve (repeated pickups are known addresses), and your order bodies stay small.
  • Use origin_format: location_format for ad-hoc pickups — errand-style deliveries where the pickup is somewhere the driver hasn't been before. Only works for single-branch merchants (see callout below).
GET /v2/branches

List branches

Returns every branch owned by the authenticated merchant.

Permission: branch:read.

GET /v2/branches 
curl -sS https://api.armadadelivery.com/v2/branches \
  -H "Authorization: Key $ARMADA_API_KEY" \
  -H "x-armada-timestamp: $TS" \
  -H "x-armada-signature: $SIG"

Response

A single branches array, each entry using the shape below.

Field
Type
Description
id required
string
24-hex Mongo ObjectId. Use this as origin.branch_id on deliveries.
name required
string
Echoes input.
phone required
string
Echoes input.
address required
string
Echoes input.
latitude required
number
Flattened from location.lat.
longitude required
number
Flattened from location.lng.
created_at required
ISO-8601 date-time
Creation time.
POST /v2/branches

Create a branch

Register a new pickup location. The response's id is what you'll pass as origin.branch_id on deliveries.

Permission: branch:write.

Request

Field
Type
Description
name required
string
Human-readable name shown in the merchant dashboard. Internal — never shown to customers.
phone required
string
Reachable phone number for the pickup. Drivers call this if they can't find the pickup.
address required
string
Free-text address printed on the dispatch sheet. Keep it specific — "Gate 3, Warehouse B" beats "Warehouse."
location.lat required
number
Pickup latitude. Used for dispatching and ETA.
location.lng required
number
Pickup longitude.
POST /v2/branches 
curl -sS -X POST https://api.armadadelivery.com/v2/branches \
  -H "Authorization: Key $ARMADA_API_KEY" \
  -H "x-armada-timestamp: $TS" -H "x-armada-signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{"name":"QA Kitchen","phone":"+96599900000","address":"Salmiya Block 1, Street 1","location":{"lat":29.3359,"lng":48.0758}}'

Response

Field
Type
Description
id required
string
24-hex Mongo ObjectId. Use this as origin.branch_id on deliveries.
name required
string
Echoes input.
phone required
string
Echoes input.
address required
string
Echoes input.
latitude required
number
Flattened from location.lat.
longitude required
number
Flattened from location.lng.
created_at required
ISO-8601 date-time
Creation time.
GET /v2/branches/:id

Retrieve a branch

Fetch a specific branch. 404 if not found or not owned by this merchant.

Permission: branch:read.

GET /v2/branches/:id 
curl -sS https://api.armadadelivery.com/v2/branches/67abc... \
  -H "Authorization: Key $ARMADA_API_KEY" \
  -H "x-armada-timestamp: $TS" -H "x-armada-signature: $SIG"
PUT /v2/branches/:id

Update a branch

Partial update — send only the fields you want to change. Missing fields are left untouched.

Permission: branch:update.

PUT /v2/branches/:id 
curl -sS -X PUT https://api.armadadelivery.com/v2/branches/67abc... \
  -H "Authorization: Key $ARMADA_API_KEY" -H "x-armada-timestamp: $TS" -H "x-armada-signature: $SIG" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+96599911111"}'
DELETE /v2/branches/:id

Delete a branch

Soft-deletes the branch. Historical orders that referenced it still render the branch data they captured at create time. You can't dispatch new orders from a deleted branch.

Permission: branch:delete.

DELETE /v2/branches/:id 
curl -sS -X DELETE https://api.armadadelivery.com/v2/branches/67abc... \
  -H "Authorization: Key $ARMADA_API_KEY" -H "x-armada-timestamp: $TS" -H "x-armada-signature: $SIG"
← Deliveries Wallet →