--- schema_version: "1" id: d0138f3586fb9792ade0281adccd4c6f0be69c1fc24356ff4499ee42c8e06402 title: Data Gift Certificates (deprecated) collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/b2c-commerce/references/generated-api-specs/ocapi-data-gift-certificates.md canonical_url: https://developer.salesforce.com/docs/commerce/b2c-commerce/references/ocapi-data-gift-certificates source_site: developer.salesforce.com content_type: documentation content_hash: c165aa6dc897e492972149672479562ba12a800a63aef52d062c22eac6050f05 products: - B2C Commerce - Salesforce APIs --- Data Gift Certificates (deprecated) # Data Gift Certificates (deprecated) Data API endpoints enable developers to build applications for merchants: Create, update, delete business objects, like products, customers, pricing and promotions or assignments. They typically provide read and write access and are designed for moderate usage. **Version:** 25.6 ## Servers * `https://{host}/s/-/dw/data/v25_6` Protocols: https. ## Security * `oauth2_application` (oauth2) Authentication flow with client ID and password with account manager. * OAuth flow application (tokenUrl: https://account.demandware.com:443/dwsso/oauth2/access\_token) * Scope x-info: Scopes are NOT supported. This is just a dummy, because the 'scopes' field is required. * `client_id` (apiKey) Add client ID for application identification. Alternative as 'client\_id' query parameter. * API key in header: x-dw-client-id ## Operations ### GET Get GiftCertificates `GET /sites/{site_id}/gift_certificates` Operation ID: `Get GiftCertificates`. Tags: sites. Security: oauth2\_application. Action to get all the gift certificates with no filtering. #### Parameters * `site_id` (path, string, required) The site context. Minimum length: 1. * `start` (query, integer (int32)) Optional start index for retrieving the items from a given index (default 0). * `count` (query, integer (int32)) Optional count for retrieving only a subset of the items (default is 25). * `select` (query, string) The property selector. #### Responses * **default** Media type: `application/json, text/xml`. Schema: `gift_certificates`. ### POST Create GiftCertificate `POST /sites/{site_id}/gift_certificates` Operation ID: `Create GiftCertificate`. Tags: sites. Security: oauth2\_application. Creates a gift certificate using the information provided. This endpoint may return the following faults: * 400 - GiftCertificateAmountOutOfRangeException - If the amount specified is out of range * 400 - GiftCertificateCreateMerchantIDNotUniqueException - If merchant id is not unique * 400 - InvalidGiftCertificateException - if the gift certificate passed in is not valid (the argument indicates the field that was invalid). * 400 - InvalidGiftCertificateStatusException - If gift certificate status specified is invalid * 400 - InvalidRecipientEmailException - If recipient email address is invalid #### Parameters * `site_id` (path, string, required) The id of the site. Minimum length: 1. #### Request body (required) Media type: `application/json, text/xml`. Schema: `gift_certificate`. #### Responses * **400** `GiftCertificateAmountOutOfRangeException` - If the amount specified is out of range or `GiftCertificateCreateMerchantIDNotUniqueException` - If merchant id is not unique or `InvalidGiftCertificateException` - if the gift certificate passed in is not valid (the argument indicates the field that was invalid). or `InvalidGiftCertificateStatusException` - If gift certificate status specified is invalid or `InvalidRecipientEmailException` - If recipient email address is invalid Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `gift_certificate`. ### GET Get GiftCertificate `GET /sites/{site_id}/gift_certificates/{merchant_id}` Operation ID: `Get GiftCertificate`. Tags: sites. Security: oauth2\_application. Action to get gift certificate information using merchant ID. This endpoint may return the following faults: * 404 - GiftCertificateNotFoundException - Thrown in case the gift certificate does not exist matching the given merchant id #### Parameters * `site_id` (path, string, required) The id of the site. Minimum length: 1. * `merchant_id` (path, string, required) The merchant id of the requested gift certificate. Minimum length: 1. #### Responses * **404** `GiftCertificateNotFoundException` - Thrown in case the gift certificate does not exist matching the given merchant id Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `gift_certificate`. ### DELETE Delete GiftCertificates `DELETE /sites/{site_id}/gift_certificates/{merchant_id}` Operation ID: `Delete GiftCertificates`. Tags: sites. Security: oauth2\_application. Deletes the gift certificate by merchant ID #### Parameters * `site_id` (path, string, required) The id of the site. Minimum length: 1. * `merchant_id` (path, string, required) One gift certificate merchant id to remove #### Responses * **204** ### PATCH Update GiftCertificate `PATCH /sites/{site_id}/gift_certificates/{merchant_id}` Operation ID: `Update GiftCertificate`. Tags: sites. Security: oauth2\_application. 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. This endpoint may return the following faults: * 400 - InvalidGiftCertificateStatusException - If gift certificate status specified is invalid * 400 - InvalidRecipientEmailException - If recipient email address is invalid * 404 - GiftCertificateNotFoundException - Thrown in case the gift certificate does not exist matching the given merchant id #### Parameters * `site_id` (path, string, required) The id of the site. Minimum length: 1. * `merchant_id` (path, string, required) The merchant id of the requested gift certificate. Minimum length: 1. #### Request body (required) Media type: `application/json, text/xml`. Schema: `gift_certificate`. #### Responses * **400** `InvalidGiftCertificateStatusException` - If gift certificate status specified is invalid or `InvalidRecipientEmailException` - If recipient email address is invalid Media type: `application/json, text/xml`. Schema: `fault`. * **404** `GiftCertificateNotFoundException` - Thrown in case the gift certificate does not exist matching the given merchant id Media type: `application/json, text/xml`. Schema: `fault`. * **default** Media type: `application/json, text/xml`. Schema: `gift_certificate`. ## Schemas ### gift\_certificates Document representing an unfiltered list of gift certificates. * `count` (_integer (int32)_) The number of returned documents. * `data` (_array of gift\_certificate_) * `expand` (_array of string_) The list of expands set for the search request. Expands are optional. * `next` (_string_) The URL of the next result page. * `previous` (_string_) The URL of the previous result page. * `select` (_string_) The fields that you want to select. * `start` (_integer (int32)_) The zero-based index of the first search hit to include in the result. Minimum: 0. * `total` (_integer (int32)_) The total number of documents. ### gift\_certificate Document representing a gift certificate * `amount` (_money_) The gift certificate amount. The user cannot change the gift certificate amount after the creation of the gift certificate. * `balance` (_money_) The gift certificate balance. This is a computed attribute and cannot be modified. * `creation_date` (_string (date-time)_, read-only) Returns the value of attribute 'creationDate'. * `description` (_string_) The description of the gift certificate. Maximum length: 4000. * `enabled` (_boolean_) The enabled flag of the gift certificate. * `last_modified` (_string (date-time)_, read-only) Returns the value of attribute 'lastModified'. * `link` (_string_) The URL to get the gift certificate. This is a computed attribute and cannot be modified. * `masked_gift_certificate_code` (_string_) The masked gift certificate code with all but the last 4 characters replaced with a '\*' character. This is a computed attribute and cannot be modified. * `merchant_id` (_string_) The merchant ID of the gift certificate. This is a unique attribute. This is a computed attribute and cannot be modified. This is used to get, update and the delete gift certificates. * `message` (_string_) The message to the recipient of the gift certificate. Maximum length: 4000. * `order_no` (_string_) The order number of the gift certificate. * `recipient_email` (_string_) The email address of the recipient of the gift certificate. * `recipient_name` (_string_) The recipient of the gift certificate. Maximum length: 256. * `sender_name` (_string_) The sender of the gift certificate. Maximum length: 256. * `status` (_string_) The status of the gift certificate. While creating a gift certificate, user can set the status to either "pending" or "issued" only. Allowed values: `issued`, `partially_redeemed`, `pending`, `redeemed`. * `transactions` (_array of account\_transaction_) The transactions of the gift certificate. This attribute is only available as part of the response. ### fault Document representing a fault message that is returned whenever the HTTP status code is greater than or equal to 400 (which indicates an error). * `arguments` (_object_) A map that provides fault arguments. Data can be used to provide error messages on the client side. Additional properties: `object`. * `cause` (_cause_) * `display_message_pattern` (_string_) The localized display message pattern, if the request parameter display\_locale was given * `message` (_string_) The message text of the java exception. * `stack_trace` (_string_) * `type` (_string_) The name of the java exception. ### money * `currency_mnemonic` (_string_) The mnemonic for the money. * `value` (_number (double)_) The value for the money. _Example_ ``` { "currency_mnemonic": "USD", "value": 100 } ``` ### account\_transaction Document representing an account transaction * `amount` (_money_) The amount of the gift certificate * `order_no` (_string_) The order number of the gift certificate * `timestamp` (_string (date-time)_) The timestamp of the transaction of the gift certificate * `type_code` (_string_) The type code of the gift certificate Allowed values: `create`, `redeem`, `delete`, `enable`, `disable`. _Example_ ``` { "amount": { "currency_mnemonic": "EUR", "value": 80 }, "order_no": "my-order_no", "timestamp": "2015-09-09T17:16:12.066Z", "type_code": "create" } ``` ### cause * `cause` (_cause_) * `message` (_string_) * `type` (_string_)