New order number type as of Q3 2020

Please be aware that as of Q3 2020 (exact date is unknown, expected around July), a new order number will be shared with our partners.

Background
Around July, we expect to introduce a new order id format. The current format only contains numbers. As of July 2020, we will add alphanumerical characters to the order id.
Example order number at this moment:
4343582952

Example order number as of Q3 2020:
A4K8290LP0

Be advised that this applies to all the orderId fields in the API.

What does this mean for you?
If you are parsing the orderId to a different data type, this might not work anymore. Please pay attention to the following:

  • In case you are using version 2 of the API, we recommended you to move away from this version as quick as possible. Version 2 has been deprecated as of April 2019 and will be switched off in April 2020. At Q3 2020, this version is not live anymore. In case of unexpected issues, please be aware that version 2 is not able to cope with alphanumerical numbers. Exposing orders through version 2 is therefore not possible.
  • In case you are using version 2.1 of the API, we also recommended you to move away from this version as quick as possible. Version 2.1 has also been deprecated as of April 2019 and will be switched off in April 2020. At Q3 2020, this version is not live anymore. In case of unexpected issues, version 2.1 is able to provide order data, but using alphanumerical numbers.
  • In case you are using version 3 of the API, there is no impact expected. However, please be advised that you will receive alphanumerical order numbers. Always verify if your system and code is able to cope with this data format.

What is expected from you?

  1. Verify if your system is able to cope with alphanumerical characters in the orderId field throughout the API.
  2. Verify your code if you are able to process alphanumerical characters.

In order to help you, we created a DEMO environment (on the Retailer API version 3) to help you test this change. You can find the DEMO scenario for this on this page for order that has order number A4K8290LP0.

How does the new orderId look like?
The new orderId will be a base 27 number system similar to hexadecimal (base 16) and consist any of the following characters (in order):
0123456789ACDEFHJKLMNPRTUWX

The new orderId will always have a length of 10 characters. The first number will be A000000001 and the last number in this range will be XXXXXXXXXX. This way the number will always have at least one letter making it distinguishable from the old orderId. Be advised that the length of the orderId might change in the future.

How to test?
To test if an orderId is within the range you can use the following regular expression:
^\s*(?:[0-9ACDEFHJKLMNPRTUWX]{10})\s*$

You can test this expression here.

Formatting
When presenting the orderId to your end-consumer (for example in a dashboard), we recommend you to add hyphens to the orderId field (similar to bol.com) to make it easier to read for customers and to prevent obscene words. For example, A4K8290LP0 will be presented to users as A4-K8-29-0L-P0. The hyphens are purely formatting similar to a date or money format. The number itself will be without hyphens. Only when presented to an interface we advise to add hyphens to better support your processes.

Geplaatst in Plaza API
bol.com Development Center