AWRA OpsHub Search

AWRA Help Center

Copy link
Help Workflow Support
01 Integrations Overview Integrations 02 Connectors Directory Integrations

Developer API

Read your own data programmatically — items, stock, customers, invoices, vendors, purchase orders — create or update items, customers and vendors, raise stock adjustments, transfers, requisitions, purchase orders, invoices, payments and expenses, and decide approvals — with an API key, from your own scripts, spreadsheets or systems.

AWRA publishes an API for your workspace's data: it reads, writes master data, and raises and decides the stock, money and approval records the app does. The reference — every resource, every filter, and copy-and-paste examples — is at the API documentation page. This article covers the parts people get wrong before they read it.

Keys Carry Your Workspace

Create keys at Settings → API Keys, and send one as a bearer token. The key identifies your organization — you do not pass a workspace or company identifier, and a key can never read another organization's data. Keys can be rotated (a new secret under the same name; the old one stops working at once) or revoked (dead immediately). Rotate on a schedule; revoke the moment a key might have leaked.

Treat a key like a password: it belongs in a server-side configuration, not in a browser page, a mobile app, or a repository.

What You Can Read

  • Identity — confirm which workspace a key belongs to.
  • Inventory — items with search, category and low-stock filters, and stock levels.
  • Sales — customers and invoices, filterable by status, customer, issue date, and whether a balance is still due.
  • Procurement — vendors (including preferred-only) and purchase orders by status, payment status, vendor and order date.

What You Can Write

  • Items — create, update and delete (POST /items, PATCH /items/{id}, DELETE /items/{id}) with an inventory:write key. A new item starts at zero stock; stock moves only through adjustments in the product.
  • Customers — create, update and delete with a sales:write key. DELETE on an item, customer or vendor moves it to the trash, only where the app allows it.
  • Vendors — create, update and delete with a procurement:write key. A vendor's payout details are refused here and stay in the product.
  • Stock (stock:write) — POST /stock-adjustments raises a pending check-in or check-out, and POST /stock-transfers a pending transfer. Nothing moves until it is approved.
  • Purchasing (purchasing:write) — POST /purchase-requisitions raises a requisition with its lines, POST /purchase-orders raises the order for an approved quotation, as in the app, and POST /purchase-orders/{id}/cancel cancels one still waiting for its goods.
  • Sales orders (sales_orders:write) — POST /sales-orders creates a draft and POST /sales-orders/{id}/confirm confirms it, reserving the stock.
  • Supplier bills (bills:write) — POST /bills captures a draft and POST /bills/{id}/post posts it. Whoever entered a bill never posts it.
  • Vendor payments (payments:write) — POST /vendor-payments prepares a payment for posted bills and submits it for a second person's approval.
  • Expense claims (claims:write) — POST /expense-claims files a claim for the employee record linked to the key's owner, and POST /expense-claims/{id}/submit submits it.
  • Invoices and payments (invoices:write) — POST /invoices creates a draft, POST /invoices/{id}/issue issues it (eTIMS files at issue where your workspace files), and POST /invoices/{id}/payments records what the customer paid.
  • Expenses (expenses:write) — POST /expenses records an expense; a payable waits for approval where your organization requires it.
  • Approval decisions (approvals:write) — POST …/{id}/decision approves or rejects a pending adjustment, transfer, requisition, expense, expense claim or vendor payment; POST /quotations/{id}/award awards a quotation and POST /purchase-orders/{id}/sign-off signs a received order off for payment.

A write needs a write scope by name, or the developer:write umbrella — except approval decisions, which need approvals:write by name. Keys created before 30 October 2026 that held sales:write or developer:write were given invoices:write and approvals:write, so they behave as they did. A read key, including the developer:read umbrella, never writes. Every write is recorded in your audit log against the key that made it.

Stock, money and approval writes act as the person who created the key. That person's permissions, plan and your approval rules apply, exactly as if they had pressed the button. A key can never decide something its owner raised. Raise with one person's key and decide with another's. The key list in Settings shows that person beside each key, under Acts as; rotating a key makes whoever rotated it the person. A key whose creator has left the workspace is refused. These writes also require an Idempotency-Key header: a retry with the same key returns the first result instead of a second write.

A key that misbehaves is reported at once. AWRA watches each key's last hour for four patterns: a burst of calls far above its usual week, at least half its calls refused or failing, repeated sign-in refusals (a revoked key still in use, or calls from outside your IP allowlist), and a caller trying endpoint after endpoint its scopes do not open. Any of them opens an exception and emails the people who manage integrations or API keys, with a copy in their bell. Each key raises at most one alert an hour, and the request log under API usage shows what it did. Revoke or rotate the key from the same screen.

