Ordexs API v1 Get an API key

Orders

Create an order

POSThttps://api.ordexs.com/v1/orders

Creates an order exactly as the store's own checkout would: the store prices every line, applies its offers and the discount code, prices delivery, checks stock and assigns the order number. You never send a price. The order arrives in the merchant's dashboard like any other.

Retrying is safe: send an Idempotency-Key header, or an external_id — a second order with the same external_id (and source_name) is refused with duplicate_external_id and the existing order's id.

If the city doesn't match one of the region's cities, the order is still created, with needs_review: "city_unmatched": the merchant confirms the city before it can go to a courier.

shipping_address.region takes the region code, its ISO code or its name, so an agent can pass on what the customer said.

When a line is short, out_of_stock carries details.lines: for each short line, line_item_index, variant_id, requested, available_quantity and preorder_possible (send "preorder": true to take it from the incoming delivery).

Body

  • customerobjectRequired
    4 child fields
    • namestringRequired

      1–160 characters

    • phonestringRequired

      E.164 ("+213551234567") or the national form.

      6–20 characters

    • phone_2string or null

      up to 20 characters

    • emailstring or null

      email · up to 160 characters

  • shipping_addressobjectRequired
    4 child fields
    • countrystring

      Optional. The store's own country is the only one accepted for now.

    • regionstringRequired

      A region from GET /v1/regions: its code ("16"), its ISO code ("DZ-16") or its name ("Alger", "الجزائر"; one typo is tolerated). The order stores the region code.

      1–60 characters

    • citystringRequired

      The city's name. An unrecognised name sets needs_review.

      1–160 characters

    • address1stringRequired

      1–500 characters

  • deliveryobject

    Required (with mode) when the store charges for delivery (GET /v1/delivery/rates says so). For a pickup or a cash collection, only courier_id is read.

    4 child fields
    • modestring

      One of home, pickup_point

    • courier_idstring

      A courier from GET /v1/delivery/rates. Leave it out to use the cheapest rate for the mode.

      starts with cour_

    • pickup_point_idstring

      up to 100 characters

    • pickup_point_namestring

      up to 200 characters

  • line_itemsarray

    What is delivered. Required except for a pickup (its goods are in collect) and a cash collection (it has none).

    up to 100 items · at least 1 item

    5 child fields
    • variant_idstring

      starts with var_

    • titlestring

      A custom line's name

      1–240 characters

    • variant_titlestring

      up to 240 characters

    • quantityintegerRequired

      1–999

    • unit_pricestring

      Set the price by hand, as the dashboard's Create order allows. Leave it out to use the variant's price. Required on a custom line.

  • typestring

    delivery: goods go to the customer. exchange: goods go to the customer and the courier takes others back (collect). pickup: the courier only collects goods from the customer. cash_collection: no goods; the courier collects an amount (total).

    One of delivery, exchange, pickup, cash_collection
    default "delivery"

  • collectobject

    What the courier takes back, for an exchange or a pickup. Name lines of an earlier order with original_order_id and line_item_id (that order must be delivered), or describe them like line_items.

    2 child fields
    • original_order_idstring

      starts with ord_

    • linesarray of objectsRequired

      up to 100 items · at least 1 item

      6 child fields
      • line_item_idstring

        A line of original_order_id.

        starts with li_

      • variant_idstring

        starts with var_

      • titlestring

        1–240 characters

      • variant_titlestring

        up to 240 characters

      • quantityintegerRequired

        1–999

      • unit_pricestring

        An amount as a decimal string in the store's currency, with no more decimals than the currency has ("3500.00" in DZD, "12.500" in TND).

  • totalstring

    What the courier collects, set by hand: the amount of a cash collection, the price difference of an exchange. Leave it out and it is the lines plus delivery.

  • shipping_feestring

    The delivery fee, set by hand instead of the store's rate.

  • discount_codestring

    1–20 characters

  • offer_idsarray of strings

    Offers the shopper took (a bundle, a quantity pack, a cross-sell add-on), as the storefront sends them. The store checks each one against the lines and its schedule, and applies only those that qualify; the rest are ignored.

    up to 4 items

  • notestring

    The customer's note, shown on the order.

    up to 1000 characters

  • external_idstring

    Your own id for this order. Unique per store and source_name.

    1–255 characters

  • source_namestring

    A short name for your integration, e.g. "chatbot".

    1–40 characters

  • metadataobject

    Up to 20 string key/value pairs of your own. Returned as sent, never shown to shoppers.

    up to 20 keys

  • preorderboolean

    A pre-order, like the dashboard's Pre-order switch: a line may take units from the variant's incoming delivery when the shelf is empty, and the order is marked as a pre-order for the merchant. Products set to allow pre-orders take them anyway; this flag extends it to any product with a delivery on its way.

    default false

  • shipobject

    Send the order to the courier right after creating it, like the dashboard's "Upload after creating". Needs the shipping:write scope. The order is created even if the courier refuses it: the answer then carries ship_error instead of shipment. Ignored by preview.

    1 child field
    • courier_idstring

      A courier account from GET /v1/delivery/rates. Leave it out to use the order's courier, the routing rules or the default.

      starts with cour_

