Checkout: orders by interface
In the Choicera checkout the customer pays for products from several brands at once. We hand your part of the order over to you, already paid. If your shop has no interface we can use directly, you build the endpoints on this page. Without them, every order arrives as an email with links to cancel and to report the shipment.
What needs doing
- Build the endpoint
POST /ordersthat creates our order in your shop, and send us the base URL and token. Done when a test order from us shows up in your shop and a second delivery of the same order does not create a second one. - Report shipping with the tracking number and every cancellation to our endpoint, signed with the key you get from us. Done when our test address accepts your reports with HTTP 200 and the test order shows as shipped on our side.
- Keep reading the emails to your order address. Returns, customer requests and payment notices only arrive there. Done when we have an order address that someone reads.
How an order runs
- Paid The customer pays in the Choicera checkout. The money runs through a licensed payment service provider and is paid out to you. At hand-over the amount is reserved. You do not ask the customer for payment; your invoice carries no bank details but the note "paid via the Choicera checkout".
- Handed over
We send the order to
POST /orders, you answer 201 with your order number. - Cancellation period
Until 23:59 on the second business day after hand-over you can cancel without us collecting the amount. The
day of hand-over does not count, nor do public holidays at your seat. The exact end is in the
order as
acceptDeadline. You may only cancel for one of the four reasons. - Accepted
Without a cancellation the order counts as accepted once the period ends, and we collect the
amount. The report
acceptedor a shipping report is an acceptance too; we then collect right away. For cards we collect before the reservation runs out at the latest, even while the period is still running. - Shipped Your shipping report with the tracking number goes to the customer as a message, with a link to track the parcel. Report the shipment no later than four weeks after acceptance; after that the order is closed on our side.
Accept the order
POST https://{your-base-url}/orders
Authorization: Bearer {your-token}
Idempotency-Key: {delivery-id}
Content-Type: application/json
Base URL and token come from you, HTTPS only with a valid certificate. We do not follow redirects. In full as a file: checkout-orders.openapi.yaml (OpenAPI 3.1, in German).
Order fields
| Field | Meaning |
|---|---|
publicRef | Choicera order number, such as C7K2M9QX4TA. Unique key; store it with your order, every report names it. |
orderedAt | Time of the order, ISO 8601 in UTC |
currency | always EUR |
test | true for orders from our test environment: create, mark, do not ship |
orderTag | Identifier you stored with us, such as an adviser code, otherwise null |
customer | First name, last name, email and marketingAllowed: whether your contract with us allows you to advertise to this customer. The email is null if your contract does not include contact details; if your shop needs one, use a placeholder address and send nothing to it. |
shippingAddress, billingAddress | Street and house number separate, addition, postcode, city, country DE or AT. No company and no parcel locker. Without a name, the name from customer applies. billingAddress is null if it equals the shipping address. |
lines | Lines with lineId, variantId from your product data, title, variantTitle, quantity, unit price, line discount, line total and vatRatePercent |
goodsCents, discountCents, shippingCents, totalCents | Goods before discount, discount, shipping and total, gross in cents. totalCents = goodsCents - discountCents + shippingCents. |
vatBreakdown | Per tax rate the shipping share, the total and the included VAT. We split shipping by goods value. Use it for your invoice. |
paymentMethod | applePay, googlePay, card, klarna, sepaDebit or paypal, for the invoice only. With klarna the customer pays Klarna; never ask the customer for payment. |
acceptDeadline | End of the cancellation period, ISO 8601 in UTC, counted from this call |
variantId is always set and is the value you deliver per variant in your product
data; we tell you which field when you connect. In the JSON feed it is variants[].sku
or variants[].id, on OXID product pages the article ID aid. Create the order with exactly these prices, without recalculating. The unit
price after discount does not always come out in whole cents; the line total is what counts.
Response
| Response | Meaning |
|---|---|
| 201 | Created and stored, body {"brandOrderRef": "SW-10042"} with your order number, at most 64 characters |
| 200 | An order with this publicRef already exists. Same response body as the first time. |
| 503 | The same publicRef is still being created. With Retry-After, never 409. |
| 4xx | Only if the body is not JSON, publicRef is missing or the token is wrong. Final except 408, 425 and 429: we then send the order by email. After 401 or 403 all further orders arrive by email until you give us a new token. |
Business reasons are not a 4xx. Accept the order and cancel it by report: price
differs with price_mismatch, item unknown or not available with
out_of_stock, country not served with country_not_served. Create at most
one order per publicRef, even if a new attempt carries a new
Idempotency-Key. Repeats carry the same body, only acceptDeadline may
change: if you answer a repeat with 200, take acceptDeadline from it.
Report back to Choicera
POST https://choicera.com/api/checkout/brand-feedback/v1
X-Choicera-Brand: {your-brand-id}
X-Choicera-Timestamp: {seconds-since-1970}
X-Choicera-Signature: {hmac-hex}
Content-Type: application/json
{"eventId": "sw-ship-10042", "publicRef": "C7K2M9QX4TA", "type": "shipped",
"shipment": {"trackingNumber": "00340434161234567890", "carrier": "dhl"}}
Every report has an eventId that is unique on your side, such as a UUID. If you
send the same eventId again, nothing changes and you get the response from the first
time; this holds after 200 and 409. After any other error you send the corrected report with the
same eventId. Send the reports for one order one after another and wait at least
30 seconds for each response, because we collect the amount right away on acceptance. Reports work
for every checkout order of yours, including one that arrived by email. In full as a file:
checkout-feedback.openapi.yaml
(OpenAPI 3.1, in German).
Reports
type | When and with what |
|---|---|
accepted | You accept before the period ends. Optional; without a cancellation the order counts as accepted after the period anyway. |
shipped | The goods are on their way; counts as acceptance too. With shipment holding trackingNumber, carrier and optionally trackingUrl. |
delivered | Delivered, if you learn about it. Without an earlier shipping report it counts as shipping report and acceptance. |
cancelled | You cancel the whole order or single lines, before the first shipping report. With cancellation holding reason and lines: "all" or per line lineId and remainingQuantity. |
Cancellation reasons
reason | Meaning |
|---|---|
price_mismatch | Price differs from your shop |
out_of_stock | not available |
country_not_served | Delivery country not served |
fraud_suspected | Suspected fraud |
One order, one shipment. If you cannot deliver everything, cancel the missing lines first and
then report the shipment. remainingQuantity is the quantity of the line you still
deliver; 0 cancels it completely. Repeating the same figure changes nothing. After the first
shipping report no cancellation is possible; returns run through us. A cancellation after the
amount was collected is still possible until the shipping report; we then refund the customer.
On a partial cancellation we spread the line discount proportionally over the remaining units; shipping stays. The response then names quantity, discount and line total per line and the new total; use them for your invoice.
Send the tracking number with shipped right away: the shipping message to the
customer goes out once. Without tracking you leave out shipment. With several parcels
you name the first number. A corrected number goes as another shipped with a new
eventId; it replaces the old one and only shows in the order status. Tracking number at most 64 characters of letters, digits, spaces and hyphens.
Carriers for carrier: dhl, dpd, hermes,
gls, ups, post_at, otherwise other. Without
trackingUrl (https only) we build the tracking link ourselves.
Response
| Response | Meaning |
|---|---|
| 200 | {"eventId": "...", "result": "applied"} taken over, or "unchanged", it already was so |
| 400 | Body unreadable, required field missing or value outside the format |
| 401 | Signature wrong, brand ID unknown or timestamp more than five minutes off our clock |
| 404 | There is no checkout order with this publicRef for your brand |
| 409 | Does not fit the state, such as a cancellation after the shipping report. The order stays as it is; state names the state. |
| 429, 503 | Not possible right now, for example shortly after hand-over. Send again after Retry-After. |
Signature
You get the key from us when you connect; it is valid for your brand only. HMAC-SHA256 signs the
string made of the timestamp exactly as in the header, a dot and the unchanged body. The key is the
UTF-8 bytes of the string you receive. The result goes into X-Choicera-Signature as
lowercase hex. The timestamp is seconds since 1970 in UTC. This is a different method from the
order webhook in step 3.
ts=$(date +%s)
body='{"eventId":"sw-accept-10042","publicRef":"C7K2M9QX4TA","type":"accepted"}'
sig=$(printf '%s.%s' "$ts" "$body" | openssl dgst -sha256 -hmac "$KEY" | sed 's/^.* //')
curl -sS https://choicera.com/api/checkout/brand-feedback/v1 \
-H 'Content-Type: application/json' -H 'X-Choicera-Brand: your-brand-id' \
-H "X-Choicera-Timestamp: $ts" -H "X-Choicera-Signature: $sig" --data "$body"
# PHP
$sig = hash_hmac('sha256', $ts . '.' . $body, $key);
To check your implementation: key beispiel-schluessel-nur-fuer-tests, timestamp
1794231600 and exactly the body from the script above, without spaces and line
breaks, give
207b0a26924107fe70e74d47472e0a214881ba2e08452fad20dafd5c8c722a94. Sign exactly the
bytes you send, in UTF-8 and without compression.
Errors and retries
| Case | Rule |
|---|---|
| We to you, retried | 5xx, 408, 425, 429, no response within 10 seconds, network errors, 2xx other than 200 and 201, a response without brandOrderRef. Every few minutes for up to two hours, then the order arrives by email. |
| We to you, final | Other 4xx and redirects. The order arrives by email right away, with the error code. |
| You to us, retry | 5xx, 503, 429, network errors, timeouts. With growing intervals, for at least 24 hours, with the same eventId. Never drop a 401: fix the clock or the key, sign again, send again. |
| You to us, final | 400, 404, 409, 413, 415. Check the report; after 400, 404, 413 and 415 a corrected report goes with the same eventId. |
If an order arrives by email because your endpoint did not answer, check by its
publicRef whether it is already in your shop before you create it.
Stock
Before payment we check that everything is available. The basis is the stock from your product data, which we read once a day. For a current figure you can also build a query:
GET https://{your-base-url}/stock?variantIds=D3-120,MAG-1001
Authorization: Bearer {your-token}
{"items": [{"variantId": "D3-120", "available": true},
{"variantId": "MAG-1001", "available": false}]}
available means at least one unit available. Shortly before payment we ask for the
items in the cart, at most 50 at a time and never IDs containing a comma, and wait at most three
seconds. So answer from your stock levels, without slow lookups. If no answer comes or an
item is missing from it, the stock from the product data applies.
What arrives by email
Even with the interface you receive these emails at your order address:
- the order itself, if your endpoint does not accept it
- the reminder one day before the period ends, as long as you have neither accepted nor cancelled
- "please do not ship" if collecting the payment fails, and "ship now" if it succeeds after all
- "will not be carried out" if collecting finally fails, and a chargeback with the request to hold the shipment
- customer requests and returns. You confirm label sent and goods received through the links in them; we remind you of the deadlines.
Refunds to the customer always run through us.
Keys and tests
You issue the token for POST /orders; you get the signing key for reports from us.
We exchange both over a channel we agree on when you connect, never in plain text by email. For a
change you accept the old and the new token for a while and let us know; we accept a new signing
key next to the old one for 14 days. If a key has leaked, we replace it at once.
Before going live we send test orders with "test": true, ideally to a separate test
base URL with its own token so your stock stays untouched. For reports on test orders we give you
a test address and a test key; no money moves there, and our real address answers them with
404. We switch the connection on for your brand before the first real
order arrives.
OXID shops
OXID has no interface for orders in its core. The official GraphQL modules only create orders the way a customer orders in the shop, with your shop's prices and without access for a service like ours. For OXID shops the endpoints on this page are therefore the way. If you have another interface that accepts orders with given prices, talk to us.
Questions about the integration: partner contact. Accept unknown fields and new values in lists; new fields and values arrive without a version change, new required fields only with a new version.
