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

id read-only
An unsigned 64-bit integer, which is unique across all Gift Cards and all Evance Accounts.
orderId read-only
The ID of the order the Gift Card was generated from. Gift Cards created manually will have a null value.
orderLineId read-only
The ID of the order line the Gift Card was generated from. Gift Cards created manually will have a null value.
productId read-only
The original Gift Card Product the Gift Card originate from, this will also be reflected in the Order Line. Gift cards created manually may have a null value.
reference
The reference is a protected property. It is written when creating a Gift Card, after which the last4Characters may be used.
The reference requires a minimum of 8 characters and a maximum of 16 characters.
last4Characters read-only
The last four characters of the gift card reference. Because gift cards are alternative payment methods, the full code cannot be retrieved.
currency
The ISO 4217 alpha code for the currency - a three letter uppercase string. The currency code may only be set on POST.
amount
The initial value of the Gift Card when it was created - may only be set on POST.
balance
The remaining balance of the card. The balance of a gift card cannot be modified directly.
isActive
A boolean value. Defaults to true - disabling a gift card cannot be undone.
expiresOn
The expiry date of the gift card. An expiry date may only be extended, it cannot be reduced. Defaults to null- no expiry (recommended).
issuerId
The ID of the Contact who issued the gift card may be:
  • An administrator who manually created the gift card.
  • A customer who purchased the gift card. In this scenario the gift card will have a valid orderId and orderLineId.
email
The email address of the recipient of the gift card.
message
A message to the recipient from the issuer.
image
An image to use as the gift card artwork. This may be populated in several ways:
  • If the Gift Card was generated from a Gift Card Product the image may represent the primary image of the Product.
  • The image was supplied manually.
  • A null value means the default Gift Card artwork will be used.
recipientId
The ID of the Contact registered as the recipient. This is only set when a user transfers the balance of their gift card into their account.
createdOn
The Date and time when the gift card was created.
modifiedOn
The date and time when the gift card was last modified.

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.
  • limit - the number of items to return per page
  • page - the current page number
  • total - the total number of available results
  • totalPages - the total number of available pages of results
links
An object containing links to traverse available search results.
  • self - the URL for the current search.
  • previous - a URL for the previous results page, or nullif there isn't one.
  • next - a URL for the next results page, or null if there isn't one

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:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string (e.g. error.not-unique if the alias supplied is already in use).


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.

  • email
  • message
  • image

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:

  • expiresOn
  • isActive - 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
  • 400 may indicate that the ID was not provided.
  • 404 means object could not be found by the ID provided.
  • 422 means the object could not be updated due to errors in the data.
context
  • parameters means the error is with the required id URL parameter.
  • data indicates an error within the data.
errors

Contains an array of error objects, each will have the following properties:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string (e.g. error.not-unique if the alias supplied is already in use).