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

# SAP Commerce Cloud

This guide is intended for SAP Commerce Cloud (formerly Hybris) merchants who are connecting their store to Violet. During this process, you will create a dedicated OAuth client in your SAP Commerce Cloud Backoffice and then provide the generated credentials to Violet through the Violet Connect onboarding tool. You will retain full control of the OAuth client and can revoke it at any time from within your Backoffice. *Total time for completion is around 10 minutes.*

## Prerequisites

* An active SAP Commerce Cloud instance with Backoffice admin access.
* Permission to create OAuth clients via Backoffice or ImpEx.
* Your OCC v2 storefront API must be enabled and accessible (typically at `https://api.<your-host>/occ/v2`).

## Step 1: Create an OAuth Client

Violet authenticates with your SAP Commerce Cloud instance using the OAuth 2.0 `client_credentials` grant. You need to create a dedicated OAuth client with the correct role and scope.

### Option A: Via Backoffice

1. Sign in to your **SAP Commerce Cloud Backoffice**.
2. Navigate to **System > OAuth > OAuth Clients**.
3. Click **Create** to add a new OAuth client.
4. Configure the following fields:
   * **Client ID**: A unique identifier (e.g. `violet-integration`).
   * **Client Secret**: A strong, randomly generated secret.
   * **Authorities**: Set to `ROLE_TRUSTED_CLIENT`.
   * **Authorized Grant Types**: Set to `client_credentials`.
   * **Scopes**: Set to `extended`.
5. Save the client.

### Option B: Via ImpEx

If you prefer to create the OAuth client using ImpEx, import the following script in your HAC (Hybris Admin Console) or via a deployment hook:

```impex
INSERT_UPDATE OAuthClientDetails ; clientId[unique=true]  ; clientSecret       ; authorities            ; authorizedGrantTypes ; scope
                                 ; violet-integration     ; <your-secret-here> ; ROLE_TRUSTED_CLIENT    ; client_credentials   ; extended
```

{% hint style="warning" %}
Replace `<your-secret-here>` with a strong secret. The client secret is stored hashed in SAP CC — you will not be able to retrieve it later. Keep a copy for Step 4 of this guide.
{% endhint %}

{% hint style="info" %}
**Why `ROLE_TRUSTED_CLIENT`?** Violet needs to create carts and place orders on behalf of customers via the `/users/{userId}/carts` and `/users/{userId}/orders` endpoints. These endpoints require trusted-client authority. A standard `ROLE_CLIENT` will authenticate successfully but fail at checkout time.
{% endhint %}

## Step 2: Identify Your Base Site ID

SAP Commerce Cloud organizes storefronts into **base sites** (e.g. `electronics`, `apparel-uk`, `powertools`). Violet needs to know which base site to operate against.

1. In Backoffice, navigate to **WCMS > Website** or **Base Commerce > Base Site**.
2. Locate the base site that corresponds to the storefront you want to connect to Violet.
3. Copy the **Site ID** (UID) — for example, `electronics` or `apparel-uk`.

Alternatively, you can list your base sites by calling your OCC API directly:

```
GET https://api.<your-host>/occ/v2/basesites
```

## Step 3: Locate Your OCC API Base URL

Your OCC v2 base URL is the root endpoint for all storefront API calls. It typically follows one of these patterns:

* `https://api.<your-host>/occ/v2`
* `https://<your-host>/occ/v2`
* `https://<your-host>/rest/v2`

You can confirm the correct URL by calling the base sites endpoint from Step 2. If it returns a JSON response with your base sites, you have the correct URL.

## Step 4: Provide Credentials to Violet

1. In the Violet Connect onboarding tool, select **SAP Commerce Cloud** as your platform.
2. Enter the following credentials:

| Field             | What to enter                       | Example                          |
| ----------------- | ----------------------------------- | -------------------------------- |
| **Store URL**     | Your OCC v2 base URL from Step 3    | `https://api.mystore.com/occ/v2` |
| **Client ID**     | The OAuth client ID from Step 1     | `violet-integration`             |
| **Client Secret** | The OAuth client secret from Step 1 | *(not displayed)*                |
| **Base Site ID**  | The base site UID from Step 2       | `electronics`                    |

3. Submit the form. Violet will immediately validate your credentials by:
   * Requesting an OAuth token from your SAP CC instance.
   * Confirming that your base site ID exists.
   * Verifying that the OAuth client has `ROLE_TRUSTED_CLIENT` authority.

If any step fails, you will see an error message and can retry with corrected values. Upon success, you will be redirected back to the channel that sent you to Violet.

## Credential Summary

| Credential    | Required | Where to find it                                  | Example                          |
| ------------- | -------- | ------------------------------------------------- | -------------------------------- |
| Store URL     | Yes      | OCC API base URL                                  | `https://api.mystore.com/occ/v2` |
| Client ID     | Yes      | Backoffice > OAuth Clients (or your ImpEx script) | `violet-integration`             |
| Client Secret | Yes      | Set at OAuth client creation time                 | *(not displayed)*                |
| Base Site ID  | Yes      | Backoffice > Base Sites, or `GET /basesites`      | `electronics`                    |

## How Violet Uses Your Credentials

Violet uses the Client ID and Client Secret to request an OAuth access token via the `client_credentials` grant against your instance's `/authorizationserver/oauth/token` endpoint. This token is used to:

* **Read your product catalog** to make your items available for purchase through connected channels.
* **Create and manage carts** when a customer begins checkout through a connected channel.
* **Place orders** by walking the OCC cart pipeline (delivery address, shipping mode, payment, and order placement).
* **Read shipping methods** to present delivery options during checkout.
* **Read inventory and pricing** to ensure accurate availability and pricing information.

Access tokens are automatically refreshed before expiry. Your Client ID and Client Secret are stored securely and encrypted at rest.

## Special Considerations

### Credential Security

Your OAuth client credentials grant server-level access to your SAP Commerce Cloud storefront API. Treat them like a password:

* Never share them outside of the secure Violet onboarding form.
* Do not embed them in client-side code, screenshots, or support tickets.
* If you suspect the credentials have been compromised, revoke them immediately (see below) and create a new OAuth client.

### Token Expiration

SAP Commerce Cloud access tokens typically expire after **12 hours** (configurable per instance). Violet handles token refresh automatically in the background — no action is required on your part. The underlying OAuth client credentials do not expire unless you revoke them.

### Revoking Credentials

To revoke your credentials at any time:

1. Sign in to your **SAP Commerce Cloud Backoffice**.
2. Navigate to **System > OAuth > OAuth Clients**.
3. Locate the OAuth client you created for Violet (e.g. `violet-integration`).
4. Delete or deactivate the client.

Once revoked, all subsequent Violet API calls to your store will fail with an authorization error. Create a new OAuth client and provide the new credentials to Violet to restore the connection.

### Webhooks (Optional)

SAP Commerce Cloud does not push webhooks by default. If your instance has the optional **Webhook Services** extension installed, Violet will attempt to register webhooks automatically for real-time sync. If the extension is not present, you can configure outbound webhooks manually in Backoffice pointing at Violet's webhook endpoint. Contact your Violet representative for the webhook URL and setup instructions.

### Permissions

The OAuth client's effective permissions are controlled by its `authorities` and `scope` configuration. Ensure the client has:

* **`ROLE_TRUSTED_CLIENT`** — required for cart and order operations on behalf of customers.
* **`scope=extended`** — required for write access to carts, orders, and payment details.

If the OAuth client is configured with only `ROLE_CLIENT`, authentication will succeed but order-related operations will fail with 401/403 errors.


---

# 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://merchant-help.violet.io/platform-guides/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.