Hoppa till huvudinnehåll

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.

  • customerId is 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 metadata value or a void's reason, holds what you put in it. Keep personal data out of free text other than notes.
  • 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 providerName that looks like a card number, 13 to 19 digits passing the Luhn check with spaces and hyphens ignored, gives 400.
  • So does such an externalTransactionId when paymentMethod is card, wallet or other. 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:

FieldPersonal dataWhat it is
customerIdNo, an idYour id of the customer, required
customerNameYesThe customer's name
customerEmailYesThe customer's e-mail address
customerPhoneYesThe customer's phone number
customerTypeNoConsumer or Business
customerCompanyNameNoThe company's name, for a business customer
customerOrganizationNumberCan beThe company's organization number. A sole trader's can be a personal identity number
customerBuyerReferenceNoThe buyer's own reference, such as a purchase order number
currencyNoThe order's currency, required
pricesIncludeVatNoWhether the unit prices include VAT, required
channelNoYour code for the shop the order comes from
externalOrderNumberNoYour own order number, unique per channel
notesYesFree text about the order
shippingAddressYesWhere the goods go, with the fields below
billingAddressYesWhere the invoice goes, with the fields below
deliveryNoHow the order is to be delivered, with the fields below
linesNoThe order's lines, with the fields below, required
integrationReferencesNoThe 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:

FieldPersonal dataWhat it is
nameYesThe recipient's name
street1YesThe street address
street2YesMore of the street address
postalCodeYesThe postal code
cityYesThe city
regionYesThe region or county
countryYesThe country's name
countryCodeYesThe country's ISO 3166 code, such as SE

delivery describes the delivery the customer chose:

FieldPersonal dataWhat it is
shippingMethodNoThe delivery method
carrierNameNoThe carrier's name
carrierCodeNoThe carrier's code
trackingNumberNoA tracking number, when you have one at checkout
trackingUrlNoA tracking page
estimatedDeliveryNoWhen the order is expected to arrive

A line, in lines of a new order and in POST /api/v1/orders/{id}/lines:

FieldPersonal dataWhat it is
articleNumberNoYour article number
descriptionNoThe article's name, as free text
quantityNoThe ordered quantity
unitPriceNoThe price per unit, in minor units
discountPercentNoA discount in percent
vatRateNoThe VAT rate in percent, required
lineTypeNoProduct, Shipping or Fee
allowReturnNoWhether the line may be returned
externalLineIdNoYour 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}:

FieldPersonal dataWhat it is
integrationTypeNoYour name for the kind of system, such as erp, on a new order
integrationIdNoYour name for the system, on a new order
externalIdNoThe order's id in that system
displayNameNoA name to show for the reference
statusNoYour status of the reference
dataNoFree text you keep with the reference
lastSyncedAtNoWhen the reference was last synchronized
orderLineIdNoThe line the reference is for, when it is for one line

Other changes to an order:

CallFieldPersonal dataWhat it is
PATCH /api/v1/orders/{id}/statusstatusNoThe status to move the order to
PUT /api/v1/orders/{id}/metadatakeyNoThe metadata's name
PUT /api/v1/orders/{id}/metadatavalueNoThe metadata's value, as free text
PUT /api/v1/orders/{id}/lines/{lineId}/metadata/{key}valueNoThe line metadata's value, as free text
PATCH /api/v1/orders/{id}/lines/{lineId}/quantitiesordered, invoiced, cancelled, shipped, delivered, returned and occurredAtNoDeprecated. See The order lifecycle

Facts​

