SAP Commerce Cloud

Overview of Violet's SAP Commerce Cloud integration for channel developers

SAP Commerce Cloud (formerly Hybris) exposes its storefront API through the OCC v2 (Omni-Commerce Connect) REST layer. Violet integrates using OAuth2 client credentials against this API.

Connection

Merchants provide the following credentials:

Field	Description
Store URL	OCC base URL (e.g. https://api.merchant.com/occ/v2)
Client ID	OAuth2 client ID
Client Secret	OAuth2 client secret
Base Site ID	The OCC site ID (e.g. electronics, apparel-uk)
Service User UID (optional)	A user UID scoped to order history access; falls back to current if not provided

There is no OAuth user-consent flow. Onboarding is credential-based.

Token Management

Violet mints OAuth tokens internally via the client credentials grant against ${baseUrl}/authorizationserver/oauth/token. Tokens are cached and refreshed approximately 30 seconds before expiry. A 401 on any call invalidates the cached token and triggers a retry.

Webhooks

SAP Commerce Cloud OCC v2 does not push native webhooks by default. Violet attempts to register webhooks via the optional SAP Webhook Services extension (webhookconfigurations endpoint). If the extension is not installed, Violet logs a degraded-mode message and operators must configure outbound webhooks manually via BackOffice, pointing them at the Violet webhook ingress endpoint.

Inbound webhook signatures use HMAC-SHA256 over the raw request body. The signature is passed in the X-Sap-Cc-Webhook-Signature header as a base64-encoded digest.

Discounts

Both custom (fixed/percentage) and synced promo codes are supported:

• Custom discounts: applied before cart creation; the bag total is decremented directly.

• Discount codes: forwarded to the OCC vouchers endpoint during cart processing. After order placement, Violet validates whether the code was applied from the appliedVouchers response and marks the discount accordingly.

Notable Behavior

• Cart-based order submission: Order submission follows the full OCC cart pipeline — create cart, add items, set addresses, set delivery mode, apply payment, apply vouchers, then place order.

• Delivery mode selection: Violet matches the requested shipping method to an available OCC delivery mode by code, then by name. If no match is found, the first available mode is used.

• Payment: OCC's payment model was designed for shopper-side card capture. Violet forwards the gateway transaction ID as a subscriptionId. Merchants whose storefronts require full PCI capture inside SAP Commerce Cloud must handle that separately before using Violet's Direct Order Submission.

• Customer listing: Standard OCC v2 does not expose a bulk customer listing endpoint. Customer sync is driven from order history rather than a direct customer list.

• Service user UID: The fetchOrders endpoint requires a user-scoped token. If using client-credentials only, provide a service user UID in the optional credential field. The literal current value only resolves under user-bearer grants, not client credentials.

• Collections: Category hierarchy and media are not synced — only name, handle, and status.