List Gift Certificates

GET

https://api.bigcommerce.com/stores/:store_hash/v2/gift_certificates

GET

/stores/:store_hash/v2/gift_certificates

curl https://api.bigcommerce.com/stores/store_hash/v2/gift_certificates \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>"

200Response

[
  {
    "amount": "1000.0000",
    "from_email": "test1@test.com",
    "from_name": "Noland",
    "to_email": "test@test.com",
    "to_name": "Alyss",
    "balance": "500.0000",
    "code": "10R-5E2-BO4-RWT",
    "currency_code": "USD",
    "customer_id": 0,
    "expiry_date": "1603306",
    "id": 24,
    "message": "Celebrate",
    "order_id": 1281,
    "purchase_date": "1672670738",
    "status": "active",
    "template": "celebration.html"
  },
  {
    "amount": "700.0000",
    "from_email": "test1@test.com",
    "from_name": "Noland",
    "to_email": "test@test.com",
    "to_name": "Alyss",
    "balance": "700.0000",
    "code": "10R-6E3-AO4-RST",
    "currency_code": "USD",
    "customer_id": 0,
    "expiry_date": "1603306",
    "id": 25,
    "message": "Test",
    "order_id": 0,
    "purchase_date": "1672670738",
    "status": "active",
    "template": "general.html"
  },
  {
    "amount": "50.0000",
    "from_email": "test15@test.com",
    "from_name": "Somethingelse",
    "to_email": "test5@test.com",
    "to_name": "Lyss",
    "balance": "50.0000",
    "code": "15R-6E3-AO4-RST",
    "currency_code": "USD",
    "customer_id": 0,
    "expiry_date": "1603306",
    "id": 27,
    "message": "Celebrate",
    "order_id": 0,
    "purchase_date": "1672670738",
    "status": "active",
    "template": "celebration.html"
  }
]

Returns a list of Gift Certificates. Optional filter parameters can be passed in.

Default sorting is by gift-certificate id, from lowest to highest.

The maximum limit is 250. If a limit isn’t provided, up to 50 gift_certificates are returned by default.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Marketing	modify	`store_v2_marketing`
Marketing	read-only	`store_v2_marketing_read_only`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see our Guide to API Accounts.

Path parameters

store_hashstringRequired

Permanent ID of the BigCommerce store.

Query parameters

min_idintegerOptional

Filter results to those with an ID greater than or equal to this value.

max_idintegerOptional

Filter results to those with an ID less than or equal to this value.

codestringOptional

Filter gift certificates by code.

order_idintegerOptional

Filter gift certificates by the associated order ID.

to_namestringOptional

Filter gift certificates by recipient name.

to_emailstringOptional

Filter gift certificates by recipient email address.

from_namestringOptional

Filter gift certificates by sender name.

from_emailstringOptional

Filter gift certificates by sender email address.

pagedoubleOptional

The page number of the results to return, starting at 1.

limitdoubleOptional

The number of results to return per page.

sortenumOptional

Field to sort results by.

Allowed values:

directionenumOptionalDefaults to asc

Sort direction. Defaults to asc.

Allowed values:

Response

amountstring

Value of the gift certificate.

from_emailstring

Email of the customer who purchased the gift certificate.

from_namestring

Name of the customer who purchased the gift certificate.

to_emailstring

Email of the recipient.

to_namestring

Name of the recipient.

balancestringOptional

Remaining value of the gift certificate. If not set, will default to the amount.

codestringOptional<=255 characters

A unique string that a customer enters to redeem the gift certificate. Gift certificate codes are limited to 20 characters. The API accepts values up to 255 characters without returning an error, but it saves only the first 20 characters and discards the rest. The response returns the saved, truncated code. If you don't set this field, BigCommerce generates a code automatically.

currency_codestringOptional

A currency code, following the ISO 4217 standard. The currency has to exist in the store first. Gift Certificates can only be used if the transactional currency of the cart is the same as the one defined in the gift certificate. If this value is not provided, the gift certificate is created using the store's default transactional currency.

customer_idintegerOptional

The ID of the customer placing the order.

expiry_datestringOptional

Date on which the gift certificate is set to expire. Date displays in the Unix timestamp format.

idintegerOptional

The ID of the gift certificate. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.

messagestringOptional

Text that will be sent to the recipient, such as “Congratulations.”

order_idintegerOptional

The ID of the order.

purchase_datestringOptional

Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Date displays in the Unix timestamp format.

statusenumOptional

Allowed values:

templateenumOptional

The email theme to use in the message sent to the recipient.

List Gift Certificates

Authentication

OAuth scopes

Authentication header

Further reading

Path parameters

Headers

Query parameters

Response