Armada Armada API v2

Invoices

Every wallet top-up and every billing cycle generates an invoice you can inspect via the API. Use these endpoints to reconcile your books against Armada's ledger, build custom accounting dashboards, or export period-based summaries.

Invoice types

The type field tells you what the invoice represents:

  • REGULAR — monthly settlement covering delivery fees accrued in a billing period. The merchant pays these.
  • TOPUP_WALLET / TAP_WALLET — a wallet top-up you made. Armada was paid; it credits your balance. These are always PAID by the time you see them.
  • REFUND_WALLET / REFUND — a refund Armada paid back to you.
  • CUSTOMER_ORDER / WALLET — specialized types that appear on certain merchant configurations. Most partners won't see these.

Status lifecycle

  • ISSUED — generated, awaiting payment.
  • SENT — delivered to the merchant (email / portal).
  • PENDING — payment initiated, not yet confirmed.
  • AUTHORIZED — card authorized for top-ups, not yet captured.
  • PAID — terminal. Money has moved.
  • CANCELED — terminal. Voided — no money moved.
GET /v2/invoices

List invoices

Paginated list. Defaults return the 20 most recent regular invoices in PAID/ISSUED/PENDING/SENT status.

Permission: invoices:read.

Query parameters

Field
Type
Description
page optional
integer
Page number, starting at 1. Default 1.
perPage optional
integer
Results per page, capped at 100. Default 20.
status optional
string
Which bucket to return. Default all mixes paid + unpaid regular invoices.
unpaidpaidtopupall
periodBegin optional
ISO date (YYYY-MM-DD)
Filter to invoices whose periodBegin ≥ this date.
periodEnd optional
ISO date (YYYY-MM-DD)
Filter to invoices whose periodEnd ≤ this date.
GET /v2/invoices 
curl -sS "https://api.armadadelivery.com/v2/invoices?status=paid&page=1&perPage=20" \
  -H "Authorization: Key $ARMADA_API_KEY" \
  -H "x-armada-timestamp: $TS" \
  -H "x-armada-signature: $SIG"

Response

200 OK 
{
  "page": 1,
  "perPage": 20,
  "total": 37,
  "invoices": [
    {
      "id": "670abc12340000000000abcd",
      "invoiceNo": "INV-2026-03-001",
      "type": "REGULAR",
      "status": "PAID",
      "amount": 142.5,
      "currency": "KWD",
      "ordersCount": 318,
      "deliveryTripsCount": 212,
      "periodBegin": "2026-03-01",
      "periodEnd": "2026-03-31",
      "dueOn": "2026-04-15",
      "createdAt": "2026-04-01T00:03:11.204Z"
    }
  ]
}
GET /v2/invoices/:id

Retrieve an invoice

Returns a single invoice. 404 if not found or not owned by this merchant (you can't fetch another merchant's invoice even if you know the id).

Permission: invoices:read.

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

Response

Field
Type
Description
id required
string
24-hex ObjectId.
invoiceNo required
string
Human-readable invoice number.
type required
string
What kind of invoice this is.
REGULARCUSTOMER_ORDERWALLETTOPUP_WALLETREFUND_WALLETREFUNDTAP_WALLET
status required
string
Current state.
ISSUEDPAIDPENDINGSENTCANCELEDAUTHORIZED
amount required
number
Invoice total in currency.
currency required
string
ISO-4217 code.
ordersCount required
integer
Number of deliveries covered by this invoice.
deliveryTripsCount required
integer
Number of delivery trips (grouped orders) covered.
periodBegin required
ISO date
Start of the billing period this invoice covers.
periodEnd required
ISO date
End of the billing period. Invoices are generated monthly.
dueOn required
ISO date
Payment due date. PAID invoices are below this as of createdAt.
createdAt required
ISO-8601 date-time
Generation time.

Common reconciliation patterns

  • Monthly books close. List with status=paid and a fixed periodBegin/periodEnd pair, sum amount.
  • Unpaid backlog. List with status=unpaid — you'll see ISSUED/SENT that haven't been paid yet.
  • Top-up history. List with status=topup — covers TAP_WALLET and top-up variants.
  • Per-order cost breakdown. The invoice carries ordersCount and deliveryTripsCount but not per-order amounts. Cross-reference with GET /v2/deliveries/:id and its deliveryFee field.
← Wallet Webhooks →