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

GiftCertificates resource (Data API 23.2)

Summary

Http Method Resource Description
GET /sites/{site_id}/gift_certificates Action to get all the gift certificates with no filtering.
POST /sites/{site_id}/gift_certificates Creates a gift certificate using the information provided.
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. This API can not operate on the transactions attribute of the GiftCertificate request object.
DELETE /sites/{site_id}/gift_certificates/{merchant_id} Deletes the gift certificate by merchant ID

Get GiftCertificates

Action to get all the gift certificates with no filtering.

Url

GET https://hostname:port/dw/data/v23_2/sites/{site_id}/gift_certificates?start={Integer}&count={Integer}&select={String}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

Response Document

GiftCertificates

Path Parameters

Parameter Type Description Constraints
site_id String The site context. minLength=1

Query Parameters

Parameter Type Description Constraints
count Integer Optional count for retrieving only a subset of the items (default is 25).  
select String The property selector.  
start Integer Optional start index for retrieving the items from a given index (default 0).  

Sample

REQUEST:
GET  /s/-/dw/data/v23_2/sites/SiteGenesis/giftcertificates 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
Content-Length: 67
Content-Type: application/json; charset=UTF-8
{
  "_v" : "23.2",
  "count" : 2,
  "data" : [
    {
        "_v" : "23.2",
        "_type" : "gift_certificate",
        "amount" :
        {
          "_type" : "money",
          "currency_mnemonic" : "USD",
          "value" : 100.00
        },
        "balance" :
        {
          "_type" : "money",
          "currency_mnemonic" : "USD",
          "value" : 80.00
        },
        "creation_date" : "2015-01-31T14:56:38.936Z",
        "enabled" : true,
        "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/gift_certificates/gift_cert_1",
        "masked_gift_certificate_code" : "************LKWJ",
        "merchant_id" : "gift_cert_1",
        "order_no" : "ASDFASDF",
        "recipient_name" : "John Smith",
        "recipient_email" : "[email protected]",
        "sender_name" : "Beatrix Smith",
        "status" : "partially_redeemed",
        "transactions" :
        [
            {
                "_type" : "account_transaction",
                "amount" :
                {
                    "_type" : "money",
                    "currency_mnemonic" : "EUR",
                    "value" : 20.00
                },
                "order_no" : "ASDFASDF",
                "timestamp" : "2015-09-09T17:16:12.066Z",
                "type_code" : "create"
            }
        ]
    },
    {
        "_v" : "23.2",
        "_type" : "gift_certificate",
        "amount" :
        {
          "_type" : "money",
          "currency_mnemonic" : "USD",
          "value" : 150.00
        },
        "balance" :
        {
          "_type" : "money",
          "currency_mnemonic" : "USD",
          "value" : 150.00
        },
        "creation_date" : "2015-04-01T14:56:38.936Z",
        "description" : "Birthday",
        "enabled" : true,
        "link" : "https://example.com/s/-/dw/data/v23_2/sites/SiteGenesis/gift_certificates/gift_cert_2",
        "masked_gift_certificate_code" : "************KASD",
        "merchant_id" : "gift_cert_2",
        "message" : "Happy Birthday",
        "order_no": "APR_01",
        "recipient_name" : "Stella",
        "recipient_email" : "[email protected]",
        "sender_name" : "John Weasley",
        "status" : "pending",
        "transactions" :
        [
            {
                "_type" : "account_transaction",
                "amount" :
                {
                    "_type" : "money",
                    "currency_mnemonic" : "USD",
                    "value" : 150.00
                },
                "order_no" : "APR_01",
                "timestamp" : "2015-04-01T14:56:38.936Z",
                "type_code" : "create"
            }
        ]
  ],
  "select": "**",
  "start" : 0,
  "total" : 2
}

Create GiftCertificate

Creates a gift certificate using the information provided.

Url

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

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

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/v23_2/sites/SiteGenesis/gift_certificates HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{
   "_v" : "23.2",
   "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

{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_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/v23_2/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" : "23.2",
   "fault" : 
   {
      "type" : "InvalidGiftCertificateException",
      "message" : "The gift certificate could not be created because 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/v23_2/sites/{site_id}/gift_certificates/{merchant_id}

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

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/v23_2/sites/SiteGenesis/gift_certificates/my-merchant_id 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

{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_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/v23_2/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" : "23.2",
   "fault" : 
   {
      "type" : "GiftCertificateNotFoundException",
      "message" : "No gift certificate with merchant ID 'my-merchant_id' for site 'TestWapi' was found."
   }
}

Update GiftCertificate

Updates the gift certificate with the specified information using merchant ID. This API can not operate on the transactions attribute of the GiftCertificate request object.

Url

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

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

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

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/v23_2/sites/SiteGenesis/gift_certificates/my-merchant_id HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
{ 
   "_resource_state" : "847f9c3c5867f641470b3046aeec31f07757991b792d722e10079926f7a289fb",
   "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
{
   "_v" : "23.2",
   "_resource_state" : "860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5",
   "_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/v23_2/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" : "23.2",
   "fault" : 
   {
      "type" : "GiftCertificateNotFoundException",
      "message" : "No gift certificate with merchant ID 'my-merchant_id' for site 'TestWapi' was found."
   }
}

Delete GiftCertificates

Deletes the gift certificate by merchant ID

Url

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

Formats

json, xml

Authentication

Name Description
OAuth Authentication via OAuth token.

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/v23_2/sites/SiteGenesis/gift_certificates/my-merchant_id HTTP/1.1
Host: example.com
Authorization: Bearer a5b6eb0d-8312-41a3-88f3-2c53c4507367
x-dw-resource-state: 860cde3040519cce439cd99e209f8a87c3ad0b7e2813edbf6f5501f763b73bd5

# in case of success:

RESPONSE:
HTTP/1.1 204 No Content

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.