Skip to main content

Going live

Go through this list before your integration reports facts from production. Each item links to the guide that explains it.

API keys​

  • Every system has its own production key, and no system uses the test tenant's key in production. See Getting started.
  • Keys are kept on your servers, in a secret store or the environment, never in a browser, an app, a repository or a log.
  • Your calls never log the X-Api-Key header.
  • You know how to replace a key: ask OrderEx for a new key, deploy it, and ask OrderEx to revoke the old one once nothing uses it.
  • If a key may have leaked, ask OrderEx to revoke it at once, and replace it. A revoked key gets 401 on every call.
  • Your integration treats a 401 as an alert to a person, not as something to retry.

Sending facts​

  • Every fact carries your own id, from the system where it happened. See A reliable integration.
  • Every create sends an Idempotency-Key, or an order has a channel and an externalOrderNumber that make a second create a 409 order-already-exists.
  • Your retries resend the same body with the same key, wait longer each time and stop after a limit.
  • A fact rejected because another fact has not arrived yet is kept and sent again later.
  • Every time has an offset, and your servers' clocks are synchronized.
  • Amounts are whole numbers in minor units, and every line has a vatRate. See Core concepts.
  • No card number is ever sent. See Payment facts.

Errors​

  • Your client acts on a problem's type and handles a type it does not know by its status code. See Errors.
  • Your logs keep a failed call's correlationId and traceId, so you can quote them.

Webhooks​

  • Every call's X-OrderEx-Signature is verified on the raw body before anything else. See Webhooks.
  • Duplicates are skipped by X-OrderEx-Event-Id.
  • Your receiver answers within 30 seconds and processes afterwards.
  • You check GET /api/v1/webhooks/{webhookId}/deliveries for deliveries that failed.

Changes to the API​

  • Your client ignores fields it does not know and treats an unknown enum value as other, as the versioning policy asks.
  • Your client logs and alerts on a response with the Deprecation header. Sunset gives the date the endpoint closes, and Link with rel="deprecation" points at the entry that says what to use instead.
  • Someone in your team follows the change list, where every change to the API is announced.
  • Your integration does not call PATCH /api/v1/orders/{id}/lines/{lineId}/quantities to report cancelled, shipped, delivered or returned quantities. See The order lifecycle.