Shopper Promotions

GET Return an array of enabled promotions for specified IDs.

GET /organizations/{organizationId}/promotions

Operation ID: getPromotions. Security: ShopperToken (sfcc.shopper-promotions, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-promotions, sfcc.shopper-standard).

In the request URL, you can specify up to 50 IDs. If you specify an ID that contains either parentheses or the separator characters, you must URL encode these characters. Each request returns only enabled promotions as the server does not consider promotion qualifiers or schedules.

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 and a 3-character instance type identifier.
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
```
ids (query, array of string, required) A comma-separated list of promotion identifiers. Maximum: 50.
Items: Maximum length: 256.
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 & RFC 1766. 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
```
personalized (query, string)
Controls whether personalization is applied to the response. Set to none to opt out of personalized response handling so the response is safe to cache at the CDN layer.

When set to none, the server skips applying personalization to the response.

Allowed values: none. Example: none.
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.

Responses

200 Promotion information retrieved successfully.

Media type: application/json. Schema: PromotionResult.

Example: PromotionsResult Multiple promotions retrieved by ID

{
  "limit": 2,
  "data": [
    {
      "id": "Buy5for50",
      "name": "Buy 5 for $50",
      "calloutMsg": "Buy 5 for $50",
      "details": "Buy any 5 qualifying items and pay only $50. Discount applied at checkout.",
      "currency": "USD",
      "startDate": "2025-01-01T00:00:00Z",
      "endDate": "2025-12-31T23:59:00Z"
    },
    {
      "id": "$5_off_ties_promotion",
      "name": "$5 Off Ties Promotion",
      "calloutMsg": "$5 off Men's Ties",
      "details": "$5 off Men's Ties when you apply coupon code TIES5.",
      "currency": "USD",
      "startDate": "2025-03-01T00:00:00Z",
      "endDate": "2025-06-30T23:59:00Z",
      "c_promoCategory": "apparel"
    }
  ],
  "total": 2
}

404 Returned when there is no promotion found with the given ID for the requested site.

Media type: application/problem+json. Schema: ErrorResponse.

Example: getPromotions404

{
  "type": "/PromotionNotFoundException",
  "detail": "There is no promotion found with the given ID for the requested site.",
  "title": "Not Found",
  "instance": "/foo"
}