Selling cash on delivery
Addresses and countries
Every address has two levels, a region and a city, whatever the country calls them. Use the geography endpoints to get them right.
Two levels, any country
Ordexs is built for cash-on-delivery merchants in several countries, and every country divides itself differently: wilayas and communes in Algeria, provinces in Morocco, gouvernorats and délégations in Tunisia. The API uses two neutral names everywhere:
region: the first level (wilaya, province, gouvernorat…), with acode;city: the second level (commune, ville, délégation…), with anameand, where the country has them, acode.
GET /v1/countries tells you what each country calls them (region_label, city_label), so your own screens can say "Wilaya" to an Algerian customer.
Getting an address right
GET /v1/regions?country=DZ: every region with itscode(Algeria:"16"is Alger) and its ISO 3166-2 code ("DZ-16").GET /v1/cities?country=DZ®ion=16: every city of that region.- Send the region code and the city name in
shipping_address:
{
"shipping_address": {
"region": "16",
"city": "Bab El Oued",
"address1": "12 rue Ali Boumendjel"
}
}A region code that doesn't exist is refused with region_unknown. A city name that doesn't match is accepted but flags the order for review (see Orders). Matching forgives case, accents and a letter or two of misspelling (bab el oued, Bab-El-Oued and Bab El Oud all match), and also accepts the city's name in local script (name_local).
In responses, both levels come back as objects: region: {code, name} and city: {code, name}.
Delivery prices
GET /v1/delivery/rates?region=16 returns what this store charges to deliver there, per mode (home or pickup_point) and courier, computed exactly as its checkout does. When a store doesn't charge for delivery, the response says so and orders need no delivery choice.
Phone numbers
The API returns phones in E.164 (+213551234567). It accepts E.164 or the country's national form (0551234567), and normalises it for the store's country. A number that can't be valid for that country is refused with validation_failed, naming the field.
Countries served today
Ordexs serves Algeria today; more countries are coming. GET /v1/countries is always the current list, and the store's own country is in GET /v1/store. Don't hard-code either.