CallFieldPersonal dataWhat it is
Cancellations and returns, POST /api/v1/orders/{id}/lines/{lineId}/cancellations and .../returnsexternalIdNoYour id of the fact
quantityNoThe quantity cancelled or returned
occurredAtNoWhen it happened in your system
POST /api/v1/orders/{id}/shipmentsexternalIdNoYour id of the shipment
nodeIdNoThe fulfillment node the goods left
shippedAtNoWhen the goods left
linesNoThe lines shipped, each with the two fields below
orderLineIdNoIn lines, the order line shipped
quantityNoIn lines, the quantity shipped
parcelsNoThe parcels, each with the two fields below
trackingNumberNoIn parcels, the carrier's tracking number
carrierNoIn parcels, the carrier's name
POST /api/v1/orders/{id}/shipments/{shipmentId}/voidreasonNoWhy the shipment is voided, as free text
occurredAtNoWhen it was voided in your system
POST /api/v1/orders/{id}/parcels/{parcelId}/tracking-eventscodeNoWhat happened to the parcel
carrierCodeNoThe carrier's own code for the event
externalEventIdNoThe carrier's id of the event
occurredAtNoWhen it happened at the carrier
POST /api/v1/orders/{id}/payment-factstypeNoWhat happened to the money
amountNoThe amount, in minor units
currencyNoThe order's currency
paymentMethodNoHow the customer paid
providerNameNoThe payment provider's name. Never card data
externalTransactionIdNoThe provider's id of the transaction. Never card data
occurredAtNoWhen it happened at the provider
allocationsNoThe lines the money is for, each with the two fields below
orderLineIdNoIn allocations, the order line the money is for
amountNoIn allocations, the line's part of the amount, in minor units

Fulfillment nodes and webhooks​

CallFieldPersonal dataWhat it is
POST /api/v1/fulfillment/nodes and PUT /api/v1/fulfillment/nodes/{id}nameNoThe node's name, unique in your tenant
typeNowarehouse, store or 3pl
POST /api/v1/webhooks and PUT /api/v1/webhooks/{webhookId}urlNoWhere OrderEx calls you
eventTypesNoThe events you want
descriptionNoYour description of the webhook
isActiveNoWhether the webhook is called, when you change it

Control​

CallFieldPersonal dataWhat it is
PUT /api/v1/control/imbalances/{imbalanceId}/statusstatusNoopen, confirmed or resolved
outcomeNogenuine, intentional or false_alarm, required with resolved only
commentNoWhy 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.

FieldPersonal dataWhat it is
emailYesThe portal user's e-mail address
passwordNo, a secretThe portal user's password
tenantSlugNoYour tenant's short name
refreshTokenNo, a secretThe 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.

FieldIn the recordsPersonal dataWhat it is
typeEvery recordNoorder, cancellation, shipment, tracking_event, payment or return
channelEvery recordNoYour code for the shop the order comes from
externalOrderNumberEvery recordNoYour own order number, which ties the record to its order
placedAtorderNoWhen the order was placed
currencyorder and paymentNoThe order's currency
pricesIncludeVatorderNoWhether the unit prices include VAT
customerTypeorderNoConsumer or Business
customerIdorderNo, an idYour customer number or a pseudonym, never a name or an e-mail address
linesorder and shipmentNoThe order's lines, or the lines shipped
externalLineIdLines, cancellation, return and allocationsNoYour own id of the line
skuLines, cancellation, return and allocationsNoThe article number, which finds the line when it has no externalLineId
descriptionLines of an orderNoThe article's name
quantityLines, cancellation and returnNoThe quantity
unitPriceLines of an orderNoThe price per unit, in minor units
discountPercentLines of an orderNoA discount in percent
vatRateLines of an orderNoThe VAT rate in percent
lineTypeLines of an orderNoproduct, shipping or fee
externalIdcancellation, return and shipmentNoYour id of the fact
occurredAtcancellation, return, tracking_event and paymentNoWhen it happened in your system
nodeIdshipmentNoThe fulfillment node the goods left
shippedAtshipmentNoWhen the goods left
parcelsshipmentNoThe parcels, each with trackingNumber and carrier
trackingNumberParcels and tracking_eventNoThe carrier's tracking number
carrierParcels and tracking_eventNoThe carrier's name
shipmentExternalIdtracking_eventNoYour id of the shipment the parcel is in
externalEventIdtracking_eventNoThe carrier's id of the event
codetracking_eventNoWhat happened to the parcel
carrierCodetracking_eventNoThe carrier's own code for the event
paymentTypepaymentNoWhat happened to the money, as type of a payment fact
amountpayment and allocationsNoThe amount, in minor units
paymentMethodpaymentNoHow the customer paid
providerNamepaymentNoThe payment provider's name. Never card data
externalTransactionIdpaymentNoThe provider's id of the transaction. Never card data
allocationspaymentNoThe 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.