Fields and personal data
This page lists every field you can send to OrderEx, through the API or in an import file, and says which of them hold personal data. Use it when you decide what your systems send, and when you describe OrderEx in your own records of processing.
What OrderEx does with what you send
OrderEx records facts about your orders and reads them back to you. It never acts on them:
- OrderEx never moves money. A payment fact records what your payment provider did, and nothing is sent to the provider.
- OrderEx never books shipping. A shipment records what your warehouse sent, and nothing is sent to a carrier.
- OrderEx never sends e-mail. A customer's e-mail address is stored as you send it, and OrderEx never writes to it.
What OrderEx sends out is the webhooks you register, to the addresses you give, as Webhooks describes.
Personal data
Personal data in OrderEx is the customer's name, e-mail address and phone number, the shipping and
billing addresses, and the order's notes. All of them are optional, and every one of them is in the
order you create with POST /api/v1/orders. Send only what you need to follow the order in
OrderEx: an order with customerId alone is complete.
customerIdis your own id of the customer. Use a customer number or a pseudonym, never a name, an e-mail address or a personal identity number.- A free text field, such as a line's
description, a metadatavalueor a void'sreason, holds what you put in it. Keep personal data out of free text other thannotes. - An import record takes no personal data: it identifies the customer only by
customerId.
Card data
OrderEx never accepts card data: no card number, expiry date, security code or cardholder name, in any field. The fields of a payment fact are checked for card numbers:
- A
providerNamethat looks like a card number, 13 to 19 digits passing the Luhn check with spaces and hyphens ignored, gives 400. - So does such an
externalTransactionIdwhenpaymentMethodiscard,walletorother. For the other methods it is accepted, since an OCR or KID reference can look like a card number. - The error never repeats the value you sent.
Send the payment provider's transaction id and name, never anything from the card itself.
Fields of the API
The tables list every field of every request body, by the call that takes it. A field that holds personal data says so in the second column.
Orders
POST /api/v1/orders creates an order:
| Field | Personal data | What it is |
|---|---|---|
customerId | No, an id | Your id of the customer, required |
customerName | Yes | The customer's name |
customerEmail | Yes | The customer's e-mail address |
customerPhone | Yes | The customer's phone number |
customerType | No | Consumer or Business |
customerCompanyName | No | The company's name, for a business customer |
customerOrganizationNumber | Can be | The company's organization number. A sole trader's can be a personal identity number |
customerBuyerReference | No | The buyer's own reference, such as a purchase order number |
currency | No | The order's currency, required |
pricesIncludeVat | No | Whether the unit prices include VAT, required |
channel | No | Your code for the shop the order comes from |
externalOrderNumber | No | Your own order number, unique per channel |
notes | Yes | Free text about the order |
shippingAddress | Yes | Where the goods go, with the fields below |
billingAddress | Yes | Where the invoice goes, with the fields below |
delivery | No | How the order is to be delivered, with the fields below |
lines | No | The order's lines, with the fields below, required |
integrationReferences | No | The order's ids in your other systems, with the fields below |
An address, in shippingAddress, billingAddress and PATCH /api/v1/orders/{id}/shipping-address,
holds personal data in every field:
| Field | Personal data | What it is |
|---|---|---|
name | Yes | The recipient's name |
street1 | Yes | The street address |
street2 | Yes | More of the street address |
postalCode | Yes | The postal code |
city | Yes | The city |
region | Yes | The region or county |
country | Yes | The country's name |
countryCode | Yes | The country's ISO 3166 code, such as SE |
delivery describes the delivery the customer chose:
| Field | Personal data | What it is |
|---|---|---|
shippingMethod | No | The delivery method |
carrierName | No | The carrier's name |
carrierCode | No | The carrier's code |
trackingNumber | No | A tracking number, when you have one at checkout |
trackingUrl | No | A tracking page |
estimatedDelivery | No | When the order is expected to arrive |
A line, in lines of a new order and in POST /api/v1/orders/{id}/lines:
| Field | Personal data | What it is |
|---|---|---|
articleNumber | No | Your article number |
description | No | The article's name, as free text |
quantity | No | The ordered quantity |
unitPrice | No | The price per unit, in minor units |
discountPercent | No | A discount in percent |
vatRate | No | The VAT rate in percent, required |
lineType | No | Product, Shipping or Fee |
allowReturn | No | Whether the line may be returned |
externalLineId | No | Your own id of the line, on a new order only |
An integration reference, in integrationReferences of a new order and in
PUT /api/v1/orders/{id}/integrations/{type}/{integrationId}:
| Field | Personal data | What it is |
|---|---|---|
integrationType | No | Your name for the kind of system, such as erp, on a new order |
integrationId | No | Your name for the system, on a new order |
externalId | No | The order's id in that system |
displayName | No | A name to show for the reference |
status | No | Your status of the reference |
data | No | Free text you keep with the reference |
lastSyncedAt | No | When the reference was last synchronized |
orderLineId | No | The line the reference is for, when it is for one line |
Other changes to an order:
| Call | Field | Personal data | What it is |
|---|---|---|---|
PATCH /api/v1/orders/{id}/status | status | No | The status to move the order to |
PUT /api/v1/orders/{id}/metadata | key | No | The metadata's name |
PUT /api/v1/orders/{id}/metadata | value | No | The metadata's value, as free text |
PUT /api/v1/orders/{id}/lines/{lineId}/metadata/{key} | value | No | The line metadata's value, as free text |
PATCH /api/v1/orders/{id}/lines/{lineId}/quantities | ordered, invoiced, cancelled, shipped, delivered, returned and occurredAt | No | Deprecated. See The order lifecycle |
Facts
| Call | Field | Personal data | What it is |
|---|---|---|---|
Cancellations and returns, POST /api/v1/orders/{id}/lines/{lineId}/cancellations and .../returns | externalId | No | Your id of the fact |
quantity | No | The quantity cancelled or returned | |
occurredAt | No | When it happened in your system | |
POST /api/v1/orders/{id}/shipments | externalId | No | Your id of the shipment |
nodeId | No | The fulfillment node the goods left | |
shippedAt | No | When the goods left | |
lines | No | The lines shipped, each with the two fields below | |
orderLineId | No | In lines, the order line shipped | |
quantity | No | In lines, the quantity shipped | |
parcels | No | The parcels, each with the two fields below | |
trackingNumber | No | In parcels, the carrier's tracking number | |
carrier | No | In parcels, the carrier's name | |
POST /api/v1/orders/{id}/shipments/{shipmentId}/void | reason | No | Why the shipment is voided, as free text |
occurredAt | No | When it was voided in your system | |
POST /api/v1/orders/{id}/parcels/{parcelId}/tracking-events | code | No | What happened to the parcel |
carrierCode | No | The carrier's own code for the event | |
externalEventId | No | The carrier's id of the event | |
occurredAt | No | When it happened at the carrier | |
POST /api/v1/orders/{id}/payment-facts | type | No | What happened to the money |
amount | No | The amount, in minor units | |
currency | No | The order's currency | |
paymentMethod | No | How the customer paid | |
providerName | No | The payment provider's name. Never card data | |
externalTransactionId | No | The provider's id of the transaction. Never card data | |
occurredAt | No | When it happened at the provider | |
allocations | No | The lines the money is for, each with the two fields below | |
orderLineId | No | In allocations, the order line the money is for | |
amount | No | In allocations, the line's part of the amount, in minor units |
Fulfillment nodes and webhooks
| Call | Field | Personal data | What it is |
|---|---|---|---|
POST /api/v1/fulfillment/nodes and PUT /api/v1/fulfillment/nodes/{id} | name | No | The node's name, unique in your tenant |
type | No | warehouse, store or 3pl | |
POST /api/v1/webhooks and PUT /api/v1/webhooks/{webhookId} | url | No | Where OrderEx calls you |
eventTypes | No | The events you want | |
description | No | Your description of the webhook | |
isActive | No | Whether the webhook is called, when you change it |
Control
| Call | Field | Personal data | What it is |
|---|---|---|---|
PUT /api/v1/control/imbalances/{imbalanceId}/status | status | No | open, confirmed or resolved |
outcome | No | genuine, intentional or false_alarm, required with resolved only | |
comment | No | Why you changed the status, as free text |
Portal sign in
The OrderEx portals sign their users in with POST /api/v1/auth/login and
POST /api/v1/auth/refresh. Your integration never calls them.
| Field | Personal data | What it is |
|---|---|---|
email | Yes | The portal user's e-mail address |
password | No, a secret | The portal user's password |
tenantSlug | No | Your tenant's short name |
refreshToken | No, a secret | The token that renews a portal session |
Fields of an import record
An import file loads the history you already have, as
The API and the import describes. Each line of the file is one record, and
its type says which kind. A record takes no personal data: the customer is only customerId.
| Field | In the records | Personal data | What it is |
|---|---|---|---|
type | Every record | No | order, cancellation, shipment, tracking_event, payment or return |
channel | Every record | No | Your code for the shop the order comes from |
externalOrderNumber | Every record | No | Your own order number, which ties the record to its order |
placedAt | order | No | When the order was placed |
currency | order and payment | No | The order's currency |
pricesIncludeVat | order | No | Whether the unit prices include VAT |
customerType | order | No | Consumer or Business |
customerId | order | No, an id | Your customer number or a pseudonym, never a name or an e-mail address |
lines | order and shipment | No | The order's lines, or the lines shipped |
externalLineId | Lines, cancellation, return and allocations | No | Your own id of the line |
sku | Lines, cancellation, return and allocations | No | The article number, which finds the line when it has no externalLineId |
description | Lines of an order | No | The article's name |
quantity | Lines, cancellation and return | No | The quantity |
unitPrice | Lines of an order | No | The price per unit, in minor units |
discountPercent | Lines of an order | No | A discount in percent |
vatRate | Lines of an order | No | The VAT rate in percent |
lineType | Lines of an order | No | product, shipping or fee |
externalId | cancellation, return and shipment | No | Your id of the fact |
occurredAt | cancellation, return, tracking_event and payment | No | When it happened in your system |
nodeId | shipment | No | The fulfillment node the goods left |
shippedAt | shipment | No | When the goods left |
parcels | shipment | No | The parcels, each with trackingNumber and carrier |
trackingNumber | Parcels and tracking_event | No | The carrier's tracking number |
carrier | Parcels and tracking_event | No | The carrier's name |
shipmentExternalId | tracking_event | No | Your id of the shipment the parcel is in |
externalEventId | tracking_event | No | The carrier's id of the event |
code | tracking_event | No | What happened to the parcel |
carrierCode | tracking_event | No | The carrier's own code for the event |
paymentType | payment | No | What happened to the money, as type of a payment fact |
amount | payment and allocations | No | The amount, in minor units |
paymentMethod | payment | No | How the customer paid |
providerName | payment | No | The payment provider's name. Never card data |
externalTransactionId | payment | No | The provider's id of the transaction. Never card data |
allocations | payment | No | The lines the money is for |
A record with a field its type does not take is rejected, so an import file cannot carry personal data by mistake.
Next
A reliable integration explains how to send every call again safely.