Reference Number Generation Guidelines
API behavior: The reference_no field is optional. If supplied, it must not be blank and must not have been used before for the same customer. The database field supports up to 255 characters. The format recommendations on this page are not validated by the API; the API does not convert values to uppercase or validate a checksum. reference_no alone does not provide duplicate request protection; use the X-Idempotency-Key header described on the Idempotency page.
The recommended structure for shipment/order reference numbers is as follows:
1. General Format
[PREFIX]-[DATE/SEQUENCE]-[RANDOM]-[CHECKSUM]
Example: ACM-260825-4F7K-9
2. Length
- Total: 10–16 characters (excluding hyphens/separators)
- Fewer than 8 → collision risk may increase
- More than 16 → manual entry errors may increase and barcode/label fields may overflow. Check how it looks in your label template.
3. Character Set
- Uppercase letters and digits only (A–Z, 0–9) — reduces case-sensitivity confusion
- In the random part, avoid these characters because they are easily confused:
0/O, 1/I/L, 5/S, 8/B
- Avoid spaces and characters such as
/, \, _, # (they can cause URL, barcode and EDI/integration issues)
- Only
- may be used as a separator (for readability, not required by the system)
4. Prefix
- Should be fixed and meaningful: customer code, channel or order type
- 2–4 characters are enough (e.g.
ACM, WEB, B2B)
- Useful for reporting/filtering, should not be random
5. Random / Sequence Part
- A date (YYMMDD) + random block combination is a balanced approach:
- Date → quick recognition by eye, sorting, archiving
- 4–6 random alphanumeric characters → unpredictability, collision prevention
- Plain sequence numbers (1, 2, 3…) are predictable and can be a security risk — competitors/third parties can infer order volume
- Purely random (without a date) → harder to track by eye, not recommended
6. Suffix / Checksum (Optional but Recommended)
- The last character can be a Luhn-like check digit
- Lets you automatically catch manual entry errors (mistyped reference numbers) in your own system
7. Uniqueness
- Generation logic:
timestamp + randomness should be used together, either one alone may not be enough
- If you also use the reference as an idempotency key in your own system, make sure repeated submissions with the same reference map to the same shipment. Duplicate request protection in the ComToHome API uses the
X-Idempotency-Key header.
8. Human-Friendly Rules
- Separating blocks with hyphens improves readability:
ACM-260825-4F7K
- Choose characters that will not be confused when read aloud or over the phone (which is why avoiding pairs like 0/O, 1/I above is important)
- There should be no upper/lower case distinction; converting to uppercase in your own system is recommended
Recommended Template
{PREFIX:2-4}-{YYMMDD:6}-{RANDOM:4-6}[-{CHECKSUM:1}]
Example: WEB-260825-7K9M
This structure is readable and sortable by date, and reduces the risk of collisions and manual entry errors. You can validate your chosen format in your integration with the regex below:
^[A-Z0-9]{2,4}-\d{6}-[A-Z0-9]{4,6}(-\d)?$