Docs
Content API
Marketing
Gift Certificates

Gift Certificates

Get a Gift Certificate

GET /gift_certificates/{id}

Request

Returns a single Gift Certificate.

Authentication

  • X-Auth-Token in header

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: {{token}}'

Response

Body

object | application/json

  • to_name    string
    required

    Name of the recipient.
    Example: John Doe

  • to_email    string
    required

    Email of the recipient.
    Example: johndoe@example.com

  • from_name    string
    required

    Name of the customer who purchased the gift certificate.
    Example: Jane Doe

  • from_email    string
    required

    Email of the customer who purchased the gift certificate.
    Example: janedoe@example.com

  • amount    string
    required

    Value of the gift certificate.
    Example: 10

  • id    integer

    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_id    integer

    The ID of the customer placing the order.
    Example: 5

  • order_id    integer

    The ID of the order.
    Example: 116

  • balance    string

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

  • purchase_date    string

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

  • expiry_date    string

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

  • template    string

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

    Allowed: birthday.html | girl.html | boy.html | celebration.html | christmas.html | general.html

    Example: celebration.html

  • message    string

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

  • code    string

    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

  • status    string

    Allowed: active | pending | disabled | expired

    Example: active

  • currency_code    string

    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.

    Example: USD

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.html",
"message": "Happy Birthday!",
"purchase_date": "1603306",
"expiry_date": "1694738",
"currency_code": "USD"
}

Update a Gift Certificate

PUT /gift_certificates/{id}

Request

Updates a Gift Certificate.

Read Only Fields

  • id
  • order_id

Authentication

  • X-Auth-Token in header

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.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

object | application/json

  • to_name    string
    required

    Name of the recipient.
    Example: John Doe

  • to_email    string
    required

    Email of the recipient.
    Example: johndoe@example.com

  • from_name    string
    required

    Name of the customer who purchased the gift certificate.
    Example: Jane Doe

  • from_email    string
    required

    Email of the customer who purchased the gift certificate.
    Example: janedoe@example.com

  • amount    string
    required

    Value of the gift certificate.
    Example: 10

  • balance    string

    The remaining value of the gift certificate. If not set, will default to the amount.
    Example: 0

  • purchase_date    string

    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_date    string

    Date on which the gift certificate is set to expire.
    Example: Mon, 02 Jan 2023 08:45:38 CST

  • customer_id    integer

    The ID of the customer placing the order.
    Example: 5

  • template    string

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

    Allowed: birthday.html | boy.html | girl.html | celebration.html | christmas.html | general.html

    Example: celebration.html

  • message    string

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

  • code    string

    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

  • status    string

    Allowed: active | pending | expired | disabled

    Example: active

  • currency_code    string

    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.

    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": "Mon, 02 Jan 2023 08:45:38 CST",
"customer_id": 5,
"template": "celebration.html",
"message": "Congratulations!",
"code": "FFZ-5N4-C7M-S78",
"status": "active",
"currency_code": "USD"
}

Response

Body

object | application/json

  • to_name    string
    required

    Name of the recipient.
    Example: John Doe

  • to_email    string
    required

    Email of the recipient.
    Example: johndoe@example.com

  • from_name    string
    required

    Name of the customer who purchased the gift certificate.
    Example: Jane Doe

  • from_email    string
    required

    Email of the customer who purchased the gift certificate.
    Example: janedoe@example.com

  • amount    string
    required

    Value of the gift certificate.
    Example: 10

  • id    integer

    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_id    integer

    The ID of the customer placing the order.
    Example: 5

  • order_id    integer

    The ID of the order.
    Example: 116

  • balance    string

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

  • purchase_date    string

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

  • expiry_date    string

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

  • template    string

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

    Allowed: birthday.html | girl.html | boy.html | celebration.html | christmas.html | general.html

    Example: celebration.html

  • message    string

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

  • code    string

    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

  • status    string

    Allowed: active | pending | disabled | expired

    Example: active

  • currency_code    string

    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.

    Example: USD

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.html",
"message": "Happy Birthday!",
"purchase_date": "1603306",
"expiry_date": "1672670738",
"currency_code": "USD"
}

