Coupons Resource (Data API 15.9)

Summary

Http Method	Resource	Description
GET	/Sites/{Site_id}/Coupons/{Coupon_id}	Action to get coupon information.
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.

Url

GET https://hostname:port/dw/data/v15_9/sites/{site_id}/coupons/{coupon_id}?select={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
select	String	The property selector.

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description

403

Status	Type	Arguments	Description
403	`SiteAccessForbiddenException`	siteId (String)	Thrown if the resource requires global instead of site-specific context.
404	`CouponNotFoundException`	couponId (String) siteId (String)	Thrown in case the coupon does not exist matching the given id

SiteAccessForbiddenException

siteId (String)

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

404

CouponNotFoundException

couponId (String)

siteId (String)

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

Sample

REQUEST:
GET /s/-/dw/data/v15_9/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" : "15.9",
  "_type" : "coupon",
   "coupon_id" : "my-coupon",
   "description" : "sytem generated coupon code.",
   "enabled" : true,
   "link" : "https://example.com/s/-/dw/data/v15_9/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":"15.9",
   "_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/v15_9/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/v15_9/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" : "15.9",
  "_type" : "coupon",
   "coupon_id" : "my-coupon",
   "description" : "sytem generated coupon code.",
   "enabled" : true,
   "link" : "https://example.com/s/-/dw/data/v15_9/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":"15.9",
   "_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/v15_9/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/v15_9/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/v15_9/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/v15_9/sites/SiteGenesis/coupons 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/v15_9/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 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
ETag: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
   "_v" : "15.9",
  "_type" : "coupon",
   "coupon_id" : "ccc",
   "description" : "sytem generated coupon code.",
   "enabled" : true,
   "link" : "https://example.com/s/-/dw/data/v15_9/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":"15.9",
   "_type":"fault",
  "fault":{
    "type":"CouponAlreadyInUseException",
    "message":"Coupon with id 'my-coupon' is already in use."
  }
}