The API and the import
Facts reach OrderEx in two ways. Your systems call the API for everything that happens from the day you connect them, and OrderEx onboarding imports a file with the history you already have, in a trial run. This page explains which to use for what.
Which to use
| The API | The import | |
|---|---|---|
| What for | The running flow: every order and fact as it happens | The history you already have, loaded in a trial run |
| Who runs it | Your systems | OrderEx onboarding, with files you prepare |
| How it arrives | The calls in these guides, one request per order or fact | Files of JSON Lines, one record per line |
| When an order was placed | When OrderEx receives it | The time in the record's placedAt |
| Personal data | The fields Fields and personal data marks | None: the customer is only customerId |
Both end up as the same facts, checked by the same rules: every import record goes through the same commands as the API, so a record the API would reject is rejected for the same reason.
The API for the running flow
Connect each system to the API for the facts it knows about, as Getting started
and The order lifecycle show: your shop creates each order with
POST /api/v1/orders when the customer checks out, your warehouse system reports each shipment, and
so on. Each fact is sent when it happens, with your own id for it, so a call sent again changes
nothing. A reliable integration explains how to retry.
Do not load your history through the API. An order created through the API is placed when OrderEx receives it, so old orders would look new.
The import for your history
The import loads the orders and facts you already have, so OrderEx can show where goods and money did not match before you connected. OrderEx onboarding runs it into your tenant during a trial run, and your systems never call it. Agree with your OrderEx contact which period to load and how to hand over the files.
Prepare the files
- Each file is JSON Lines in UTF-8: one JSON object per line, one record per object.
- A record's
typesays what it is, and Fields and personal data lists the fields of each type. A record with a field its type does not take is rejected. - Every record names its order by
channelandexternalOrderNumber, the same pair your shop sends to the API. - Every time is the time in your system, such as
placedAt,shippedAtoroccurredAt, with its offset. - Each source has its own files: orders hold
orderandcancellationrecords, shipments holdshipmentandtracking_eventrecords, payments holdpaymentrecords and returns holdreturnrecords.
How OrderEx runs them
- Orders are imported first, then shipments, payments and returns. A record whose order or shipment is not there yet is rejected, and the file can be run again once it is.
- Each order is imported all or nothing. A rejected order is reported with its reason and the line of the file it is on, and the rest of the file goes on.
- The same file imported twice creates each fact once, since every fact carries your own id.
- OrderEx imports only into a tenant in a trial run. Your production integration uses the API.
Next
Reading data shows how to read orders, their timeline and their shipments back.