GiftCertificates Resource (Data API 16.3)

Summary

Http Method Resource Description
POST /Sites/{Site_id}/Gift_certificates Creates a gift certificate using the information provided. If a gift certificate with the same unique identifier, it will be deleted and a new one will be created.
GET /Sites/{Site_id}/Gift_certificates/{Merchant_id} Action to get gift certificate information using merchant ID.
PATCH /Sites/{Site_id}/Gift_certificates/{Merchant_id} Updates the gift certificate with the specified information using merchant ID. 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 gift certificate 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 gift certificate "ETag", a 412 (InvalidIfMatchException) fault is returned.
DELETE /Sites/{Site_id}/Gift_certificates/{Merchant_id} Deletes the gift certificate by merchant ID

Create GiftCertificate

Creates a gift certificate using the information provided. If a gift certificate with the same unique identifier, it will be deleted and a new one will be created.

Url

POST https://hostname:port/dw/data/v16_3/sites/{site_id}/gift_certificates

Formats

json, xml

Request Document

GiftCertificate

Response Document

GiftCertificate

Path Parameters

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

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
400 InvalidGiftCertificateException

fieldId (String)

 if the gift certificate passed in is not valid (the argument indicates the field that was invalid).
400 GiftCertificateAmountOutOfRangeException

value (String)

 If the amount specified is out of range
400 GiftCertificateCreateMerchantIDNotUniqueException

siteId (String)

 If merchant id is not unique
400 InvalidRecipientEmailException

email (String)

 If recipient email address is invalid
400 InvalidGiftCertificateStatusException

value (String)

 If gift certificate status specified is invalid

Sample

REQUEST:
POST /s/-/dw/data/v16_3/sites/SiteGenesis/gift_certificates
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
   "_v" : "16.3",
   "amount": {"currency_mnemonic": "USD", "value": 1000},
   "description" : "my-description",
   "message" : "my-message",
   "sender_name" : "my-sender_name",
   "recipient_name" : "my-recipient_name",
   "recipient_email" : "my-recipient_email",
   "status" : "issued",
   "order_no" : "my-order_no",
   "enabled" : false
}

# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
ETag: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
   "_v" : "16.3",
   "_type" : "gift_certificate",
   "amount" : 
   {
      "_type" : "money",
      "currency_mnemonic" : "USD",
      "value" : 100.00
   },
   "balance" : 
   {
      "_type" : "money",
      "currency_mnemonic" : "USD",
      "value" : 100.00
   },
   "creation_date" : "2015-07-31T14:36:17.544Z",
   "description" : "my-description",
   "enabled" : false,
   "link" : "https://example.com/s/-/dw/data/v16_3/sites/SiteGenesis/gift_certificates/my-merchant_id",
   "masked_gift_certificate_code" : "************KTIP",
   "merchant_id" : "my-merchant_id",
   "message" : "my-message",
   "order_no" : "my-order_no",
   "recipient_name" : "my-recipient_name",
   "recipient_email" : "my-recipient_email",
   "sender_name" : "my-sender_name",
   "status" : "issued",
   "transactions" : 
    [
        {
            "_type" : "account_transaction",
            "amount" : 
            {
                "_type" : "money",
                "currency_mnemonic" : "EUR",
                "value" : 80.00
            },
            "order_no" : "my-order_no",
            "timestamp" : "2015-09-09T17:16:12.066Z",
            "type_code" : "create"
        }
    ]

}

# 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" : "16.3",
   "fault" : 
   {
      "type" : "InvalidGiftCertificateException",
      "message" : "Could not create gift certificate: the field 'Amount' is missing or incorrect."
   }
}

Get GiftCertificate

Action to get gift certificate information using merchant ID.

Url

GET https://hostname:port/dw/data/v16_3/sites/{site_id}/gift_certificates/{merchant_id}

Formats

json, xml

Response Document

GiftCertificate

Path Parameters

Parameter Type Description Constraints
merchant_id String The merchant id of the requested gift certificate. minLength=1
site_id String The id of the site. minLength=1

In case of a failure Fault Document is returned.

Faults

Status Type Arguments Description
404 GiftCertificateNotFoundException

giftcertificateMerchantId (String)

siteId (String)

 Thrown in case the gift certificate does not exist matching the given merchant id

Sample