Returns

201 Created · The new order. OrderCreated

  • idstringRequired

    starts with ord_

  • objectstringRequired

    always "order"

  • numberstring or nullRequired

    The number the merchant uses, e.g. "ORD-00042".

  • statusstringRequired

    pending → confirmed → (with a courier) shipped → delivered or returned. scheduled, attempt_1…attempt_3, double, waiting and cancelled are set by the merchant's team; preparing, shipped, delivered, returned and deleted come from the courier. New values may be added — treat an unknown one like pending.

    One of pending, confirmed, scheduled, attempt_1, attempt_2, attempt_3, double, waiting, cancelled, preparing, shipped, delivered, returned, deleted

  • sourcestring

    Where the order came from: storefront, dashboard, api or import.

  • source_namestring or null

    The integration that created it, as it named itself in source_name.

  • external_idstring or null

    The id the integration gave this order.

  • needs_reviewstring or null

    Why the merchant must check this order before it can go to a courier. city_unmatched — the city was not recognised. null when nothing needs checking.

  • preorderboolean

    Marked as a pre-order (the goods are on their way to the merchant).

  • assigned_toobject or null

    The teammate working this order.

    2 child fields
    • idstring
    • namestring
  • typestring

    See OrderCreate.type. New values may be added.

    One of delivery, exchange, pickup, cash_collection

  • exchange_ofstring or null

    The delivered order this exchange replaces goods from.

  • collectobject or null

    What the courier takes back, for an exchange or a pickup.

    3 child fields
    • stagestring or null

      Where the collected goods are (pending until they come back).

    • summarystring or null

      The line the courier prints for the goods to collect.

    • linesarray of objects
      8 child fields
      • original_line_item_idstring or null
      • product_idstring or null
      • variant_idstring or null
      • titlestring
      • variant_titlestring or null
      • quantityinteger
      • restockedinteger

        Units put back into stock when they came back.

      • written_offinteger
  • metadataobject

    Your own key/value pairs, returned as you sent them.

  • customerobjectRequired
    5 child fields
    • idstring or null
    • namestring
    • phonestring or null

      E.164.

    • phone_2string or null
    • emailstring or null
  • shipping_addressAddressRequired
    4 child fields
    • countrystring
    • regionobject
      2 child fields
      • codestring
      • namestring
    • cityobject
      2 child fields
      • codestring or null
      • namestring
    • address1string or null
  • deliveryobject
    7 child fields
    • modestring or null

      One of home, pickup_point

    • labelstring or null
    • courierobject or null
      1 child field
      • namestring
    • pickup_pointobject or null
      2 child fields
      • idstring
      • namestring or null
    • tracking_codestring or null
    • tracking_urlstring or null

      The customer's tracking page for this order, on the store's address (https://<store>.myordexs.com/track/<code>). Send it to the customer: it shows every step of the delivery, in the store's language. Each order has its own private link, and it stays the same if the parcel is sent again. It stops working 3 days after the order is delivered or returned (the page then says the link has expired); a cancelled order has no tracking page. null in test mode.

      uri

    • shipped_atstring or null

      ISO 8601 date-time, UTC

  • line_itemsarray of objectsRequired
    10 child fields
    • idstring
    • product_idstring or null
    • variant_idstring or null
    • titlestring
    • variant_titlestring or null
    • skustring or null
    • quantityinteger
    • unit_priceMoney

      An amount of money. amount is a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.

      2 child fields
      • amountstringRequired
      • currencystringRequired
    • totalMoney

      An amount of money. amount is a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.

      2 child fields
      • amountstringRequired
      • currencystringRequired
    • image_urlstring or null
  • discount_codestring or null

    The code the shopper used; null when none

  • discount_namestring or null

    The name of the discount applied

  • offersarray of strings

    Names of the offers applied.

  • offer_idsarray of strings

    The offers applied

  • subtotalMoneyRequired

    An amount of money. amount is a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.

    2 child fields
    • amountstringRequired
    • currencystringRequired
  • shippingMoneyRequired

    An amount of money. amount is a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.

    2 child fields
    • amountstringRequired
    • currencystringRequired
  • discountMoney

    An amount of money. amount is a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.

    2 child fields
    • amountstringRequired
    • currencystringRequired
  • totalMoneyRequired

    An amount of money. amount is a decimal STRING with exactly the currency's number of decimals ("1250.00" in DZD, "12.500" in TND) — never parse it into a float.

    2 child fields
    • amountstringRequired
    • currencystringRequired
  • paymentobjectRequired
    6 child fields
    • methodstring

      "cod" (cash on delivery), "card" (paid in full online by card) or "card_deposit" (a deposit paid online by card, the rest in cash on delivery). More methods may be added.

    • statusstring

      unpaid: nothing received yet. pending: the shopper chose card and has not finished paying. partially_paid: a card deposit was received, the rest is collected on delivery. paid: fully paid (online, or the cash was recorded).

      One of unpaid, pending, partially_paid, paid

    • paid_atstring or null

      ISO 8601 date-time, UTC

    • amount_paidMoney

      What the shopper already paid online toward the order.

      2 child fields
      • amountstringRequired
      • currencystringRequired
    • amount_to_collectMoney

      What the courier collects in cash at delivery: total minus amount_paid.

      2 child fields
      • amountstringRequired
      • currencystringRequired
    • card_discountMoney

      The store’s discount for paying by card, already included in discount and taken off total. Zero for cash on delivery.

      2 child fields
      • amountstringRequired
      • currencystringRequired
  • notestring or null

    The customer's note at checkout.

  • archivedboolean
  • scheduled_forstring or null

    ISO 8601 date-time, UTC

  • livemodebooleanRequired
  • created_atstringRequired

    ISO 8601 date-time, UTC

  • updated_atstringRequired

    ISO 8601 date-time, UTC

  • shipmentShipment or null

    The shipment, when "ship" was sent and the courier took the parcel.

    21 child fields
    • idstringRequired

      starts with shp_

    • objectstringRequired

      always "shipment"

    • order_idstringRequired

      starts with ord_

    • courierobjectRequired
      3 child fields
      • idstring or null

        The store's courier account. null for a test shipment.

      • brandstring

        The courier company, e.g. "zrexpress", "yalidine". "test" for a test shipment.

      • account_namestring or null

        The name the merchant gave the account.

    • tracking_codestring or nullRequired

      The courier's tracking number. null when the send failed.

    • statusShipmentStatusRequired

      pending (registered with the courier, not picked up yet), in_transit, delivered, returned, cancelled, or failed (the courier refused it). New values may be added.

      One of pending, in_transit, delivered, returned, cancelled, failed

    • stageShipmentStage or null
    • stage_changed_atstring or null

      ISO 8601 date-time, UTC

    • status_detailstring or null

      The courier's own words for its last report, in the courier's language.

    • codobject

      The cash on delivery, as the courier reports it.

      2 child fields
      • statusstring or null

        delivered_unpaid: delivered, the courier has not collected yet. cash_collected: the courier holds the cash. paid: the courier paid the merchant. null when the courier does not report it.

        One of delivered_unpaid, cash_collected, paid, archived

      • settled_atstring or null

        ISO 8601 date-time, UTC

    • return_statusstring or null

      suspended: on hold at the courier. return_ready: coming back, waiting for the merchant to collect it. returned_in: handed back.

      One of suspended, return_ready, returned_in

    • driverobject or null
      2 child fields
      • namestring or null
      • phonestring or null

        E.164 when it could be read.

    • eventsarray of objects

      The courier's history of the parcel, oldest first (the last 50).

      3 child fields
      • atstring or null

        The courier's own timestamp, as it sends it.

      • labelstring
      • kindstring or null
    • failure_messagestring or null

      Why the courier refused the parcel

    • validated_atstring or null

      When the parcel was validated with the courier.

      ISO 8601 date-time, UTC

    • packed_atstring or null

      When the parcel was marked packed.

      ISO 8601 date-time, UTC

    • last_checked_atstring or null

      When Ordexs last asked the courier about it.

      ISO 8601 date-time, UTC

    • sent_atstring

      ISO 8601 date-time, UTC

    • livemodebooleanRequired
    • created_atstringRequired

      ISO 8601 date-time, UTC

    • updated_atstringRequired

      ISO 8601 date-time, UTC

  • ship_errorobject or null

    Why the send failed, in the usual error shape (code, message, details). The order exists; send it later with POST /v1/orders/{order_id}/ship.

    4 child fields
    • codestring
    • messagestring
    • detailsobject
    • request_idstring

Errors

Every error has the same shape. This endpoint can answer with: