SupplyWise REST API v1

REST API for third-party integrations. Two authentication methods are supported, both via the Authorization: Bearer <token> header:

  1. API keys — issued from Supplier → Settings → API Keys. Scoped to one supplier. Best for server-to-server integrations (analytics syncs, accounting bridges, etc.).
  2. 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/json for 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.

MethodPathPurpose
GET/api/v1/suppliersList suppliers the token can access
GET/api/v1/suppliers/{supplierId}/customersSearch/list customers
GET/api/v1/suppliers/{supplierId}/customers/{customerId}/productsList a customer's available products (with their pricing)
GET/api/v1/suppliers/{supplierId}/ordersIncremental order sync (cursor + filters, includes line items)
POST/api/v1/suppliers/{supplierId}/ordersCreate 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}/pdfDownload the order's tax-invoice PDF (application/pdf)
POST/api/v1/suppliers/{supplierId}/orders/{orderReference}/send-confirmationSend the order confirmation for an order (e.g. one created with sendConfirmationEmail: false)
GET/api/v1/suppliers/{supplierId}/credit-notesIncremental 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/suppliers returns 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.
  • lastUsedAt is 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:

EndpointPurpose
POST /oauth/registerDynamic client registration (RFC 7591). Returns client_id. No client secret.
GET /oauth/authorizeRedirects to SupplyWise login (Clerk). On consent, redirects back with ?code=....
POST /oauth/tokenExchange 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

  1. 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_uris is required, and it is binding. Every URI you register is validated at registration time and stored; at the consent screen your redirect_uri must 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.1 or [::1], on any port and any path (OAuth 2.1 / RFC 8252 §7.3). http to any other host is rejected with invalid_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: and about: schemes are refused.
    • At most 10 redirect URIs, 2048 characters each; client_name at most 200 characters. client_name is shown to the user on the consent screen.

    Invalid metadata returns 400 with an RFC 7591 §3.2.2 body — {"error":"invalid_redirect_uri"} or {"error":"invalid_client_metadata"} — and an error_description naming the problem.

    Requested grant_types and token_endpoint_auth_method are ignored: every client is a public client using PKCE, and the response always says authorization_code + refresh_token, response_types: ["code"], token_endpoint_auth_method: "none".

  2. 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=....

  3. 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"
    }
    

    scope is what the user approved on the consent screen. The REST API does not check it. dashboard matters only to the MCP server's dashboard tools. A token issued before that scope existed shows orders:read orders:write, and a refresh keeps the original scope.

  4. Call the API with Authorization: Bearer <access_token>.

  5. 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_token AND a new refresh_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. nextCursor in the response is the bookmark for the next call.
  • Pass ?limit=N to choose the page size. Default and maximum 100.
  • Optional createdSince / createdUntil further bound the _creationTime range (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 after that 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, from createdSince, or from updatedSince".
  • When there are no more rows, hasMore is false and nextCursor is the id of the last row you saw (so re-running the same call returns zero new rows until something appears).
  • For the updatedAt value 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 | wholesale
  • archived — true | false (defaults to hiding archived; archived: true is the SupplyWise equivalent of "inactive")
  • search — case-insensitive free-text match. Substring-matches against the customer's name, the venue's name, and the venue's businessName
  • limit — 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: true means the customer pays before the order ships (the rest is then ignored). Otherwise paymentTermsType (always returned explicitly) says how an invoice falls due:

    • "daysAfterInvoice" — payWithinDays days after the invoice date ("Net 30 days"). The default.
    • "daysAfterEndOfMonth" — payWithinDays days after the end of the calendar month the invoice was raised in ("30 days EOM"; 0 = the last day of that month).
    • "dayOfFollowingMonth" — on day paymentTermsDayOfMonth (1–31) of the month after the invoice month. A day past the end of that month means its last day, so 31 is "end of the following month". For these customers payWithinDays is not used (it is normally 0) and must not be read as a day count.

    payWithinDays is a whole number ≥ 0 for every customer whose terms have been saved since these rules were introduced; treat anything else as legacy data. paymentTermsDayOfMonth is null unless 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), or null for no limit (none set, or the customer is payUpfront / 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 (default false). When true, products with status hidden are returned alongside active ones. Use the status field 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's nextCursor (the "bookmark")
  • limit — page size, 1–100, default 100
  • status — active | voided. Omit for both (default).
  • orderType — retail | wholesale
  • orderCategory — free-text category tag (e.g. Service). Optional supplier-set classification, orthogonal to orderType (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 is unpaid — see paidAmountCents / amountDueCents below)
  • shippingStatus — pending | processing | shipped | delivered | cancelled | awaiting-pickup | pickup-completed
  • createdSince, createdUntil — unix ms or ISO-8601 bounds on the order creation time
  • updatedSince — 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..."
}

