Coupons Resource (Data API 16.4)

Summary

Http Method Resource Description
GET /Sites/{Site_id}/Coupons/{Coupon_id} Action to get coupon information.
The following fields are returned in the Coupon document when specifying the stats expand:
  • exported_code_count
  • redemption_count
  • total_codes_count
PATCH /Sites/{Site_id}/Coupons/{Coupon_id} Updates the coupon with the specified information. The request must include the If-Match header, which holds the last known base-point information. The value of this header is an "ETag" representing the coupon state. If the request does not contain an If-Match header with the current server customer "ETag", a 409 (IfMatchRequiredException) fault is returned. If the If-Match header does not match the current server coupon "ETag", a 412 (InvalidIfMatchException) fault is returned.
DELETE /Sites/{Site_id}/Coupons/{Coupon_id} Delete a coupon by id.
PUT /Sites/{Site_id}/Coupons/{Coupon_id} Creates a coupon using the information provided. If a coupon exists with the same unique identifier, the coupon is replaced completely.

Get Coupon

Action to get coupon information.

The following fields are returned in the Coupon document when specifying the stats expand:
  • exported_code_count
  • redemption_count
  • total_codes_count

Url

GET https://hostname:port/dw/data/v16_4/sites/{site_id}/coupons/{coupon_id}?select={String}&expand={String}

Formats

json, xml

Response Document

Coupon

Path Parameters

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

Query Parameters

Parameter Type Description Constraints
expand String The expand parameter. A comma separated list with the allowed values (stats).  
select String The property selector.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 CouponNotFoundException

couponId (String)

siteId (String)

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

Sample

REQUEST:
GET /s/-/dw/data/v16_4/sites/SiteGenesis/coupons/my-coupon 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
ETag: 43c2d7a118bd0a4034399ed86c86654b40c198ea64fd3195e5587d9211d10d7e
{
   "_v" : "16.4",
  "_type" : "coupon",
   "coupon_id" : "my-coupon",
   "description" : "sytem generated coupon code.",
   "enabled" : true,
   "link" : "https://example.com/s/-/dw/data/v16_4/sites/SiteGenesis/coupons/my-coupon",
   "redemption_limits" : {
      "limit_per_code" : 1,
      "limit_per_customer" : 0,
      "limit_per_time_frame" : {
         "limit" : 0,
         "redemption_time_frame" : 0
      }
   },
   "system_codes_config" : {
      "code_prefix" : "sys",
      "number_of_codes" : 100
   },
   "redemption_count": 2,
   "type" : "system_codes"
}

# 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":"16.4",
   "_type":"fault",
  "fault":{
    "type":"CouponNotFoundException",
    "message":"No coupon with id 'my-coupon' for site 'SiteGenesis' found."
  }
}

Update Coupon

Updates the coupon with the specified information. The request must include the If-Match header, which holds the last known base-point information. The value of this header is an "ETag" representing the coupon state. If the request does not contain an If-Match header with the current server customer "ETag", a 409 (IfMatchRequiredException) fault is returned. If the If-Match header does not match the current server coupon "ETag", a 412 (InvalidIfMatchException) fault is returned.

Url

PATCH https://hostname:port/dw/data/v16_4/sites/{site_id}/coupons/{coupon_id}

Formats

json, xml

Request Document

Coupon

Response Document

Coupon

Path Parameters

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

Header Parameters

Parameter Type Description Constraints
If-Match String Must match the last eTag.  

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 CouponUpdateReadOnlyException

couponId (String)

field (String)

Thrown if you try to update certain fields in a coupon after redeeming or exporting it.
400 CouponCodeDuplicateException

couponId (String)

couponCode (String)

Thrown if the code provided is in use by another coupon.
400 SystemGeneratedCouponQuotaException

couponId (String)

reason (String)

count (String)

maxCount (String)

Thrown whenever a quota regarding system-generated coupons is violated
404 CouponNotFoundException

couponId (String)

siteId (String)

Thrown if the coupon does not exist matching the given id.

Sample

REQUEST:
POST /s/-/dw/data/v16_4/sites/SiteGenesis/coupons/my-coupon HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
If-Match: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

