Gift Cards API v2
The Gift Cards resource lets you get, create, or update gift cards.
Gift cards have some protected properties, which are either only writable on creation, or may only be modified under certain conditions. Although Gift cards cannot be deleted, they can be disabled. Disabling a gift card cannot be undone.
Scopes
Access to the Gift Cards API requires that the client have the following scopes granted:
gift-cards- Permits write access to add, update or remove gift cards.gift-cards.readonly- Read only access to search or get gift card data.
The Gift Card Object
Example JSON response
{
"data": {
"id": 1234,
"orderId": null,
"orderLineId": null,
"productId": null,
"last4Characters": "c6b8",
"currency": "GBP",
"amount": "50.00",
"balance": "50.00",
"isActive": true,
"expiresOn": null,
"issuerId": null,
"email": null,
"message": null,
"image": null,
"recipientId": null,
"createdOn": "2024-09-07T05:27:00+00:00",
"modifiedOn": "2024-09-07T05:27:00+00:00"
}
}
List/search Gift Cards
GET
/api/v2/gift-cards.json
Get or search for one or more gift cards using a range of accepted query parameters.
Requires either the gift-cards or gift-cards.readonly OAuth
scope.
Query parameters
amount
Return gift cards matching the amount supplied. |
amount:min
Return gift cards with an amount greater than or equal to the amount supplied. |
amount:max
Return gift cards with an amount less than or equal to the amount supplied. |
balance
Return gift cards matching the balance supplied. |
balance:min
Return gift cards with a balance greater than or equal to the amount supplied. |
balance:max
Return gift cards with a balance less than or equal to the amount supplied. |
createdOn:min
Return gift cards with a createdOn datetime greater than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
createdOn:max
Return gift cards with a createdOn datetime less than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
createdOn:after
Return gift cards with a createdOn datetime greater than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
createdOn:before
Return gift cards with a createdOn datetime less than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
|
email
Search for gift cards sent to a specific email address. |
expiresOn:min
Search for gift cards expiring on or after the date supplied. |
expiresOn:max
Search for gift cards expiring on or before the date supplied. |
expiresOn:after
Search for gift cards expiring after the date supplied. |
expiresOn:before
Search for gift cards expiring before the date supplied. |
id:in
Return gift cards specified within a comma-separated list of Gift Card IDs. |
id:min
Return gift cards with an ID greater than or equal to that specified. |
id:max
Return gift cards with an ID less than or equal to that specified. |
id:after
Return gift cards with an ID greater than that specified. |
id:before
Return gift cards with an ID less than that specified. |
issuerId
Search for gift cards from a specific sender (customer or administrator). |
last4Characters
Search for gift cards matching the last 4 characters supplied. For security reasons you cannot search for a reference. |
modifiedOn:min
Return gift cards with a modifiedOn datetime greater than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
modifiedOn:max
Return gift cards with a modifiedOn datetime less than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
modifiedOn:after
Return gift cards with a modifiedOn datetime greater than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00) |
modifiedOn:before
Return gift cards with a modifiedOn datetime less than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
|
recipientId
Search for gift cards assigned to a specific customer. |
JSON response
Evance will return a JSON object containing the following properties:
success
A successful search request containing zero or more results will always return a true value.
|
status
An integer matching the HTTP response code. A successful request will have a status of 200.
|
data
An array containing zero or more Gift Card data objects. |
pagination
Search results include a pagination object contain information about the current page, total pages, the limit per page and the total number of results available.
|
links
An object containing links to traverse available search results.
|
Example JSON response
{
"success": true,
"status": 200,
"data": [
{
"data": {
"id": 1234,
"orderId": null,
"orderLineId": null,
"productId": null,
"last4Characters": "c6b8",
"currency": "GBP",
"amount": "50.00",
"balance": "25.00",
"isActive": true,
"expiresOn": null,
"issuerId": null,
"email": null,
"message": null,
"image": null,
"recipientId": null,
"createdOn": "2024-09-07T05:27:00+00:00",
"modifiedOn": "2024-09-07T08:05:00+00:00"
}
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"links": {
"self": "https://examples.evance.me/api/v2/gift-cards.json",
"previous": null,
"next": null
}
}
Get a single Gift Card
GET
/api/v2/gift-cards/{id}.json
Retrieve a single Gift Card using its ID.
Requires either the gift-cards or gift-cards.readonly OAuth
scope.
URL parameters
id
required
The ID of the Gift Card is supplied as a path parameter. |
Response
Returns an object with the following properties:
success
A boolean where a value of true represents a successful request.
|
status
The HTTP status code e.g. 200 for a successful request.
|
data
Contains the Gift Card object. |
Example JSON response
{
"data": {
"id": 1234,
"orderId": null,
"orderLineId": null,
"productId": null,
"last4Characters": "c6b8",
"currency": "GBP",
"amount": "50.00",
"balance": "25.00",
"isActive": true,
"expiresOn": null,
"issuerId": null,
"email": "username@email-address.com",
"message": null,
"image": null,
"recipientId": null,
"createdOn": "2024-09-07T05:27:00+00:00",
"modifiedOn": "2024-09-07T08:05:00+00:00"
}
}
Add a Gift Card
POST
/api/v2/gift-cards.json
Requires the gift-cards OAuth scope.
Request body
data
required
Containing a Gift Card object. |
Example JSON request
When creating a gift card the minimum requirements are a
reference,
amount and
currency. The currency supplied must be a valid ISO 4217 alpha code supported
by one of the Account’s locales.
{
"data": {
"reference": "12e45a781b34c6b8",
"amount": "50.00",
"currency": "GBP"
}
}
If you would like to create a gift card for a recipient, you will require an
email address with an optional
message.
{
"data": {
"reference": "12e45a781b34c6b8",
"amount": "50.00",
"currency": "GBP",
"email": "name@email-address.com"
}
}
Success response
If the Gift Card was created successfully you should receive a response with a 201 status
code:
{
"data": {
"id": 1234,
"orderId": null,
"orderLineId": null,
"productId": null,
"last4Characters": "c6b8",
"currency": "GBP",
"amount": "50.00",
"balance": "50.00",
"isActive": true,
"expiresOn": null,
"issuerId": null,
"email": null,
"message": null,
"image": null,
"recipientId": null,
"createdOn": "2024-09-07T05:27:00+00:00",
"modifiedOn": "2024-09-07T05:27:00+00:00"
}
}
For security reasons the reference is omitted from the return object.
success
A boolean where a value of true means the Gift Card was created successfully.
|
status
The HTTP status code e.g. 201 means the Gift Card was created successfully. |
data
Contains the Gift Card object you created including its new id. |
Error responses
If the Gift Card could not be created you will encounter a response with a 422 status code:
success
A boolean where a value of false means the object could not be created.
|
status
A response code of 422 means the object could not be created and you should
check the errors property for further information. |
context
The context property indicates where the error occurred. For a 422 error this
will typically contain a value of data, indicating that there was an error
with the data object supplied. |
errors
Contains an array of error objects, each will have the following properties:
|
Update a Gift Card
PUT
/api/v2/gift-cards/{id}.json
Updating an existing Gift Card is limited to a subset of its writable properties available on creation.
Requires the gift-cards OAuth scope.
URL parameters
id
required
The ID of your Gift Card object |
Request body
Once a Gift Card has been created updates are limited to a small subset of properties.
The following properties are only editable if the existing gift card has a null email address.
emailmessageimage
If these are supplied during an update, Evance will send an email to the recipient email address with the message and artwork image.
The only other properties that may be modified are:
expiresOnisActive- disabling a gift card cannot be undone.
data
required
Containing updates to your Gift Card object. |
Example JSON request
To update a Gift Card you must PUT JSON to this resource within a data object. You do
not need to supply all properties and may choose to only supply properties that require modifying.
{
"data": {
"email": "username@email-address.com"
}
}
Success response
If the Gift Card was updated successfully you should receive a response with a 200 status
code:
success
A boolean where a value of true means the object was updated successfully.
|
status
The HTTP status code e.g. 200 means the object was updated successfully. |
data
Contains the Gift Card object you updated. |
Error responses
If the Product could not be updated you will encounter a response with either a 400,
404or
422status code:
success
A boolean where a value of false means the item could not be updated.
|
status
|
context
|
errors
Contains an array of error objects, each will have the following properties:
|