weightGrams is null when the product has no configured weight, and shippingAddress is null when 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 opaque id for cross-references.
  • invoiceReference — the invoice number (the Xero InvoiceNumber / MYOB Number), {prefix}-{orderNumber}. The prefix is configurable per supplier (default SWI, e.g. SWI-1234; a supplier using BRW gets BRW-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 (use orderNumber / orderReference). A supplier can let MYOB assign the invoice number instead (Settings > Integrations > MYOB, "Let MYOB number my invoices"). For those suppliers the MYOB Number is MYOB's own, this invoiceReference is written into the MYOB invoice's Journal Memo as SupplyWise {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 — purchaseOrderNumber on 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-hour HH:mm in the supplier's timezone, on deliveryDate), when the supplier offers pickup time windows; otherwise null.
  • 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 — see GET /credit-notes. A credit note linked to a specific order carries that order's orderReference in the orderReference field.
  • orderTotalCents / amountToPayCents — flat convenience mirrors of totals.orderTotal.inclGst.amountCents and totals.amountToPay.inclGst.amountCents (both incl. GST, in cents). orderTotalCents is the invoice total; amountToPayCents is the total payable after any credit notes were applied (plus any card surcharge). It is not reduced by payments already made — use amountDueCents for what the customer still owes. Prefer these for simple integrations; the nested totals object carries the full ex-GST/GST split.
  • paidAmountCents / amountDueCents — part payments (incl. GST, in cents). paidAmountCents is the money recorded against the order so far (card, direct debit, bank transfer, or a payment the supplier recorded by hand). amountDueCents is what the customer still owes: amountToPayCents − paidAmountCents, floored at 0, for an active order whose paymentStatus is unpaid, and 0 for every other order (paid, settling, in the refund lifecycle, or voided). A part-paid order keeps paymentStatus: "unpaid" — there is no separate status — so tell it apart with paidAmountCents > 0. It becomes paid (or paid-awaiting-settlement) once the remainder is paid. Recording a part payment bumps updatedAt, so a changed-since sync (updatedSince) picks it up. To reconcile: amountDueCents is the open balance to show on a statement or receivable; don't subtract paidAmountCents from amountToPayCents yourself.
  • Revenue ex GST: every line item has both lineRevenueIncGstCents and lineRevenueExGstCents. 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), and lineRevenueIncGstCents is the two added together. Either way, the lines' lineRevenueIncGstCents add up to totals.itemsTotal.inclGst. Their lineRevenueExGstCents add up to totals.itemsTotal.exclGst only for "excl-gst" orders. On an "excl-gst" order, unitPriceIncGstCents × quantity can differ from lineRevenueIncGstCents by 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, lineRevenueExGstCents is unitPriceExGstCents × 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 quantity in units configured by the supplier — there is no separate pack-size field on a product. Quantities are whole numbers, except for products flagged allowFractionalQuantities (see GET .../products), where they may carry up to 3 decimal places (e.g. 1.5 for a product sold by weight). unitOfMeasure is always "unit" (kept on the payload for forward-compat). If you need product-level pack-size metadata, the supplier should encode it in productName / 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 / supplierId corresponds 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 from GET .../customers
  • selectedProducts (required, non-empty) — items must have quantity > 0. An order with no items (empty array, or all quantities <= 0) is rejected with 422. Each item is:
    • productId (required) — id from GET .../products. Every id must resolve to a product available to this customer; if any id is unknown or unavailable the whole request is rejected with 422 listing the bad ids (no partial order is created).
    • quantity (required) — number > 0. Whole numbers only, unless the product has allowFractionalQuantities: true (see GET .../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 with 422.
    • optionsSelected (required) — array of selected product options; use [] if none. Each option is an object:
      • productOptionId (required) — id of the product option
      • name (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 as customPrice: 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 with lineGstBasis: "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-order
  • shippingAddress (optional) — all six fields are strings. If omitted, the order uses the customer's venue shipping address (and may be null in 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 when pickupOrDelivery is pickup).
  • sendConfirmationEmail (optional, default true) — set to false to suppress all order confirmation notifications (email, push, and in-app) to supplier and venue users. Until a confirmation is sent (via the send-confirmation endpoint 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 to pending for delivery orders and awaiting-pickup for pickup orders (or pending when the supplier has turned on "New pickup orders start as Pending").
  • orderCategory (optional) — free-text category tag, e.g. "Service". Supplier-set classification, orthogonal to orderType (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 (null in responses). An empty/whitespace-only value is rejected with 400. You can filter by it later with GET .../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/pdf
  • Content-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. A voided (or otherwise non-active) order has no confirmation to send and returns 422.
  • 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's nextCursor
  • limit — page size, 1–100, default 100
  • status — 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": "..." } }
CodeStatusMeaning
unauthorized401Missing/invalid bearer token. Response includes WWW-Authenticate.
forbidden403Token valid but not for this supplier.
not_found404Unknown resource or route.
bad_request400Malformed JSON or invalid params.
unprocessable_entity422Server-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_allowed405Wrong HTTP method on a known route.
internal_error500Unexpected.

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.