Skip to navigation

Your own IDs

How to attach the id an object has in your own system, and how to find objects by it.
View as Markdown

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.

Value1 to 128 characters, not blank, no control characters. null when absent.
WhenOptional when you create the object. PATCH changes a customer, a location or a printer’s value, and null removes it. A job’s is set when the job is queued and does not change.
UniqueNo. Tillcast does not guard it. Two objects, of one kind or of two, can carry the same value.
Personal dataDo not put any in it.

Because it is not unique

  • Send an Idempotency-Key with 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.

curl "https://api.tillcast.com/v1/customers?client_reference_id=acct-1042" \
-H "Authorization: Bearer $TILLCAST_API_KEY"

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.