Order & reference numbers

Every order gets an order number such as ICE-000042: the supplier's prefix, a dash, and that supplier's next number, padded to six digits. The order number is the invoice number. There is no separate invoice number. A reference number is different: it's a number the supplier types in themselves, such as the customer's PO number or the supplier's own number from their accounting system, and the app checks it isn't used twice. Purchase orders, statements and payments have numbers of their own, listed below.

Who uses it

Supplier staff find orders by number, quote it to customers, type reference numbers, and match Clipp invoices to their accounting system.
Restaurants see the order number on the invoice, emails, texts, the pay page and the card checkout, and the reference number on the invoice.
Support uses the order number to find an order. It's printed on every invoice page.

Every number at a glance

Number	Looks like	Who sets it	One sequence per	When it's given
Order / invoice number	`ICE-000042`	The app	Supplier	When the order is created
Purchase order number	`ICE-PO-000322`	The app	Supplier (the buyer)	When the PO is created
Statement number	`1012`	The app	Supplier	When the statement is created
Reference number	anything, e.g. `PO-7781` or `INV 20931`	Supplier staff	(checked for duplicates)	Whenever it's typed
Payment reference	a check number, a transaction ID, card last 4	Supplier staff	Not checked	When a payment is recorded
Customer Ref ID / Vendor Ref ID	the supplier's own account code	Supplier staff	Not checked	On the customer or vendor

There are no receipt numbers, credit memo numbers or return (RMA) numbers. A return or a refund is shown on its order's invoice, under that order's number.

Order number

Format

PREFIX-NNNNNN: the prefix, a dash, and the next number in that supplier's sequence, padded to 6 digits.

Supplier	Prefix	Sequence	Order number
Smoove Ice Cream (no prefix set)	SMO: the first 3 letters or digits of the name	304	`SMO-000304`
NYC Fisher Hub (no prefix set)	NYC	42	`NYC-000042`
Supplier with a prefix set to `fan`	FAN	29	`FAN-000029`
Any supplier, after 999,999 orders		1,000,000	`ICE-1000000` (7 digits, no truncation)

The prefix is the supplier's own order prefix if one is set. Otherwise it's the first three letters or digits of the business name, skipping spaces and punctuation, in capitals. Accented and non-Latin letters count as letters.
Suppliers can't set the prefix in the app. There's no field for it. Clipp sets it on request (verify the process).
Changing the prefix doesn't restart the count. If the prefix changes from FAN to LAS after order 29, the next order is LAS-000030.

One sequence per supplier

Each supplier has one counter. Every order takes the next number, whoever placed it: the restaurant in its app, the restaurant from the QR ordering page, the supplier, or the AI voice agent. An order the supplier creates takes its number when it is created; a restaurant's order takes it when the cart is sent, and a saved cart takes none until then.

A restaurant ordering from three suppliers at once gets three orders, one per supplier. Each takes a number from its own supplier's sequence when the cart is sent: SMO-000305, NYC-000043, ICE-000117.
Numbers are unique within a supplier. Two suppliers whose prefixes come out the same (for example "Ice Co" and "Ice Cream World", both ICE) can both have an ICE-000042. Searches are always within your own orders, so this only matters if you compare documents across suppliers.

When the number is given

Order	Gets its number
Supplier creates an order (new order dialog, or recording an order)	When it's created
Restaurant saves a cart	No supplier number. The order shows a temporary `DRAFT-` number until it is placed
Restaurant places an order (submits the cart)	When the cart is submitted, from that supplier's own sequence
A failed save	No number is used. The count only moves when the order is actually placed

Gapless: a failed save doesn't use up a number.
The number never changes, whatever happens to the order: edits, returns, cancellation.
Canceled orders keep their number. The number isn't reused.

Sorting by order number

Sorting by Order # compares the digits as numbers, so SMO-000099 comes before SMO-000100. After a prefix change, orders group by prefix first (all FAN- orders, then all LAS- orders), each in number order.

Where the order number shows

