IDs

Every sale can have multiple identifiers (ids). This page explains which ids are available and how to use them, which must be unique and which are optional.

Sale ID $.id

This top level id (under the $.data.id key) is the primary identifier for a sale. It MUST be unique across all sales for a given tenant. Usually this id is generated by the system and should not be changed. For special cases where the id must be known in advance, the client can provide an id when creating a sale.

caution

If the client provides an id when creating a sale, it is the client's responsibility to ensure that the id is unique. Furthermore the client MUST ensure that the id is generated in a cryptographically secure way. A client provided id MUST be random and MUST NOT be predictable or enumerable. Since the id will be used in URLs it should be URL safe. It is preferable to use shorter IDs, like ULIDs (26 characters) or custom alphanumeric IDs. When using UUIDs it is advisable to use the Base58 encoding which represent a UUID in 22 characters (instead of the usual 36 when using hexadecimal representation).

External ID $.data.attributes.externalId

This id is an optional identifier for a sale. It is commonly used to reference a sale from an internal processes (such as returns). While the external id does not have to be unique, it is recommended to use unique values to avoid confusion. The external id can contain sequential and predictable values (e.g. {branchId}-{cashRegisterId}-{receiptNumber}). The external id is indexed and thus can be used to search for a sale in the system.