Salesforce B2C Commerce 24.7 > Open Commerce API 23.2 > Shop API resources 23.2

Promotions resource (Shop API 23.2)

Summary

Http Method Resource Description
GET /promotions 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.
GET /promotions/({id},...,{id}) 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.
GET /promotions/{id} 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.

Get multiple promotions by filter criteria

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.

Url

GET http://hostname:port/dw/shop/v23_2/promotions?campaign_id={String}&start_date={String}&end_date={String}&currency={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT.
None No authentication.

Response Document

PromotionResult

Query Parameters

Parameter Type Description Constraints
campaign_id String Find the promotions assigned to this campaign (mandatory) mandatory=true, maxLength=256, minLength=1, nullable=false
currency String The currency mnemonic specified for price  
end_date String The end date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ  
start_date String The start date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
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
400 EndDateBeforeStartException   Thrown when the given end date is before the given start date

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.promotions.beforeGET

beforeGET (campaignId : String , startDate : String , endDate : String ) : Status

The function is called before the request will be processed.

Parameters:
campaignId - Find the promotions assigned to this campaign (mandatory)
startDate - The start date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ
endDate - The end date of the promotion in ISO8601 date time format: yyyy-MM-dd'T'HH:mmZ
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.promotions.modifyGETResponse

modifyGETResponse (doc : PromotionResult ) : Status

The function is called after the request has been processed.

Parameters:
doc - the document
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/promotions?campaign_id=test-campaign&start_date=2010-06-01T00:00Z&end_date=2011-06-01T00:00Z HTTP/1.1
Host: example.com
Accept: application/json
 
RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=900,must-revalidate
{
  "_v" : "23.2",
  "_type" : "promotion_result",
  "count": 2,
  "total": 2,
  "data":
  [{
    "id": "15off-gps",
    "name": "GPS 15% Off",
    "callout_msg": "15% Off GPS Unit With Coupon",
    "details": "15% Off GPS Unit With Coupon with a coupon.",
    "image": "",
    "start_date" : "2010-06-01T00:00Z",
    "end_date" : "2020-06-01T00:00Z"
  },
  {
    "id": "20off-tvs",
    "name": "20% Off select TVs",
    "callout_msg": "20% Off select TVs",
    "details": "20% Off TVs, selected models only for this promotion. Limit 1 television per order",
    "image": "",
    "start_date" : "2010-06-01T00:00Z",
    "end_date" : "2020-06-01T00:00Z",
    "discounted_products_link" : "http://example.com/dw/shop/v23_2/product_search?pretty_print=true&refine=pmid=20off-tvs"
  }]
}

Get multiple promotions by Id

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.

Url

GET http://hostname:port/dw/shop/v23_2/promotions/({id},...,{id})?locale={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT.
None No authentication.

Response Document

PromotionResult

Path Parameters

Parameter Type Description Constraints
ids [String] The ids of the requested promotions. maxItems=50, maxLength=256

Query Parameters

Parameter Type Description Constraints
locale String The locale context.  

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.promotion.beforeGET

beforeGET (id : String ) : Status

The function is called before the request will be processed.

Parameters:
id - The id of the requested promotion.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.promotion.modifyGETResponse

modifyGETResponse (scriptPromotion : Promotion , doc : Promotion ) : Status

The function is called after the request has been processed.

Parameters:
scriptPromotion - an instance of dw.campaign.Promotion
doc - the document
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/promotions/(15off-gps,20off-tvs) HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=900,must-revalidate
{
  "_v" : "23.2",
  "_type":"promotion_result",
  "count":2,
  "total":2,
  "data":
  [{
    "id":"15off-gps",
    "name":"GPS 15% Off",
    "callout_msg":"15% Off GPS Unit With Coupon",
    "details":"15% Off GPS Unit With Coupon with a coupon.",
    "image":"",
    "start_date" : "2010-06-01T00:00Z",
    "end_date" : "2020-06-01T00:00Z"
  },
  {
    "id":"20off-tvs",
    "name":"20% Off select TVs",
    "callout_msg":"20% Off select TVs",
    "details":"20% Off TVs, selected models only for this promotion. Limit 1 television per order",
    "image":"",
    "start_date" : "2010-06-01T00:00Z",
    "end_date" : "2020-06-01T00:00Z",
    "discounted_products_link" : "http://example.com/dw/shop/v23_2/product_search?pretty_print=true&refine=pmid=20off-tvs"
  }]
}

Get promotion

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.

Url

GET http://hostname:port/dw/shop/v23_2/promotions/{id}?locale={String}

Formats

json, xml

Authentication

Name Description
JWT Authentication via Customer JWT.
None No authentication.

Response Document

Promotion

Path Parameters

Parameter Type Description Constraints
id String The id of the requested promotion. maxLength=256

Query Parameters

Parameter Type Description Constraints
locale String The locale context.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 PromotionNotFoundException

promotionId (String)

siteId (String)

 Thrown when there is no promotion found with the given ID for the requested site

Customization

This Resource supports server-side customization.

Extension Point Method Detail
dw.ocapi.shop.promotion.beforeGET

beforeGET (id : String ) : Status

The function is called before the request will be processed.

Parameters:
id - The id of the requested promotion.
Returns:
a non-null Status ends the hook execution
dw.ocapi.shop.promotion.modifyGETResponse

modifyGETResponse (scriptPromotion : Promotion , doc : Promotion ) : Status

The function is called after the request has been processed.

Parameters:
scriptPromotion - an instance of dw.campaign.Promotion
doc - the document
Returns:
a non-null Status ends the hook execution

Sample

REQUEST:
GET /dw/shop/v23_2/promotions/15off-gps HTTP/1.1
Host: example.com
Accept: application/json

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
Cache-Control: max-age=900,must-revalidate
{
  "_v" : "23.2",
  "_type":"promotion",
  "id":"15off-gps",
  "name":"GPS 15% Off",
  "callout_message":"15% Off GPS Unit With Coupon",
  "details":"15% Off GPS Unit With Coupon with a coupon.",
  "image":"",
  "start_date" : "2010-06-01T00:00Z",
  "end_date" : "2020-06-01T00:00Z"
}

Infocenter Retirement: On June 30, 2023, the Infocenter was retired, and documentation currently hosted on the Infocenter will be published to Salesforce Help, Commerce Cloud Developer Center, and Salesforce B2C Commerce Developer Documentation Resources. For more information, see the release note.

X OCAPI versions 15.x and 16.x will be retired on March 31, 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.