*# Shopper Consent

API Overview

The Shopper Consent API offers a centralized method for managing shopper consent. With this API, shoppers can view and update subscription preferences for marketing communications across various channels. This API controls how and where shoppers receive marketing messages while ensuring compliance with privacy regulations.

Key Features

• Multi-Channel Support: Manage communication subscriptions across email, SMS, push notifications, in-app messages, and postal mail.
• Organization-Based Management: Isolate consent preferences by organization for multi-tenant environments.
• Real-Time Updates: Instantly create and retrieve subscription preferences.
• Compliance Ready: Built with privacy regulations and consent-management best practices in mind.

Authentication & Authorization

The Shopper Consent API requires a JSON Web Token acquired using the Shopper Consent endpoint:

https://{{shortcode}}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{{organizationId}}/customers/actions/login

You must include the relevant scope(s) in the client ID used to generate the SLAS token.

Required Scopes

• sfcc.shopper-consents: Required for reading communication subscription data (GET operations).
• sfcc.shopper-consents.rw: Required for creating and modifying communication subscription data (POST operations).

Use Cases

Shopper Subscription Management

• Retrieve communication subscriptions: Retrieve relevant communication subscription options with display information.
• Guest shoppers can retrieve communication subscriptions options without pre-defined shopper credentials, for example: email address, phone number.
• Authenticated shoppers can retrieve communication subscription options available to their shopper credentials.
• Communication subscription options can be filtered by one or more qualifying tags.
• Update communication subscription consent preferences.

Data Model

Subscriptions

Subscriptions represent a shopper's consent to receive specific types of marketing communications. Each subscription includes:

• Identifier: Descriptive identifier
• Consent Status: Opt-in or opt-out
• Display Information: Title, subtitle, and description for customer-facing interfaces
• Tags: Categorical tags indicating where the subscription option can appear
• Channels: Supported communication methods, such as email, SMS, push notification

Channels

Channels define the communication methods available for a subscription:

• email: Email communications
• sms: SMS/text messages
• whatsapp: WhatsApp

Tags

Tags indicate where subscription options are displayed in your shopper experience. Tags are also accepted as optional filtering parameters in the retrieval of shopper consent subscriptions. For example:

• homepage_banner: Main website homepage
• registration: Shopper registration process
• checkout: Checkout process
• user_profile: User profile management area

Best Practices

User Experience

• Make it easy for shoppers to update their preferences.
• Respect shopper choices immediately.

Implementation Guidelines

• Implement clear and prominent unsubscribe mechanisms.

Compliance Considerations

• Ensure consent is freely given, specific, informed, and unambiguous.
• Implement proper data retention and deletion policies.
• Provide easy access to consent history and preferences.

Error Handling

The API uses standard HTTP status codes and returns detailed error information to help with troubleshooting:

• 400 Bad Request: Invalid request format or missing required fields
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: Insufficient permissions for the requested operation
• 404 Not Found: Requested organization or resource not found
• 500 Internal Server Error: Unexpected server error

Rate Limits

To ensure fair usage and system stability, the Shopper Consent API implements rate limiting. Refer to the response headers for current rate limit status and adjust your integration accordingly.*

For instructions on how to retrieve access token for admin APIs: https://developer.salesforce.com/docs/commerce/commerce-api/guide/authorization-for-admin-apis.html

Example with admin auth

import { ShopperConsents, ClientConfig } from "commerce-sdk";
// or
const { ShopperConsents, ClientConfig } = require("commerce-sdk");

const clientConfig: ClientConfig = {
  parameters: {
    clientId: "XXXXXX",
    organizationId: "XXXX",
    shortCode: "XXX",
    siteId: "XX"
  }
};

token = { access_token: 'INSERT_ACCESS_TOKEN_HERE' };

clientConfig.headers['authorization'] = `Bearer ${token.access_token}`;
const shopperConsentsClient = new ShopperConsents(clientConfig);

API Version: 1.4.4
Last Updated: