Frostbyte API v1

Your product catalogue: SKUs, pricing, tax, and tracking settings. The list endpoint supports free-text search, exact SKU/barcode lookup, sorting, and modifiedSince for incremental sync.

Key fields: id, sku, name, description, barcode, costPrice, defaultPrice, taxRate (fraction 0-1), imageUrl, unit of measure, category, tracking flags (batch/serial), isActive, totalStockOnHand, createdAt, updatedAt; the detail shape adds reorderQuantity, notes, purchase/sale units, variants, suppliers, and per-warehouse stock levels

sku and barcode are exact, case-insensitive matches (?sku=PUMP-1 matches “pump-1” but never “PUMP-10”) — built for connectors resolving order lines by SKU and for scan-driven flows. They AND-combine with every other filter; search stays a contains match over name, SKU, and barcode.

Customer records used on sales orders and invoices, including contact details, currency, and payment terms. Contacts and addresses are addressable as their own sub-resources — list them, and create, replace, or delete them individually.

Key fields: id, code, name, email, phone, currency, payment terms, credit limit, isActive, createdAt, updatedAt; addresses and contacts are detail-shape fields (GET /customers/{id})

The contacts and addresses sub-resources keep a single-primary / single-default-per-dimension invariant: creating or flagging one primary contact (or one default-billing / default-shipping address) automatically clears the previous one, all in one transaction. After every write the customer's scalar email / phone / address mirror is re-synced from the current primary/defaults, so the customer header stays consistent — and the write returns the full customer detail so you see both the children and the recomputed mirror in one round-trip.

PUT on a contact or address is a full-resource REPLACE (unlike the merge-style PUT /customers/{id} header update): omit an optional field and it is cleared, not preserved. Send the whole child every time.

Deleting the last contact or address is permitted — neither the app nor the API enforces a minimum, and the scalar mirror is left intact rather than wiped when no child rows remain. These contact/address POSTs do not take an Idempotency-Key; child creation is low-risk and a duplicate just adds another row.

Supplier records used on purchase orders, including contact details and currency. The detail shape adds locations and a per-product price list with lead times.

Key fields: id, code, name, email, phone, currency, isActive, createdAt, updatedAt; the detail shape adds locations and a priceList (per-product supplierSku, supplierPrice, leadTimeDays, minOrderQty, isPreferred)

The detail price list returns up to 500 rows (preferred rows first, then cheapest).

Sales orders through their lifecycle: create a DRAFT, confirm it (reserving stock and enforcing credit), dispatch what has been packed, complete it once invoiced, or cancel it with full stock reversal. Picking and packing happen in the Frostbyte Pro app between confirm and dispatch.

Key fields: id, orderNumber, status, customer, orderDate, lines (product, quantity in base units, unitPrice, discountPct and taxRate as fractions 0-1, line total), subtotal, tax total, total, createdAt, updatedAt

Transitions return 200 with the same detail shape as GET /sales-orders/{id}. Calling a transition in the wrong current status returns 422 unprocessable with a message naming the actual status — which is also what a concurrent double-transition sees, since every transition runs in a single transaction holding a row lock on the order.

Stock semantics: confirm reserves stock (aggregated across bins per warehouse). Dispatch never touches stock — it was deducted at picking; dispatch advances dispatched quantities, stamps the ship date on the first dispatch only, and moves the dispatched lines' allocated serial numbers to SOLD (whole units). A full dispatch also pushes fulfilment to a linked Shopify, WooCommerce, or BigCommerce order. Cancel releases reservations (CONFIRMED) or returns exactly the picked quantity to stock and releases the unpicked balance (PICKING/PACKED), and returns allocated serials to AVAILABLE.

Sales-order amounts are always in your organisation's base currency — there is no currency field on a sales order. Invoices carry a currency label.

POST /sales-orders/{id}/invoice is the one way to create an invoice through the API (invoices are otherwise read-only). Invoice creation can auto-send the invoice over Foodstuffs EDI — it does so when the order carries a Foodstuffs PO reference and your Foodstuffs integration has auto-send enabled. Pass suppressEdi: true to create the invoice without sending (e.g. for drafting or replays). The EDI send is fire-and-forget, so the 201 returns the created invoice even if a later send fails. The invoiceDate (today) and dueDate (from your payment terms) are server-derived — there is no override.

Invoices for reporting and reconciliation, plus payment recording. Invoices themselves are generated from sales orders inside Frostbyte Pro; once issued, payments against them can be recorded through the API.

Key fields: id, invoiceNumber, status, customer, issue date, due date, currency, lines, subtotal, tax total, total, amount paid / due, payments (id, amount, paymentDate, method, reference), createdAt, updatedAt

Invoices cannot be created or edited via the API — payment recording is the single invoice write in v1.

Payments are recorded in the invoice's stored currency; there is no conversion. A currency mismatch, a payment on a VOID, PAID, or DRAFT invoice, or an amount exceeding the remaining balance all return 422 — and the balance check re-runs under a row lock, so concurrent payments can never jointly overpay. The invoice becomes PAID at the full total (within a half-cent rounding tolerance); a partial payment on an OVERDUE invoice stays OVERDUE; otherwise PARTIALLY_PAID.

Money moves once and only once: send an Idempotency-Key header so a timed-out retry replays the original 201 instead of double-recording — see Idempotency under Conventions.

Purchase orders through their lifecycle: create a DRAFT, submit it for approval, approve it, record goods receipts against it — including batch and serial intake — or cancel it.

Key fields: id, orderNumber, status, supplier, order date, expected date, currency, lines (product, quantity in base units, unit cost, taxRate as fraction 0-1), subtotal, tax total, total, createdAt, updatedAt

Transitions return 200 with the same detail shape as GET /purchase-orders/{id}; the wrong current status returns 422 unprocessable naming the actual status. API keys are organisation-level credentials, so one write key can create, submit, AND approve the same purchase order — if your organisation relies on two-person approval, keep the approve step in the app or give the approving system its own key and process.

Receipt lines: { poLineId, productId (must match the PO line's product), quantity (base units, > 0), binId? }. Batch-tracked products require batchNumber — it resolves to an existing batch or auto-creates a new one (expired or recalled batches are rejected with 422); batchId and batchNumber are mutually exclusive. Serial-tracked products need serialNumbers matching the quantity exactly, or autoGenerateSerials: true — and whole-number quantities. Up to 1000 serials per line; received serials are created as AVAILABLE and linked to the PO line.

Over-receipt (receiving more than ordered) is allowed and flagged in the audit log. Landed costs cannot be added via the API — add them to a receipt in the app; cost prices still update on receipt via the weighted-average path, so a missing exchange rate surfaces as 422. Marking a fully received order COMPLETED also remains in-app.

Receipts move stock and consume a receipt number, so the endpoint supports the Idempotency-Key header — see Idempotency under Conventions.

Changed 2026-06-12: sortBy without an explicit sortDir now sorts descending, matching /sales-orders (it previously sorted ascending). Pass sortDir=asc if you relied on the old order — see the changelog.

Current stock levels per product per warehouse — the same numbers the app shows. Quantities are in base units. Each row carries updatedAt, the checkpoint value for incremental sync.

Key fields: product (id, sku, name), warehouse (id, code), quantity on hand, quantity reserved/allocated, quantity available, batch breakdown for batch-tracked products, updatedAt

modifiedSince covers every quantity or reservation change, but batch-only changes (a batch quarantined, merged, or split) update the batch breakdown without bumping the row's updatedAt — they will not surface under modifiedSince.

Archived products' residual stock is hidden by default; pass includeInactiveProducts=true to see it for reconciliation.

The warehouses configured for your organisation. Use warehouse ids when filtering stock on hand or posting stock adjustments.

Key fields: id, code, name, isActive, zones (with their bins)

Zones and bins are capped per response: up to 50 zones per warehouse and up to 500 bins per zone.

Adjust on-hand stock up or down with an audited reason — for cycle counts, write-offs, or corrections driven by an external system — and read adjustments back for reconciliation.

Key fields: id, adjustmentNumber, reason, status (DRAFT | COMPLETED | VOIDED), notes, completedAt, createdAt, updatedAt, lines (productId, warehouseId, binId, batchId, quantityChange — signed, in base units — costPerUnit); the same shape is returned by POST, the list, and the detail endpoint

Adjustments that would take batch- or serial-tracked stock negative are rejected with 422.

A single request can contain at most 50 adjustment lines.

The reason FILTER accepts STOCK_REQUISITION (requisition-issued adjustments move real stock, so hiding them would corrupt reconciliation), but POST rejects that reason — it is reserved for the in-app requisitions workflow.

Fulfilment view of your sales orders for 3PL and warehouse integrations: pick / pack / dispatch state plus carrier and tracking. Shipments are created from sales orders inside Frostbyte Pro; the API exposes the read view and the two transitions a 3PL writes back — pack and dispatch.

Key fields: id, shipmentNumber, status, salesOrder (id, orderNumber), carrier, trackingNumber, totalWeight, shipDate, notes, lineCount, createdAt, updatedAt; the detail shape adds lines (soLineId, productId, product {sku, name}, quantity in base units, unitPrice, taxRate as a fraction 0-1)

Only pack and dispatch are exposed — creating, picking, completing picking, cancelling, and delivering a shipment stay in the app. To correct carrier / tracking after a successful dispatch, send the dispatch again only if the shipment is still PACKED; a replay under the same Idempotency-Key with a different body returns 422 idempotency_key_reuse, so use a fresh key (or set tracking at the first dispatch).

The recall and FEFO traceability moat, read-only: lot/expiry batches with their per-location quantities, and individual serial numbers with their full status-transition history. Both are scoped to your organisation and gated on inventory view.

Key fields: Batch: id, batchNumber, status, manufactureDate, expiryDate, product (id, sku, name — derived from the batch's items, null for an empty batch), unitCost, notes, createdAt, updatedAt; the detail adds items[] (per warehouse / bin quantity) and a rolled-up totalQuantity. SerialNumber: id, serialNumber, status, product, receivedAt, soldAt, returnedAt, notes, createdAt, updatedAt; the detail adds the current batch / warehouse / bin placement and the full transition history

A batch has no product of its own — its product is derived from its line items, so an item-less batch returns product: null. In practice every batch is created against one product.

modifiedSince on batches keys off the batch's own updatedAt, so a quantity change that touches only a batch-item row (a merge or split) without bumping the batch will not surface — the same incremental-sync caveat as Stock On Hand.

Price tiers and an effective-price resolver, so a webstore or connector can price a line exactly the way the Frostbyte Pro sales-order form does — without re-implementing the pricing engine. All three reads are gated on products view.

Key fields: PriceTier: id, tierIndex, name, isActive, productPriceCount, customerCount, createdAt, updatedAt; the detail adds productPrices (productId, sku, productName, price) and quantityBreaks (productId, minQuantity, unitPrice). Resolver result: productId, customerId, quantity, basePrice, resolvedPrice, source (default | tier | quantity_break | customer_discount), appliedTierId, appliedDiscountPct

Resolver precedence mirrors the sales-order form exactly: the product's defaultPrice, then the customer's price tier if one applies, then a quantity break if the ordered quantity reaches one. A quantity break OVERRIDES the tier — they never stack — and source reports the last step that moved the price. Prices and quantities are in base units.

The customer's standing discount is informational only: it is surfaced as appliedDiscountPct (a fraction 0-1) but never folded into resolvedPrice, because the app applies it to the line TOTAL, not the unit price. So source is never customer_discount today — the value exists for forward-compatibility — and resolvedPrice is the pre-discount unit price you'd put on the line.

Read-only lookups for the ids the write endpoints ask for — the same lists the app shows in its dropdowns. Resolve a categoryId, a unit-of-measure id, a customerGroupId, a sales-rep user id, or a supplier's shipping locations before you create or update the parent record.

Key fields: Category: id, name, parentId, sortOrder. UnitOfMeasure: id, name, abbreviation, type. CustomerGroup: id, name, isActive. SalesRep: id (the user id), name, email, role. SupplierLocation: id, name, type, contact and structured address fields, isDefaultShipping, isDefaultBilling

The sales-reps id is the USER id (what a sales order's assignee / a customer's sales rep points at), not the membership row id. The list returns nothing beyond id, name, email, and role.

Read-only BI snapshots — the same figures the app's reports show, gated on reports view. These are point-in-time snapshots, not paginated lists: each builder caps its result (noted per endpoint) and silently truncates beyond the cap, so narrow with the filters when a dataset is large.

Key fields: Each report returns an object wrapping its row array(s) — movements, rows, items + totalValue, invoices, batches, or products — with the exact row fields listed in the OpenAPI document and the markdown reference

A filter id that isn't in your organisation (warehouseId, categoryId, productId, customerId) returns 422 invalid_reference. There are no path {id} resources here, so these endpoints never return 404.

Hitting a builder's cap gives you a partial report with no flag in the response — the snapshot is intentionally unpaginated. Narrow the date window or filters to stay under the cap.

Outbound webhooks push events to your endpoint instead of you polling for changes. Subscribe a public HTTPS URL to one or more events; when a matching change is committed — whether it came through this API or someone working in the Frostbyte Pro app — we POST a small, HMAC-signed payload to your URL, retrying with backoff until you acknowledge it. Manage subscriptions, inspect the delivery log, and fire a test ping through the endpoints below. See the Webhooks subsection under Conventions for the payload shape, the signature scheme, and delivery semantics.

Key fields: id, url, events (the subscribed event strings, or ["*"] for all), description, secretPrefix (the only fragment of the signing secret ever returned — the full secret is shown once at creation), isActive, failureCount, lastSuccessAt, lastFailureAt, disabledAt, createdAt, updatedAt. The signing secret itself (secretEnc) is stored AES-encrypted and is NEVER returned after creation. Delivery rows carry: id, event, status (PENDING | DELIVERED | DEAD), attempts, responseStatus, lastError, deliveredAt, createdAt, and the thin payload

The full signing secret is returned ONLY in the 201 from POST /webhooks. Afterwards every read returns secretPrefix alone — there is no endpoint that re-reveals or rotates it. Lost the secret? Delete the subscription and create a fresh one.

Webhooks fire for changes made through this API AND for the same actions performed by a person in the Frostbyte Pro app — they reflect the data, not the channel.

Up to 25 active subscriptions per organisation. Subscribe one URL to several events (or ["*"] for all) rather than creating a subscription per event.