A number of standards are expected to be used throughout OMS, both by the requests and responses sent to the APIs. These standards define how different data is formatted or abbreviated and communicated through OMS, and failing to follow these standards may result in an inability for the request to be processed or the order/payment failing to be authorized. This page currently covers the expectations for building date/time parameters, locales, currencies, and tracking numbers.
String Encoding & Multi-Byte Characters
In many API guides, string parameters have a noted minimum and maximum length. However, this assumes all characters in the string are single bytes – there are some complications when multi-byte characters are present.
Multi-byte characters, including non-Latin and accented characters, have to be converted into XHTML entities before they can be saved in the OMS database as it only stores latin1 characters. This conversion can cause a string that was previously under the allowed length to go over the limit as the encoding takes up more data, causing a error. The cause for this error may not be immediately clear to the user, as the string appears to be a valid length to them if they are unaware that some characters take up more than one byte.
This is not limited to strings in API requests – in user interfaces and data received from a storefront, multi-byte characters and emojis may be encountered if they were entered into text fields such as gift messages or delivery instructions. These characters must be converted as well, and emojis in particular usually cause errors as they cannot be properly encoded.
This can also occasionally affect translated text in the OMS interfaces – a string that was previously few enough characters to fit in a table column, for example, can become too long once translated and become cut off.
Kibo uses the internet standard format for dates (RFC-3339) and also uses a 24-hour clock as the default for most cases involving dates and times. This applies to order creation, shipping, other fulfillment records, and so forth where the date and time is relevant to an order’s information. This format will be how all dates and times are returned in blocks of data from API GET calls, as well as how the dates and times should be supplied in POST/PUT calls when necessary.
The standard can be understood with the formatting “yyyy-MM-dd’T’HH:mm:ssXXX”. For example, 6:07:27 PM on April 11, 2014 would be depicted as “2014-04-11T18:07:27+00:00”.
The following table defines the details of the format requirements:
|Year||YYYY||4-digit representation of the year|
|Day||DD||2-digit representation of the day of the month|
|Month||MM||2 digit representation of the month|
|Time||HH:MM:SS||24-hour time (00:00:00 – 23:59:59)|
IETF & ISO Codes
Kibo uses standardized IETF (Internet Engineering Task Force) and ISO (International Organization for Standardization) codes to denote locales and currencies in OMS. These are explained in the Create Order guide where they are often needed when making requests, but are also listed here for quick reference with all APIs.
The IETF codes for locations commonly used in OMS are below:
|IETF Code||Meaning||IETF Code||Meaning||IETF Code||Meaning|
|en-GB||British English||fr-CA||Canadian French||ru-RU||Russian|
|en-HL||Hong Kong English||fr-FR||French||sv-SE||Swedish|
The ISO codes for the supported currencies in OMS are:
|ISO Code||Currency||ISO Code||Currency||ISO Code||Currency|
|USD||US Dollar||RUB||Russian Ruble||UAH||Ukrainian Hryvnia|
|CAD||Canadian Dollar||MEX||Mexican Peso||HUF||Hungarian Forint|
|GBP||Pound Sterling||MXN||Mexican Peso||IDR||Indonesian Rupiah|
|CHF||Swiss Franc||EUR||Euro||IRR||Iranian Rial|
|NOK||Norwegian Krone||DKK||Danish Krone||KWD||Kuwaiti Dinar|
|SEK||Swedish Krona||SGD||Singapore Dollar||TWD||New Taiwan Dollar|
|HKD||Hong Kong Dollar||PLN||Poland Zloty||QAR||Qatari Rial|
|CNY||Yuan Renminbi||RON||Romanian Leu||SAR||Saudi Riyal|
|JPY||Yen||ARS||Argentine Peso||THB||Thai Baht|
|NZD||New Zealand Dollar||BRL||Brazil Real||AED||UAE Dirham|
|KRW||South Korean Won||HRK||Croatian Kuna||AUD||Australian Dollar|
|INR||Indian Rupee||CZK||Czech Koruna|