*Download API specification

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.

The Shopper Consent API provides sensible defaults for optional fields to simplify integration:

• Consent Type: Defaults to "marketing" for marketing communications.
• Consent Required: Defaults to false, making subscriptions optional by default.
• Default Status: Defaults to "opt_out" to respect privacy-first principles.
• Tags: Defaults to an empty array when not specified.

Authentication & Authorization

The Shopper Consent API requires a shopper access token from the Shopper Login and API Access Service (SLAS).

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

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

For a full list of required permissions, see the Authorization Scopes Catalog.

For details on how to request a shopper access token from SLAS, see the guest user flows for public clients and private clients in the SLAS guides.

Data Model

Subscriptions

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

• Subscription Id: Descriptive identifier
• Channels: Array of communication methods - Email, SMS, or WhatsApp
• Consent Type: Marketing or legal subscription classification
• Consent Required: Whether the subscription is mandatory for the shopper
• Default Status: Default opt-in or opt-out behavior
• Consent Status: Array of status entries for each channel showing current opt-in or opt-out status (conditionally returned based on expand parameter)
• Rich Display Information:
• Title: Simple localized string for subscription name
• Subtitle: Simple localized string with HTML markup support for descriptions
• Localized content determined by the locale parameter
• Tags: Categorical tags indicating where the subscription option can appear (defaults to empty array, max 10 tags)

Channels

Channels define the communication methods available for a subscription:

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

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 form
• checkout: Checkout flow
• user_profile: User profile management section

Use Cases

Retrieve communication subscriptions

Retrieve relevant communication subscription options with rich display information.

• Communication subscription options can be filtered by one or more qualifying tags.
• Use the expand parameter to conditionally include subscription status.

Update individual subscription consent

Update consent status for a single subscription with simple request/response pattern.

Bulk subscription updates

Efficiently manage multiple subscription preferences with a single request.

• Update 1-50 subscriptions per bulk request.
• Partial success handling with detailed error reporting for failed updates.

Advanced Features

Expand Parameter

The expand parameter provides conditional field inclusion:

• expand=[] (default): Returns basic subscription information
• expand=["consentStatus"]: Include consent status information in the response
• Future expansion may include additional fields

Best Practices

• Use single subscription updates for real-time, interactive preference changes.
• Use bulk operations when updating multiple subscriptions to reduce API calls and improve performance.
• Only request status information when needed using the expand parameter to reduce latency.*
  

Simple example:

  import { ShopperConsents } from "commerce-sdk-isomorphic";

  const clientConfig = {
    parameters: {
      clientId: "XXXXXX",
      organizationId: "XXXX",
      shortCode: "XXX",
      siteId: "XX"
    }
  };
  const shopperConsentsClient = new ShopperConsents(clientConfig);

API Version: 0.0.33
Last Updated: