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

Promotions resource (Data API 23.2)

Summary

Http Method Resource Description
GET /sites/{site_id}/promotions/{id} Action to get promotion information.
PATCH /sites/{site_id}/promotions/{id} Updates the promotion with the specified information.
DELETE /sites/{site_id}/promotions/{id} Deletes the promotion by ID
PUT /sites/{site_id}/promotions/{id} Creates a promotion using the information provided.

Get Promotion

Action to get promotion information.

Url

GET https://hostname:port/dw/data/v23_2/sites/{site_id}/promotions/{id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

Promotion

Path Parameters

Parameter Type Description Constraints
id String The id of the requested promotion. minLength=1
site_id String The site context. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 PromotionNotFoundException

promotionId (String)

siteId (String)

 Thrown in case the promotion does not exist matching the given id

Sample

REQUEST:
GET /s/-/dw/data/v23_2/sites/SiteGenesis/promotions/order-promotion HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
Content-Type: application/json; charset=UTF-8

# in case of success:
 
RESPONSE:
HTTP/1.1 200 OK
Expires: Thu, 01-Aug-2014 00:00:00 GMT
x-dw-resource-state: 43c2d7a118bd0a4034399ed86c86654b40c198ea64fd3195e5587d9211d10d7e
{
   "_v" : "23.2",
   "_type" : "promotion",
   "assignment_information" : 
   {
      "_type" : "promotion_assignment_information",
      "active" : true,
      "active_campaign_assignments" : 
      [
         
         {
            "_type" : "promotion_campaign_assignment",
            "campaign_id" : "test-campaign",
            "description" : "$10 off orders $200 and up",
            "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/promotion_campaign_assignments/order-promotion/test-campaign",
            "promotion_id" : "order-promotion",
            "schedule" : 
            {
               "_type" : "schedule"
            }
         }
      ],
      "campaign_id" : "test-campaign",
      "end_date" : "2050-06-01T00:00:00.000Z",
      "schedule" : 
      {
         "_type" : "schedule"
      },
      "schedule_type" : "campaign",
      "start_date" : "2010-06-01T00:00:00.000Z"
   },
   "enabled" : true,
   "exclusivity" : "class",
   "id" : "order-promotion",
   "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/promotion_campaign_assignments/my-promotion/order-promotion",
   "name" : 
   {
      "default" : "$10 off orders $200 and up"
   },
   "promotion_class" : "order"
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 400 BAD REQUEST
Expires: Thu, 01-Jan-1970 00:00:00 GMT
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"PromotionNotFoundException",
    "message":"No promotion with ID 'my-promotion' in site 'SiteGenesis' was found."
  }
}

Update Promotion

Updates the promotion with the specified information.

Url

PATCH https://hostname:port/dw/data/v23_2/sites/{site_id}/promotions/{id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

Promotion

Response Document

Promotion

Path Parameters

Parameter Type Description Constraints
id String The id of the requested promotion. minLength=1
site_id String The site context. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 PromotionNotFoundException

promotionId (String)

siteId (String)

 Thrown in case the promotion does not exist matching the given id

Sample

REQUEST:
PATCH /dw/data/v23_2/sites/SiteGenesis/promotions/my-promotion HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

{
   "enabled" : true,
   "name" : "My Promotion",
   "exclusivity" : "class",
   "promotion_class" : "order"
}
# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
   "_v" : "23.2",
   "_type" : "promotion",
   "enabled" : true,
   "exclusivity" : "class",
   "name" : 
   {
      "default" : "My Promotion"
   },
   "id" : "my-promotion",
   "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/promotion_campaign_assignments/my-promotion/my-promotion",
   "promotion_class" : "order"
}

# in case of failure:

RESPONSE:
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"PromotionNotFoundException",
    "message":"No promotion with ID 'my-promotion' was found."
  }
}

Delete Promotion

Deletes the promotion by ID

Url

DELETE https://hostname:port/dw/data/v23_2/sites/{site_id}/promotions/{id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Path Parameters

Parameter Type Description Constraints
id String Promotion id to remove minLength=1, nullable=false
site_id String The site context. minLength=1

Sample

REQUEST:
DELETE /s/-/dw/data/v23_2/sites/SiteGenesis/promotions/my-promotion HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

Create Promotion

Creates a promotion using the information provided.

Url

PUT https://hostname:port/dw/data/v23_2/sites/{site_id}/promotions/{id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Request Document

Promotion

Response Document

Promotion

Path Parameters

Parameter Type Description Constraints
id String The id of the promotion to create. minLength=1
site_id String The site context. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 IdConflictException

bodyID (String)

urlID (String)

 if the Id in request is not the same as the ID in document.

Sample

REQUEST:
PUT /dw/data/v23_2/sites/SiteGenesis/promotions/my-promotion HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
   "enabled" : true,
   "name" : "My Promotion",
   "exclusivity" : "class",
   "promotion_class" : "order"
}

# in case of success:

RESPONSE:
HTTP/1.1 201 CREATED
Content-Length: 67
Location: https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/promotions/my-promotion
Content-Type: application/json; charset=UTF-8
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
   "_v" : "23.2",
   "_type" : "promotion",
   "active" : true,
   "enabled" : true,
   "exclusivity" : "no",
   "id" : "my-promotion",
   "name" : 
   {
      "default" : "My Promotion"
   },
   "promotion_class" : "product"
}

# in case of failure:

RESPONSE:
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: max-age=0,no-cache,no-store,must-revalidate
{
  "_v" : "23.2",
  "fault":{
    "type":"PromotionCreateException",
    "message":"The promotion with ID ''my-promotion' could not be created.
  }
}

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.