Retrying Safely

Money and stock actions, such as POS sales and payments, stock check-ins, check-outs and transfers, invoice and bill payments, payment runs, payouts, journals and payroll posting, accept the same Idempotency-Key header. The key is scoped to your workspace, the caller and the endpoint. A repeat with the same key and the same body gets the first response back and does not run again. The same key with a different body is refused with 409, as is a repeat that arrives while the first is still running. A validation error is not stored, so you can correct the request and send it again under the same key. Generate one key per intended action, and reuse it only to retry that action. The AWRA mobile app sends a key on these actions; web forms do not yet.

Paging: Numbered Pages Or A Cursor

Lists are paginated — 25 by default, up to 100 per request. Which paging mode you choose matters once your data is large:

  • Numbered pages are fine for browsing and for small result sets, and give you a total.
  • Cursor paging is what you want to read a whole resource. Page 1,000 costs what page 1 costs, and no row is skipped or duplicated if records change while you are paging. Follow the next link the response gives you; do not build cursors yourself, and do not expect a total.

Sync Incrementally

Ask for what changed rather than re-reading everything: an updated since timestamp returns only records modified at or after that moment. Store the time of your last successful run and pass it next time. An unparseable timestamp is rejected with an error rather than silently ignored — which is deliberate, because a silently ignored filter would hand you a full export while you believed you were syncing a delta.

Good Manners

  • Filter on the server, not in your script. Every resource has filters; use them instead of downloading everything and discarding most of it.
  • Handle failure. Retry with a delay; never hammer a failing endpoint in a tight loop. Every error comes back in the standard RFC 7807 problem format (application/problem+json), with a code to branch on and, for a validation failure, each field's messages.
  • Do not poll for events. If you need to react to something happening, subscribe to an outbound webhook (below), or drive it from Workflow Automation or a connector rather than a loop asking whether it happened yet.

Outbound Webhooks: AWRA Tells You

Instead of polling, subscribe a URL of yours to an event. Open Settings → Webhooks & API, add a webhook endpoint, choose the event and keep the signing secret it shows you once. You can send a test delivery from the same list. The events you can subscribe to:

EventSent when
order.shippedA stock transfer is completed.
invoice.createdA customer invoice is created.
invoice.paidA customer invoice is paid in full.
purchase_order.createdA purchase order is created.
customer.createdA customer is created.
vendor.createdA vendor is created.
item.low_stockAn item falls to its reorder point.
workflow.webhookOnly when a workflow action names this endpoint.

Verifying a delivery. Every delivery is a POST carrying the headers X-Awra-Event, X-Awra-Delivery (unique per delivery, so you can ignore a repeat), X-Awra-Timestamp and, when the endpoint has a secret, X-Awra-Signature. The signature is sha256= followed by the hex HMAC-SHA256 of the timestamp, a full stop, and the raw request body, keyed with your secret. Recompute it on your side, compare in constant time, and reject a timestamp that is far from now.

Retries. A delivery that fails with a connection error, a timeout, a 5xx, 408, 425 or 429 is retried; any other 4xx is taken as your answer and not retried. Each endpoint’s Retry Policy sets the attempts (default 3, at most 8, first try included) and the starting wait (default 30 seconds), which doubles on each retry up to one hour. A delivery that runs out of attempts is dead-lettered: it shows in the delivery log, the endpoint is marked failing, and it lands in the integration failure digest.

Where it may send. The URL must be https:// and reach a public address. Private, internal and loopback addresses are refused when you save the endpoint and again at send time, the address is looked up once and pinned for the delivery, and redirects are not followed.

What It Writes, And How

It writes master data — items, customers and vendors — and the stock, money and approval records listed above. Each one goes through the same actions as the app, so a receipt above its order, a location outside its warehouse, a payment above the balance or an approval above someone's threshold is refused through the API as it is on screen. An item's stock changes only through adjustments, and a supplier's payout details only in the app under dual control. To load records in bulk, use the import templates on the module you are loading, or the connectors. To move data between AWRA and another system on a schedule, look at Integrations first — it is usually already built.

Feature overview: Developer API.

Need help with this topic?

Capture the module, record number, branch or warehouse, user, visible message, and what you expected to happen before contacting support.

Open support guide