API conventions

Requests and responses

Send JSON request bodies with Content-Type: application/json. Most commerce payloads use snake_case field names. Some subsystems, including plugin management, expose fields such as packageName; follow each endpoint's contract.

Treat IDs as opaque strings. Use the returned id to address a resource; a human-readable order number is not the resource ID.

Money

Monetary values use integer cents. For example, 1299 represents 12.99 in a currency with two decimal places.

Product selling prices such as base_price_cents are gross. Purchase-cost fields can be net. Use the field's documented meaning instead of assuming every amount includes tax.

Order line items preserve pricing and tax snapshots. Compute displayed totals from server-provided values, especially during checkout.

Pagination

The administrative product and order lists use these parameters:

{
  "products": [],
  "count": 0,
  "limit": 50,
  "offset": 0
}

count is the matching record count, not the current page length. Resource-specific visibility rules can further restrict returned items. In the product list, member channel restrictions are applied after the page query, so a short page does not necessarily mean the end of the catalog. Advance by limit and use the pagination metadata.

Not all endpoints use this envelope. For example, the storefront product list returns a products array without the same pagination contract.

Errors

Errors raised through the kernel's HTTP error helpers use error and message, with optional details:

{
  "error": "not_found",
  "message": "Nicht gefunden"
}

Messages may be in German. Prefer status codes and machine-readable error values for application logic. Some older endpoints return only an error field.

Retrying requests

Retry transient read failures with bounded backoff. For writes, inspect the endpoint's behavior and check the resulting resource before retrying. The API does not promise a universal idempotency header across all routes.

For checkout event delivery, use the event ID to deduplicate notifications as described in Webhooks.