--- schema_version: "1" id: 152f44d8eb6428c7418f758af5049730ff35bdd3fe5da64742b3462e824de907 title: Shop Promotions (deprecated) collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-shop-promotions.md canonical_url: https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-shop-promotions source_site: developer.salesforce.com content_type: documentation content_hash: dc15f5262a54093c3740648be33cdbb3f41ac60ae7ecf4db9c5de714a44a3364 products: - B2C Commerce - Salesforce APIs --- Shop Promotions (deprecated) # Shop Promotions (deprecated) The Shop API endpoints enable developers to build full shopper-experience applications such as storefronts. They are designed for high-scale usage, and include a number of areas such as Baskets & Orders, Customers, Products and Pricing. Shop API endpoints are typically read-only APIs, with the exception of baskets and orders. **Version:** 25.6 ## Servers * `https://{host}/s/{siteId}/dw/shop/v25_6` Protocols: https. ## Security * `customers_auth` (basic) User authentication either for a registered or a guest customer (selectable in request body). Access via Base64 encoded customer:password string as 'Authorization: Basic' header. * `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager. * OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token) * Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required. * `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter. * API key in header: x-dw-client-id ## Operations ### GET Get multiple promotions by filter criteria `GET /promotions` Operation ID: `Get multiple promotions by filter criteria`. Tags: promotions. Security: client\_id; customers\_auth. Handles get promotion by filter criteria Returns an array of enabled promotions matching specified filter criteria. In the request URL, you must provide a campaign\_id parameter, and you can optionally specify a date range by providing start\_date and end\_date parameters. Both parameters are required to specify a date range: omitting one causes the server to return a MissingParameterException fault. Each request returns only enabled promotions; the server does not consider promotion qualifiers or schedules. This endpoint may return the following faults: * 400 - EndDateBeforeStartException - Thrown when the given end date is before the given start date * 400 - MissingEndDateException - Thrown when a start date, but no end date was given * 400 - MissingStartDateException - Thrown when an end date but no start date was given #### Parameters * `campaign_id` (query, string, required) Find the promotions assigned to this campaign (mandatory) Minimum length: 1. Maximum length: 256. * `start_date` (query, string) The start date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ * `end_date` (query, string) The end date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ * `currency` (query, string) The currency mnemonic specified for price #### Responses * **400** `EndDateBeforeStartException` - Thrown when the given end date is before the given start date or `MissingEndDateException` - Thrown when a start date, but no end date was given or `MissingStartDateException` - Thrown when an end date but no start date was given Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `promotion_result`. ### GET Get multiple promotions by Id `GET /promotions/({ids})` Operation ID: `Get multiple promotions by Id`. Tags: promotions. Security: client\_id; customers\_auth. Returns an array of enabled promotions for a list of specified ids. In the request URL, you can specify up to 50 ids. You must enclose the list of ids in parentheses. 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; the server does not consider promotion qualifiers or schedules. #### Parameters * `ids` (path, array of string, required) The ids of the requested promotions. Maximum length: 256. * `locale` (query, string) The locale context. #### Responses * **default** Media type: `application/json, text/xml`. Schema: `promotion_result`. ### GET Get promotion `GET /promotions/{id}` Operation ID: `Get promotion`. Tags: promotions. Security: client\_id; customers\_auth. Returns an enabled promotion using a specified id. Each request returns a response only for an enabled promotion; the server does not consider promotion qualifiers or schedules. This endpoint may return the following faults: * 404 - PromotionNotFoundException - Thrown when there is no promotion found with the given ID for the requested site #### Parameters * `id` (path, string, required) The id of the requested promotion. Maximum length: 256. * `locale` (query, string) The locale context. #### Responses * **404** `PromotionNotFoundException` - Thrown when there is no promotion found with the given ID for the requested site Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `promotion`. ## Schemas ### fault Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error). * `arguments` (_object_) A map that provides fault arguments. Data can be used to provide error messages on the client side. Additional properties: `object`. * `cause` (_cause_) * `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given * `message` (_string_) The message text of the java exception. * `stack_trace` (_string_) * `type` (_string_) The name of the java exception. ### promotion\_result Result document containing an array of promotions. * `count` (_integer (int32)_) The number of returned documents. * `data` (_array of promotion_) The array of promotion documents. * `total` (_integer (int32)_) The total number of documents. _Example_ ``` { "count": 2, "data": [ { "callout_msg": "15% Off GPS Unit With Coupon", "details": "15% Off GPS Unit With Coupon with a coupon.", "end_date": "2020-06-01T00:00Z", "id": "15off-gps", "image": "", "name": "GPS 15% Off", "start_date": "2010-06-01T00:00Z" }, { "callout_msg": "20% Off select TVs", "details": "20% Off TVs, selected models only for this promotion. Limit 1 television per order", "discounted_products_link": "http://example.com/dw/shop/{version}/product_search?pretty_print=true&refine=pmid=20off-tvs", "end_date": "2020-06-01T00:00Z", "id": "20off-tvs", "image": "", "name": "20% Off select TVs", "start_date": "2010-06-01T00:00Z" } ], "total": 2 } ``` ### promotion Document representing a promotion. * `callout_msg` (_string (html)_) The localized call-out message of the promotion. * `currency` (_string_) The currency that a promotion can be applied to. A null value means that the promotion applies to all allowed currencies. * `details` (_string (html)_) The localized detailed description of the promotion. * `discounted_products_link` (_string_) An optional product search link. Product promotions that are marked searchable provide a product search link with the promotion id as refinement. * `end_date` (_string (date-time)_) The end date of the promotion. This property follows the ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ . The time zone of the date time is always UTC. * `id` (_string_) The unique id of the promotion. * `image` (_string_) The URL to the promotion image. * `name` (_string_) The localized name of the promotion. * `start_date` (_string (date-time)_) The start date of the promotion. This property follows the ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ. The time zone of the date time is always UTC. _Example_ ``` { "callout_message": "15% Off GPS Unit With Coupon", "details": "15% Off GPS Unit With Coupon with a coupon.", "end_date": "2020-06-01T00:00Z", "id": "15off-gps", "image": "", "name": "GPS 15% Off", "start_date": "2010-06-01T00:00Z" } ``` ### cause * `cause` (_cause_) * `message` (_string_) * `type` (_string_)