Delete a Gift Certificate

DELETE /gift_certificates/{id}

Request

Deletes a Gift Certificate.

Authentication

  • X-Auth-Token in header

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: {{token}}'

Response

Get All Gift Certificates

GET /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

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: {{token}}'

Response

Body

array | application/json

  • to_name    string
    required

    Name of the recipient.
    Example: John Doe

  • to_email    string
    required

    Email of the recipient.
    Example: johndoe@example.com

  • from_name    string
    required

    Name of the customer who purchased the gift certificate.
    Example: Jane Doe

  • from_email    string
    required

    Email of the customer who purchased the gift certificate.
    Example: janedoe@example.com

  • amount    string
    required

    Value of the gift certificate.
    Example: 10

  • id    integer

    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_id    integer

    The ID of the customer placing the order.
    Example: 5

  • order_id    integer

    The ID of the order.
    Example: 116

  • balance    string

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

  • purchase_date    string

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

  • expiry_date    string

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

  • template    string

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

    Allowed: birthday.html | girl.html | boy.html | celebration.html | christmas.html | general.html

    Example: celebration.html

  • message    string

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

  • code    string

    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

  • status    string

    Allowed: active | pending | disabled | expired

    Example: active

  • currency_code    string

    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.

    Example: USD

example

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

Create a Gift Certificate

POST /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

Parameters

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

Body

object | application/json

  • to_name    string
    required

    Name of the recipient.
    Example: John Doe

  • to_email    string
    required

    Email of the recipient.
    Example: johndoe@example.com

  • from_name    string
    required

    Name of the customer who purchased the gift certificate.
    Example: Jane Doe

  • from_email    string
    required

    Email of the customer who purchased the gift certificate.
    Example: janedoe@example.com

  • amount    string
    required

    Value of the gift certificate.
    Example: 10

  • balance    string

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

  • purchase_date    string

    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_date    string

    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_id    integer

    The ID of the customer placing the order.
    Example: 5

  • template    string

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

    Allowed: birthday.html | boy.html | girl.html | celebration.html | christmas.html | general.html

    Example: celebration.html

  • message    string

    Text that will be sent to the recipient, such as “Congratulations.”
    <= 250 characters
    Example: Congratulations!

  • code    string

    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

  • status    string

    Allowed: active | pending | expired | disabled

    Example: active

  • currency_code    string

    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.

    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.html",
"message": "Congratulations!",
"code": "FFZ-5N4-C7M-S78",
"status": "active",
"currency_code": "USD"
}

Response

Body

object | application/json

  • to_name    string
    required

    Name of the recipient.
    Example: John Doe

  • to_email    string
    required

    Email of the recipient.
    Example: johndoe@example.com

  • from_name    string
    required

    Name of the customer who purchased the gift certificate.
    Example: Jane Doe

  • from_email    string
    required

    Email of the customer who purchased the gift certificate.
    Example: janedoe@example.com

  • amount    string
    required

    Value of the gift certificate.
    Example: 10

  • id    integer

    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_id    integer

    The ID of the customer placing the order.
    Example: 5

  • order_id    integer

    The ID of the order.
    Example: 116

  • balance    string

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

  • purchase_date    string

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

  • expiry_date    string

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

  • template    string

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

    Allowed: birthday.html | girl.html | boy.html | celebration.html | christmas.html | general.html

    Example: celebration.html

  • message    string

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

  • code    string

    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

  • status    string

    Allowed: active | pending | disabled | expired

    Example: active

  • currency_code    string

    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.

    Example: USD

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.html",
"message": "Happy Birthday!",
"purchase_date": "1603306",
"expiry_date": "1694738",
"currency_code": "USD"
}

Delete All Gift Certificates

DELETE /gift_certificates

Request

By default, it deletes all Gift Certificates.

Authentication

  • X-Auth-Token in header

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: {{token}}'

Response

Body

object | application/json

    example

    {}
    Did you find what you were looking for?
    Delete a CouponGet a Gift Certificate