Choicera Integration
Contract v1, as of 8 November 2026

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

  1. Build the endpoint POST /orders that 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.
  2. 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.
  3. 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

  1. 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".
  2. Handed over We send the order to POST /orders, you answer 201 with your order number.
  3. 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.
  4. Accepted Without a cancellation the order counts as accepted once the period ends, and we collect the amount. The report accepted or 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.
  5. 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

FieldMeaning
publicRefChoicera order number, such as C7K2M9QX4TA. Unique key; store it with your order, every report names it.
orderedAtTime of the order, ISO 8601 in UTC
currencyalways EUR
testtrue for orders from our test environment: create, mark, do not ship
orderTagIdentifier you stored with us, such as an adviser code, otherwise null
customerFirst 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, billingAddressStreet 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.
linesLines with lineId, variantId from your product data, title, variantTitle, quantity, unit price, line discount, line total and vatRatePercent
goodsCents, discountCents, shippingCents, totalCentsGoods before discount, discount, shipping and total, gross in cents. totalCents = goodsCents - discountCents + shippingCents.
vatBreakdownPer tax rate the shipping share, the total and the included VAT. We split shipping by goods value. Use it for your invoice.
paymentMethodapplePay, googlePay, card, klarna, sepaDebit or paypal, for the invoice only. With klarna the customer pays Klarna; never ask the customer for payment.
acceptDeadlineEnd 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

ResponseMeaning
201Created and stored, body {"brandOrderRef": "SW-10042"} with your order number, at most 64 characters
200An order with this publicRef already exists. Same response body as the first time.
503The same publicRef is still being created. With Retry-After, never 409.
4xxOnly 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

typeWhen and with what
acceptedYou accept before the period ends. Optional; without a cancellation the order counts as accepted after the period anyway.
shippedThe goods are on their way; counts as acceptance too. With shipment holding trackingNumber, carrier and optionally trackingUrl.
deliveredDelivered, if you learn about it. Without an earlier shipping report it counts as shipping report and acceptance.
cancelledYou 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

reasonMeaning
price_mismatchPrice differs from your shop
out_of_stocknot available
country_not_servedDelivery country not served
fraud_suspectedSuspected 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

ResponseMeaning
200{"eventId": "...", "result": "applied"} taken over, or "unchanged", it already was so
400Body unreadable, required field missing or value outside the format
401Signature wrong, brand ID unknown or timestamp more than five minutes off our clock
404There is no checkout order with this publicRef for your brand
409Does not fit the state, such as a cancellation after the shipping report. The order stays as it is; state names the state.
429, 503Not 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

CaseRule
We to you, retried5xx, 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, finalOther 4xx and redirects. The order arrives by email right away, with the error code.
You to us, retry5xx, 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, final400, 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.