SupplyWise REST API v1
REST API for third-party integrations. Two authentication methods are
supported, both via the Authorization: Bearer <token> header:
- API keys — issued from Supplier → Settings → API Keys. Scoped to one supplier. Best for server-to-server integrations (analytics syncs, accounting bridges, etc.).
- OAuth 2.1 — same OAuth server as the MCP endpoint; a single access token works for both MCP and REST. Scoped to the user (access to every supplier they belong to). Best for end-user-facing integrations.
- Base URL:
https://actions.supplywise.com.au(the Convex deployment URL also works if you're hitting a non-production environment) - Content-Type:
application/jsonfor request and response bodies - CORS:
*allowed (third-party browser clients work) - Rate limits: there is no hard per-endpoint rate limit at the moment. Convex queries are cheap, but please keep concurrent in-flight requests to ≤ 10 per supplier and use the cursor-based incremental sync (see below) rather than re-pulling the full history on every run. Get in touch if you need to sustain anything heavier.
- History: every order ever created against the supplier is available — there is no rolling window. You can backfill 12–24 months of trend data on the first sync and then incrementally pull deltas.
Quick reference
Every REST endpoint below also has an equivalent tool on the SupplyWise MCP
server (/mcp, OAuth-only) — e.g. POST .../orders ↔ create_order,
GET .../customers/{customerId}/products ↔ get_customer_products (the MCP
tool is PAGED — 100 compact products per call by default, with search,
limit, offset and detail: 'full'; the REST route still returns the whole
catalogue in full detail),
GET .../credit-notes ↔ list_credit_notes,
POST .../send-confirmation ↔ send_order_confirmation, and
GET .../orders/{orderReference}/pdf ↔ get_order_pdf (which returns the PDF
inline as a base64 application/pdf resource blob, plus a downloadUrl in the
text part for clients that would rather fetch it — same
Authorization: Bearer <token> header). If you're wiring up an AI assistant,
prefer the MCP server. The relationship is one-way: every REST endpoint has an
MCP equivalent, but the MCP server has many more tools than REST has
endpoints — it covers most of the supplier dashboard (orders, customers,
products, price lists, inventory, purchasing, and more; list_toolsets and
find_tools list them). REST is not being extended to match.
| Method | Path | Purpose |
|---|---|---|
GET | /api/v1/suppliers | List suppliers the token can access |
GET | /api/v1/suppliers/{supplierId}/customers | Search/list customers |
GET | /api/v1/suppliers/{supplierId}/customers/{customerId}/products | List a customer's available products (with their pricing) |
GET | /api/v1/suppliers/{supplierId}/orders | Incremental order sync (cursor + filters, includes line items) |
POST | /api/v1/suppliers/{supplierId}/orders | Create an order on behalf of a customer |
GET | /api/v1/suppliers/{supplierId}/orders/{orderReference} | Fetch a single order by reference (SWO-1234) |
GET | /api/v1/suppliers/{supplierId}/orders/{orderReference}/pdf | Download the order's tax-invoice PDF (application/pdf) |
POST | /api/v1/suppliers/{supplierId}/orders/{orderReference}/send-confirmation | Send the order confirmation for an order (e.g. one created with sendConfirmationEmail: false) |
GET | /api/v1/suppliers/{supplierId}/credit-notes | Incremental credit note sync (cursor + filters) |
API key authentication
The simplest option. A supplier owner creates a key in
Settings → API Keys, gives it a name, and copies the generated value
(format: swsk_<64 hex chars>). The full value is shown exactly once — store
it somewhere safe; SupplyWise only retains a SHA-256 hash.
Each request:
curl https://actions.supplywise.com.au/api/v1/suppliers \
-H "Authorization: Bearer swsk_<your-key>"
Properties:
- Scoped to the single supplier the key was issued for. The supplier ID is
inferred from the key, so
GET /api/v1/suppliersreturns just the one supplier and you can use that ID in subsequent paths. - Revocable at any time from the same settings page. Revoked keys are rejected immediately.
- Only supplier owners can create or revoke keys.
lastUsedAtis recorded so you can spot keys that are no longer in use.
For sandboxing: create a separate API key against the Test Supplier account on staging (ask your SupplyWise contact for an invite). The same endpoints and schemas are available against the staging deployment URL.
API keys are independent of the OAuth flow — you don't need to register an OAuth client or run an authorization redirect.
OAuth authentication
Use OAuth when the integration acts on behalf of a logged-in SupplyWise user (so it can access every supplier they belong to without each one having to issue an API key).
The OAuth metadata is RFC 8414 / RFC 9728 compatible. Most generic OAuth
clients can discover everything from WWW-Authenticate on a 401.
GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource
The path-suffixed forms (RFC 9728 §3.1 / RFC 8414 §3.1) are served too, and
return the same documents — /.well-known/oauth-protected-resource/mcp,
/.well-known/oauth-protected-resource/api/v1, and
/.well-known/oauth-authorization-server/mcp. Clients that probe those first
no longer get a 404.
GET /mcp in a browser answers 405 Method Not Allowed with a short JSON
explanation and the same WWW-Authenticate challenge as an unauthenticated
POST — the MCP endpoint itself only speaks JSON-RPC over POST.
Endpoints:
| Endpoint | Purpose |
|---|---|
POST /oauth/register | Dynamic client registration (RFC 7591). Returns client_id. No client secret. |
GET /oauth/authorize | Redirects to SupplyWise login (Clerk). On consent, redirects back with ?code=.... |
POST /oauth/token | Exchange code + code_verifier for tokens. Also accepts grant_type=refresh_token to rotate. |
Token lifetimes:
- Access token: 24 hours.
- Refresh token: sliding 60-day window. Each successful refresh issues a new refresh token whose expiry is reset to 60 days from that moment, so an integration that refreshes at least once every 60 days stays connected indefinitely.
Refresh tokens are rotated on use (OAuth 2.1 best practice). The previous refresh token is immediately revoked when you exchange it. If an already-rotated refresh token is presented a second time, SupplyWise treats it as a possible compromise and revokes the entire rotation chain — the user will need to re-authorize. Store the latest refresh token returned by every /oauth/token call.
Walkthrough
-
Register your client (one-time):
curl -X POST https://actions.supplywise.com.au/oauth/register \ -H 'Content-Type: application/json' \ -d '{"client_name":"My Workflow Tool","redirect_uris":["https://my-tool.example.com/oauth/callback"]}'Store the returned
client_id.redirect_urisis required, and it is binding. Every URI you register is validated at registration time and stored; at the consent screen yourredirect_urimust be an exact string match for one of them (no normalisation, no trailing-slash leniency, no prefix or wildcard matching). Register every callback you will use, then send exactly one of them.Redirect URI rules:
https://…— always fine.http://…— loopback only:localhost,127.0.0.1or[::1], on any port and any path (OAuth 2.1 / RFC 8252 §7.3).httpto any other host is rejected withinvalid_redirect_uri.- Private-use schemes for native/desktop apps are supported —
myapp://callback,com.example.app:/oauth2redirect(RFC 8252). - No fragments, and the
javascript:,data:,vbscript:,file:,blob:andabout:schemes are refused. - At most 10 redirect URIs, 2048 characters each;
client_nameat most 200 characters.client_nameis shown to the user on the consent screen.
Invalid metadata returns
400with an RFC 7591 §3.2.2 body —{"error":"invalid_redirect_uri"}or{"error":"invalid_client_metadata"}— and anerror_descriptionnaming the problem.Requested
grant_typesandtoken_endpoint_auth_methodare ignored: every client is a public client using PKCE, and the response always saysauthorization_code+refresh_token,response_types: ["code"],token_endpoint_auth_method: "none". -
Send the user to authorize, with a PKCE pair:
https://actions.supplywise.com.au/oauth/authorize ?response_type=code &client_id=<client_id> &redirect_uri=https://my-tool.example.com/oauth/callback &code_challenge=<base64url(sha256(verifier))> &code_challenge_method=S256 &state=<csrf-token>The user logs in via Clerk and is redirected to your
redirect_uri?code=...&state=.... -
Exchange the code for a token:
curl -X POST https://actions.supplywise.com.au/oauth/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=authorization_code' \ -d 'code=<code>' \ -d 'code_verifier=<verifier>' \ -d 'redirect_uri=https://my-tool.example.com/oauth/callback'Returns:
{ "access_token": "...", "token_type": "Bearer", "expires_in": 86400, "refresh_token": "...", "scope": "orders:read orders:write dashboard" }scopeis what the user approved on the consent screen. The REST API does not check it.dashboardmatters only to the MCP server's dashboard tools. A token issued before that scope existed showsorders:read orders:write, and a refresh keeps the original scope. -
Call the API with
Authorization: Bearer <access_token>. -
Refresh before (or after) the access token expires:
curl -X POST https://actions.supplywise.com.au/oauth/token \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=refresh_token' \ -d 'refresh_token=<refresh_token>'Returns a new
access_tokenAND a newrefresh_token. Persist both — the refresh token you just sent is now revoked, and only the new one will work next time.
Pagination model (used by /orders and /credit-notes)
The high-volume list endpoints share the same forward-only cursor model,
with two modes chosen by whether you pass updatedSince:
Mode A — creation-time sync (default)
The primary "catch up on new rows" loop. Results are sorted by creation
time ascending (oldest first). The cursor is a row id; after=<id>
returns rows strictly newer than that id's creation time.
- Pass
?after=<id>to bookmark where you left off. The id you pass is not included in the result.nextCursorin the response is the bookmark for the next call. - Pass
?limit=Nto choose the page size. Default and maximum 100. - Optional
createdSince/createdUntilfurther bound the_creationTimerange (unix ms or ISO-8601).
Mode B — changed-since sync (updatedSince set)
The secondary "pick up state changes on rows I've already seen" loop.
Pass updatedSince=<unix-ms or ISO-8601> and results are sorted by
updatedTime ascending. Every order / credit note write path bumps
updatedTime, so this catches payments, shipping status changes, MYOB
sync transitions, etc.
Behind the scenes this hits a dedicated supplierId_updatedTime compound
index, so the cost is O(rows-changed-since-T), not O(rows-total) —
safe to run on a busy supplier with hundreds of thousands of historic
orders.
after=<id> still works in Mode B, but its meaning shifts: it skips
past the cursor row in updatedTime order, not _creationTime.
That means a cursor obtained from a Mode-A call is not a valid
cursor for a Mode-B call (or vice-versa) — persist them separately,
under different keys, if you run both loops.
Cursor invalidation and other behaviour
- If you pass an
afterthat doesn't exist (or belongs to a different supplier), the endpoint returns an empty page rather than silently ignoring the cursor. Treat that as "cursor invalid — reseed from the last known good id, fromcreatedSince, or fromupdatedSince". - When there are no more rows,
hasMoreisfalseandnextCursoris the id of the last row you saw (so re-running the same call returns zero new rows until something appears). - For the
updatedAtvalue returned on each row: rows that have never been edited fall back to_creationTime, so this field is always populated.
Recommended sync loop
Persist two cursors per supplier — creation_cursor and
updated_cursor — and run two passes each tick:
# Pass 1 — catch new orders
cursor = creation_cursor or null
loop:
resp = GET /orders?after={cursor or omit}&limit=100
process(resp.data)
cursor = resp.nextCursor
if !resp.hasMore: break
creation_cursor = cursor
# Pass 2 — catch state changes on previously-ingested orders
cursor = updated_cursor or null
loop:
resp = GET /orders?updatedSince={last_run_started_at}&after={cursor or omit}&limit=100
process(resp.data)
cursor = resp.nextCursor
if !resp.hasMore: break
updated_cursor = cursor
Webhooks are not currently offered — please use the cursor model.
Endpoints
All requests require a valid bearer token. The token grants access to every supplier the authenticated user belongs to. Cross-tenant requests return 403.
GET /api/v1/suppliers
List the suppliers the authenticated token can access.
{
"data": [{ "id": "j57...", "name": "Test Supplier", "slug": "testsupplier" }]
}
GET /api/v1/suppliers/{supplierId}/customers
List customers belonging to a supplier.
Query params (all optional):
customerType—retail|wholesalearchived—true|false(defaults to hiding archived;archived: trueis the SupplyWise equivalent of "inactive")search— case-insensitive free-text match. Substring-matches against the customer'sname, the venue'sname, and the venue'sbusinessNamelimit— page size (1–100, default 50)
Each customer carries:
-
id,name,customerType(retail|wholesale),archived -
category— the supplier-defined customer category (e.g."Distributor","Direct","Tier A"). Use this for grouping in analytics. -
payUpfront,paymentTermsType,payWithinDays,paymentTermsDayOfMonth— payment terms.payUpfront: truemeans the customer pays before the order ships (the rest is then ignored). OtherwisepaymentTermsType(always returned explicitly) says how an invoice falls due:"daysAfterInvoice"—payWithinDaysdays after the invoice date ("Net 30 days"). The default."daysAfterEndOfMonth"—payWithinDaysdays after the end of the calendar month the invoice was raised in ("30 days EOM";0= the last day of that month)."dayOfFollowingMonth"— on daypaymentTermsDayOfMonth(1–31) of the month after the invoice month. A day past the end of that month means its last day, so31is "end of the following month". For these customerspayWithinDaysis not used (it is normally0) and must not be read as a day count.
payWithinDaysis a whole number ≥ 0 for every customer whose terms have been saved since these rules were introduced; treat anything else as legacy data.paymentTermsDayOfMonthisnullunless the type is"dayOfFollowingMonth". Month boundaries are in the supplier's timezone. -
creditLimitCents— the most an on-account wholesale customer may owe the supplier at once, in integer cents incl. GST (it is compared with what they owe on unpaid orders, which is incl. GST;500000= $5,000.00), ornullfor no limit (none set, or the customer ispayUpfront/ retail). Once an order leaves the customer owing more than this on their unpaid orders, their ordering block is switched on automatically: they are emailed a statement and the web store and mobile app stop taking new orders until it is paid. The limit never refuses an order itself — orders created through this API still go through, and count towards what is owed. -
venue— contact + business details (ABN, billing/shipping address, phone, email) -
xeroContactId/myobContactId— for matching against accounting systems
{
"data": [
{
"id": "...",
"name": "Test Venue Main",
"customerType": "wholesale",
"archived": false,
"category": { "id": "...", "name": "Distributor" },
"venue": {
"id": "...",
"name": "Test Venue",
"businessName": "Test Pty Ltd",
"abn": "...",
"billingAddress": { ... },
"shippingAddress": { ... }
},
"payUpfront": false,
"payWithinDays": 30,
"paymentTermsType": "daysAfterInvoice",
"paymentTermsDayOfMonth": null,
"creditLimitCents": null
}
],
"hasMore": false
}
GET /api/v1/suppliers/{supplierId}/customers/{customerId}/products
List the products available to that customer, with customer-specific pricing applied (price lists, customer-group filters, etc. — same rules as the in-app order creation form).
By default only products with status active are returned. Products with
status hidden (set up but not shown in the storefront) are excluded.
Query params (all optional):
includeHidden—true|false(defaultfalse). Whentrue, products with statushiddenare returned alongsideactiveones. Use thestatusfield on each product to tell them apart.
{
"data": [
{
"id": "...",
"name": "Single Origin Espresso 1kg",
"sku": "SO-ESP-1KG",
"description": "...",
"status": "active",
"salesCode": "200",
"chargeGST": true,
"weight": 1000,
"stockStatus": "in-stock",
"stockLevel": 42,
"allowFractionalQuantities": false,
"categories": ["Coffee"],
"customerPrice": { "amountCents": 4500, "currency": "aud" },
"originalPrice": { "amountCents": 5000, "currency": "aud" },
"unitPriceExGstCents": 4091,
"gstCents": 409
}
],
"pricesExGst": false
}
customerPrice / originalPrice — incl. GST for a GST-bearing product
(chargeGST: true), like every stored price. unitPriceExGstCents is the
customer's price ex GST (customerPrice ÷ 1.1, rounded to the cent; the same
as customerPrice for a GST-free product). gstCents is the GST in
customerPrice (customerPrice − unitPriceExGstCents; 0 for a GST-free
product). For a customer the supplier has marked international (GST-free),
every product comes back with chargeGST: false, customerPrice already ex
GST and gstCents: 0.
pricesExGst — true when this customer is quoted and charged ex GST (a
wholesale customer of a supplier that quotes wholesale prices ex GST; their
orders come back with lineGstBasis: "excl-gst"). Quote such a customer
unitPriceExGstCents plus GST: their store shows $40.91 ex GST, not $45.00.
categories — names of the supplier's product categories this product is in
(empty array when uncategorised).
allowFractionalQuantities — when true the supplier sells this product in
fractional quantities (e.g. by weight): POST .../orders accepts a fractional
quantity (up to 3 decimal places) for it. When false (the default),
quantities must be whole numbers.
GET /api/v1/suppliers/{supplierId}/orders
Incremental order sync. Returns finalised orders (status active) plus
voided orders (voided) so you can both ingest sales and reverse out
cancellations. Cart / draft rows are never returned. Line items are
included inline.
Query params (all optional):
after— order id from a previous response'snextCursor(the "bookmark")limit— page size, 1–100, default 100status—active|voided. Omit for both (default).orderType—retail|wholesaleorderCategory— free-text category tag (e.g.Service). Optional supplier-set classification, orthogonal toorderType(a service order is still retail or wholesale). Matched case-insensitively against the supplier's saved categories. Most orders have no category; omit to return all orders.paymentStatus—paid|unpaid|paid-awaiting-settlement|awaiting-refund|refund-initiated|refund-failed|refunded(a part-paid order isunpaid— seepaidAmountCents/amountDueCentsbelow)shippingStatus—pending|processing|shipped|delivered|cancelled|awaiting-pickup|pickup-completedcreatedSince,createdUntil— unix ms or ISO-8601 bounds on the order creation timeupdatedSince— unix ms or ISO-8601; only return orders updated at/after this time
Response shape:
{
"data": [
{
"id": "j57...",
"orderReference": "SWO-1234",
"orderNumber": 1234,
"orderStatus": "active",
"orderType": "wholesale",
"orderCategory": null,
"createdAt": 1735603200000,
"updatedAt": 1735603500000,
"customer": {
"id": "...",
"name": "Test Venue Main",
"customerType": "wholesale",
"archived": false,
"category": { "id": "...", "name": "Distributor" }
},
"venue": {
"id": "...",
"name": "Test Venue",
"businessName": "Test Pty Ltd"
},
"paymentStatus": "paid",
"paymentMethod": "zai_card",
"paymentDueDate": null,
"shippingStatus": "delivered",
"pickupOrDelivery": "delivery",
"deliveryDate": "2026-05-20",
"pickupWindow": null,
"shippingAddress": {
"addressLine1": "1 Test St",
"addressLine2": "",
"suburb": "Sydney",
"state": "NSW",
"postcode": "2000",
"country": "AU"
},
"purchaseOrderNumber": "PO-99",
"notes": "Leave at back gate",
"deliveryNotes": null,
"supplierNotes": null,
"lineGstBasis": null,
"totals": {
"itemsTotal": {
"exclGst": { "amountCents": 8182, "currency": "aud" },
"inclGst": { "amountCents": 9000, "currency": "aud" },
"gst": { "amountCents": 818, "currency": "aud" }
},
"shippingTotal": {
"exclGst": { "amountCents": 0, "currency": "aud" },
"inclGst": { "amountCents": 0, "currency": "aud" },
"gst": { "amountCents": 0, "currency": "aud" }
},
"subtotal": {
"exclGst": { "amountCents": 8182, "currency": "aud" },
"inclGst": { "amountCents": 9000, "currency": "aud" },
"gst": { "amountCents": 818, "currency": "aud" }
},
"orderTotal": {
"exclGst": { "amountCents": 8182, "currency": "aud" },
"inclGst": { "amountCents": 9000, "currency": "aud" },
"gst": { "amountCents": 818, "currency": "aud" }
},
"amountToPay": {
"exclGst": { "amountCents": 8182, "currency": "aud" },
"inclGst": { "amountCents": 9000, "currency": "aud" },
"gst": { "amountCents": 818, "currency": "aud" }
},
"discountPercentage": null,
"discountAmount": null
},
"orderTotalCents": 9000,
"amountToPayCents": 9000,
"paidAmountCents": 9000,
"amountDueCents": 0,
"xeroInvoiceStatus": "synced",
"myobInvoiceStatus": null,
"invoiceReference": "INV-1234",
"items": [
{
"id": "...",
"productId": "...",
"productName": "Single Origin Espresso 1kg",
"productSku": "SO-ESP-1KG",
"productDescription": "...",
"salesCode": "200",
"quantity": 2,
"unitOfMeasure": "unit",
"unitPriceIncGstCents": 4500,
"unitPriceExGstCents": 4091,
"lineRevenueIncGstCents": 9000,
"lineRevenueExGstCents": 8182,
"chargeGST": true,
"options": [],
"weightGrams": 1000
}
]
}
],
"hasMore": true,
"nextCursor": "j57..."
}
weightGramsisnullwhen the product has no configured weight, andshippingAddressisnullwhen neither the order nor the customer's venue has one set.
Notes on the order shape:
orderReference— human-readable identifier (SWO-{orderNumber}). Unique per supplier but not globally unique. Use the opaqueidfor cross-references.invoiceReference— the invoice number (the XeroInvoiceNumber/ MYOBNumber),{prefix}-{orderNumber}. The prefix is configurable per supplier (defaultSWI, e.g.SWI-1234; a supplier usingBRWgetsBRW-1234). A prefix change only applies to new invoices — an order keeps the invoice number it was issued with, so one supplier's orders can carry different prefixes. Treat it as an opaque string; don't parse the order number out of it (useorderNumber/orderReference). A supplier can let MYOB assign the invoice number instead (Settings > Integrations > MYOB, "Let MYOB number my invoices"). For those suppliers the MYOBNumberis MYOB's own, thisinvoiceReferenceis written into the MYOB invoice's Journal Memo asSupplyWise {invoiceReference}, and the MYOB number is stored on the order (orders.myobInvoiceNumber) but is not exposed by this API. (The MYOB invoice's Customer PO No. field carries the customer's own PO number —purchaseOrderNumberon the order — not this.)orderStatus:active— finalised order. Counts as a sale.voided— cancelled/reversed. Subtract from your sales totals.
pickupWindow— pickup orders only: the pickup time window the customer chose at checkout,{ "start": "07:00", "end": "09:00" }(24-hourHH:mmin the supplier's timezone, ondeliveryDate), when the supplier offers pickup time windows; otherwisenull.- Voided orders + credit notes: when a supplier cancels an active
order it flips to
orderStatus: "voided". Partial refunds and returns come through as credit notes — seeGET /credit-notes. A credit note linked to a specific order carries that order'sorderReferencein theorderReferencefield. orderTotalCents/amountToPayCents— flat convenience mirrors oftotals.orderTotal.inclGst.amountCentsandtotals.amountToPay.inclGst.amountCents(both incl. GST, in cents).orderTotalCentsis the invoice total;amountToPayCentsis the total payable after any credit notes were applied (plus any card surcharge). It is not reduced by payments already made — useamountDueCentsfor what the customer still owes. Prefer these for simple integrations; the nestedtotalsobject carries the full ex-GST/GST split.paidAmountCents/amountDueCents— part payments (incl. GST, in cents).paidAmountCentsis the money recorded against the order so far (card, direct debit, bank transfer, or a payment the supplier recorded by hand).amountDueCentsis what the customer still owes:amountToPayCents − paidAmountCents, floored at 0, for anactiveorder whosepaymentStatusisunpaid, and0for every other order (paid, settling, in the refund lifecycle, or voided). A part-paid order keepspaymentStatus: "unpaid"— there is no separate status — so tell it apart withpaidAmountCents > 0. It becomespaid(orpaid-awaiting-settlement) once the remainder is paid. Recording a part payment bumpsupdatedAt, so a changed-since sync (updatedSince) picks it up. To reconcile:amountDueCentsis the open balance to show on a statement or receivable; don't subtractpaidAmountCentsfromamountToPayCentsyourself.- Revenue ex GST: every line item has both
lineRevenueIncGstCentsandlineRevenueExGstCents. The customer-specific (post-discount) unit price is already baked in. lineGstBasis— how the order's GST was worked out, line by line.null(almost every order): each line is priced inc GST (lineRevenueIncGstCents=unitPriceIncGstCents×quantity) and its GST is back-calculated from that."excl-gst": the supplier quotes wholesale prices ex GST, so each GST line is priced ex GST (lineRevenueExGstCents=unitPriceExGstCents×quantity), its GST is 10% of that (rounded to the cent), andlineRevenueIncGstCentsis the two added together. Either way, the lines'lineRevenueIncGstCentsadd up tototals.itemsTotal.inclGst. TheirlineRevenueExGstCentsadd up tototals.itemsTotal.exclGstonly for"excl-gst"orders. On an"excl-gst"order,unitPriceIncGstCents×quantitycan differ fromlineRevenueIncGstCentsby a few cents (200 × $2.45 ex is $539.00 inc, while the stored inc unit $2.70 × 200 is $540.00); use the line figures. On other orders,lineRevenueExGstCentsisunitPriceExGstCents×quantity($2.45 × 200 = $490.00), which can differ by a few cents from the ex-GST amount the invoice charges, worked out from the line's inc total ($540.00 inc is $490.91 ex). The value is fixed when the order is created and never changes afterwards, even if the supplier later changes the setting. GST-free lines (chargeGST: false) are the same under both.- Pack size / unit of measure: SupplyWise records
quantityin units configured by the supplier — there is no separate pack-size field on a product. Quantities are whole numbers, except for products flaggedallowFractionalQuantities(seeGET .../products), where they may carry up to 3 decimal places (e.g.1.5for a product sold by weight).unitOfMeasureis always"unit"(kept on the payload for forward-compat). If you need product-level pack-size metadata, the supplier should encode it inproductName/productDescription(e.g."Espresso 1kg — case of 6"). - Branch / entity: SupplyWise does not currently model a separate
branch or business entity on an order. A single API key /
supplierIdcorresponds to one trading entity. If a supplier operates multiple branches, they appear as separate suppliers in SupplyWise (and each one issues its own API key).
POST /api/v1/suppliers/{supplierId}/orders
Create an order on behalf of a customer. Mirrors the supplier "create on
behalf of" flow in the web app — by default the customer receives the same
order confirmation email they would normally get. Set
sendConfirmationEmail: false to suppress that email.
Request body:
{
"customerId": "...",
"selectedProducts": [
{
"productId": "...",
"quantity": 2,
"optionsSelected": [
{
"productOptionId": "...",
"name": "Grind",
"value": "Espresso",
"feeAmountCents": 0
}
],
"customPrice": { "amountCents": 4500, "currency": "aud" }
}
],
"purchaseOrderNumber": "",
"notes": "",
"shippingAddress": {
"addressLine1": "1 Test St",
"addressLine2": "",
"suburb": "Sydney",
"state": "NSW",
"postcode": "2000",
"country": "AU"
},
"pickupOrDelivery": "delivery",
"requestedDeliveryDate": "2026-05-20",
"sendConfirmationEmail": true,
"shippingStatus": "processing",
"orderCategory": "Service"
}
Fields:
customerId(required) — id fromGET .../customersselectedProducts(required, non-empty) — items must havequantity > 0. An order with no items (empty array, or all quantities<= 0) is rejected with422. Each item is:productId(required) — id fromGET .../products. Every id must resolve to a product available to this customer; if any id is unknown or unavailable the whole request is rejected with422listing the bad ids (no partial order is created).quantity(required) — number> 0. Whole numbers only, unless the product hasallowFractionalQuantities: true(seeGET .../products), in which case fractional quantities with up to 3 decimal places are accepted (e.g.1.5). A fractional quantity on a product without the flag is rejected with422.optionsSelected(required) — array of selected product options; use[]if none. Each option is an object:productOptionId(required) — id of the product optionname(required, string) — option group name, e.g."Grind"value(required, string) — chosen value, e.g."Espresso"feeAmountCents(optional, integer) — surcharge for this option, in cents. It is added to the unit price, so it is on the same basis ascustomPrice: incl. GST for a GST-bearing product.
customPrice(optional) — override the unit price. Object{ "amountCents": <integer cents>, "currency": "aud" }, incl. GST for a GST-bearing product (like every stored price). If omitted, the customer's normal (post-discount) price applies. For a supplier that quotes wholesale prices ex GST (orders come back withlineGstBasis: "excl-gst"), send the ex-GST price × 1.1 rounded to the cent — e.g. $2.45 ex GST →270. The order charges exactly $2.45 ex GST per unit.
pickupOrDelivery(required) —pickup|delivery|deliver-with-existing-ordershippingAddress(optional) — all six fields are strings. If omitted, the order uses the customer's venue shipping address (and may benullin the response if neither is set). Applies to both pickup and delivery.purchaseOrderNumber,notes(optional, default"")requestedDeliveryDate(optional) —YYYY-MM-DD. Accepted for both pickup and delivery orders (interpreted as the requested pickup date whenpickupOrDeliveryispickup).sendConfirmationEmail(optional, defaulttrue) — set tofalseto suppress all order confirmation notifications (email, push, and in-app) to supplier and venue users. Until a confirmation is sent (via thesend-confirmationendpoint below, or by a supplier user from the SupplyWise UI) the order page in the supplier dashboard shows "The customer hasn't been notified about this order yet" with a Notify customer button, and that first confirmation is worded as a new order rather than an update.shippingStatus(optional) — initial shipping status for the order:pending|processing|shipped|delivered|cancelled|awaiting-pickup|pickup-completed. If omitted, defaults topendingfor delivery orders andawaiting-pickupfor pickup orders (orpendingwhen the supplier has turned on "New pickup orders start as Pending").orderCategory(optional) — free-text category tag, e.g."Service". Supplier-set classification, orthogonal toorderType(retail/wholesale). Works like a tag: if it matches one of the supplier's existing categories (case-insensitive) the existing tag's casing is reused, otherwise a new category is created and remembered — it then appears in the category dropdown in the SupplyWise UI and can be reused on future orders. If omitted the order is left uncategorised (nullin responses). An empty/whitespace-only value is rejected with400. You can filter by it later withGET .../orders?orderCategory=Service(also case-insensitive).
Returns 201 with the created order wrapped in a data envelope:
{ "data": { ...order } }. The order object has the same shape as a single
record in the GET /orders response (including items).
GET /api/v1/suppliers/{supplierId}/orders/{orderReference}
Look up a previously-created order by its reference (e.g. SWO-1234).
Returns the same shape as a single record in the GET /orders response.
GET /api/v1/suppliers/{supplierId}/orders/{orderReference}/pdf
Download the tax-invoice PDF for an order (the same PDF the supplier can download from the platform and that is attached to confirmation emails).
Unlike the other endpoints, the response body is the raw PDF file, not JSON:
Content-Type: application/pdfContent-Disposition: attachment; filename="SWO-1234.pdf"
curl -sS \
"$BASE/api/v1/suppliers/$SUPPLIER_ID/orders/SWO-1234/pdf" \
-H "Authorization: Bearer $TOKEN" \
-o SWO-1234.pdf
Errors are still returned as JSON (with the usual { "error": { ... } }
shape): 404 if the order doesn't exist for this supplier, 401/403 for
auth failures.
POST /api/v1/suppliers/{supplierId}/orders/{orderReference}/send-confirmation
Send the order confirmation for an existing order. This is the companion to
the POST /orders sendConfirmationEmail: false option — use it to deliver
the confirmation later (or to re-send it). It does exactly what creating the
order with sendConfirmationEmail: true would have done: the same
confirmation email to the supplier and venue, plus push / in-app
notifications.
- No request body is required (send an empty
POST). - The order must be
active. Avoided(or otherwise non-active) order has no confirmation to send and returns422. - The underlying email is idempotency-keyed for 24 hours, so a duplicate call shortly after the first won't deliver the email twice.
curl -X POST \
"$BASE/api/v1/suppliers/$SUPPLIER_ID/orders/SWO-1234/send-confirmation" \
-H "Authorization: Bearer $TOKEN"
Returns 200 with:
{ "data": { "orderReference": "SWO-1234", "sent": true } }
Errors: 404 if the order doesn't exist for this supplier, 422 if it is
not active.
GET /api/v1/suppliers/{supplierId}/credit-notes
Incremental credit note sync. Same pagination model as /orders.
Use this to net refunds/returns against revenue.
Query params (all optional):
after— credit note id from a previous response'snextCursorlimit— page size, 1–100, default 100status—unused|used|voided. Omit for all.createdSince,createdUntil,updatedSince— same semantics as/orders
Response:
{
"data": [
{
"id": "...",
"creditNoteReference": "SWC-12",
"creditNoteNumber": 12,
"customerId": "...",
"orderId": "...",
"orderReference": "SWO-1234",
"description": "Partial return — 2 units damaged",
"type": "product",
"status": "used",
"totalAmount": {
"exclGst": { "amountCents": 8182, "currency": "aud" },
"inclGst": { "amountCents": 9000, "currency": "aud" },
"gst": { "amountCents": 818, "currency": "aud" }
},
"lineGstBasis": null,
"createdAt": 1735603500000,
"updatedTime": 1735604000000
}
],
"hasMore": false,
"nextCursor": "..."
}
creditNoteReference is {prefix}-{creditNoteNumber}, where the prefix is
derived from the supplier's configurable invoice number prefix: SWC for the
default (SWC-12), otherwise the invoice prefix plus C (a supplier using
BRW issues BRWC-12). Existing credit notes keep their reference when the
prefix changes.
A credit note with a non-null orderReference was raised against that
order. One with a null orderReference is a standalone customer credit
(e.g. a goodwill credit not tied to a specific sale).
lineGstBasis says how totalAmount was worked out, the same as on an order.
null (almost every credit note): each line is priced inc GST. "excl-gst":
the supplier quotes wholesale prices ex GST, so each GST line is its ex-GST
unit price × quantity, plus 10% GST rounded to the cent. It is fixed when the
credit note is created and never changes. An amount credit note ("By Amount")
is always null.
Errors
All errors use the same envelope:
{ "error": { "code": "not_found", "message": "..." } }
| Code | Status | Meaning |
|---|---|---|
unauthorized | 401 | Missing/invalid bearer token. Response includes WWW-Authenticate. |
forbidden | 403 | Token valid but not for this supplier. |
not_found | 404 | Unknown resource or route. |
bad_request | 400 | Malformed JSON or invalid params. |
unprocessable_entity | 422 | Server-side validation failed — a missing or wrongly-typed required field (the message names the field), an invalid delivery date, no valid line items. |
method_not_allowed | 405 | Wrong HTTP method on a known route. |
internal_error | 500 | Unexpected. |
Worked examples
Create an order
TOKEN=... # API key or OAuth access token
BASE=https://actions.supplywise.com.au
# 1. Find a supplier
SUPPLIER_ID=$(curl -s "$BASE/api/v1/suppliers" \
-H "Authorization: Bearer $TOKEN" | jq -r '.data[0].id')
# 2. Find a customer
CUSTOMER_ID=$(curl -s "$BASE/api/v1/suppliers/$SUPPLIER_ID/customers?search=Test%20Venue%20Main" \
-H "Authorization: Bearer $TOKEN" | jq -r '.data[0].id')
# 3. Find a product
PRODUCT_ID=$(curl -s "$BASE/api/v1/suppliers/$SUPPLIER_ID/customers/$CUSTOMER_ID/products" \
-H "Authorization: Bearer $TOKEN" | jq -r '.data[0].id')
# 4. Create an order
curl -X POST "$BASE/api/v1/suppliers/$SUPPLIER_ID/orders" \
-H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d @- <<JSON
{
"customerId": "$CUSTOMER_ID",
"selectedProducts": [{ "productId": "$PRODUCT_ID", "quantity": 1, "optionsSelected": [] }],
"purchaseOrderNumber": "",
"notes": "Created via REST API",
"shippingAddress": {
"addressLine1": "1 Test St", "addressLine2": "",
"suburb": "Sydney", "state": "NSW",
"postcode": "2000", "country": "AU"
},
"pickupOrDelivery": "delivery"
}
JSON
Incremental order sync
TOKEN=...
BASE=https://actions.supplywise.com.au
SUPPLIER_ID=...
CURSOR=$(cat /var/lib/myapp/supplywise-cursor 2>/dev/null || echo "")
while : ; do
Q="limit=100"
[ -n "$CURSOR" ] && Q="$Q&after=$CURSOR"
RESP=$(curl -s "$BASE/api/v1/suppliers/$SUPPLIER_ID/orders?$Q" \
-H "Authorization: Bearer $TOKEN")
echo "$RESP" | jq '.data[] | { ref: .orderReference, customer: .customer.name, total: .totals.orderTotal.inclGst.amountCents }'
HAS_MORE=$(echo "$RESP" | jq -r '.hasMore')
CURSOR=$(echo "$RESP" | jq -r '.nextCursor')
[ "$HAS_MORE" = "true" ] || break
done
echo "$CURSOR" > /var/lib/myapp/supplywise-cursor
Backfill last 24 months
SINCE=$(date -u -v-24m +%Y-%m-%dT00:00:00Z) # or `date -u -d "24 months ago" ...` on Linux
curl -s "$BASE/api/v1/suppliers/$SUPPLIER_ID/orders?createdSince=$SINCE&limit=100" \
-H "Authorization: Bearer $TOKEN"
# …then page with `after=` as above.