Surface	Wording
Orders list	"Order ID" / "Order" column
Invoice list	"Invoice ID" (verify column label)
Invoice PDF, packing slip, pending order	Under the title (Invoice, Packing Slip or Pending Order), above "Ref. No"
Every invoice page footer	"Order # ICE-000042, Page 1 of 2, Printed …"
PDF file name	e.g. `Invoice-ICE-000042.pdf`; the restaurant app saves `ICE-000042-Invoice.pdf`
New order email to the supplier	"<ICE-000042> New Order Received from {restaurant}"
Status email to the restaurant	"Order #ICE-000042: Status Changed to …"
Delivered email	"Your order ICE-000042 from {supplier} has been delivered"
Overdue email	"Payment Reminder: Overdue Invoice #ICE-000042"
Texts and push notifications	"Your order ICE-000042 from {supplier} …"
Public pay page	"Invoice #"
Card checkout (Stripe)	Line "Invoice ICE-000042", and the payment's description in Stripe
Card-on-file charge	"Invoice ICE-000042"
PayPal checkout	PayPal's invoice ID field
Chat	"Hi {restaurantName}, Can we chat regarding your order {orderID}?"
Statements	One row per invoice, by order number
Bookkeeping	"Invoice #" column, and descriptions like "… for order ICE-000042"

Page links never contain the order number. They use an internal ID or a secure link.

Searching

Screen	Matches
Orders	Order number, reference number, customer name. The placeholder says "Search by Customer Name or Order ID", but reference numbers match too
Invoices	Order number, reference number, customer name
Purchase orders	PO number, vendor name, reference number ("Search by Order ID/ Vendor/ Ref.no")
Statements	Statement number, recipient phone and email ("Search by Statement no. / Phone number")
Restaurant app orders	"Search by supplier or order number"

Purchase order number

PREFIX-PO-NNNNNN, for example ICE-PO-000322.

The prefix is the buying supplier's own prefix, not the vendor's. A supplier's sales orders and purchase orders run side by side: ICE-000011 and ICE-PO-000322.
Purchase orders have their own sequence, separate from sales orders.
Given when the PO is created. Never changes.
The PO invoice PDF is titled "PO INVOICE", with the PO number and "Ref. No: …" when set. File name: ICE-PO-000322_151026.pdf (PO number and the date as DDMMYY).
There's no separate PO invoice number.

Statement number

A plain number with no prefix and no padding: 1, 2, … 1012, one sequence per supplier.

Printed on the statement PDF as "STATEMENT NO. 1012"; the restaurant's statement link and app show "Statement #1012".
Given when the statement is created. If creating it fails, that number is skipped.
Searchable by number on the customer's statements list.

Reference number

A number the supplier types onto an order, invoice or purchase order to tie it to someone else's paperwork.

Document	What it's for	Checked for duplicates against
Sales order / invoice	The customer's PO number, or the supplier's own invoice number from their accounting system (see Known limitations)	Your other placed orders for any customer, ignoring capital letters. A saved cart or a canceled order doesn't hold its number
Purchase order	The vendor's own invoice number	Your other purchase orders from this vendor, ignoring capital letters

Entering it

Where: the new order dialog, the order detail header ("Add Reference Number"), and the new purchase order dialog. Labels: "Reference Number", "Ref. No".
Placeholders: "Enter ref. no from your Customer" (orders) and "Enter ref. no from your Vendor" (purchase orders).
Leading and trailing spaces are removed. A blank reference number is fine and is never a duplicate.
It can be changed or cleared later.

Duplicate check

As you type, the app checks whether the number is already used. The check waits for you to stop typing for a moment before it runs.

What you see	Meaning
"Reference number already used on" + a link to the other order	Another order already has it. The link opens that order in a new tab
"Reference number already used for this customer"	Fallback wording when the other order can't be linked
"Reference number already used for this vendor"	The same, on a purchase order

The warning doesn't disable the Save or Submit button. If you save anyway, the server refuses it with a message such as: Reference number "PO-7781" is already used on order ICE-000040 for this supplier, or, on a purchase order, … is already used on purchase order ICE-PO-000301 for this vendor.
"PO-7781" and "po-7781" count as the same number.
Editing an order that already shares a number with another is allowed as long as you don't change the reference number. Only a real change is checked again.
A canceled order gives its number back, and a saved cart doesn't hold one until it's placed. The number is checked again when a cart is placed.
If the check can't reach the server (for example, offline), it shows nothing rather than blocking you.

