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

1 [
2   {
3     "amount": "1000.0000",
4     "from_email": "test1@test.com",
5     "from_name": "Noland",
6     "to_email": "test@test.com",
7     "to_name": "Alyss",
8     "balance": "500.0000",
9     "code": "10R-5E2-BO4-RWT",
10     "currency_code": "USD",
11     "customer_id": 0,
12     "expiry_date": "1603306",
13     "id": 24,
14     "message": "Celebrate",
15     "order_id": 1281,
16     "purchase_date": "1672670738",
17     "status": "active",
18     "template": "celebration.html"
19   },
20   {
21     "amount": "700.0000",
22     "from_email": "test1@test.com",
23     "from_name": "Noland",
24     "to_email": "test@test.com",
25     "to_name": "Alyss",
26     "balance": "700.0000",
27     "code": "10R-6E3-AO4-RST",
28     "currency_code": "USD",
29     "customer_id": 0,
30     "expiry_date": "1603306",
31     "id": 25,
32     "message": "Test",
33     "order_id": 0,
34     "purchase_date": "1672670738",
35     "status": "active",
36     "template": "general.html"
37   },
38   {
39     "amount": "50.0000",
40     "from_email": "test15@test.com",
41     "from_name": "Somethingelse",
42     "to_email": "test5@test.com",
43     "to_name": "Lyss",
44     "balance": "50.0000",
45     "code": "15R-6E3-AO4-RST",
46     "currency_code": "USD",
47     "customer_id": 0,
48     "expiry_date": "1603306",
49     "id": 27,
50     "message": "Celebrate",
51     "order_id": 0,
52     "purchase_date": "1672670738",
53     "status": "active",
54     "template": "celebration.html"
55   }
56 ]

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.

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

1 [
2   {
3     "amount": "1000.0000",
4     "from_email": "test1@test.com",
5     "from_name": "Noland",
6     "to_email": "test@test.com",
7     "to_name": "Alyss",
8     "balance": "500.0000",
9     "code": "10R-5E2-BO4-RWT",
10     "currency_code": "USD",
11     "customer_id": 0,
12     "expiry_date": "1603306",
13     "id": 24,
14     "message": "Celebrate",
15     "order_id": 1281,
16     "purchase_date": "1672670738",
17     "status": "active",
18     "template": "celebration.html"
19   },
20   {
21     "amount": "700.0000",
22     "from_email": "test1@test.com",
23     "from_name": "Noland",
24     "to_email": "test@test.com",
25     "to_name": "Alyss",
26     "balance": "700.0000",
27     "code": "10R-6E3-AO4-RST",
28     "currency_code": "USD",
29     "customer_id": 0,
30     "expiry_date": "1603306",
31     "id": 25,
32     "message": "Test",
33     "order_id": 0,
34     "purchase_date": "1672670738",
35     "status": "active",
36     "template": "general.html"
37   },
38   {
39     "amount": "50.0000",
40     "from_email": "test15@test.com",
41     "from_name": "Somethingelse",
42     "to_email": "test5@test.com",
43     "to_name": "Lyss",
44     "balance": "50.0000",
45     "code": "15R-6E3-AO4-RST",
46     "currency_code": "USD",
47     "customer_id": 0,
48     "expiry_date": "1603306",
49     "id": 27,
50     "message": "Celebrate",
51     "order_id": 0,
52     "purchase_date": "1672670738",
53     "status": "active",
54     "template": "celebration.html"
55   }
56 ]

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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

store_hashstringRequired

Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json

The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.

Query parameters

min_idintegerOptional

max_idintegerOptional

codestringOptional

order_idintegerOptional

to_namestringOptional

to_emailstringOptional

from_namestringOptional

from_emailstringOptional

pagedoubleOptional

limitdoubleOptional

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.

balancestring

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

codestring<=255 characters

A unique string that a customer can input to redeem a gift certificate. Values greater than 20 characters will be trimmed down to the first 20 characters and returned in the response. If this field is not set, a value will be autogenerated.

currency_codestring

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_idinteger

The ID of the customer placing the order.

expiry_datestring

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

idinteger

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.

messagestring

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

order_idinteger

The ID of the order.

purchase_datestring

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

statusenum

Allowed values:

templateenum

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

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.

Headers

AcceptstringRequiredDefaults to application/json

The MIME type of the response body.

The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.

Query parameters

min_idintegerOptional

max_idintegerOptional

codestringOptional

order_idintegerOptional

to_namestringOptional

to_emailstringOptional

from_namestringOptional

from_emailstringOptional

pagedoubleOptional

limitdoubleOptional

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.

balancestring

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

codestring<=255 characters

currency_codestring

customer_idinteger

The ID of the customer placing the order.

expiry_datestring

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

idinteger

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.

messagestring

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

order_idinteger

The ID of the order.

purchase_datestring

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

statusenum

Allowed values:

templateenum

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

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

1	[
2	{
3	"amount": "1000.0000",
4	"from_email": "test1@test.com",
5	"from_name": "Noland",
6	"to_email": "test@test.com",
7	"to_name": "Alyss",
8	"balance": "500.0000",
9	"code": "10R-5E2-BO4-RWT",
10	"currency_code": "USD",
11	"customer_id": 0,
12	"expiry_date": "1603306",
13	"id": 24,
14	"message": "Celebrate",
15	"order_id": 1281,
16	"purchase_date": "1672670738",
17	"status": "active",
18	"template": "celebration.html"
19	},
20	{
21	"amount": "700.0000",
22	"from_email": "test1@test.com",
23	"from_name": "Noland",
24	"to_email": "test@test.com",
25	"to_name": "Alyss",
26	"balance": "700.0000",
27	"code": "10R-6E3-AO4-RST",
28	"currency_code": "USD",
29	"customer_id": 0,
30	"expiry_date": "1603306",
31	"id": 25,
32	"message": "Test",
33	"order_id": 0,
34	"purchase_date": "1672670738",
35	"status": "active",
36	"template": "general.html"
37	},
38	{
39	"amount": "50.0000",
40	"from_email": "test15@test.com",
41	"from_name": "Somethingelse",
42	"to_email": "test5@test.com",
43	"to_name": "Lyss",
44	"balance": "50.0000",
45	"code": "15R-6E3-AO4-RST",
46	"currency_code": "USD",
47	"customer_id": 0,
48	"expiry_date": "1603306",
49	"id": 27,
50	"message": "Celebrate",
51	"order_id": 0,
52	"purchase_date": "1672670738",
53	"status": "active",
54	"template": "celebration.html"
55	}
56	]