{
   "redemption_limits":
   { "_delete": 0,
     "limit_per_customer" : "3"
   }
  "description":"My coupon 1 as example"
}
# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
ETag: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
   "_v" : "16.4",
  "_type" : "coupon",
   "coupon_id" : "my-coupon",
   "description" : "sytem generated coupon code.",
   "enabled" : true,
   "link" : "https://example.com/s/-/dw/data/v16_4/sites/SiteGenesis/coupons/my-coupon",
   "redemption_limits" : {
      "limit_per_customer" : 3,
      "limit_per_time_frame" : {
         "lmit" : 0,
         "redemption_time_frame" : 0
      }
   },
   "system_codes_config" : {
      "code_prefix" : "xmas2014-",
      "max_number_of_codes" : 100
   },
   "type" : "system_codes"
}

# 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":"16.4",
   "_type":"fault",
  "fault":{
    "type":"CouponNotFoundException",
    "message":"No coupon with id 'my-coupon' found."
  }
}

Delete Coupon

Delete a coupon by id.

Url

DELETE https://hostname:port/dw/data/v16_4/sites/{site_id}/coupons/{coupon_id}

Formats

json, xml

Path Parameters

Parameter Type Description Constraints
coupon_id String Id of the coupon to delete from the site. minLength=1, nullable=false
site_id String The site context. minLength=1

Sample

REQUEST:
DELETE /s/-/dw/data/v16_4/sites/site-one/coupons/my-coupon 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 Coupon

Creates a coupon using the information provided. If a coupon exists with the same unique identifier, the coupon is replaced completely.

Url

PUT https://hostname:port/dw/data/v16_4/sites/{site_id}/coupons/{coupon_id}

Formats

json, xml

Request Document

Coupon

Response Document

Coupon

Path Parameters

Parameter Type Description Constraints
coupon_id String The id of the coupon to create. minLength=1, nullable=false
site_id String The site context. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 CouponInvalidException

couponId (String)

fieldId (String)

Thrown if the coupon passed in is not valid (the argument indicates the field that was invalid).
400 CouponCodeDuplicateException

couponId (String)

couponCode (String)

Thrown if the code provided is in use by another coupon.
400 CouponCreateSingleCodeException

couponId (String)

code (String)

Thrown if a single code coupon does not set the coupon code properly.
400 IdConflictException

bodyID (String)

urlID (String)

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

couponId (String)

reason (String)

count (String)

maxCount (String)

Thrown whenever a quota regarding system-generated coupons is violated
403 SiteAccessForbiddenException

siteId (String)

Thrown if the resource requires global instead of site-specific context.

Sample

REQUEST:
PUT /s/-/dw/data/v16_4/sites/SiteGenesis/coupons/ccc HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
   "coupon_id" : "ccc",
   "description" : "sytem generated coupon code.",
   "enabled" : true,
   "link" : "https://example.com/s/-/dw/data/v16_4/sites/SiteGenesis/coupons/ccc",
   "redemption_limits" : {
      "limit_per_code" : 1,
      "limit_per_customer" : 0,
      "limit_per_time_frame" : {
         "lmit" : 0,
         "redemption_time_frame" : 0
      }
   },
   "system_codes_config" : {
      "code_prefix" : "xmas2014-",
      "max_number_of_codes" : 100
   },
   "type" : "system_codes"
}

# in case of success:

RESPONSE:
HTTP/1.1 201 CREATED
Content-Length: 42
Location: https://example.com/s/-/dw/data/v16_4/sites/SiteGenesis/coupons/ccc
Content-Type: application/json; charset=UTF-8
ETag: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
   "_v" : "16.4",
  "_type" : "coupon",
   "coupon_id" : "ccc",
   "description" : "sytem generated coupon code.",
   "enabled" : true,
   "link" : "https://example.com/s/-/dw/data/v16_4/sites/SiteGenesis/coupons/ccc",
   "redemption_limits" : {
      "limit_per_code" : 1,
      "limit_per_customer" : 0,
      "limit_per_time_frame" : {
         "lmit" : 0,
         "redemption_time_frame" : 0
      }
   },
   "system_codes_config" : {
      "code_prefix" : "xmas2014-",
      "max_number_of_codes" : 100
   },
   "type" : "system_codes"
}

# 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":"16.4",
   "_type":"fault",
  "fault":{
    "type":"CouponAlreadyInUseException",
    "message":"Coupon with id 'my-coupon' is already in use."
  }
}
X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used and to tailor advertising. By continuing to use this site you are giving us your consent to do this.