Gift Certificates | BigCommerce Dev Center

Get a Gift Certificate

GET https://api.bigcommerce.com/stores/{store_hash}/v2/gift_certificates/{id}

Request

Returns a single Gift Certificate.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
The MIME type of the response body.
id in path - integer - required
ID of the gift certificate.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/gift_certificates/[id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

application/json

to_namestring
required
Name of the recipient.
Example: John Doe
to_emailstring
required
Email of the recipient.
Example: johndoe@example.com
from_namestring
required
Name of the customer who purchased the gift certificate.
Example: Jane Doe
from_emailstring
required
Email of the customer who purchased the gift certificate.
Example: janedoe@example.com
amountstring
required
Value of the gift certificate.
Example: 10

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.
Example: 1
customer_idinteger
The ID of the customer placing the order.
Example: 5
order_idinteger
The ID of the order.
Example: 116
balancestring
Remaining value of the gift certificate. If not set, will default to the amount.
Example: 0
purchase_datestring
Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Date displays in the RFC 2822 timestamp format.
Example: Tue, 20 Jan 1970 08:45:38 CST
expiry_datestring
Date on which the gift certificate is set to expire. Date displays in the RFC 2822 timestamp format.
Example: Mon, 2 Jan 2023 08:45:38 CST
templatestring
The email theme to use in the message sent to the recipient.
Allowed: Birthday | Girl | Boy | Celebration | Christmas | General
Example: Celebration
messagestring
Text that will be sent to the recipient, such as “Congratulations.”
Example: Congratulations!
codestring
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.
<= 255 characters
Example: FFZ-5N4-C7M-S78
statusstring
Allowed: active | pending | disabled | expired
Example: active

example

{
  "id": 1,
  "customer_id": 5,
  "order_id": 116,
  "code": "FFZ-5N4-C7M-S78",
  "to_name": "John Doe",
  "to_email": "johndoe@example.com",
  "from_name": "Jane Doe",
  "from_email": "janedoe@example.com",
  "amount": "10",
  "balance": "0",
  "status": "active",
  "template": "Birthday",
  "message": "Happy Birthday!",
  "purchase_date": "Tue, 20 Jan 1970 08:45:38 CST",
  "expiry_date": "Mon, 2 Jan 2023 08:45:38 CST"
}

Update a Gift Certificate

PUT https://api.bigcommerce.com/stores/{store_hash}/v2/gift_certificates/{id}

Request

Updates a Gift Certificate.

Read Only Fields

id
order_id

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
id in path - integer - required
ID of the gift certificate.
Content-Type in header with default of application/json - string - required
The MIME type of the request body.

Body

application/json

to_namestring
required
Name of the recipient.
Example: John Doe
to_emailstring
required
Email of the recipient.
Example: johndoe@example.com
from_namestring
required
Name of the customer who purchased the gift certificate.
Example: Jane Doe
from_emailstring
required
Email of the customer who purchased the gift certificate.
Example: janedoe@example.com
amountstring
required
Value of the gift certificate.
Example: 10

balancestring
Remaining value of the gift certificate. If not set, will default to the amount.
Example: 0
purchase_datestring
Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Enter date in RFC-2822 format.
Example: Mon, 19 Jan 1970 07:21:46 CST
expiry_datestring
Date on which the gift certificate is set to expire.
Example: Mon, 02 Jan 2023 08:45:38 CST
customer_idinteger
The ID of the customer placing the order.
Example: 5
templatestring
The email theme to use in the message sent to the recipient.
Allowed: Birthday | Boy | Girl | Celebration | Christmas | General
Example: Celebration
messagestring
Text that will be sent to the recipient, such as “Congratulations.”
Example: Congratulations!
codestring
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.
<= 255 characters
Example: FFZ-5N4-C7M-S78
statusstring
Allowed: active | pending | expired | disabled
Example: active

example

{
  "to_name": "John Doe",
  "to_email": "johndoe@example.com",
  "from_name": "Jane Doe",
  "from_email": "janedoe@example.com",
  "amount": "10",
  "balance": "0",
  "purchase_date": "Mon, 19 Jan 1970 07:21:46 CST",
  "expiry_date": "Mon, 02 Jan 2023 08:45:38 CST",
  "customer_id": 5,
  "template": "Celebration",
  "message": "Congratulations!",
  "code": "FFZ-5N4-C7M-S78",
  "status": "active"
}

Response

Body

application/json

to_namestring
required
Name of the recipient.
Example: John Doe
to_emailstring
required
Email of the recipient.
Example: johndoe@example.com
from_namestring
required
Name of the customer who purchased the gift certificate.
Example: Jane Doe
from_emailstring
required
Email of the customer who purchased the gift certificate.
Example: janedoe@example.com
amountstring
required
Value of the gift certificate.
Example: 10

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.
Example: 1
customer_idinteger
The ID of the customer placing the order.
Example: 5
order_idinteger
The ID of the order.
Example: 116
balancestring
Remaining value of the gift certificate. If not set, will default to the amount.
Example: 0
purchase_datestring
Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Date displays in the RFC 2822 timestamp format.
Example: Tue, 20 Jan 1970 08:45:38 CST
expiry_datestring
Date on which the gift certificate is set to expire. Date displays in the RFC 2822 timestamp format.
Example: Mon, 2 Jan 2023 08:45:38 CST
templatestring
The email theme to use in the message sent to the recipient.
Allowed: Birthday | Girl | Boy | Celebration | Christmas | General
Example: Celebration
messagestring
Text that will be sent to the recipient, such as “Congratulations.”
Example: Congratulations!
codestring
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.
<= 255 characters
Example: FFZ-5N4-C7M-S78
statusstring
Allowed: active | pending | disabled | expired
Example: active

example

{
  "id": 1,
  "customer_id": 5,
  "order_id": 116,
  "code": "FFZ-5N4-C7M-S78",
  "to_name": "John Doe",
  "to_email": "johndoe@example.com",
  "from_name": "Jane Doe",
  "from_email": "janedoe@example.com",
  "amount": "10",
  "balance": "0",
  "status": "active",
  "template": "Birthday",
  "message": "Happy Birthday!",
  "purchase_date": "Tue, 20 Jan 1970 08:45:38 CST",
  "expiry_date": "Mon, 2 Jan 2023 08:45:38 CST"
}

Delete a Gift Certificate

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/gift_certificates/{id}

Request

Deletes a Gift Certificate.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
The MIME type of the response body.
id in path - integer - required
ID of the gift certificate.

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/gift_certificates/[id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Get All Gift Certificates

GET https://api.bigcommerce.com/stores/{store_hash}/v2/gift_certificates

Request

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-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
The MIME type of the response body.
min_id in query - integer
max_id in query - integer
code in query - string
order_id in query - integer
to_name in query - string
to_email in query - string
from_name in query - string
from_email in query - string
page in query - number
limit in query - number

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/gift_certificates' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

array | application/json

example

[
  {
    "id": 24,
    "code": "10R-5E2-BO4-RWT",
    "amount": "1000.0000",
    "status": "active",
    "balance": "500.0000",
    "to_name": "Alyss",
    "order_id": 1281,
    "template": "Celebration",
    "to_email": "test@test.com",
    "from_name": "Noland",
    "from_email": "test1@test.com",
    "customer_id": 0,
    "expiry_date": "Mon, 2 Jan 2023 08:45:38 CST",
    "purchase_date": "Tue, 20 Jan 1970 08:45:38 CST"
  },
  {
    "id": 25,
    "code": "10R-6E3-AO4-RST",
    "amount": "700.0000",
    "status": "active",
    "balance": "700.0000",
    "to_name": "Alyss",
    "order_id": 0,
    "template": "General",
    "to_email": "test@test.com",
    "from_name": "Noland",
    "from_email": "test1@test.com",
    "customer_id": 0,
    "expiry_date": "Mon, 2 Jan 2023 08:45:38 CST",
    "purchase_date": "Tue, 20 Jan 1970 08:45:38 CST"
  },
  {
    "id": 27,
    "code": "15R-6E3-AO4-RST",
    "amount": "50.0000",
    "status": "active",
    "balance": "50.0000",
    "to_name": "Lyss",
    "order_id": 0,
    "template": "Celebration",
    "to_email": "test5@test.com",
    "from_name": "Somethingelse",
    "from_email": "test15@test.com",
    "customer_id": 0,
    "expiry_date": "Mon, 2 Jan 2023 08:45:38 CST",
    "purchase_date": "Tue, 20 Jan 1970 08:45:38 CST"
  }
]

Create a Gift Certificate

POST https://api.bigcommerce.com/stores/{store_hash}/v2/gift_certificates

Request

Creates a Gift Certificate.

Required Fields

to_name
to_email
from_name
from_email
amount

Read Only Fields

id
order_id

Notes

When a gift certificate is created through the API, no email notification is triggered to the specified recipient.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Content-Type in header with default of application/json - string - required
The MIME type of the request body.

Body

application/json

to_namestring
required
Name of the recipient.
Example: John Doe
to_emailstring
required
Email of the recipient.
Example: johndoe@example.com
from_namestring
required
Name of the customer who purchased the gift certificate.
Example: Jane Doe
from_emailstring
required
Email of the customer who purchased the gift certificate.
Example: janedoe@example.com
amountstring
required
Value of the gift certificate.
Example: 10

balancestring
Remaining value of the gift certificate. If not set, will default to the amount.
Example: 0
purchase_datestring
Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Enter date in RFC-2822 format.
Example: Mon, 19 Jan 1970 07:21:46 CST
expiry_datestring
Date on which the gift certificate is set to expire. The date must be in RFC 2822 format.
Example: Tue, 20 Jan 1970 08:45:38 CST
customer_idinteger
The ID of the customer placing the order.
Example: 5
templatestring
The email theme to use in the message sent to the recipient.
Allowed: Birthday | Boy | Girl | Celebration | Christmas | General
Example: Celebration
messagestring
Text that will be sent to the recipient, such as “Congratulations.”
<= 250 characters
Example: Congratulations!
codestring
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.
<= 255 characters
Example: FFZ-5N4-C7M-S78
statusstring
Allowed: active | pending | expired | disabled
Example: active
currency_codestring
A currency code, following the ISO 4217 standard. The currency has to exists in the store first.

Gift Certificates can only be used if the transactional currency of the cart is the same to 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
Example: USD

example

{
  "to_name": "John Doe",
  "to_email": "johndoe@example.com",
  "from_name": "Jane Doe",
  "from_email": "janedoe@example.com",
  "amount": "10",
  "balance": "0",
  "purchase_date": "Mon, 19 Jan 1970 07:21:46 CST",
  "expiry_date": "Tue, 20 Jan 1970 08:45:38 CST",
  "customer_id": 5,
  "template": "Celebration",
  "message": "Congratulations!",
  "code": "FFZ-5N4-C7M-S78",
  "status": "active",
  "currency_code": "USD"
}

Response

Body

application/json

to_namestring
required
Name of the recipient.
Example: John Doe
to_emailstring
required
Email of the recipient.
Example: johndoe@example.com
from_namestring
required
Name of the customer who purchased the gift certificate.
Example: Jane Doe
from_emailstring
required
Email of the customer who purchased the gift certificate.
Example: janedoe@example.com
amountstring
required
Value of the gift certificate.
Example: 10

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.
Example: 1
customer_idinteger
The ID of the customer placing the order.
Example: 5
order_idinteger
The ID of the order.
Example: 116
balancestring
Remaining value of the gift certificate. If not set, will default to the amount.
Example: 0
purchase_datestring
Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Date displays in the RFC 2822 timestamp format.
Example: Tue, 20 Jan 1970 08:45:38 CST
expiry_datestring
Date on which the gift certificate is set to expire. Date displays in the RFC 2822 timestamp format.
Example: Mon, 2 Jan 2023 08:45:38 CST
templatestring
The email theme to use in the message sent to the recipient.
Allowed: Birthday | Girl | Boy | Celebration | Christmas | General
Example: Celebration
messagestring
Text that will be sent to the recipient, such as “Congratulations.”
Example: Congratulations!
codestring
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.
<= 255 characters
Example: FFZ-5N4-C7M-S78
statusstring
Allowed: active | pending | disabled | expired
Example: active

example

{
  "id": 1,
  "customer_id": 5,
  "order_id": 116,
  "code": "FFZ-5N4-C7M-S78",
  "to_name": "John Doe",
  "to_email": "johndoe@example.com",
  "from_name": "Jane Doe",
  "from_email": "janedoe@example.com",
  "amount": "10",
  "balance": "0",
  "status": "active",
  "template": "Birthday",
  "message": "Happy Birthday!",
  "purchase_date": "Tue, 20 Jan 1970 08:45:38 CST",
  "expiry_date": "Mon, 2 Jan 2023 08:45:38 CST"
}

Delete All Gift Certificates

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/gift_certificates

Request

By default, it deletes all Gift Certificates.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
The MIME type of the response body.

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/gift_certificates' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

example

{}

Get a Gift Certificate

Request

Authentication

Parameters

example

Response

Body

to_namestringrequired

to_emailstringrequired

from_namestringrequired

from_emailstringrequired

amountstringrequired

idinteger

customer_idinteger

order_idinteger

balancestring

purchase_datestring

expiry_datestring

templatestring

messagestring

codestring

statusstring

example

Update a Gift Certificate

Request

Authentication

Parameters

Body

to_namestringrequired

to_emailstringrequired

from_namestringrequired

from_emailstringrequired

amountstringrequired

balancestring

purchase_datestring

expiry_datestring

customer_idinteger

templatestring

messagestring

codestring

statusstring

example

Response

Body

to_namestringrequired

to_emailstringrequired

from_namestringrequired

from_emailstringrequired

amountstringrequired

idinteger

customer_idinteger

order_idinteger

balancestring

purchase_datestring

expiry_datestring

templatestring

messagestring

codestring

statusstring

example

Delete a Gift Certificate

Request

Authentication

Parameters

example

Response

Get All Gift Certificates

Request

Authentication

Parameters

example

Response

Body

example

Create a Gift Certificate

Request

Authentication

Parameters

Body

to_namestringrequired

to_namestring
required

to_emailstring
required

from_namestring
required

from_emailstring
required

amountstring
required

to_namestring
required

to_emailstring
required

from_namestring
required

from_emailstring
required

amountstring
required

to_namestring
required

to_emailstring
required

from_namestring
required

from_emailstring
required

amountstring
required

to_namestring
required

to_emailstring
required

from_namestring
required

from_emailstring
required

amountstring
required

to_namestring
required

to_emailstring
required

from_namestring
required

from_emailstring
required

amountstring
required