Example

Step	Result
ICE-000040 for Harbor Bistro has reference `PO-7781`
New order for Harbor Bistro, type `po-7781`	Warning: "Reference number already used on ICE-000040"
Save anyway	Refused: Reference number "po-7781" is already used on order ICE-000040 for this supplier
Change it to `PO-7782`	Warning clears; saves
Clear it	Saves. A blank reference number is never a duplicate

Where it shows

Invoice PDF and packing slip ("Ref. No: PO-7781", under the order number) · the on-screen invoice · the purchase orders table ("Ref. No" column) · the restaurant app ("Reference #") · search on orders, invoices and purchase orders.

Payment reference

When recording a cash, check, ACH or card payment by hand, staff can type a reference: "Check Number (optional)" for a check, "Transaction ID (optional)" for ACH. It's limited to 15 characters.

It shows next to the payment as "Check #1234", "Txn 98765" or "Card x4242".
It isn't checked for duplicates and isn't a Clipp-issued receipt number.
Online card and PayPal payments carry the processor's own ID instead. Staff don't type it.

Customer Ref ID and Vendor Ref ID

The supplier's own account code for a customer ("Customer Ref ID") or a vendor ("Vendor Ref ID"), set on the customer or vendor record.

Free text, not checked for duplicates. Searchable on the customers list.
Printed as "Account #" on the detailed packing slip, a layout enabled only for some suppliers (verify which).

Where it shows up

Orders list and order detail · Invoice list and preview · Invoice PDF, packing slip and pending order PDF · PO invoice PDF · Statement PDF and link · Order, status, delivered and overdue emails · Texts and push notifications · Public pay page · Card and PayPal checkout · Card-on-file charges · Bookkeeping · Restaurant app.

Permissions

Nobody can change an order, PO or statement number. Anyone who can edit an order or purchase order can set its reference number. Payment references are set by whoever records the payment. Customer and Vendor Ref IDs by anyone who can edit the customer or vendor (verify roles).

Decisions

