---
schema_version: "1"
id: bdb36cad8b7a2709705545e246385e9f2acd44b4ffe52f12afd8512c2c8077c7
title: Shopper Consents
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-consents.md
canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-consents
source_site: developer.salesforce.com
content_type: documentation
content_hash: cb1c5a32f27f14ac4680a04b3c62255f88c4f8a415c90b897cdfa5484c307da2
products:
  - B2C Commerce API
  - Salesforce APIs
---
Shopper Consents

# Shopper Consents

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-consents/shopper-consents-oas-v1-public.yaml)

## 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.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

For details on how to request a shopper access token from SLAS, see the guest user flows for [public clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-public-client.html) and [private clients](https://developer.salesforce.com/docs/commerce/commerce-api/guide/slas-private-client.html) in the SLAS guides.

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Responses from this API are not cached. Consent data is unique to each shopper.

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Get Consent Subscriptions

Retrieve the communication subscriptions for a shopper.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-consents/v1/organizations/{organizationId}/subscriptions?siteId=RefArch" \
  -H "Authorization: Bearer {access_token}"
```

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

### 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

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

**Version:** 1.2.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/shopper/shopper-consents/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-consents: Allows read operations on shopper consents
    *   Scope sfcc.shopper-consents.rw: Allows read/write operations on shopper consents
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-consents: Allows read operations on shopper consents
    *   Scope sfcc.shopper-consents.rw: Allows read/write operations on shopper consents
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-consents: Allows read operations on shopper consents
    *   Scope sfcc.shopper-consents.rw: Allows read/write operations on shopper consents

## Operations

### GET Get shopper consent preferences

`GET /organizations/{organizationId}/subscriptions`

Operation ID: `getSubscriptions`. Security: ShopperToken (sfcc.shopper-consents, sfcc.shopper-consents.rw); ShopperClientContextToken (sfcc.shopper-consents, sfcc.shopper-consents.rw).

Retrieve all subscription preferences for the shopper (authenticated or guest).

Use the 'expand' parameter to include additional fields in the response:

*   expand=\["consentStatus"\]: Include subscription status information
*   expand=\[\]: Default behavior, excludes status for privacy and performance

The expand parameter provides privacy benefits by not exposing sensitive status information unless explicitly requested.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `tags` (query, array of Tag, style: form, explode: false) Optional parameter of 0 or more query string values which act as a filtering criteria. Multiple values are treated with `OR` logic, and absence of a value indicates no filtering by tag is desired.  
    Minimum items: 0. Maximum items: 10.
    
    _Example: one_ One tag filter
    
    ```
    [
      "homepage_banner"
    ]
    ```
    
    _Example: multiple_ Multiple tag filters (ORs)
    
    ```
    [
      "homepage_banner",
      "user_profile",
      "checkout",
      "registration"
    ]
    ```
    
*   `expand` (query, array of string, style: form, explode: false)
    
    Optional parameter to expand response with additional fields. Accepts an array of field names to include in the response. Currently supports:
    
    *   "consentStatus": Include consent status information in the response
    
    Future expansions may include additional fields.
    
      
    Items: Allowed values: `consentStatus`. Example: `consentStatus`. Default: `[]`. Minimum items: 0. Maximum items: 10. Unique items.
    
    _Example: empty_ No expansion (default behavior)
    
    ```
    []
    ```
    
    _Example: consentStatus_ Include status information
    
    ```
    [
      "consentStatus"
    ]
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `personalized` (query, string) Controls whether personalization is applied to the response. When set to `none`, the server skips applying personalization to the response.  
    Allowed values: `none`. Example: `none`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Responses

*   **200** Successfully retrieved subscription preferences.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionResponse`.
    
    _Example ConsentSubscriptionResponseGuest: same as GET /organizations/{organizationId}/subscriptions 200 response._ GUEST shopper's available consent subscriptions
    
    _Example: ConsentSubscriptionResponseAuthenticated_ AUTHENTICATED shopper's available consent subscriptions
    
    ```
    {
      "data": [
        {
          "subscriptionId": "weekly-newsletter",
          "channels": [
            "email",
            "whatsapp"
          ],
          "title": "Weekly Newsletter",
          "subtitle": "Get our weekly newsletter with the latest updates. <a href=\"https://example.com/newsletter\">Learn more</a>",
          "consentType": "marketing",
          "consentRequired": false,
          "defaultStatus": "opt_out",
          "tags": [
            "homepage_banner",
            "user_profile"
          ]
        },
        {
          "subscriptionId": "promotional-offers",
          "channels": [
            "sms"
          ],
          "title": "Promotional Offers",
          "subtitle": "Receive special promotional offers. <a href=\"https://example.com/offers\">View terms</a>",
          "consentType": "marketing",
          "consentRequired": false,
          "defaultStatus": "opt_out",
          "tags": [
            "checkout"
          ]
        }
      ]
    }
    ```
    
    _Example: ConsentSubscriptionResponseAuthenticatedExpanded_ AUTHENTICATED shopper's consent subscriptions with expand=\["consentStatus"\]
    
    ```
    {
      "data": [
        {
          "subscriptionId": "weekly-newsletter",
          "channels": [
            "email",
            "whatsapp"
          ],
          "consentStatus": [
            {
              "channel": "email",
              "contactPointValue": "customer@example.com",
              "status": "opt_in"
            },
            {
              "channel": "whatsapp",
              "contactPointValue": "+1 555 123 4567",
              "status": "opt_out"
            }
          ],
          "title": "Weekly Newsletter",
          "subtitle": "Get our weekly newsletter with the latest updates. <a href=\"https://example.com/newsletter\">Learn more</a>",
          "consentType": "marketing",
          "consentRequired": false,
          "defaultStatus": "opt_out",
          "tags": [
            "homepage_banner",
            "user_profile"
          ]
        },
        {
          "subscriptionId": "promotional-offers",
          "channels": [
            "sms"
          ],
          "consentStatus": [
            {
              "channel": "sms",
              "contactPointValue": "+1 555 987 6543",
              "status": "opt_out"
            }
          ],
          "title": "Promotional Offers",
          "subtitle": "Receive special promotional offers. <a href=\"https://example.com/offers\">View terms</a>",
          "consentType": "marketing",
          "consentRequired": false,
          "defaultStatus": "opt_out",
          "tags": [
            "checkout",
            "user_profile"
          ]
        },
        {
          "subscriptionId": "privacy-policy-updates",
          "channels": [
            "email"
          ],
          "consentStatus": [
            {
              "channel": "email",
              "contactPointValue": "customer@example.com",
              "status": "opt_in"
            }
          ],
          "title": "Privacy Policy Updates",
          "subtitle": "Important updates to our privacy policy. <a href=\"https://example.com/privacy\">Read policy</a>",
          "consentType": "legal",
          "consentRequired": true,
          "defaultStatus": "opt_in",
          "tags": [
            "registration"
          ]
        }
      ]
    }
    ```
    
    _Example: ConsentSubscriptionResponseGuest_ GUEST shopper's available consent subscriptions
    
*   **400** Error retrieving subscription preferences
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ConsentSubscriptionError_
    
    ```
    {
      "title": "Error Retrieving Consent Subscription",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/bad-request",
      "detail": "Error retrieving consent subscription."
    }
    ```
    

### POST Update shopper subscription preference

`POST /organizations/{organizationId}/subscriptions`

Operation ID: `updateSubscription`. Security: ShopperToken (sfcc.shopper-consents.rw); ShopperClientContextToken (sfcc.shopper-consents.rw).

Update the consent status for a single subscription.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `ConsentSubscriptionRequest`.

_Example: ConsentSubscriptionUpdateRequest_ Single subscription update request

```
{
  "subscriptionId": "weekly-newsletter",
  "contactPointValue": "john.doe@example.com",
  "channel": "email",
  "status": "opt_in"
}
```

#### Responses

*   **200** Subscription update completed successfully.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionUpdateResponse`.
    
    _Example: ConsentSubscriptionUpdateResponseSuccess_ Single subscription update successful (200 response)
    
    ```
    {
      "subscriptionId": "weekly-newsletter",
      "contactPointValue": "john.doe@example.com",
      "channel": "email",
      "status": "opt_in"
    }
    ```
    
*   **400** Error with request format or validation
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: ConsentSubscriptionUpdateError_
    
    ```
    {
      "title": "Error Updating Consent Subscription",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "Consent subscription could not be updated."
    }
    ```
    

### POST Update shopper subscription preferences

`POST /organizations/{organizationId}/subscriptions/actions/bulk`

Operation ID: `updateSubscriptions`. Security: ShopperToken (sfcc.shopper-consents.rw); ShopperClientContextToken (sfcc.shopper-consents.rw).

Update the consent status for multiple subscriptions in a single bulk request. Supports 1-50 subscription updates per request with partial success handling.

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `locale` (query, LocaleCode) A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.
    
    _Example: LanguageCountry_
    
    ```
    en-US
    ```
    
    _Example: CountryCode_
    
    ```
    US
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body (required)

Media type: `application/json`. Schema: `ConsentSubscriptionBulkRequest`.

_Example: ConsentSubscriptionBulkUpdateRequest_ Bulk subscription update request

```
{
  "subscriptions": [
    {
      "subscriptionId": "weekly-newsletter",
      "contactPointValue": "john.doe@example.com",
      "channel": "email",
      "status": "opt_in"
    },
    {
      "subscriptionId": "sms-alerts",
      "contactPointValue": "+1 555 123 4567",
      "channel": "sms",
      "status": "opt_out"
    }
  ]
}
```

#### Responses

*   **200** All subscription updates completed successfully.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionBulkResponse`.
    
    _Example: ConsentSubscriptionBulkUpdateResponseSuccess_ All subscription updates successful (200 response)
    
    ```
    {
      "results": [
        {
          "subscriptionId": "weekly-newsletter",
          "contactPointValue": "john.doe@example.com",
          "channel": "email",
          "status": "opt_in",
          "success": true
        },
        {
          "subscriptionId": "sms-alerts",
          "contactPointValue": "+1 555 123 4567",
          "channel": "sms",
          "status": "opt_out",
          "success": true
        }
      ]
    }
    ```
    
*   **207** Partial success - some subscription updates succeeded, others failed.
    
    Media type: `application/json`. Schema: `ConsentSubscriptionBulkResponse`.
    
    _Example: ConsentSubscriptionBulkUpdateResponsePartial_ Partial success - some updates failed (207 response)
    
    ```
    {
      "results": [
        {
          "subscriptionId": "weekly-newsletter",
          "contactPointValue": "john.doe@example.com",
          "channel": "email",
          "status": "opt_in",
          "success": true
        },
        {
          "subscriptionId": "sms-alerts",
          "contactPointValue": "invalid-phone",
          "channel": "sms",
          "status": "opt_out",
          "success": false,
          "error": {
            "code": "INVALID_CONTACT_POINT",
            "message": "Invalid phone number format",
            "details": {
              "field": "contactPointValue",
              "provided": "invalid-phone"
            }
          }
        }
      ]
    }
    ```
    
*   **400** Error with bulk request format or validation
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: BulkValidationError_
    
    ```
    {
      "title": "Bulk Request Validation Error",
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/validation",
      "detail": "One or more validation errors occurred in the bulk request.",
      "instance": "/organizations/f_ecom_zzrf_001/subscriptions"
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### LocaleCode

A descriptor for a geographical region by both a language and country code. By combining these two, regional differences in a language can be addressed, such as with the request header parameter `Accept-Language` following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766). This can also just refer to a language code, also RFC 2616/1766 compliant, as a default if there is no specific match for a country. Finally, can also be used to define default behavior if there is no locale specified.

One of: `LanguageCountry`, `LanguageCode`, `DefaultFallback`.

### Tag

Filter criteria for consent subscriptions

Type: `string`.

Minimum length: 1. Maximum length: 256. Example: `homepage_banner`.

### ConsentSubscriptionResponse

Collection wrapper of consent subscriptions

*   `data` (_array of ConsentSubscription_, required)  
    Minimum items: 0. Maximum items: 50.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.

### ConsentSubscriptionRequest

Consent subscription update request

*   `subscriptionId` (_SubscriptionId_, required)
*   `contactPointValue` (_ContactPointValue_, required)
*   `channel` (_ChannelType_, required)
*   `status` (_ConsentStatus_, required)

### ConsentSubscriptionUpdateResponse

Single subscription update response

*   `subscriptionId` (_SubscriptionId_, required)
*   `channel` (_ChannelType_, required)
*   `contactPointValue` (_ContactPointValue_, required)
*   `status` (_ConsentStatus_, required)

### ConsentSubscriptionBulkRequest

Bulk request for updating multiple consent subscriptions

*   `subscriptions` (_array of ConsentSubscriptionRequest_, required) Array of subscription consent updates to process  
    Minimum items: 1. Maximum items: 50.
    
    _Example_
    
    ```
    [
      {
        "subscriptionId": "weekly-newsletter",
        "channel": "email",
        "contactPointValue": "john.doe@example.com",
        "status": "opt_in"
      },
      {
        "subscriptionId": "sms-alerts",
        "channel": "sms",
        "contactPointValue": "+1 555 123 4567",
        "status": "opt_out"
      }
    ]
    ```
    

### ConsentSubscriptionBulkResponse

Bulk response with results for each subscription update request

*   `results` (_array of ConsentSubscriptionResult_, required) Results for each subscription update request

### LanguageCountry

A concatenated version of the standard Language and Country codes, combined with a hyphen '`-`'.

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]-\[A-Z\]\[A-Z\]$. Example: `en-US`.

### LanguageCode

A two letter lowercase language code conforming to the [ISO 639-1](https://www.iso.org/iso-639-language-codes.html) standard. Additionally, this may be used to submit requests with the header parameter `Accept-Language`, following [RFC 2616](https://tools.ietf.org/html/rfc2616) & [RFC 1766](https://tools.ietf.org/html/rfc1766).

Type: `string`.

Pattern: ^\[a-z\]\[a-z\]$. Example: `en`.

### DefaultFallback

A specialized value indicating the system default values for locales.

Type: `string`.

Default: `default`. Pattern: ^default$. Example: `default`.

### ConsentSubscription

*   `subscriptionId` (_SubscriptionId_, required)
*   `channels` (_SubscriptionChannel_, required)
*   `consentStatus` (_object_) Subscription status information across different channels. This field is only included in the response when the 'expand' parameter contains "consentStatus". For privacy and performance reasons, status is not returned by default.
    
    Includes all fields of `SubscriptionStatusArray`.
    
*   `title` (_SubscriptionTitle_)
*   `subtitle` (_SubscriptionSubtitle_)
*   `tags` (_array of Tag_)  
    Default: `[]`. Minimum items: 0. Maximum items: 10.
    
    _Example_
    
    ```
    [
      "homepage_banner",
      "user_profile"
    ]
    ```
    
*   `consentType` (_string_) Type of consent subscription  
    Allowed values: `marketing`, `legal`. Default: `marketing`. Example: `marketing`.
*   `consentRequired` (_boolean_) Whether this subscription is mandatory for the user  
    Default: `false`. Example: `false`.
*   `defaultStatus` (_string_) Default consent status for this subscription  
    Allowed values: `opt_in`, `opt_out`. Default: `opt_out`. Example: `opt_out`.

### SubscriptionId

Identifier for the communication subscription

Type: `string`.

Minimum length: 1. Maximum length: 255. Pattern: ^\[a-z0-9\]+(?:-\[a-z0-9\]+)\*$. Example: `weekly-newsletter`.

### ContactPointValue

The customer's contact point value, polymorphic based on the channel type as below:

*   `sms` - Subject's phone number in E.164 format, ex: `+1 424 535 3546`
*   `email` - Subject's email address in RFC 5321 & RFC 5322 format, ex: `jack.sparrow@salesforce.com`

Type: `string`.

Minimum length: 3. Maximum length: 320. Example: `jack.sparrow@salesforce.com`.

### ChannelType

Type: `string`.

Allowed values: `email`, `sms`, `whatsapp`. Example: `email`.

### ConsentStatus

The consent status of the subscription as supplied or recorded by this system

Type: `string`.

Allowed values: `opt_in`, `opt_out`. Example: `opt_in`.

### ConsentSubscriptionResult

Individual subscription update result with input parameters

*   `subscriptionId` (_SubscriptionId_, required)
*   `channel` (_ChannelType_, required)
*   `contactPointValue` (_ContactPointValue_, required)
*   `status` (_ConsentStatus_, required)
*   `success` (_boolean_, required) Whether the subscription update was successful  
    Example: `true`.
*   `error` (_object_) Error details (present when success is false)
    
    Includes all fields of `ConsentSubscriptionError`.
    

### SubscriptionChannel

Array of `ChannelType`.

Minimum items: 1. Maximum items: 3. Unique items.

_Example_

```
[
  "email",
  "sms"
]
```

### SubscriptionStatusArray

Array of subscription status entries for different channels

Array of `SubscriptionStatusEntry`.

Minimum items: 0. Maximum items: 10.

_Example_

```
[
  {
    "channel": "email",
    "contactPointValue": "john.doe@example.com",
    "status": "opt_in"
  },
  {
    "channel": "sms",
    "contactPointValue": "+1 555 123 4567",
    "status": "opt_out"
  }
]
```

### SubscriptionTitle

The localized title of the subscription for shopper displays

Type: `string`.

Minimum length: 1. Maximum length: 255. Example: `Weekly Newsletter`.

### SubscriptionSubtitle

The localized subtitle of the subscription for shopper displays, may contain HTML markup

Type: `string`.

Minimum length: 1. Maximum length: 2000. Example: `Stay informed about new features. <a href="https://example.com/features">Learn more</a>`.

### ConsentSubscriptionError

Error details for failed subscription updates

*   `code` (_string_, required) Error code indicating the type of failure  
    Maximum length: 100. Example: `INVALID_CONTACT_POINT`.
*   `message` (_string_, required) Human-readable error message  
    Maximum length: 500. Example: `Invalid email address format`.
*   `details` (_object_) Additional error details
    
    _Example_
    
    ```
    {
      "field": "contactPointValue",
      "provided": "invalid-email"
    }
    ```
    

### SubscriptionStatusEntry

Individual subscription status entry for a specific channel

*   `channel` (_ChannelType_, required)
*   `contactPointValue` (_ContactPointValue_, required)
*   `status` (_ConsentStatus_, required)

_Example_

```
{
  "channel": "email",
  "contactPointValue": "john.doe@example.com",
  "status": "opt_in"
}
```