# OrderDen

> Order, quote, invoice and stock management for small makers and trades:
> clients, a costed catalog with recipes and materials, quotes that become
> orders that become invoices, payments, purchasing, production runs, stock
> with a movement ledger, shipping labels and reports.

Everything the web app does is available over a REST API at `https://0.0.0.0:3000/api/v1`,
included in every plan. Authenticate with a bearer key from Company Settings →
API keys (`Authorization: Bearer od_live_…`).

Start with `GET /api/v1/me`: it says which workspace the key acts in, the role
and permission flags it carries, and how much of the plan's quota is left. A
key made by somebody who may not see costs gets responses with every cost and
margin field **absent** — plan for that rather than treating it as an error.

Conventions: JSON in and out; success is `{"data": …}` and lists add
`{"meta": {total, page, pageSize, pageCount}}`; money is decimal strings;
dates are ISO-8601; partial updates use PATCH. Every list takes
`?updatedSince=<ISO timestamp>` for polling, `?page`/`?pageSize`, `?sort`
and `?format=csv`. Writes accept an `Idempotency-Key` header and replay the
first response for 24 hours, so a retry after a timeout is safe.

## API reference

- [OpenAPI 3.0 description](https://0.0.0.0:3000/api/v1/openapi.json): the machine-readable spec
- [Full API surface](https://0.0.0.0:3000/llms-full.txt): every endpoint and event, one file
- [Interactive explorer](https://0.0.0.0:3000/docs/api-explorer)

## Endpoint groups

- **Custom fields & bulk** (13 endpoints)
- **Catalog tree** (23 endpoints)
- **Setup** (10 endpoints)
- **Stock** (17 endpoints)
- **Organization** (11 endpoints)
- **Reports** (25 endpoints)
- **Activity** (1 endpoints)
- **Clients** (21 endpoints)
- **Items** (10 endpoints)
- **Variants & kits** (12 endpoints)
- **Materials & recipes** (20 endpoints)
- **Production** (9 endpoints)
- **Enquiries** (6 endpoints)
- **Purchase orders from clients** (6 endpoints)
- **Quotes** (23 endpoints)
- **Invoices** (25 endpoints)
- **Payments** (9 endpoints)
- **Settings** (20 endpoints)
- **Orders** (22 endpoints)
- **Credit notes** (10 endpoints)
- **Attachments** (10 endpoints)
- **Statements** (5 endpoints)
- **Client portal** (11 endpoints)
- **Pricing** (5 endpoints)
- **Shipping** (14 endpoints)
- **Print batches** (3 endpoints)
- **Stocktakes** (7 endpoints)
- **Barcodes** (3 endpoints)
- **Locations** (5 endpoints)
- **Purchases** (19 endpoints)
- **Price lists** (10 endpoints)
- **Carriers** (5 endpoints)
- **Taxes** (12 endpoints)
- **Vendors** (7 endpoints)
- **Projects** (21 endpoints)
- **Expenses** (21 endpoints)
- **Accounting** (7 endpoints)
- **Imports** (6 endpoints)
- **Payment terms** (11 endpoints)
- **Change orders** (2 endpoints)
- **Reminders** (13 endpoints)
- **Notifications** (2 endpoints)
- **Webhooks** (11 endpoints)
- **Team & access** (9 endpoints)

## Webhooks

Subscribe with `POST /api/v1/webhooks` `{url, events}`. Deliveries are signed
`X-OrderDen-Signature: t=<unix>,v1=<hmac-sha256(secret, t + "." + body)>` and retried
on a 1m / 5m / 30m / 2h / 12h ladder. Events:

- `quote.sent` — A quote was sent to a client. Payload: the quote.
- `quote.accepted` — A client accepted a quote, in the portal or by hand.
- `quote.declined` — A client declined a quote.
- `order.created` — An order was raised — by hand, from a quote, or imported.
- `order.confirmed` — An order left draft and is committed: stock is reserved.
- `order.shipped` — An order shipped in full. Partial shipments do not fire this.
- `order.completed` — An order finished — shipped and settled, or closed short.
- `invoice.sent` — An invoice was issued to a client.
- `invoice.paid` — An invoice reached a zero balance, however it got there.
- `payment.received` — A payment was recorded, online or by hand.
- `payment.refunded` — A refund was issued against a payment.
- `client.created` — A client was added.
- `client.updated` — A client changed. `previous` carries the fields as they were.
- `item.updated` — A catalog item changed. `previous` carries the fields as they were.
- `stock.low` — An item's available quantity fell to or below its reorder point.
- `production.completed` — A production run finished and its output went into stock.

## Guides

- [Getting started](https://0.0.0.0:3000/docs/getting-started): Sign up, set up your workspace, invite your team.
- [Pre-release: what to expect](https://0.0.0.0:3000/docs/pre-release): The free tier is real, there is no paid plan and no support model, and there is no guarantee your data will be preserved — what that means, and what to do about it.
- [Starter kits](https://0.0.0.0:3000/docs/starter-kits): The setup your trade already uses — units, materials with real costs, recipes, terms and wording — installed in one click, with sample data you can remove just as easily.
- [OrderDen on your phone](https://0.0.0.0:3000/docs/mobile): Add it to your home screen, take photos straight into the app, and get notifications on a phone with the app closed.
- [Dashboard](https://0.0.0.0:3000/docs/dashboard): Your customizable widget board and date ranges.
- [Clients](https://0.0.0.0:3000/docs/clients): Company profiles, contacts, addresses, terms and notes.
- [Items & pricing](https://0.0.0.0:3000/docs/items): The catalog: item numbers, client prices and COGS calculators.
- [Wholesale and retail pricing](https://0.0.0.0:3000/docs/price-lists): Named price lists with their own minimums and case packs, put a client on one, and every document charges the right price by itself.
- [Materials, recipes and what things cost](https://0.0.0.0:3000/docs/materials): What you buy in, the units you count it in, and the bill of materials that turns both into a cost per unit — with labour, overhead and margin.
- [Passwords & signing in](https://0.0.0.0:3000/docs/passwords): Signing in with your email address, choosing a password, and the reset link when you have forgotten it.
- [Roles, permissions, two-factor and sessions](https://0.0.0.0:3000/docs/team-and-security): The five roles, the eight permission flags, two-factor authentication with passkeys, and the devices you are signed in on.
- [Your data](https://0.0.0.0:3000/docs/your-data): The full download, and what happens when OrderDen support signs in as you.
- [Importing your spreadsheet](https://0.0.0.0:3000/docs/import): Load clients and items from a CSV — mapping, preview, duplicates and undo.
- [Enquiries](https://0.0.0.0:3000/docs/enquiries): A public request form that becomes a quote, with the client matched or created.
- [Quotes](https://0.0.0.0:3000/docs/quotes): Priced proposals — send, get accepted, convert to orders.
- [Orders & shipping](https://0.0.0.0:3000/docs/orders): Confirmed work: shipments, tracking, packing lists, invoicing.
- [Invoices & payments](https://0.0.0.0:3000/docs/invoices): Bill clients, record payments, track balances due.
- [Tax](https://0.0.0.0:3000/docs/taxes): Named rates and groups, per-line tax, exempt clients and the tax collected.
- [Getting paid online](https://0.0.0.0:3000/docs/payments): Take card and US bank payments on a share link with Stripe; fees and refunds.
- [Credit notes, refunds, returns and write-offs](https://0.0.0.0:3000/docs/credit-notes): Correcting a sale without pretending it never happened: what comes back, where the money goes, and the difference between a credit and a bad debt.
- [Deposits, instalments and final invoices](https://0.0.0.0:3000/docs/deposits): Half now and the rest on delivery: named payment terms that ask for a deposit, a deposit invoice raised the moment a quote is accepted, instalments on a project, and a final invoice that deducts what has already been paid.
- [Recurring invoices, cards on file and late fees](https://0.0.0.0:3000/docs/recurring): Money that arrives without anybody chasing it: retainers and subscriptions billed on a schedule, a card the client leaves on file, charges taken on the due date with a retry ladder behind them, and the late fee that has three guard rails and one exception.
- [Signatures on quotes](https://0.0.0.0:3000/docs/signatures): A client signing a quote — typed or drawn — with the record that makes it worth having: who, when, from where, and a fingerprint of the document exactly as it was in front of them.
- [When an email does not arrive](https://0.0.0.0:3000/docs/bounced-email): What a bounced address and a spam complaint mean, what OrderDen does about each, and how to get an address working again.
- [Reminders, follow-ups and status emails](https://0.0.0.0:3000/docs/reminders): Chasing an unpaid invoice, nudging an unanswered quote, telling a customer their order shipped — automatically, in your words, and stopping the moment it should.
- [Statements of account](https://0.0.0.0:3000/docs/statements): What a client owes over a period: printed, emailed, scheduled, and on their portal.
- [Client portal](https://0.0.0.0:3000/docs/client-portal): Give a client an account: everything of theirs in one place, messages on the document, and files both ways.
- [Documents & sharing](https://0.0.0.0:3000/docs/documents-and-sharing): Themes, numbering, print, email, attachments and the client portal.
- [Spending: purchases and expenses in one list](https://0.0.0.0:3000/docs/spending): Everything that went out, on one screen, with a type column saying which kind of record it came from — and why the two records stay two records: receiving a purchase is what gives your materials a cost, and an expense never touches stock.
- [Vendors & purchasing](https://0.0.0.0:3000/docs/purchasing): The money-out side: suppliers, purchase orders and payments.
- [Projects: track time, costs and profit on a piece of work](https://0.0.0.0:3000/docs/projects): The container a whole piece of work hangs off — its quote, its orders, its invoices, the timber, the hours and the parking — and the one question at the end of it: did that project make money?
- [Expenses, receipts and profit and loss](https://0.0.0.0:3000/docs/expenses): The everything-else spend: photograph a receipt and be done, file it under a category that means something at tax time, charge what you spent for a client back to them, and see whether the whole thing made money.
- [Shipping labels](https://0.0.0.0:3000/docs/shipping): Buy and print postage from the order: USPS, UPS and FedEx priced side by side, the label kept where you can reprint it, and the parcel marking itself delivered.
- [Inventory: what is on the shelf, and where](https://0.0.0.0:3000/docs/inventory): How many there are and which bin they are in — quantity on hand from a movement ledger, allocated against available, bins you can search and pick by, stocktakes, adjustments and valuation.
- [Making stock: production runs, batches and curing](https://0.0.0.0:3000/docs/production): Turn a recipe into stock: what a run consumes and produces, what a batch cost, batch codes and cure dates, buildable quantity and made-to-order.
- [Reports](https://0.0.0.0:3000/docs/reports): Revenue and margin by client, item and period; backlog aging, cycle time, on-time rate; inventory valuation and stock movements.
- [Tax time: COGS, inventory value and your expense summary](https://0.0.0.0:3000/docs/tax-time): What the things you sold cost you, worked out from the stock ledger and laid out the way a tax return asks for it — with every figure drillable and the reconciliation printed underneath.
- [Handing the numbers to your accountant](https://0.0.0.0:3000/docs/accounting): A period's books as the files QuickBooks and Xero import — sales, credits, payments, bills, expenses, fees and a journal that balances every day — with your own chart of accounts mapped once.
- [Activity & history](https://0.0.0.0:3000/docs/activity-history): The named trail of every change, org-wide and per record.
- [Search & lists](https://0.0.0.0:3000/docs/search-and-lists): Global search, filters, and columns you shape per list.
- [Custom fields](https://0.0.0.0:3000/docs/custom-fields): The two or three things about your business OrderDen does not know — added properly, so they filter, export, import and print rather than living in a notes box.
- [Settings](https://0.0.0.0:3000/docs/settings): Personal Settings, Company Settings and Account & Billing — who sees what, and where everything lives.
- [Plans & billing](https://0.0.0.0:3000/docs/plans-and-billing): Free and OrderDen: the 50 free invoices, the per-seat price, what unlimited means, and yearly billing.
- [Account credit](https://0.0.0.0:3000/docs/account-credit): Credit OrderDen has put on your bill: how it comes off your next invoice, and what it is not.
- [Webhooks & automation](https://0.0.0.0:3000/docs/webhooks): Get told the moment something happens instead of asking: signed deliveries with retries, the polling filter for anything without a public URL, idempotency keys, Zapier and the MCP server.
- [API reference](https://0.0.0.0:3000/docs/api): The public REST API, included in every plan.

## Optional

- [MCP server](https://0.0.0.0:3000/docs/api): `npx orderden-mcp` with `ORDERDEN_API_KEY` set, for assistants that speak the Model Context Protocol