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:

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

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.

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.

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

1. 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.