> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/ecom-platforms/sap-commerce-cloud.md).

# SAP Commerce Cloud

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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/ecom-platforms/sap-commerce-cloud.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.