These guides provide examples for many tasks that a developer will need to be familiar with during implementation.



OMS Standards

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.

Date/Time Formatting

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:

YearYYYY4-digit representation of the year
DayDD2-digit representation of the day of the month
MonthMM2 digit representation of the month
TimeHH:MM:SS24-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 CodeMeaningIETF CodeMeaningIETF CodeMeaning
en-USUS Englishde-DEGermannl-NLDutch
en-CACanadian Englishel-GRGreekno-NONorwegian
en-GBBritish Englishfr-CACanadian Frenchru-RURussian
en-HLHong Kong Englishfr-FRFrenchsv-SESwedish
en-INIndian Englishit-ITItalianzh-cmn-CNMandarin
es-ESSpanishja-JPJapanesezh-HANTTraditional Chinese
es-MXMexican Spanishko-KRKoreanzh-yue-CNCantonese

The ISO codes for the supported currencies in OMS are:

ISO CodeCurrencyISO CodeCurrencyISO CodeCurrency
USDUS DollarRUBRussian RubleUAHUkrainian Hryvnia
CADCanadian DollarMEXMexican PesoHUFHungarian Forint
GBPPound SterlingMXNMexican PesoIDRIndonesian Rupiah
CHFSwiss FrancEUREuroIRRIranian Rial
NOKNorwegian KroneDKKDanish KroneKWDKuwaiti Dinar
SEKSwedish KronaSGDSingapore DollarTWDNew Taiwan Dollar
HKDHong Kong DollarPLNPoland ZlotyQARQatari Rial
CNYYuan RenminbiRONRomanian LeuSARSaudi Riyal
JPYYenARSArgentine PesoTHBThai Baht
NZDNew Zealand DollarBRLBrazil RealAEDUAE Dirham
KRWSouth Korean WonHRKCroatian KunaAUDAustralian Dollar
INRIndian RupeeCZKCzech Koruna