Your own IDs
Customers, locations, printers and jobs each have an id that Tillcast makes. Your software has its own ids for the same things: an account number, a venue code, the name of a till, an order number. One field holds yours, on all four kinds: client_reference_id.
Because it is not unique
- Send an
Idempotency-Keywith every create. A retry of the same request answers the first object again. Without the key, a create that is sent twice makes two objects, with the same value on both. - If you need find-or-create, search first, then create when nothing was found.
Find objects by it
Each list takes client_reference_id and answers with every object of your organization that carries that exact value. An unknown value is an empty list, never 404. The value is compared as it is: no case folding, no trimming, no prefix. The query string is form-decoded, so write a plus sign as %2B.
The same parameter works on GET /v1/locations, GET /v1/printers and GET /v1/jobs. A search narrows with customer, location and, for jobs, printer. Jobs are found for seven days after they end, newest first. A key limited to one customer finds only that customer’s objects.
Do not use one constant value for every job: a search by a value that thousands of objects share is slow when it is narrowed. A search can also answer a short or an empty page with has_more: true and a next_cursor: follow the cursor until has_more is false. See Searches can answer a short page.
The old names
Earlier names of this field, external_id on customers and locations and reference on jobs, are refused with 400 parameter_unknown. Use client_reference_id.