REQUEST:
GET  /s/-/dw/data/v16_3/sites/SiteGenesis/gift_certificates/my-merchant_id
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.3",
   "_type" : "gift_certificate",
   "amount" : 
   {
      "_type" : "money",
      "currency_mnemonic" : "USD",
      "value" : 100.00
   },
   "balance" : 
   {
      "_type" : "money",
      "currency_mnemonic" : "USD",
      "value" : 100.00
   },
   "creation_date" : "2015-07-31T14:56:38.936Z",
   "description" : "my-description",
   "enabled" : true,
   "link" : "https://example.com/s/-/dw/data/v16_3/sites/SiteGenesis/gift_certificates/my-merchant_id",
   "masked_gift_certificate_code" : "************LKWJ",
   "merchant_id" : "my-merchant_id",
   "message" : "my-message",
   "order_no" : "my-order_no",
   "recipient_name" : "my-recipient_name",
   "recipient_email" : "my-recipient_email",
   "sender_name" : "my-sender_name",
   "status" : "my-status",
   "transactions" : 
    [
        {
            "_type" : "account_transaction",
            "amount" : 
            {
                "_type" : "money",
                "currency_mnemonic" : "EUR",
                "value" : 80.00
            },
            "order_no" : "my-order_no",
            "timestamp" : "2015-09-09T17:16:12.066Z",
            "type_code" : "create"
        }
    ]
}

# in case of failure:
 
RESPONSE:
HTTP/1.1 404 Not Found
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.3",
   "fault" : 
   {
      "type" : "GiftCertificateNotFoundException",
      "message" : "No gift certificate with merchant ID 'my-merchant_id' for site 'TestWapi' found."
   }
}

Update GiftCertificate

Updates the gift certificate with the specified information using merchant ID. 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 gift certificate 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 gift certificate "ETag", a 412 (InvalidIfMatchException) fault is returned.

Url

PATCH https://hostname:port/dw/data/v16_3/sites/{site_id}/gift_certificates/{merchant_id}

Formats

json, xml

Request Document

GiftCertificate

Response Document

GiftCertificate

Path Parameters

Parameter Type Description Constraints
merchant_id String The merchant id of the requested gift certificate. minLength=1
site_id String The id of the site. 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 InvalidRecipientEmailException

email (String)

 If recipient email address is invalid
400 InvalidGiftCertificateStatusException

value (String)

 If gift certificate status specified is invalid
404 GiftCertificateNotFoundException

giftcertificateMerchantId (String)

siteId (String)

 Thrown in case the gift certificate does not exist matching the given merchant id

Sample

REQUEST:
PATCH  /s/-/dw/data/v16_3/sites/SiteGenesis/gift_certificates/my-merchant_id
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
If-Match: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

{ 
   "description" : "Gift certificate sample description-updated",
   "enabled":false, 
   "message" : "Gift certificate sample message-updated",
   "recipient_email": "[email protected]",
   "recipient_name": "xyz-updated",
   "sender_name": "abc-updated",
   "status": "pending"
}
# in case of success:

RESPONSE:
HTTP/1.1 200 OK
Content-Length: 67
Content-Type: application/json; charset=UTF-8
ETag: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5
{
   "_v" : "16.3",
   "_type" : "gift_certificate",
   "amount" : 
   {
      "_type" : "money",
      "currency_mnemonic" : "USD",
      "value" : 100.00
   },
   "balance" : 
   {
      "_type" : "money",
      "currency_mnemonic" : "USD",
      "value" : 100.00
   },
   "creation_date" : "2015-07-31T15:05:52.311Z",
   "description" : "Gift certificate sample description-updated",
   "enabled" : false,
   "link" : "https://example.com/s/-/dw/data/v16_3/sites/SiteGenesis/gift_certificates/my-merchant_id",
   "masked_gift_certificate_code" : "***********cate",
   "merchant_id" : "my-merchant_id",
   "message" : "Gift certificate sample message-updated",
   "order_no" : "my-order_no",
   "recipient_email" : "[email protected]",
   "recipient_name" : "xyz-updated",
   "sender_name" : "abc-updated",
   "status" : "pending",
   "transactions" : 
    [
        {
            "_type" : "account_transaction",
            "amount" : 
            {
                "_type" : "money",
                "currency_mnemonic" : "EUR",
                "value" : 80.00
            },
            "order_no" : "my-order-no",
            "timestamp" : "2015-09-09T17:16:12.066Z",
            "type_code" : "create"
        }
    ]   
}

# 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.3",
   "fault" : 
   {
      "type" : "GiftCertificateNotFoundException",
      "message" : "No gift certificate with merchant ID 'my-merchant_id' for site 'TestWapi' found."
   }
}

Delete GiftCertificates

Deletes the gift certificate by merchant ID

Url

DELETE https://hostname:port/dw/data/v16_3/sites/{site_id}/gift_certificates/{merchant_id}

Formats

json, xml

Path Parameters

Parameter Type Description Constraints
merchant_id String One gift certificate merchant id to remove  
site_id String The id of the site. minLength=1

Sample

REQUEST:
DELETE /s/-/dw/data/v16_3/sites/SiteGenesis/gift_certificates/my-merchant_id
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

© Copyright 2000-2020, salesforce.com inc. All rights reserved. Various trademarks held by their respective owners.

 Show URL Submit FeedbackPrivacy Policy
OCAPI obsolete versions 13.x and 14.x will be end of life in 2020 and versions 15.x and 16.x in 2021. For dates and more information, see the OCAPI versioning and deprecation policy and this Knowledge Article.
X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.