---
schema_version: "1"
id: f78380db1af36a58844163b78c68164dc58a5d9b7ab05a74cc1301ef75e5382f
title: Shopper Gift Certificates
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/commerce-api/references/generated-api-specs/shopper-gift-certificates.md
canonical_url: https://developer.salesforce.com/docs/commerce/commerce-api/references/shopper-gift-certificates
source_site: developer.salesforce.com
content_type: documentation
content_hash: 3bcff0dddbee99413a2fed318a1bee92d3c8741e51406a896a73c987b2e2cfc8
products:
  - B2C Commerce API
  - Salesforce APIs
---
Shopper Gift Certificates

# Shopper Gift Certificates

[Download API specification](https://developer.salesforce.com/static/commercecloud/commerce-api/shopper-gift-certificates/shopper-gift-certificates-oas-v1-public.yaml)

## API Overview

Use the Shopper Gift Certificates API to obtain gift certificate details.

### Authentication & Authorization

The Shopper Gift Certificates API requires a JSON Web Token acquired via the Shopper Customers endpoint:

```
https://{shortCode}.api.commercecloud.salesforce.com/customer/shopper-customers/v1/organizations/{organizationId}/customers/actions/login
```

You must include the relevant scope(s) in the client ID used to generate the SLAS token. For details, see [Authorization Scopes Catalog.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/auth-z-scope-catalog.html)

### Customization

#### Custom Properties

This API supports custom properties (prefixed with `c_`). For details, see [Custom Properties.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/custom-properties.html)

#### Hooks

For details on working with hooks, see [Extensibility with Hooks.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/extensibility_via_hooks.html)

### Request Details

#### URL Encoding

If resource identifiers in request parameters contain commas (`,`) or percent signs (`%`), they must be URL encoded. For details, see [Encode URL Special Characters.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/url-encode.html)

### Response Details

#### Personalization

Responses from this API are not personalized via the Shopper Context API.

#### Caching

Responses from this API are not cached.

#### Timeouts

Shopper API requests must respond within 10 seconds, including any hook execution. If a response exceeds this threshold, an HTTP 504 status code is returned. For details, see [Timeouts and Limits.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/timeouts-limits.html)

#### Error Handling

Error responses follow the [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) problem detail format. To trace errors, include a `correlation-id` header in your request — the response returns it as `x-correlation-id`. For details, see [HTTP Status Codes and Errors.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/error-response-codes.html)

### Use Cases

#### Retrieve a Gift Certificate

Look up a gift certificate by its code. The code is sent in the request body (not the URL) for security.

```sh
curl "https://{shortCode}.api.commercecloud.salesforce.com/pricing/shopper-gift-certificates/v1/organizations/{organizationId}/gift-certificate?siteId=RefArch" \
  -X POST \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "giftCertificateCode": "GIFT-1234-ABCD" }'
```

#### Retrieve Existing Gift Certificate Details

A shopper who received a code identifying a gift certificate can use the gift certificate code to query information, such as the status or remaining balance.

### Related APIs

*   [Gift Certificates (Admin)](https://developer.salesforce.com/docs/commerce/commerce-api/references/gift-certificates?meta=Summary) — Create and manage gift certificates.

**Version:** 1.3.2

## Servers

*   `https://{shortCode}.api.commercecloud.salesforce.com/pricing/shopper-gift-certificates/v1`
    *   `shortCode (default shortCode) An eight-character string assigned to a realm for routing purposes. See [Base URL and Request Formation.](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html)`

## Security

*   `ShopperToken` (oauth2) ShopperToken authentication follows the authorization code grant flow, as defined by the OAuth 2.1 standard. Depending on the type of OAuth client (public or private), this authorization flow has further requirements. For a detailed description of the authorization flow, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). A shopper token allows you to access the Shopper API endpoints of both the Open Commerce API (OCAPI) and the B2C Commerce API. These endpoints can be used to build headless storefronts and other applications. The `ShopperToken` security scheme is a parent of other security schemes, such as `ShopperTokenTsob`. A Shopper API endpoint can require a specific child scheme (`ShopperTokenTsob`, for example) that cannot be accessed with a regular shopper token.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-gift-certificates: Allows read operations on shopper gift certificates
    *   OAuth flow authorizationCode (authorizationUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/authorize, tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token)
    *   Scope sfcc.shopper-gift-certificates: Allows read operations on shopper gift certificates
*   `ShopperClientContextToken` (oauth2) ShopperClientContextToken is a separate security scheme used to track and validate client context information. It is valid for Guest shoppers flows only using SLAS private clients. For registered shoppers, use existing ShopperToken flows. For authentication details, see the [SLAS overview](https://developer.salesforce.com/docs/commerce/commerce-api/references?meta=shopper-login:Summary). This token allows access to Shopper API endpoints for guest shoppers only.
    *   OAuth flow clientCredentials (tokenUrl: https://{shortCode}.api.commercecloud.salesforce.com/shopper/auth/v1/organizations/{organizationId}/oauth2/token?hint=client\_context)
    *   Scope sfcc.shopper-gift-certificates: Allows read operations on shopper gift certificates

## Operations

### POST Retrieve an existing gift certificate.

`POST /organizations/{organizationId}/gift-certificate`

Operation ID: `getGiftCertificate`. Security: ShopperToken (sfcc.shopper-gift-certificates, sfcc.shopper-standard); ShopperClientContextToken (sfcc.shopper-gift-certificates, sfcc.shopper-standard).

#### Parameters

*   `organizationId` (path, OrganizationId, required) An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).
    
    _Example_
    
    ```
    f_ecom_zzxy_prd
    ```
    
*   `siteId` (query, SiteId, required) The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites.
    
    _Example: SiteId_
    
    ```
    RefArch
    ```
    
*   `sfdc_usid` (header, string (uuid)) A unique shopper identifier (USID) for tracking client context. Used with endpoints secured with ShopperClientContextToken. This header is required for all endpoints secured with ShopperClientContextToken.  
    Example: `550e8400-e29b-41d4-a716-446655440000`.
*   `sfdc_shopper_context` (header, string) Shopper context information (for example clientIP, sourceCode, and customQualifiers) passed in from a trusted backend application.

#### Request body

Media type: `application/json`. Schema: `GiftCertificateRequest`.

_Example: Gift-Certificates_

```
{
  "giftCertificateCode": "MYGIFTCERTIFICATECODE"
}
```

#### Responses

*   **200** Gift certificate retrieved successfully.
    
    Media type: `application/json`. Schema: `GiftCertificate`.
    
    _Example: CreateGiftCertificate_ A newly issued gift certificate with full balance.
    
    ```
    {
      "amount": 100,
      "balance": 100,
      "enabled": true,
      "maskedGiftCertificateCode": "************FJWQ",
      "merchantId": "00000001",
      "recipientEmail": "jane.doe@example.com",
      "recipientName": "Jane Doe",
      "senderName": "John Smith",
      "status": "issued",
      "description": "Happy Birthday!"
    }
    ```
    
*   **404** Returned when the given gift certificate code is not valid.
    
    Media type: `application/problem+json`. Schema: `ErrorResponse`.
    
    _Example: GiftCertificate404_
    
    ```
    {
      "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-found",
      "title": "Gift Certificate Not Found Exception",
      "detail": "The gift certificate with the provided code could not be retrieved."
    }
    ```
    

## Schemas

### OrganizationId

An identifier for the Salesforce Commerce Cloud organization the request is being made by. It consists of a prefix 'f\_ecom\_' followed by a 4-character [realm identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#realm-id) and a 3-character [instance type identifier](https://developer.salesforce.com/docs/commerce/commerce-api/guide/base-url.html#instance-id).

Type: `string`.

Pattern: ^f\_ecom\_\[a-z\]{4}\_(prd|stg|dev|s\[0-9\]{2}|\[0-9\]{3})$. Example: `f_ecom_zzxy_prd`.

### SiteId

The identifier of the site that a request is being made in the context of. Attributes might have site specific values, and some objects may only be assigned to specific sites

Type: `string`.

Minimum length: 1. Maximum length: 32. Example: `RefArch`.

### GiftCertificateRequest

Document representing a gift certificate request data.

*   `giftCertificateCode` (_string_, required) The gift certificate code.  
    Example: `MYGIFTCERTIFICATECODE`.

### GiftCertificate

Document representing a gift certificate.

*   `amount` (_number (double)_, required) The gift certificate original amount.  
    Example: `100`.
*   `balance` (_number (double)_, required) The gift certificate remaining balance.  
    Example: `100`.
*   `description` (_string_) The gift certificate description.
*   `enabled` (_boolean_, required) Is the gift certificate is enabled?  
    Example: `true`.
*   `maskedGiftCertificateCode` (_string_, required) The masked gift certificate code.  
    Example: `************FJWQ`.
*   `merchantId` (_string_, required) The merchant ID.  
    Example: `00000001`.
*   `message` (_string_) The message.
*   `recipientEmail` (_string_, required) The recipient email.  
    Example: `p@gmail.com`.
*   `recipientName` (_string_, required) The recipient name.  
    Example: `sampleuser`.
*   `senderName` (_string_, required) The sender name.  
    Example: `Salesforce Support`.
*   `status` (_string_, required) The gift certificate status.  
    Allowed values: `pending`, `issued`, `partially_redeemed`, `redeemed`. Example: `issued`.

Additional properties: `any`.

Additional Property Support

This type supports additional properties passed along with the defined properties of this API. To indicate that the properties were defined and expected to be handled as additional properties, they are expected to be prefixed with a `c_`. The type will reject any property that does not fit this pattern, only allowing additional properties beginning with the known prefix.

Example: `c_trackingId`.

### ErrorResponse

*   `title` (_string_, required) A short, human-readable summary of the problem type. It will not change from occurrence to occurrence of the problem, except for purposes of localization  
    Maximum length: 256. Example: `You do not have enough credit`.
*   `type` (_string_, required) A URI reference \[RFC3986\] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML \[W3C.REC-html5-20141028\]). When this member is not present, its value is assumed to be "about:blank". It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `NotEnoughMoney`.
*   `detail` (_string_, required) A human-readable explanation specific to this occurrence of the problem.  
    Example: `Your current balance is 30, but that costs 50`.
*   `instance` (_string_) A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. It accepts relative URIs; this means that they must be resolved relative to the document's base URI, as per \[RFC3986\], Section 5.  
    Maximum length: 2048. Example: `/account/12345/msgs/abc`.