One number sequence per supplier, shared by every way of placing an order. A supplier's invoices run in one unbroken series, however the order came in.
The order number is the invoice number. One number to quote, search and reconcile. (#2205: it also shows on card payments.)
No number is used up by a failed save. The number is taken inside the same save as the order. The cost: two orders created at the same instant for one supplier may make one retry. (#2198)
Order numbers sort by their number, not as text. A prefix change doesn't scramble the list. (#2345)
Reference numbers are checked as you type, but never block the button. A slow check can't stop someone working; the server refuses a real duplicate. (#2299, #2140)
A purchase order's reference number is the vendor's invoice number. (#2140)
Every invoice page carries the order number in its footer. A loose page can always be matched to its order. (#2146)
A saved cart takes a DRAFT- placeholder, not a supplier number. Carts a restaurant never sends no longer leave gaps in the supplier's series. (#2389)
Payment references are short and separate from notes. (#2137, #2187)

Specs

draft-order-number.feature
# prefix: DON
Feature: Draft order number
A restaurant's saved cart does not use up a supplier's order number. It shows a
temporary DRAFT number until the order is placed, and then takes the supplier's next number.

Rule: A saved cart takes no supplier number

    Scenario: DON-001 each supplier order on a saved cart gets its own temporary number
      Given a restaurant saves a cart with items from two suppliers
      When the cart is saved
      Then each order shows a different DRAFT number
      And neither supplier's order count moves

Rule: The real number is taken when the order is placed

    Scenario: DON-002 submitting the cart gives each supplier its own next number
      Given a saved cart with items from two suppliers
      When the restaurant submits the cart
      Then each order takes the next number from its own supplier's sequence
      And the DRAFT number is gone

    Scenario: DON-003 a failed submit uses no number
      Given a saved cart
      When submitting the cart fails after the number was taken
      Then the order keeps its DRAFT number
      And the supplier's order count is unchanged

    Scenario: DON-004 an order a supplier records directly gets its number at creation
      Given a supplier records a new order for a customer
      When the order is created
      Then it takes the supplier's next number at once

    Scenario: DON-005 a supplier moving a saved order to Placed gives it a real number
      Given a saved order with a DRAFT number
      When the supplier moves it to Placed
      Then it takes the supplier's next number

    Scenario: DON-006 an order that already has a real number keeps it
      Given a saved order that already carries a real number
      When the restaurant submits the cart
      Then the number is unchanged
      And no new number is used

    Scenario: DON-007 submitting a placed cart again uses no number
      Given a cart that was already submitted
      When the restaurant submits it again
      Then the order number is unchanged
      And the supplier's order count is unchanged

    Scenario: DON-008 many drafts for one supplier never clash
      Given a restaurant saves several carts for one supplier in quick succession
      When each cart is saved
      Then every order has a different DRAFT number

    Scenario: DON-009 a migrated draft gets a real number when placed
      Given a draft moved over from the old order system with a DRAFT number
      When it is placed
      Then it takes the supplier's next number

    Scenario: DON-010 a supplier added to a saved cart is a draft too
      Given a saved cart for one supplier
      When the restaurant adds items from a second supplier
      Then the new order shows a DRAFT number
      And the second supplier's order count does not move

    Scenario: DON-011 the placement message shows the real number
      Given a saved cart
      When the restaurant submits the cart
      Then the message to the supplier shows the real order number
      And it does not show a DRAFT number

reference-number-reuse.feature
# prefix: RNR
Feature: Reference number reuse
A supplier's own invoice number is unique among their placed orders. A canceled order
gives its reference number back, so the supplier can use it on another order.

Rule: A canceled order releases its reference number

    Scenario: RNR-001 a number held by a canceled order can be used again
      Given an order with reference number "QB-11" has been canceled
      When the supplier gives "QB-11" to another order for the same customer
      Then the number is accepted

    Scenario: RNR-002 a number held by a live order is still refused
      Given a placed order has reference number "QB-12"
      When the supplier gives "QB-12" to another order for the same customer
      Then the number is refused as already used

Known limitations

What an order's reference number means isn't settled. It's described as the supplier's own invoice number and checked across all of the supplier's placed orders, but the warning still says "for this customer" while the server says "for this supplier" (product decision needed).
Order numbers can repeat across suppliers with the same prefix.
Suppliers can't change their prefix themselves.
Saved carts show a DRAFT-… number in the web app, the restaurant app and the driver QR sheet until they are placed. Showing "TBD" instead is a later change.
Statement numbers can skip when creating a statement fails.
The orders search box doesn't mention reference numbers, and the statements search box doesn't mention email, though both match.

FAQ

Where's the invoice number? It's the order number. ICE-000042 is both. See Order number.

Why did my numbering jump from FAN to LAS? The prefix changed. The count carries on, so LAS-000030 follows FAN-000029. Ask Clipp to change the prefix.

There's a gap in my order numbers. Carts a restaurant saved but never sent don't use a number, so they don't cause gaps. Canceled orders keep their numbers, so they aren't gaps. Orders from before numbering became gapless may have gaps.

Why does this order end in "-2"? It was brought over from Clipp's earlier order system, where two live orders shared a number. The earlier one kept it and this one got -2.

The app warned me the reference number is already used. Can I still save? No. The server refuses a real duplicate. Use a different number, or clear it. If you're editing an order that already shared a number, you can keep it as it is.

Is "PO-7781" different from "po-7781"? No. Capital letters are ignored when checking for duplicates.

Can two suppliers have the same order number? Yes, if their prefixes are the same. Within one supplier, never.

Who uses it​

Every number at a glance​

Order number​

Format​

One sequence per supplier​

When the number is given​

Sorting by order number​

Where the order number shows​

Searching​

Purchase order number​

Statement number​

Reference number​

Entering it​

Duplicate check​

Example​

Where it shows​

Payment reference​

Customer Ref ID and Vendor Ref ID​

Where it shows up​

Permissions​

Decisions​

Specs​

Known limitations​

FAQ​