Introduction

Welcome to the VoucherCart API v2!

The VoucherCart API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded and JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

VoucherCart uses JWT authentication described in RFC-7519 specification.

Almost all VoucherCart endpoints require authorization using the JWT token, which is expected to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer JWT_TOKEN

You must replace JWT_TOKEN with your JWT Token.

Get JWT Token

HTTP Request

curl -X POST "https://api.vouchercart.com/v2.1/authorize" \
    -u "[email protected]:password" \
    --data "subdomain=my-sales-page"

POST https://api.vouchercart.com/v2.1/authorize

With this request you must add Authorization header using the Basic method.

Authorization header should be comprised of a base64-encoded combination of user's email (login) and password separated by a colon. Sample header may look like this: Authorization: Basic base64(concat(login, :, password))

Parameter	Type	Description
subdomain	string, required	Name of the domain

HTTP Response

Response example:

{
  "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI5MmEyMjgwOC1iZDU1LTQxMzQtODc4Mi04MjUwNWFkMTZkNjMiLCJpYXQiOiIxNDgxMDI2OTk3IiwiZXhwIjoiMTQ4MTExMzM5NyIsImF1ZCI6ImNsaWVudDEiLCJ1c2VyIjoxfQ.5KIC2E_KC9garXNxAxgf_GGVjuTRyU_nddwChxjVWbw",
  "identifiedBy": "92a22808-bd55-4134-8782-82505ad16d63",
  "profile": {
    "email": "[email protected]",
    "fullName": "Jane Doe",
    "id": 1,
    "locale": "en"
  },
  "refreshToken": "RTZmQzZjc0MzU1NDdlYzcxYTk3NGEwM2FjNTNlY2YxMDg5YWYxNjcwNw",
  "status": "authenticated"
}

If you are authenticated successfully you will receive a JSON response with an accessToken - a JWT token. JWT token can be used as authorization key which should be added to Authorization header. Most API endpoints require Bearer method to authorize, so you will need to supply JWT token in header: Authorization: Bearer eyJ0eXAiOiJKV...

Attribute	Type	Description
accessToken	string	A JWT token
identifiedBy	string	ID of the generated token
profile	Profile object	See The Profile object below
refreshToken	string	Refresh token
status	string	Should return `authenticated`, otherwise request has failed.

The Profile object

Attribute	Type	Description
email	string	E-mail address of the user
fullName	string	Full name
id	integer	ID of the user object
locale	string	Language code used by user

Refresh token

JWT technique uses short-lived tokens, which means that the JWT will be valid only for a short duration (1 day) after authentication. With refresh tokens your application may delay expiration of the session.

HTTP Request

curl -X PUT "https://api.vouchercart.com/v2.1/refresh" \
    --data "accessToken=my-jwt-token&refreshToken=RTrefreshToken"

PUT https://api.vouchercart.com/v2.1/refresh

Parameter	Type	Description
accessToken Required	string	The JWT token that is about to expire (or has already expired)
refreshToken Required	string	Refresh token acquired during authorization. Starts with `RT` letters.

HTTP Response

Response example:

{
  "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJqdGkiOiI5MmEyMjgwOC1iZDU1LTQxMzQtODc4Mi04MjUwNWFkMTZkNjMiLCJpYXQiOiIxNDgxMDI4NzIxIiwiZXhwIjoiMTQ4MTExNTEyMSIsImF1ZCI6ImNsaWVudDEiLCJ1c2VyIjoxfQ.pkxwkokz5tHXtUthRHH-hdkDd9wxaTliRebtAbmyBuw",
  "identifiedBy": "92a22808-bd55-4134-8782-82505ad16d63",
  "refreshToken": "RTZjgwYzhkMmFhZjU5OWRlOTdmNzIzNjY2ZGMzYTcxODEwOWJjMjJiMw",
  "status": "refreshed"
}

N.B. refreshToken and accessToken change with each /refresh request (they are rotating). A refreshToken that has already been used cannot be used again.

Attribute	Type	Description
accessToken	string	A JWT token
identifiedBy	string	ID of the generated token
refreshToken	string	Refresh token
status	string	Should return `refreshed`, otherwise request has failed.

Responses

200 - OK
201 - Created
202 - Accepted
204 - No Content
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
409 - Conflict
422 - Unprocessable Content
429 - Too Many Requests
500, 502, 503, 504 - Server Errors

VoucherCart uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with VoucherCart's servers.

Code	Meaning
200	The request succeeded. The body holds the requested object or list
201	The object was created. The `Location` header holds its URL
202	The request was accepted, but the result is not ready yet. Repeat the request after the number of seconds in the `Retry-After` header
204	The request succeeded and the response has no body
400	The request is not valid: a parameter is missing or wrong, or the action is not allowed for this object (for example, the voucher has expired). The `message` says why
401	The access token is missing, not valid or expired
403	The token is valid, but the user or the account is not allowed to do this
404	The object does not exist on your account
409	The request conflicts with the current state, or the same request is still being processed. The endpoint description says when
422	The request is well formed, but cannot be processed as sent. The endpoint description says when
429	Too many requests in a short time. Wait and try again
503	The service or the result is not available right now. Repeat the request after the number of seconds in the `Retry-After` header

Not every endpoint returns every code. Where an endpoint gives a code a specific meaning, its description says so.

Error response body often contains additional details.

Expanding objects

Expand example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/orders?expand[]=payments&expand[]=deliveries" \
  -H "Authorization: Bearer JWT_TOKEN"

N.B. You can expand multiple objects at once by identifying multiple items in the expand[] array.

Many objects contain the ID or a list of IDs of a related object(s) in their response properties. For example, an Order has associated Payment IDs. Those objects can be expanded inline with the expand request parameter. Objects that can be expanded are noted in this documentation. The parameter applies to the response of that request only. It is read only by endpoints that list expandable objects; there, a name that is not on the list is rejected with 400, and other endpoints ignore the parameter.

Pagination

Lists are paginated with cursors under the /v2.1 prefix only. Only the first call fetching a list has to specify parameters such as order_by, order and limit. The response is wrapped in a List object and contains cursors for fetching the next and previous pages.

Under the /v2 prefix these list endpoints are not paginated: they return a plain JSON array of all objects, without the list wrapper, and ignore the pagination parameters.

The List object

The List object example

{
    "object": "list",
    "data": [],
    "count": 0,
    "previous": "PREVIOUS_PAGE_TOKEN",
    "has_previous": false,
    "next": "NEXT_PAGE_TOKEN",
    "has_next": false,
    "per_page": 10
}

Attribute	Type	Description
object	string	list object identifier
data	array	array of requested objects
count	integer	count of returned objects
previous	string	cursor to the previous page
has_previous	boolean	true if the previous page is not empty at the time of response
next	string	cursor to the next page
has_next	boolean	true if the next page is not empty at the time of response
per_page	integer	the `limit` sent with this request, or `10` when none was sent (on calls with a `cursor` the page size stored in the cursor applies)

First call

First call to the index resource can contain pagination parameters.

HTTP Request

Pagination first call example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/orders?order_by=created_at&order=desc&limit=25" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Default	Description
order_by	string	depends on resource	field used to sort records, fields that can be used are noted in resource documentation
order	string	`desc`	`desc` for descending sorting order or `asc` for ascending
limit	integer	`10`	a page size limit, min: 1 max: 50

HTTP Response

Response example:

{
  "object": "list",
  "data": [
    {
      "id": 18,
      "object": "order",
      "language": "en",
      "purchaser": {
        "name": "Jon Smith",
        "email": "[email protected]",
        "phone": ""
      },
      "products": [
        32
      ],
      "deliveries": [],
      "payments": [
        47
      ]
    },
    {
      "id": 17,
      "object": "order",
      "language": "en",
      "purchaser": {
        "name": "Meghan Smith",
        "email": "[email protected]",
        "phone": ""
      },
      "products": [
        31
      ],
      "deliveries": [],
      "payments": [
        46
      ]
    }
  ],
  "count": 2,
  "previous": "eyJkaXIiOiJwcmV2aW91cyIsImN1cnNvciI6IjE4Iiwib3JkZXJfYnkiOiJvLmNyZWF0ZWRfYXQiLCJvcmRlciI6IkRFU0MiLCJsaW1pdCI6MTB9",
  "has_previous": false,
  "next": "eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiOSIsIm9yZGVyX2J5Ijoiby5jcmVhdGVkX2F0Iiwib3JkZXIiOiJERVNDIiwibGltaXQiOjEwfQ==",
  "has_next": true,
  "per_page": 10
}

List object

Subsequent calls

Subsequent calls have to use the cursor returned by the first or previous call to retrieve the next or previous page. A malformed cursor is rejected with 400; a cursor that no longer points at a record in the list returns 404.

When the cursor parameter is provided, other pagination parameters such as order_by or limit are ignored.

HTTP Request

Pagination subsequent call example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/orders?cursor=eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiOSIsIm9yZGVyX2J5Ijoiby5jcmVhdGVkX2F0Iiwib3JkZXIiOiJERVNDIiwibGltaXQiOjEwfQ==" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
cursor	string	cursor to the next or previous page, pagination parameters like `order`, `order_by` are already stored in token

HTTP Response

The same as in the first call

Common objects

VoucherCart API uses some common objects to represent often reused concepts.

The Money hash

The Money hash example:

{
  "amount": 12345,
  "currency": "GBP"
}

This example represents monetary value of £123.45

Attribute	Type	Description
amount	integer	Amount, expressed in the smallest units of currency (e.g. pence)
currency	string	ISO 4217 Currency Code, e.g. `GBP`

The Translation hash

The Translation hash example:

{
  "en": "Fruits",
  "pl": "Owoce",
  "de": "Früchte"
}

This example represents translation for "Fruits" text

Attribute	Type	Description
key	string	ISO 639-1:2002 Locale Code, e.g. `en`
value	string	Translated text

Redeem Locations

Places and websites where vouchers can be redeemed.

The Redeem Location object

The Redeem Location object example (physical location):

{
  "id": 786322,
  "object": "redeem_location",
  "type": "physical",
  "name": "Adara Hotel",
  "is_sale_location": true,
  "is_private": false,
  "address_line1": "302 George Street",
  "address_line2": "",
  "city": "Edinburgh",
  "postcode": "EH2 3TY",
  "region": null,
  "email": "[email protected]",
  "phone": "01234567890",
  "latitude": "55.952910",
  "longitude": "-3.200390",
  "website": "https://www.example.com"
}

The Redeem Location object example (online location):

{
  "id": 789912,
  "object": "redeem_location",
  "type": "online",
  "name": "Online Shop",
  "is_sale_location": false,
  "is_private": false,
  "url": "https://shop.example.com",
  "explainer_video_url": "",
  "instructions": "Enter the voucher code at checkout.",
  "images": []
}

A redeem location is either physical (a place) or online (a website). The attributes after is_private depend on the type.

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `redeem_location`	redeem location object identifier
type	enum: `physical`, `online`
name	string
is_sale_location	boolean	`true` if vouchers are also sold at this location
is_private	boolean
organisation_redeem_location	string	Only present when the location is linked to a location of the Organisation

Attributes of a physical location:

Attribute	Type	Description
address_line1	string
address_line2	string
city	string
postcode	string
region	string or null
email	string
phone	string
latitude	string or null
longitude	string or null
website	string

Attributes of an online location:

Attribute	Type	Description
url	string	URL of the website where the voucher is redeemed
explainer_video_url	string
instructions	string
images	array	array of image URLs

List all Redeem Locations

GET https://api.vouchercart.com/v2.1/redeem-locations

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/redeem-locations" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
sales_page_id	integer	Only locations of this Sales Page, plus locations not tied to any Sales Page. Required when the request is sent without the `Authorization` header, because the Sales Page then identifies the merchant. When it is left out of an authenticated request, all locations of the merchant are listed.

Pagination parameters

See Pagination

Redeem locations are listed by name, A to Z, with the default order=desc; order=asc reverses the list. order_by accepts only created_at, which has no effect.

HTTP Response

Response example:

{
  "object": "list",
  "data": [
    {
      "id": 786322,
      "object": "redeem_location",
      "type": "physical",
      "name": "Adara Hotel",
      "is_sale_location": true,
      "is_private": false,
      "address_line1": "302 George Street",
      "address_line2": "",
      "city": "Edinburgh",
      "postcode": "EH2 3TY",
      "region": null,
      "email": "[email protected]",
      "phone": "01234567890",
      "latitude": "55.952910",
      "longitude": "-3.200390",
      "website": "https://www.example.com"
    },
    {
      "id": 789912,
      "object": "redeem_location",
      "type": "online",
      "name": "Online Shop",
      "is_sale_location": false,
      "is_private": false,
      "url": "https://shop.example.com",
      "explainer_video_url": "",
      "instructions": "Enter the voucher code at checkout.",
      "images": []
    }
  ],
  "count": 2,
  "previous": "eyJkaXIiOiJwcmV2aW91cyIsImN1cnNvciI6IjIiLCJvcmRlcl9ieSI6InJsLmNyZWF0ZWRfYXQiLCJvcmRlciI6IkRFU0MiLCJsaW1pdCI6MTB9",
  "has_previous": false,
  "next": "eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiMSIsIm9yZGVyX2J5IjoicmwuY3JlYXRlZF9hdCIsIm9yZGVyIjoiREVTQyIsImxpbWl0IjoxMH0=",
  "has_next": false,
  "per_page": 10
}

List object containing Redeem Location objects. Under /v2 a plain array of Redeem Location objects is returned instead (see Pagination).

Vouchers

Vouchers resource

The Voucher object

The Voucher object example:

{
  "id": 6843354,
  "object": "voucher",
  "sales_page": 78641,
  "voucher_title": {
    "en": "A monetary voucher"
  },
  "promotion_title": {
    "en": ""
  },
  "description": {
    "en": "<p>A monetary voucher description</p>"
  },
  "img_url": "https://images.vouchercart.com/assets/XXXXXXXXXXXXXXXXXXXX.jpg",
  "is_active": true,
  "categories": [
    13345,
    65578
  ],
  "is_published": true,
  "access_level": "published",
  "is_featured": false,
  "is_available": true,
  "sale_period_is_unlimited": false,
  "is_redeemable_everywhere": false,
  "redeem_locations": [
    17745
  ],
  "layouts": [
    1224,
    4557
  ],
  "version": 12,
  "type_name": "buyerDefined",
  "display_options": {
    "is_voucher_message_off": false,
    "price_visible": true,
    "changing_price_visibility_by_buyer_allowed": true
  },
  "postal_delivery_enabled": false,
  "default_option_sell_price": {
    "amount": 100,
    "currency": "GBP"
  },
  "default_option_display_price": null,
  "default_option_real_value": null,
  "quantity": null,
  "sold": 10,
  "options": [
    43
  ],
  "position": 2,
  "sale_period_from": "2019-07-23T04:45:00+0000",
  "sale_period_to": "2019-07-23T04:47:00+0000",
  "shipping_methods": [
    13456,
    74563,
    89744
  ],
  "url": "https://test-company.vouchercart.com/v/6843354",
  "multi_use": false
}

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `voucher`	voucher object identifier
sales_page	integer	related Sale Page ID
voucher_title	Translation hash
promotion_title	Translation hash
description	Translation hash
img_url	string	URL
is_active	boolean
categories Expandable	array	array of Category objects or array of Category IDs (see Expanding Objects)
is_published	boolean
access_level	enum: `published`, `unpublished`, `secret`
is_featured	boolean
is_available	boolean
sale_period_is_unlimited	boolean
is_redeemable_everywhere	boolean
redeem_locations Expandable	array	array of Redeem Location objects or array of Redeem Location IDs (see Expanding Objects)
layouts Expandable	array	array of Layout objects or array of Layout IDs (see Expanding Objects)
version	integer
type_name	enum: `fixed`, `buyerDefined`, `predefined`, `ticket`, `reloadable_gift_card`
display_options	Display Options hash
postal_delivery_enabled	boolean
default_option_sell_price	Money hash
default_option_display_price	Money hash
default_option_real_value	Money hash or null	Always `null` to callers without a token
quantity	integer or null	Always `null` to callers without a token
sold	integer or null	Always `null` to callers without a token
options Expandable	array	array of Voucher Option objects or array of Voucher Option IDs (see Expanding Objects)
position	integer	Position on Sales Page
sale_period_from	string	ISO 8601 date format, returned only if `sale_period_is_unlimited` = `false`
sale_period_to	string or null	ISO 8601 date format, returned only if `sale_period_is_unlimited` = `false`; `null` when the sale period has no end
shipping_methods Expandable	array	array of Shipping Method hashes or array of Shipping Method IDs (see Expanding Objects), available only if `postal_delivery_enabled` = `true`
created_at Read Only	string	ISO 8601 date format
url Read Only	string	URL to voucher details page at voucher's sales page
multi_use	boolean

The Layout object

The Layout object example:

{
  "id": 11237,
  "object": "voucher_layout",
  "image": "https://images.vouchercart.com/assets/XXXXXXXX.png"
}

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `voucher_layout`	layout object identifier
image	string	URL

The Display Options hash

The Display Options hash example:

{
  "is_voucher_message_off": false,
  "price_visible": true,
  "changing_price_visibility_by_buyer_allowed": true
}

Attribute	Type	Description
is_voucher_message_off	boolean
price_visible	boolean
changing_price_visibility_by_buyer_allowed	boolean

The Voucher Option object

The Voucher Option object example:

{
  "id": 246846,
  "object": "voucher_option",
  "type": "fixed",
  "description": {
    "en": "Large (qty=null,qtyW=5)"
  },
  "quantity": null,
  "quantity_weight": 5,
  "sold": 0,
  "sold_out": false,
  "sell_price": {
    "amount": 100,
    "currency": "GBP"
  },
  "leaf": true,
  "level": 0,
  "real_value": {
    "amount": 0,
    "currency": "GBP"
  },
  "display_price": {
    "amount": 0,
    "currency": "GBP"
  },
  "parent_id": 24,
  "custom_order": 0
}

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `voucher_option`	voucher option object identifier
type	enum: `fixed`, `range`	`range` for an option whose amount the buyer chooses
description	Translation hash
quantity	integer or null	Always `null` to callers without a token
quantity_weight	integer
sold	integer or null	Always `null` to callers without a token
sold_out	boolean
sell_price	Money hash
leaf	boolean
level	integer
real_value	Money hash or null	Always `null` to callers without a token
display_price	Money hash
max_sell_price	Money hash
redeem_stock	integer or null	Always `null` to callers without a token
parent_id	integer
custom_order	integer	default = 0

The Shipping Method hash

The Shipping Method hash example:

{
  "voucher_delivery_shipping_method_id": 3225,
  "shipping_method_id": 31225,
  "name": "UK 1st Class (DL Wallet)",
  "description": "Seeded Postal Fulfilment Method uk_1st_class",
  "delivery_duration": 1,
  "available_only_for_manual_orders": false,
  "uses_postal_fulfilment": true,
  "calculator": {
    "type": "per_item",
    "rate": {
      "amount": 359,
      "currency": "GBP"
    }
  }
}

Attribute	Type	Description
voucher_delivery_shipping_method_id	integer
shipping_method_id	integer
name	string
description	string
delivery_duration	integer	Expected delivery duration in days
available_only_for_manual_orders	boolean
uses_postal_fulfilment	boolean
calculator	Shipping Method Calculator hash

The Shipping Method Calculator hash

The Shipping Method Calculator hash example:

{
  "type": "per_item",
  "rate": {
    "amount": 359,
    "currency": "GBP"
  }
}

Attribute	Type	Description
type	enum: `per_item`
rate	Money hash

List all Vouchers

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/vouchers

The Authorization header is optional. Without a token the list holds only published vouchers that are available for sale, and quantity, sold and default_option_real_value of each voucher are null (so are quantity, sold, real_value and redeem_stock of expanded options).

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/vouchers" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)

Pagination parameters

See Pagination

Available order_by:

created_at

Expandables

See Expanding objects

Available expand[]:

redeem_locations
categories
shipping_methods
layouts
options

HTTP Response

Response example:

{
  "object": "list",
  "data": [
    {
      "id": 21,
      "object": "voucher",
      "sales_page": 78641,
      "voucher_title": {
        "en": "Relax SPA Stay with Afternoon Tea"
      },
      "promotion_title": {
        "en": ""
      },
      "description": {
        "en": "<p>Relax Spa Stay with Afternoon Tea includes:</p><ul><li>1 Night Stay in a Superior Double or Twin room</li><li>Breakfast next morning</li><li>Afternoon Tea with Glass of Bubbles</li><li>Choice of 30 minute Back Massage or 30 min Express Facial</li><li>Use of Leisure Facilities throughout your stay</li></ul>"
      },
      "img_url": "https://images.vouchercart.com/assets/XXXXXXXXXXXXX.jpg",
      "is_active": true,
      "categories": [],
      "is_published": true,
      "access_level": "published",
      "is_featured": false,
      "is_available": true,
      "sale_period_is_unlimited": false,
      "is_redeemable_everywhere": false,
      "redeem_locations": [
        1
      ],
      "layouts": [
        39,
        40
      ],
      "version": 0,
      "type_name": "fixed",
      "display_options": {
        "is_voucher_message_off": false,
        "price_visible": true,
        "changing_price_visibility_by_buyer_allowed": true
      },
      "postal_delivery_enabled": false,
      "default_option_sell_price": {
        "amount": 19900,
        "currency": "GBP"
      },
      "default_option_display_price": null,
      "default_option_real_value": null,
      "quantity": null,
      "sold": 10,
      "options": [
        44
      ],
      "position": 1,
      "url": "https://test-company.vouchercart.com/v/6843353",
      "multi_use": false,
      "sale_period_from": "2019-07-23T04:45:00+0000",
      "sale_period_to": "2019-07-25T04:47:00+0000"
    },
    {
      "id": 15,
      "object": "voucher",
      "sales_page": 78641,
      "voucher_title": {
        "en": "Friends & Family Shooting Lesson"
      },
      "promotion_title": {
        "en": ""
      },
      "description": {
        "en": "<p>Buy an individual shooting lesson for £55 and you can add up to three extra friends or family for an additional £20 each. </p><p>The lesson includes 50 clays and then a further 20 clays for each additional person.</p><p>Suitable for those with little, or no previous experience.</p>"
      },
      "img_url": "https://images.vouchercart.com/assets/XXXXXXXXXXXXX.jpg",
      "is_active": true,
      "categories": [],
      "is_published": true,
      "access_level": "published",
      "is_featured": false,
      "is_available": true,
      "sale_period_is_unlimited": true,
      "is_redeemable_everywhere": true,
      "redeem_locations": [],
      "layouts": [
        31
      ],
      "version": 3,
      "type_name": "fixed",
      "display_options": {
        "is_voucher_message_off": false,
        "price_visible": true,
        "changing_price_visibility_by_buyer_allowed": true
      },
      "postal_delivery_enabled": true,
      "default_option_sell_price": {
        "amount": 5000,
        "currency": "GBP"
      },
      "default_option_display_price": null,
      "default_option_real_value": null,
      "quantity": null,
      "sold": 10,
      "options": [
        38
      ],
      "position": 14,
      "shipping_methods": [
        4,
        5,
        6,
        7,
        8
      ],
      "url": "https://test-company.vouchercart.com/v/6843354",
      "multi_use": false
    }
  ],
  "count": 2,
  "previous": "eyJkaXIiOiJwcmV2aW91cyIsImN1cnNvciI6IjIyIiwib3JkZXJfYnkiOiJ2LmNyZWF0ZWRfYXQiLCJvcmRlciI6IkRFU0MiLCJsaW1pdCI6MTB9",
  "has_previous": false,
  "next": "eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiOCIsIm9yZGVyX2J5Ijoidi5jcmVhdGVkX2F0Iiwib3JkZXIiOiJERVNDIiwibGltaXQiOjEwfQ==",
  "has_next": true
}

List object containing Voucher objects

Retrieve a Voucher

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/vouchers/{VoucherId}

The Authorization header is optional. Without a token only a voucher that is available for sale is found, and quantity, sold and default_option_real_value are null (so are quantity, sold, real_value and redeem_stock of expanded options).

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/vouchers/15" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
VoucherId Required	integer	Path parameter

Expandables

See Expanding objects

Available expand[]:

redeem_locations
categories
shipping_methods
layouts
options

HTTP Response

Response example:

{
    "id": 15,
    "object": "voucher",
    "sales_page": 78641,
    "voucher_title": {
      "en": "Friends & Family Shooting Lesson"
    },
    "promotion_title": {
      "en": ""
    },
    "description": {
      "en": "<p>Buy an individual shooting lesson for £55 and you can add up to three extra friends or family for an additional £20 each. </p><p>The lesson includes 50 clays and then a further 20 clays for each additional person.</p><p>Suitable for those with little, or no previous experience.</p>"
    },
    "img_url": "https://images.vouchercart.com/assets/XXXXXXXXXXXXX.jpg",
    "is_active": true,
    "categories": [],
    "is_published": true,
    "access_level": "published",
    "is_featured": false,
    "is_available": true,
    "sale_period_is_unlimited": true,
    "is_redeemable_everywhere": true,
    "redeem_locations": [],
    "layouts": [
      31
    ],
    "version": 3,
    "type_name": "fixed",
    "display_options": {
      "is_voucher_message_off": false,
      "price_visible": true,
      "changing_price_visibility_by_buyer_allowed": true
    },
    "postal_delivery_enabled": true,
    "default_option_sell_price": {
      "amount": 5000,
      "currency": "GBP"
    },
    "default_option_display_price": null,
    "default_option_real_value": null,
    "options": [
      38
    ],
    "position": 14,
    "shipping_methods": [
      4,
      5,
      6,
      7,
      8
    ],
    "url": "https://test-company.vouchercart.com/v/6843354",
    "quantity": null,
    "sold": 10,
    "multi_use": false
  }

The Voucher object

Orders

Orders resource

The Order object

The Order object example:

{
  "id": 18,
  "object": "order",
  "language": "en",
  "purchaser": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": ""
  },
  "reference": "813713-WRB-1335GB",
  "external_reference": "shopify-1001",
  "products": [423664, 7545346],
  "deliveries": [42123],
  "payments": [4389],
  "is_manual_order": false,
  "created_at": "2019-08-19T11:00:39Z",
  "buyer_consent_to_promotion_offers": false,
  "utm_parameters": {
    "source": "newsletter",
    "medium": "email",
    "campaign": "christmas",
    "term": null
  },
  "sales_page_name": "Test Company",
  "created_by": null,
  "sale_location_name": null,
  "is_paid": true,
  "additional_data": null,
  "charges": [],
  "digital_wallet_enabled": false
}

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `order`	order object identifier
language Required	string	ISO 639-1:2002 Locale Code ex. `en`
purchaser Required	Purchaser hash
reference Read Only	string	VoucherCart's Order reference
external_reference	string or null	Your own reference for the order, max 255 characters. Unique within the sales page: creating an order with a reference that is already used returns the existing order (see Create an Order)
products Required Expandable	array	array of Product objects or array of Product IDs (see Expanding Objects)
deliveries Read Only Expandable	array	array of Delivery objects or array of Delivery IDs (see Expanding Objects)
discount_codes Write Only	array	array of strings
is_paid	boolean	When creating: default `true`. Creates the order as already paid, for example when the buyer paid in another shop. Record how it was paid with Record a Manual Payment. Ignored for callers authenticated with an OAuth (Passport) token: their orders are always created unpaid. In responses: whether the order is paid
payments Read Only Expandable	array	array of Payment objects or array of Payment IDs (see Expanding Objects)
is_manual_order Read Only	boolean
created_at Read Only	string	ISO 8601 date string ex. `2019-08-19T11:00:39Z`
buyer_consent_to_promotion_offers Read Only	boolean	Consent of the buyer to send promotional offers
utm_parameters Read Only	hash	`source`, `medium`, `campaign` and `term` UTM parameters the order was placed with, each a string or null
sales_page_name Read Only	string
created_by Read Only	hash or null	`first_name`, `last_name` and `email` of the dashboard user who created the order; `null` for orders placed by buyers
sale_location_name Read Only	string or null	Name of the sale location of a manual order
additional_data Read Only	hash or null	Extra data recorded by an integration, for example the POS till. Its shape depends on the integration
charges Read Only Expandable	array	Charges added to the order, each with `id`, `charge_id`, `name`, `type` and `amount` (Money hash). Empty unless `expand[]=charges` is sent to Retrieve an Order
digital_wallet_enabled Read Only	boolean	Whether Apple Wallet and Google Wallet passes are switched on for the sales page of the order

The Purchaser hash

The Purchaser hash example:

{
  "name": "John Doe",
  "email": "[email protected]",
  "phone": "+1 987 654 321"
}

Attribute	Type	Description
name Required	string
email Required	string
phone	string

The Product object

The Product object example (Electronic Delivery Method):

{
  "id": 35,
  "name": "A Monetary Voucher",
  "object": "order-product",
  "voucher_id": 19,
  "voucher_version": 0,
  "option_id": 42,
  "layout_id": 35,
  "message": "Best wishes!",
  "hide_price": false,
  "delivery_method": "electronic",
  "price_paid_calculator": "regular",
  "internal_note": null,
  "regular_price": {
    "amount": 2000,
    "currency": "GBP"
  },
  "price_paid": {
    "amount": 2000,
    "currency": "GBP"
  },
  "recipient": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "voucher_from": "John Smith",
  "voucher_to": "Samantha White",
  "is_multiuse": false,
  "is_monetary": true,
  "redeemable_from": "2020-01-27T09:51:46+0000",
  "redeemable_to": "2020-04-27T09:51:46+0000",
  "redeem_stock": 1,
  "redeem_used": 0,
  "redeem_remaining": 1,
  "price_on_voucher": "£999.00",
  "redeemable_everywhere": true,
  "redeemable_on_redeem_locations": [
    7,
    8,
    9
  ],
  "delivery_date": null,
  "status": "in_progress",
  "delivery_status": "sent"
}

The Product object example (Postal Delivery Method):

{
  "id": 33,
  "name": "Laughter yoga",
  "object": "order-product",
  "voucher_id": 14,
  "voucher_version": 0,
  "option_id": 37,
  "layout_id": 29,
  "message": "",
  "hide_price": false,
  "delivery_method": "postal",
  "price_paid_calculator": "regular",
  "internal_note": null,
  "regular_price": {
    "amount": 10000,
    "currency": "GBP"
  },
  "price_paid": {
    "amount": 10000,
    "currency": "GBP"
  },
  "shipping_address": {
    "name": "John Smith",
    "address_line_1": "Lake Street 123",
    "address_line_2": "",
    "city": "New York",
    "postcode": "10001",
    "county": "NY",
    "country": "us"
  },
  "voucher_from": "John Smith",
  "voucher_to": "Samantha White",
  "is_multiuse": false,
  "is_monetary": true,
  "redeemable_from": "2020-01-27T09:51:46+0000",
  "redeemable_to": "2020-04-27T09:51:46+0000",
  "redeem_stock": 1,
  "redeem_used": 0,
  "redeem_remaining": 1,
  "price_on_voucher": "£999.00",
  "redeemable_everywhere": true,
  "redeemable_on_redeem_locations": [
    7,
    8,
    9
  ],
  "delivery_date": null,
  "status": "in_progress",
  "shipping_status": "not_sent"
}

Attribute	Type	Description
id Read Only	integer
name Read Only	string	Product name
object Read Only	string, value = `order-product`	order product object identifier
voucher_id Required	integer
voucher_version Required	integer
option_id Required	integer
layout_id Required	integer
voucher_from	string
voucher_to	string
message	string
hide_price	boolean	`true` if price should be hidden on voucher
delivery_method Required	enum: `postal`, `electronic`, `printout`, `vc_card`, `pickup`, `collect`, `collect_now`	`collect`: the buyer collects the voucher later at a collection location; `collect_now`: the voucher is handed over on the spot
price_paid_calculator	enum: `regular`, `free`, `charity`	Default: `regular`. `free` needs the Create Free Manual Orders permission and `charity` the Create Charity Manual Orders permission; without it the order is refused with `401`
internal_note	string	Max length: 500
regular_price Read Only	Money hash
price_paid Read Only	Money hash
recipient	Recipient object
shipping_status Read Only	string	Shipping status of the voucher, for example `not_sent`, `packed`, `sent`, `delivered`; returned only if `delivery_method` = `postal`
delivery_status Read Only	string	Delivery status of the voucher, for example `sent`, `delivered`, `undelivered`, `ready_for_collection`, `collected`; returned only if `delivery_method` = `electronic`, `collect` or `collect_now`
shipping_address Conditionally Required	Shipping Address object	Required if `delivery_method` = `postal`
option_amount Conditionally Required Write Only	Money hash	Required only for Monetary Vouchers (a.k.a. Buyer Defined / Range Vouchers)
voucher_delivery_shipping_method_id Conditionally Required Write Only	integer	Required if `delivery_method` = `postal`. The `voucher_delivery_shipping_method_id` of one of the voucher's Shipping Method hashes
voucher_delivery_collect_option_id Conditionally Required Write Only	integer	Required if `delivery_method` = `collect` or `collect_now`. ID of the collection option
voucher_delivery_collect_location_id Conditionally Required Write Only	integer	Required if `delivery_method` = `collect`. ID of the collection location
delivery_date	string or null	ISO 8601 date string ex. `2019-08-19T11:00:00+0000`. When the voucher is sent to the recipient; when set, `recipient` with `name` and `email` is required
quantity Write Only	integer	Max value: 300. Creates this many identical vouchers in one bulk order. Send it with a single product in `products`
product_type Write Only	string	Default: `voucher`
is_multiuse Read Only	boolean
is_monetary Read Only	boolean
redeemable_from Read Only	string	ISO 8601 date string ex. `2019-08-19T11:00:39Z`
redeemable_to Read Only	string	ISO 8601 date string ex. `2019-08-19T11:00:39Z`
redeem_stock Read Only	integer	The full balance of the voucher. For a multi-use monetary voucher (`is_multiuse` and `is_monetary` both `true`) it is an amount in the smallest currency unit (`5000` = £50.00); for any other voucher it counts uses (`1` for a single-use voucher)
redeem_used Read Only	integer	How much of `redeem_stock` was already redeemed, in the same unit
redeem_remaining Read Only	integer	`redeem_stock` minus `redeem_used`, in the same unit
price_on_voucher Read Only	string	Formatted price string that depending on `hide_price` value can be printed on voucher
redeemable_everywhere Read Only	boolean	Is redeemable on all Redeem Locations
redeemable_on_redeem_locations Read Only	integer[]	if `redeemable_everywhere` = `false` then it is redeemable on Redeem Locations of those ids
status Read Only	enum: `in_progress`, `completed`, `cancelled`, `refunded`, `regenerated`, `archived`, `voided`	`in_progress` until the voucher is fully redeemed, then `completed`

The Recipient object

The Recipient object example:

{
  "name": "John Doe",
  "email": "[email protected]"
}

Attribute	Type	Description
name Required	string
email Required	string

The Shipping Address object

The Shipping Address object example:

{
  "name": "John Smith",
  "address_line_1": "Lake Street 123",
  "address_line_2": "",
  "city": "New York",
  "postcode": "10001",
  "county": "NY",
  "country": "us"
}

Attribute	Type	Description
name Required	string
address_line_1 Required	string
address_line_2	string
city Required	string
postcode Required	string
county Conditionally Required	string	Required if `country` = `us`: the US state, as its two-letter code (`NY`) or its full name (`New York`). Free text for other countries
country Required	string	ISO 3166-1 alpha-2 Country Code ex. `gb`

The Delivery object

The Delivery object example:

{
  "id": 34,
  "name": "UK 1st Class (DL Wallet)",
  "object": "order-product-delivery",
  "regular_price": {
    "amount": 359,
    "currency": "GBP"
  },
  "price_paid": {
    "amount": 359,
    "currency": "GBP"
  },
  "related_product_id": 33
}

Attribute	Type	Description
id Read Only	integer
name Read Only	string
regular_price Read Only	Money hash
price_paid Read Only	Money hash
related_product_id Read Only	integer

The Payment object

The Payment object example:

{
  "transaction_id": "6-9-4594304",
  "card_type": "visa",
  "card_number": "XXXXXXXXXXXX0211",
  "amount": {
    "amount": 10359,
    "currency": "GBP"
  },
  "gateway": "Stripe",
  "gateway_status": "active",
  "created_at": "2019-08-19T11:00:39Z"
}

Attribute	Type	Description
transaction_id Read Only	string
card_type Read Only	string	`visa`, `amex`, `mastercard`, ... - available for selected Payment Gateways
card_number Read Only	string
amount Read Only	Money hash
gateway Read Only	string
gateway_status Read Only	string
created_at Read Only	string	ISO 8601 date string ex. `2019-08-19T11:00:39Z`

The Refund object

The Refund object example:

{
  "id": 27784,
  "object": "refund",
  "total": {
    "amount": 1999,
    "currency": "GBP"
  },
  "product": 32,
  "order": 18,
  "created_by": "Jon Smith",
  "created_at": "2019-10-14T08:43:21+0000",
  "reason": "Reasonable refund reason",
  "through_payment_gateway": true,
  "gateway": "Stripe",
  "gateway_name": "Stripe",
  "gateway_refund_status": "completed",
  "gateway_refund_transaction_id": "ch_1FTP98AoRqCdB7Aku4oi7Xgd"
}

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `refund`	refund object identifier
total Read Only	Money hash
product Expandable	int or Product object	Product object or Product ID (see Expanding Objects)
order Expandable	int or Order object	Order object or Order ID (see Expanding Objects)
created_by Read Only	string
created_at Read Only	string	ISO 8601 date string ex. `2019-08-19T11:00:39Z`
reason	string	Reason for refund
through_payment_gateway	boolean	Was refund processed through payment gateway
gateway Read Only	string	available only if `through_payment_gateway` = `true`
gateway_name Read Only	string	Same value as `gateway`
gateway_refund_status Read Only	enum: `in_progress`, `completed`, `failed`	available only if `through_payment_gateway` = `true`
gateway_refund_transaction_id Read Only	string	available only if `through_payment_gateway` = `true`

Create an Order

POST https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/orders

HTTP Request

Request example:

curl -X POST 'https://api.vouchercart.com/v2.1/sales-pages/1337/orders' \
  -H 'Authorization: Bearer JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary '
  {
    "purchaser": {
      "name": "Jon Smith",
      "email": "[email protected]",
      "phone": ""
    },
    "products": [
      {
        "option_id": 35338,
        "option_amount": {
          "amount": 10000,
          "currency": "GBP"
        },
        "voucher_id": 13555,
        "layout_id": 31231,
        "voucher_version": 0,
        "hide_price": false,
        "message": "Have a nice one",
        "delivery_method": "postal",
        "shipping_address": {
          "name": "John Smith",
          "address_line_1": "Lake Street 123",
          "address_line_2": "",
          "city": "New York",
          "postcode": "10001",
          "county": "NY",
          "country": "us"
        },
        "voucher_delivery_shipping_method_id": 6332,
        "internal_note": null,
        "voucher_from": "John Smith",
        "voucher_to": "Samantha White"
      }
    ],
    "language": "en"
  }
'

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)

Request body

Order object. Besides its writable attributes the request accepts:

Parameter	Type	Description
sale_location_id	integer or null	ID of the Redeem Location where the order is sold; it must be one marked as a sale location. Required when your account setting requires a sale location on manual orders. Answers `401` when the signed-in user has no access to that location

HTTP Response

Successful response (code 201) contains Location header with URL to the created resource

Response example:

< HTTP/2 201
< location: https://api.vouchercart.com/v2.1/sales-pages/1/orders/5667846

Retrying safely with `external_reference`

Send your own reference for the order, for example the order number in your shop, as external_reference. It is unique within the sales page, so a request you retry — after a timeout, say — never creates a second order:

Status	Meaning
`201`	The order was created
`200`	An order with this `external_reference` already exists on the sales page; nothing was created, and the `Location` header points to that order
`409`	Another request with the same `external_reference` is creating the order at this moment; retry later, or follow the `Location` header when it is present

Record a Manual Payment

POST https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/audit-order-payment-audits

Records how a manual order was paid, and its payment reference — the same as the "Payment reference" field when a manual order is created in the dashboard. Send it once, right after the order is created with is_paid: true.

The payment type and the reference are shown on the order in the dashboard and in the "Manual Payment Type" and "Manual Payment Reference" columns of the Orders Export.

Requires the Create Manual Orders permission.

HTTP Request

Request example:

curl -X POST "https://api.vouchercart.com/v2.1/sales-pages/1337/audit-order-payment-audits" \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary '
  {
    "order_id": 1818,
    "payment_type": "credit_debit_card",
    "payment_reference_number": "Shopify #1001"
  }'

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
order_id Required	integer	ID of the order the payment belongs to
payment_type Required	string	One of `cash`, `credit_debit_card`, `free`, `charity`
payment_reference_number	string or null	Your reference for the payment, for example the order number in your shop

HTTP Response

Status	Meaning
`201`	Recorded; the `Location` header points to the new record

To change the reference later, send PATCH https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/audit-order-payment-audits/{Id} with payment_reference_number, where {Id} is the last part of the Location header.

List all Orders

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/orders

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/orders" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
external_reference	string	Only the order created with this `external_reference`

Pagination parameters

See Pagination

Available order_by:

created_at

Expandables

See Expanding objects

Available expand[]:

products
deliveries
payments

HTTP Response

Response example:

{
  "object": "list",
  "data": [
    {
      "id": 18,
      "object": "order",
      "language": "en",
      "purchaser": {
        "name": "Jon Smith",
        "email": "[email protected]",
        "phone": ""
      },
      "reference": "813713-WRB-1335GB",
      "products": [
        32
      ],
      "deliveries": [],
      "payments": [
        47
      ],
      "created_at": "2019-08-19T11:00:39Z",
      "buyer_consent_to_promotion_offers": false,
      "sales_page_name": "Test Company"
    },
    {
      "id": 17,
      "object": "order",
      "language": "en",
      "purchaser": {
        "name": "Meghan Smith",
        "email": "[email protected]",
        "phone": ""
      },
      "reference": "423713-WRB-1698GB",
      "products": [
        31
      ],
      "deliveries": [],
      "payments": [
        46
      ],
      "created_at": "2019-08-19T11:00:39Z",
      "buyer_consent_to_promotion_offers": false,
      "sales_page_name": "Test Company"
    }
  ],
  "count": 2,
  "previous": "eyJkaXIiOiJwcmV2aW91cyIsImN1cnNvciI6IjE4Iiwib3JkZXJfYnkiOiJvLmNyZWF0ZWRfYXQiLCJvcmRlciI6IkRFU0MiLCJsaW1pdCI6MTB9",
  "has_previous": false,
  "next": "eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiOSIsIm9yZGVyX2J5Ijoiby5jcmVhdGVkX2F0Iiwib3JkZXIiOiJERVNDIiwibGltaXQiOjEwfQ==",
  "has_next": true
}

List object containing Order objects

Retrieve an Order

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/orders/{OrderId}

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/orders/18" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
OrderId Required	integer	Path parameter

Expandables

See Expanding objects

Available expand[]:

products
deliveries
payments

charges (this endpoint only)

HTTP Response

Response example:

{
  "id": 18,
  "object": "order",
  "language": "en",
  "purchaser": {
    "name": "Jon Smith",
    "email": "[email protected]",
    "phone": ""
  },
  "reference": "423713-WRB-1698GB",
  "products": [
    32
  ],
  "deliveries": [],
  "payments": [
    47
  ],
  "is_manual_order": false,
  "created_at": "2019-08-19T11:00:39Z",
  "buyer_consent_to_promotion_offers": false,
  "sales_page_name": "Test Company"
}

The Order object

Refund a Product

POST https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/orders/{OrderId}/products/{ProductId}/refund

Refunds one product of an order and voids its voucher. A fully redeemed voucher cannot be refunded; a multi-use voucher that is only partly redeemed can be.

When the client has a Shopify integration, the Shopify discount code of the voucher is deleted as well.

Requires the Refund permission.

HTTP Request

Request example:

curl -X POST "https://api.vouchercart.com/v2.1/sales-pages/1337/orders/1818/products/3247/refund" \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary '
  {
    "through_payment_gateway": false,
    "send_email_to_buyer": false,
    "reason": "Refunded in Shopify, order #1001"
  }'

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
OrderId Required	integer	Path parameter, Order ID
ProductId Required	integer	Path parameter, Product ID
through_payment_gateway Required	boolean	`true` returns the money through the payment gateway the order was paid with. Use `false` when the money is returned outside VoucherCart, for example for a manual order paid elsewhere.
send_email_to_buyer Required	boolean	Sends the refund email to the buyer. Ignored when `through_payment_gateway` is `true`: the email is then always sent
reason	string	Shown with the refund in the dashboard and in reports

HTTP Response

Status	Meaning
`204`	The product was refunded
`400`	The product cannot be refunded, for example because the voucher was fully redeemed, already refunded, or ordered as free or charity; the message says why
`404`	The order or the product does not exist on your account

Cancel a Product

POST https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/orders/{OrderId}/products/{ProductId}/cancel

Cancels one product of an order and voids its voucher, without recording a refund. To void a voucher whose money was returned, use Refund a Product instead, so that reports show it as refunded.

When the client has a Shopify integration, the Shopify discount code of the voucher is deleted as well.

Requires the Refund permission.

HTTP Request

Request example:

curl -X POST "https://api.vouchercart.com/v2.1/sales-pages/1337/orders/1818/products/3247/cancel" \
  -H "Authorization: Bearer JWT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary '
  {
    "reason": "Order cancelled in Shopify, order #1001",
    "send_email_to_buyer": false
  }'

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
OrderId Required	integer	Path parameter, Order ID
ProductId Required	integer	Path parameter, Product ID
reason Required	string	Shown with the cancellation in the dashboard
send_email_to_buyer Required	boolean	Sends the cancellation email to the buyer

HTTP Response

Status	Meaning
`204`	The product was cancelled
`400`	The product cannot be cancelled
`404`	The order or the product does not exist on your account

Product Refunds List

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/orders/{OrderId}/products/{ProductId}/refunds

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/orders/1818/products/3247/refunds" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
OrderId Required	integer	Path parameter, Order ID
ProductId Required	integer	Path parameter, Product ID

Pagination parameters

See Pagination

Available order_by:

created_at

Expandables

See Expanding objects

Available expand[]:

product
order
order.payments

HTTP Response

Response example:

{
  "object": "list",
  "data": [
    {
      "id": 27784,
      "object": "refund",
      "total": {
        "amount": 1999,
        "currency": "GBP"
      },
      "product": 32,
      "order": 18,
      "created_by": "Jon Smith",
      "created_at": "2019-10-14T08:43:21+0000",
      "reason": "Reasonable refund reason",
      "through_payment_gateway": true,
      "gateway": "Stripe",
      "gateway_name": "Stripe",
      "gateway_refund_status": "completed",
      "gateway_refund_transaction_id": "ch_1FTP98AoRqCdB7Aku4oi7Xgd"
    }
  ],
  "count": 1,
  "previous": "eyJkaXIiOiJwcmV2aW91cyIsImN1cnNvciI6IjIiLCJvcmRlcl9ieSI6Im92ci5jcmVhdGVkX2F0Iiwib3JkZXIiOiJERVNDIiwibGltaXQiOjEwfQ==",
  "has_previous": false,
  "next": "eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiMiIsIm9yZGVyX2J5Ijoib3ZyLmNyZWF0ZWRfYXQiLCJvcmRlciI6IkRFU0MiLCJsaW1pdCI6MTB9",
  "has_next": false
}

List object containing Refund objects

Product Redemptions List

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/orders/{OrderId}/products/{ProductId}/redemptions

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/orders/1818/products/3247/redemptions" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
OrderId Required	integer	Path parameter, Order ID
ProductId Required	integer	Path parameter, Product ID

Pagination parameters

See Pagination

Available order_by:

created_at

Expandables

This list has no expandable objects.

HTTP Response

Response example:

{
  "object": "list",
  "data": [
    {
      "id": 34,
      "object": "redemption",
      "redeem_location": 1,
      "order_product": 26,
      "reductor": 100,
      "created_at": "2021-01-27T12:53:33+0000"
    },
    {
      "id": 33,
      "object": "redemption",
      "redeem_location": 1,
      "order_product": 26,
      "reductor": 100,
      "created_at": "2021-01-27T12:53:22+0000"
    },
    {
      "id": 32,
      "object": "redemption",
      "redeem_location": 1,
      "order_product": 26,
      "reductor": 100,
      "created_at": "2021-01-27T12:53:13+0000"
    }
  ],
  "count": 3,
  "previous": "eyJkaXIiOiJwcmV2aW91cyIsImN1cnNvciI6IjM0Iiwib3JkZXJfYnkiOiJyYi5jcmVhdGVkX2F0Iiwib3JkZXIiOiJERVNDIiwibGltaXQiOjEwfQ==",
  "has_previous": false,
  "next": "eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiMjUiLCJvcmRlcl9ieSI6InJiLmNyZWF0ZWRfYXQiLCJvcmRlciI6IkRFU0MiLCJsaW1pdCI6MTB9",
  "has_next": false
}

List object containing Redemption objects

Redemptions

Redemptions resource

The Redemption object

The Redemption object example:

{
  "id": 789354,
  "object": "redemption",
  "redeem_location": 786,
  "order_product": 985635,
  "voucher_code": "ABC123",
  "reductor": 1,
  "created_at": "2019-07-23T04:45:00+0000"
}

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `redemption`	redemption object identifier
redeem_location Required	integer	ID of the Redeem Location where the voucher is redeemed. Always returned as an ID; it cannot be expanded
order_product Expandable Conditionally Required	Product object or integer	Related Product object or Product ID (see Expanding Objects), Required if `voucher_code` not provided
voucher_code Write Only Conditionally Required	string	Required if `order_product` not provided
reductor Required	integer	How much to redeem, min value = 1. For a multi-use monetary voucher (`is_multiuse` and `is_monetary` both `true` on the Product object) it is an amount in the smallest currency unit (`1500` = £15.00); for any other voucher it is a number of uses (`1` for a single-use voucher)
send_redemption_email Write Only	boolean	Default: `true`. Sends the "voucher redeemed" email to the voucher recipient (to the buyer when the voucher has no recipient, never for postal vouchers). Send `false` to redeem without the email
integration_id Write Only	integer	ID of the PMS integration the redemption is posted to. The three fields below are used only together with it
integration_related_id Write Only	string	The record in the PMS the redemption is posted to, for example the bill or the reservation
cloudbeds_house_account_id Write Only	integer	Cloudbeds only: the house account the redemption is posted to. When sent, it is used instead of `integration_related_id`
profile_id Write Only	string	Depends on the PMS: the customer profile in Mews, the bill number in Stayntouch
created_at Read Only	string	ISO 8601 date format

Create a Redemption

POST https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/redemptions

HTTP Request

Request example:

curl -X POST 'https://api.vouchercart.com/v2.1/sales-pages/1337/redemptions' \
  -H 'Authorization: Bearer JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 6f1c2a1e-6b1d-4b55-9f3e-2a7d8c0b4e11' \
  --data-binary '
  {
    "redeem_location": 786,
    "voucher_code": "ABC123",
    "reductor": 1
  }
'

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
Idempotency-Key	string	Header, optional. Max length: 255. See Retrying a redemption safely

Request body

Redemption object

HTTP Response

Successful response (code 201) contains Location header with URL to the created resource

Status	Meaning
`201`	The voucher was redeemed
`400`	The request failed validation, no voucher matches `voucher_code` or `order_product` ("Could not find matching Order Product"), or the voucher cannot be redeemed: for example the `reductor` is more than what is left, the voucher cannot be redeemed at this redeem location, or the PMS refused the posting. The `message` says which
`403`	The voucher was issued by another client

An expired voucher is refused with 400, unless the signed-in user has the permission to extend voucher expiry: then the expiry is extended to one hour from now and the voucher is redeemed.

Response example:

< HTTP/2 201
< location: https://api.vouchercart.com/v2.1/sales-pages/1/redemptions/745698

Retrying a redemption safely

A redemption can take a few seconds when the voucher is posted to a PMS, so a request can time out on your side while the redemption still completes on ours. Sending the same request again would then redeem the voucher twice.

To retry safely, send an Idempotency-Key header with a value you generate for each new redemption, for example a UUID, and send the same value again when you retry that redemption. The key is unique within your account.

Response	Meaning
`201`	The voucher was redeemed. The key is now linked to this redemption
`200`	This key was already used with the same request. Nothing was redeemed again; the `Location` header points to the redemption made the first time
`409`	A request with this key is still being processed. Wait and retry. When another request with the same key has just made the redemption, the `Location` header points to it
`422`	This key was already used with a different request body. Use a new key for a new redemption
`400`	The `Idempotency-Key` header is empty or longer than 255 characters

A key is linked to a redemption only when the redemption succeeds. If a request with a key is refused (for example the voucher has expired, or the PMS rejected the posting), nothing is saved and the same key can be used again.

Without the header the endpoint works as before: every request redeems the voucher again.

Retry response example:

< HTTP/2 200
< location: https://api.vouchercart.com/v2.1/sales-pages/1/redemptions/745698

Retrieve a Redemption

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/redemptions/{RedemptionId}

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/redemptions/789354" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
RedemptionId Required	integer	Path parameter

Expandables

See Expanding objects

Available expand[]:

order_product

HTTP Response

Response example:

{
  "id": 789354,
  "object": "redemption",
  "redeem_location": 786,
  "order_product": 985635,
  "reductor": 1,
  "created_at": "2019-07-23T04:45:00+0000"
}

The Redemption object

Cancel a Redemption

POST https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/orders/{OrderId}/products/{ProductId}/cancel-redeem/{RedemptionId}

Cancels a redemption and gives the redeemed amount (or use) back to the voucher. The redemption stays in the history of the voucher, marked as cancelled. When the redemption was posted to a PMS or POS integration, the cancellation is posted there too.

The signed-in user needs the permission to cancel redemptions on the sales page the voucher was sold on.

HTTP Request

Request example:

curl -X POST "https://api.vouchercart.com/v2.1/sales-pages/1337/orders/18/products/35/cancel-redeem/789354" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
OrderId Required	integer	Path parameter, ID of the Order
ProductId Required	integer	Path parameter, ID of the Product in the order
RedemptionId Required	integer	Path parameter, ID of the Redemption to cancel

The request has no body.

HTTP Response

Status	Meaning
204	The redemption was cancelled. The response has no body
400	The redemption could not be cancelled: it was already cancelled, the ID is not a redemption, the user has no permission to cancel redemptions, or the PMS or POS refused the cancellation. The `message` says which
404	The order or the product does not exist on your account

Response example:

< HTTP/2 204

Voucher Status

Check a voucher by its code before you redeem it

The Voucher Status object

The Voucher Status object example:

{
  "object": "voucher-status",
  "voucher_code": "ABC1234",
  "order_id": 18,
  "is_expired": false,
  "is_not_yet_redeemable": false,
  "is_redeemed": false,
  "order_product": {
    "id": 35,
    "name": "A Monetary Voucher",
    "object": "order-product",
    "status": "in_progress",
    "is_multiuse": true,
    "is_monetary": true,
    "redeemable_from": "2026-01-27T09:51:46+0000",
    "redeemable_to": "2027-01-27T09:51:46+0000",
    "redeem_stock": 5000,
    "redeem_used": 1500,
    "redeem_remaining": 3500,
    "redeemable_everywhere": false,
    "redeemable_on_redeem_locations": [
      7,
      8
    ],
    "redemptions": [
      {
        "id": 789354,
        "object": "redemption",
        "redeem_location": 7,
        "order_product": 35,
        "reductor": 1500,
        "created_at": "2026-03-02T12:15:00+0000"
      }
    ]
  }
}

Attribute	Type	Description
object Read Only	string, value = `voucher-status`	voucher status object identifier
voucher_code Read Only	string	The code of the voucher that was found
order_id Read Only	integer	ID of the Order the voucher was sold in
is_expired Read Only	boolean	`true` if the voucher can no longer be redeemed because its redeem period has ended
is_not_yet_redeemable Read Only	boolean	`true` if the redeem period of the voucher has not started yet
is_redeemed Read Only	boolean	`true` if nothing is left to redeem on the voucher
order_product Read Only	Product object	The voucher as sold in the order, with its balance (`redeem_stock`, `redeem_used`, `redeem_remaining`), its redeem period, its status and the list of its `redemptions`. For a multi-use monetary voucher (`is_multiuse` and `is_monetary` both `true`) `redeem_stock`, `redeem_used` and `redeem_remaining` are amounts in the smallest currency unit (`5000` = £50.00); for any other voucher they count uses. The example above is shortened; the full list of attributes is in The Product object

Retrieve a Voucher Status

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/voucher-status?voucher_code={VoucherCode}

Finds a voucher by its code and returns its balance, its redeem period and its redemptions. Nothing is redeemed.

Only vouchers sold by your account are found. A voucher whose order is not paid is not found.

The code is matched as in Create a Redemption, with one difference: when the sales page belongs to an organisation, a redemption also finds vouchers sold by the other accounts of the organisation, and this endpoint does not. For such a voucher it answers 404, although a redemption with the same voucher_code may succeed.

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/voucher-status?voucher_code=ABC1234" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
voucher_code Required	string	Query parameter, the code printed on the voucher

HTTP Response

Response example:

{
  "object": "voucher-status",
  "voucher_code": "ABC1234",
  "order_id": 18,
  "is_expired": false,
  "is_not_yet_redeemable": false,
  "is_redeemed": false,
  "order_product": {
    "id": 35,
    "object": "order-product",
    "...": "..."
  }
}

The Voucher Status object

Status	Meaning
200	The voucher was found
400	`voucher_code` is missing or longer than 255 characters
404	No paid voucher of your account has this code

VC Cards

A VC Card is a physical or digital VoucherCart card. It holds one or more tokens (for example the UID of an NFC chip), the vouchers loaded onto it and, once registered, its owner.

VC Cards must be enabled for your account. Otherwise every VC Card endpoint answers 401.

The VC Card object

The VC Card object example:

{
  "id": "6f1c2b9e-3d4a-4b8e-9a51-2c7d8e9f0a11",
  "object": "vc-card",
  "state": "inactive",
  "client_id": 123,
  "client_name": "Example Hotel",
  "created_at": "2026-09-14T10:21:05.000000Z",
  "vc_card_tokens": [
    {
      "type": "VcCardTokenNFC",
      "vc_card_uid": "04A1B2C3D4E5F6",
      "is_active": true
    }
  ],
  "products": [
    {
      "order_product_id": 985635
    }
  ],
  "state_reason": "Card reported lost",
  "owner": {
    "id": 4567,
    "full_name": "Jane Example",
    "email": "[email protected]",
    "phone": "+441234567890",
    "vc_promotions_enabled": false,
    "vcc_promotions_enabled": true
  }
}

Attribute	Type	Description
id Read Only	string	UUID of the card
object Read Only	string, value = `vc-card`	VC Card object identifier
state Read Only	string	`initial` - created, never activated; `active` - can be used; `inactive` - deactivated
client_id Read Only	integer	ID of the account the card belongs to
client_name Read Only	string	Name of the account the card belongs to
created_at Read Only	string	ISO 8601 date format
vc_card_tokens Read Only	array of VC Card Token objects	Tokens identifying the card, for example its NFC chip
products Expandable Read Only	array	Vouchers loaded onto the card. Each item is `{"order_product_id": ...}`, or a Product object when expanded (see Expanding Objects)
state_reason Read Only	string	Reason given when the card was deactivated. Present only when `state` is `inactive`
owner Read Only	VC Card Owner object	Present only when the card has an owner

The VC Card Token object

The VC Card Token object example:

{
  "type": "VcCardTokenNFC",
  "vc_card_uid": "04A1B2C3D4E5F6",
  "is_active": true
}

Attribute	Type	Description
type Read Only	string	Token type, for example `VcCardTokenNFC` for an NFC chip
vc_card_uid Read Only	string	Card number or NFC UID. Use it in the `vc_card_token_uid` filter of List all VC Cards
is_active Read Only	boolean

The VC Card Owner object

The VC Card Owner object example:

{
  "id": 4567,
  "full_name": "Jane Example",
  "email": "[email protected]",
  "phone": "+441234567890",
  "vc_promotions_enabled": false,
  "vcc_promotions_enabled": true
}

Attribute	Type	Description
id Read Only	integer
full_name	string
email	string
phone	string	Can be `null`
vc_promotions_enabled	boolean	The owner agreed to marketing from VoucherCart
vcc_promotions_enabled	boolean	The owner agreed to marketing from you

The VC Card Activity object

The VC Card Activity object example:

{
  "object": "vc-card-activity",
  "id": 30211,
  "vc_card_id": "6f1c2b9e-3d4a-4b8e-9a51-2c7d8e9f0a11",
  "created_by_name": "Front Desk",
  "created_by_email": "[email protected]",
  "admin_logged_as": null,
  "comment": "Card reported lost",
  "type": "Card Deactivated",
  "user_id": 812,
  "user_type": "jwt",
  "user_ip": "203.0.113.10",
  "created_at": "2026-10-02T09:12:44.000000Z"
}

Attribute	Type	Description
object Read Only	string, value = `vc-card-activity`	VC Card Activity object identifier
id Read Only	integer
vc_card_id Read Only	string	UUID of the card
created_by_name Read Only	string	Name of the user who made the change
created_by_email Read Only	string	Email of the user who made the change
admin_logged_as Read Only	string	Set when VoucherCart support made the change on your behalf, otherwise `null`
comment Read Only	string	Reason given for the change, if any
type Read Only	string	What happened: `Card Activated`, `Card Deactivated`, `Card Reactivated (active)` (reactivated, card has an owner), `Card Reactivated (initial)` (reactivated, card has no owner), `Card Activation Skipped`
user_id Read Only	integer	ID of the user who made the change
user_type Read Only	string	Who made the change: `client` (dashboard user), `jwt` (API), `buyer`, `vc_card_owner`, `pos_user`
user_ip Read Only	string	IP address the change was made from
created_at Read Only	string	ISO 8601 date format

List all VC Cards

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/vc-cards

Lists the cards of your account. When the sales page belongs to an organisation, the list also contains the cards of the other accounts in that organisation; client_id and client_name tell them apart. The other VC Card endpoints work only on cards of your own account and answer 404 for the rest.

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/vc-cards?vc_card_token_uid=04A1B2C3D4E5F6" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
vc_card_token_uid	string	Only the card with this card number or NFC UID
email	string	Only cards of the owner with this email address
order_product_id	integer	Only cards holding this voucher (Product ID)

Pagination parameters

See Pagination

Available order_by:

created_at

Expandables

See Expanding objects

Available expand[]:

products - each item becomes a Product object with these extra attributes: purchased_at, order_id, voucherCode, domain_name, is_paid

HTTP Response

Response example:

{
  "object": "list",
  "data": [
    {
      "id": "6f1c2b9e-3d4a-4b8e-9a51-2c7d8e9f0a11",
      "object": "vc-card",
      "state": "active",
      "client_id": 123,
      "client_name": "Example Hotel",
      "created_at": "2026-09-14T10:21:05.000000Z",
      "vc_card_tokens": [
        {
          "type": "VcCardTokenNFC",
          "vc_card_uid": "04A1B2C3D4E5F6",
          "is_active": true
        }
      ],
      "products": [
        {
          "order_product_id": 985635
        }
      ],
      "owner": {
        "id": 4567,
        "full_name": "Jane Example",
        "email": "[email protected]",
        "phone": "+441234567890",
        "vc_promotions_enabled": false,
        "vcc_promotions_enabled": true
      }
    }
  ],
  "count": 1,
  "previous": "eyJkaXIiOiJwcmV2aW91cyIsImN1cnNvciI6IjZmMWMyYjllLTNkNGEtNGI4ZS05YTUxLTJjN2Q4ZTlmMGExMSIsIm9yZGVyX2J5IjoidmMuY3JlYXRlZF9hdCIsIm9yZGVyIjoiREVTQyIsImxpbWl0IjoxMH0=",
  "has_previous": false,
  "next": "eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiNmYxYzJiOWUtM2Q0YS00YjhlLTlhNTEtMmM3ZDhlOWYwYTExIiwib3JkZXJfYnkiOiJ2Yy5jcmVhdGVkX2F0Iiwib3JkZXIiOiJERVNDIiwibGltaXQiOjEwfQ==",
  "has_next": false,
  "per_page": 10
}

List object containing VC Card objects

Retrieve a VC Card

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/vc-cards/{VcCardId}

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/vc-cards/6f1c2b9e-3d4a-4b8e-9a51-2c7d8e9f0a11" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
VcCardId Required	string	Path parameter, UUID of the card

Expandables

See Expanding objects

Available expand[]:

products - each item becomes a Product object with these extra attributes: purchased_at, order_id, voucherCode, domain_name, is_paid

HTTP Response

Response example:

{
  "id": "6f1c2b9e-3d4a-4b8e-9a51-2c7d8e9f0a11",
  "object": "vc-card",
  "state": "active",
  "client_id": 123,
  "client_name": "Example Hotel",
  "created_at": "2026-09-14T10:21:05.000000Z",
  "vc_card_tokens": [
    {
      "type": "VcCardTokenNFC",
      "vc_card_uid": "04A1B2C3D4E5F6",
      "is_active": true
    }
  ],
  "products": [
    {
      "order_product_id": 985635
    }
  ],
  "owner": {
    "id": 4567,
    "full_name": "Jane Example",
    "email": "[email protected]",
    "phone": "+441234567890",
    "vc_promotions_enabled": false,
    "vcc_promotions_enabled": true
  }
}

The VC Card object. Code 404 when the card does not exist or belongs to another account.

List VC Card activity

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/vc-cards/{VcCardId}/activity

History of one card: activations, deactivations, product changes and similar events, oldest first.

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/vc-cards/6f1c2b9e-3d4a-4b8e-9a51-2c7d8e9f0a11/activity?limit=25" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
VcCardId Required	string	Path parameter, UUID of the card
limit	integer	Page size, default `10`, min: 1 max: 50
cursor	string	Cursor to the next or previous page, taken from the previous response

HTTP Response

Response example:

{
  "object": "list",
  "data": [
    {
      "object": "vc-card-activity",
      "id": 30210,
      "vc_card_id": "6f1c2b9e-3d4a-4b8e-9a51-2c7d8e9f0a11",
      "created_by_name": "Front Desk",
      "created_by_email": "[email protected]",
      "admin_logged_as": null,
      "comment": null,
      "type": "Card Activated",
      "user_id": 812,
      "user_type": "jwt",
      "user_ip": "203.0.113.10",
      "created_at": "2026-09-14T10:21:05.000000Z"
    },
    {
      "object": "vc-card-activity",
      "id": 30211,
      "vc_card_id": "6f1c2b9e-3d4a-4b8e-9a51-2c7d8e9f0a11",
      "created_by_name": "Front Desk",
      "created_by_email": "[email protected]",
      "admin_logged_as": null,
      "comment": "Card reported lost",
      "type": "Card Deactivated",
      "user_id": 812,
      "user_type": "jwt",
      "user_ip": "203.0.113.10",
      "created_at": "2026-10-02T09:12:44.000000Z"
    }
  ],
  "per_page": 25,
  "previous": null,
  "has_previous": false,
  "next": null,
  "has_next": false
}

List of VC Card Activity objects. Code 404 when the card does not exist or belongs to another account.

Deactivate a VC Card

POST https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/vc-cards/{VcCardId}/deactivate

Blocks the card, for example when it is lost or stolen. The card state becomes inactive and the reason is saved in the card activity. If the card has an owner, we email the owner to confirm. Deactivating a card that is already inactive changes nothing.

Requires the manage.orders permission, otherwise the response is 401.

HTTP Request

Request example:

curl -X POST 'https://api.vouchercart.com/v2.1/sales-pages/1337/vc-cards/6f1c2b9e-3d4a-4b8e-9a51-2c7d8e9f0a11/deactivate' \
  -H 'Authorization: Bearer JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary '
  {
    "reason": "Card reported lost"
  }
'

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
VcCardId Required	string	Path parameter, UUID of the card

Request body

Attribute	Type	Description
reason Required	string	Why the card is blocked. Saved in the card activity and shown to the owner

HTTP Response

Successful response (code 204) has no body. Code 400 when reason is missing, 404 when the card does not exist or belongs to another account.

Activate a VC Card

POST https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/vc-cards/{VcCardId}/activate

Activates or reactivates the card, depending on its current state:

initial - first activation, the card becomes active.
inactive - reactivation. The reason is saved in the card activity. If the card has an owner, the card becomes active and we email the owner. If the card has no owner, it goes back to initial; assign an owner to make it active.
active - nothing changes.

Requires the vccard.reactivate permission, otherwise the response is 401.

HTTP Request

Request example:

curl -X POST 'https://api.vouchercart.com/v2.1/sales-pages/1337/vc-cards/6f1c2b9e-3d4a-4b8e-9a51-2c7d8e9f0a11/activate' \
  -H 'Authorization: Bearer JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary '
  {
    "reason": "Card found by the guest",
    "confirmation": true
  }
'

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
VcCardId Required	string	Path parameter, UUID of the card

Request body

Attribute	Type	Description
reason Required	string	Why the card is reactivated. Saved in the card activity. Required in every request, but ignored on a first activation
confirmation Required	boolean	Must be `true`

HTTP Response

Successful response (code 204) has no body, also when the card was already active. Code 400 when reason or confirmation is missing or invalid, 404 when the card does not exist or belongs to another account.

Assign an owner to a VC Card

POST https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/vc-cards/{VcCardId}/owner

Registers the card to a person and activates the card. If an owner with this email already exists, we update their name, phone and marketing choices with the values sent; otherwise we create a new owner. When vcc_promotions_enabled is true, we also add the owner to your default newsletter list.

The card must not be inactive. To register a deactivated card, activate it first.

HTTP Request

Request example:

curl -X POST 'https://api.vouchercart.com/v2.1/sales-pages/1337/vc-cards/6f1c2b9e-3d4a-4b8e-9a51-2c7d8e9f0a11/owner' \
  -H 'Authorization: Bearer JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary '
  {
    "full_name": "Jane Example",
    "email": "[email protected]",
    "phone": "+441234567890",
    "vc_promotions_enabled": false,
    "vcc_promotions_enabled": true
  }
'

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
VcCardId Required	string	Path parameter, UUID of the card

Request body

Attribute	Type	Description
full_name Required	string	Max 255 characters
email Required	string	Email address, max 255 characters
phone	string
vc_promotions_enabled	boolean	Marketing from VoucherCart. Default `false`
vcc_promotions_enabled	boolean	Marketing from you. Default `false`

HTTP Response

Successful response (code 204) has no body. Code 400 with message Card already has a owner when the card is registered to someone else, 404 when the card does not exist or belongs to another account.

Sales Pages

A Sales Page is a merchant's voucher shop (also called a domain). Its ID is the SalesPageId used in many paths.

The Sales Page object

The Sales Page object example:

{
  "id": 1,
  "object": "sales-page",
  "name": "test-company",
  "company": {
    "name": "Test Company Name"
  },
  "address": {
    "address_line1": "Mayfair Lane",
    "address_line2": "",
    "city": "London",
    "postcode": "W1K W1J",
    "hide_address": false,
    "latitude": "51.508333099999990",
    "longitude": "-0.154718900000000"
  },
  "contact": {
    "phone": "01234567890",
    "hide_phone": false,
    "email": "[email protected]",
    "hide_email": false,
    "website": "https://test.example.com",
    "hide_website": false
  },
  "social_media": {
    "facebook": "https://www.facebook.com/example/",
    "twitter": "https://x.com/example",
    "instagram": "https://www.instagram.com/example",
    "linkedin": "https://linkedin.com/in/example"
  },
  "payment_gateways": [
    3,
    9,
    10
  ],
  "organisation": null,
  "organisation_sale_container": null,
  "skin": 2,
  "reseller_hash": null
}

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `sales-page`	sales page object identifier
name	string
company	Company hash
address	Address hash
contact	Contact hash
social_media	Social Media hash
payment_gateways Expandable Read Only	array	array of Payment Gateway IDs, or of Payment Gateway objects when expanded with `expand[]=payment_gateways` (see Expanding objects)
organisation Read Only	string or null	ID of the Organisation the Sales Page belongs to; when there is none, the same value as `organisation_sale_container`
organisation_sale_container Read Only	string or null	ID of the Organisation whose sale container the Sales Page belongs to
skin Expandable Read Only	integer or Skin object	Skin ID, or the Skin object when expanded with `expand[]=skin` (see Expanding objects)
reseller_hash Read Only	string or null	related Reseller hash

The Address hash

The Address hash example:

{
  "address_line1": "Mayfair Lane",
  "address_line2": "",
  "city": "London",
  "postcode": "W1K W1J",
  "hide_address": false,
  "latitude": "51.508333099999990",
  "longitude": "-0.154718900000000"
}

Attribute	Type	Description
address_line1	string
address_line2	string
city	string
postcode	string
hide_address	boolean
latitude	string
longitude	string

The Company hash

The Company hash example:

{
  "name": "Test Company Name"
}

Attribute	Type	Description
name	string

The Contact hash

The Contact hash example:

{
  "phone": "01234567890",
  "hide_phone": false,
  "email": "[email protected]",
  "hide_email": false,
  "website": "https://test.example.com",
  "hide_website": false
}

Attribute	Type	Description
phone	string
hide_phone	boolean
email	string
hide_email	boolean
website	string
hide_website	boolean

The Social Media hash example:

{
  "facebook": "https://www.facebook.com/example/",
  "twitter": "https://x.com/example",
  "instagram": "https://www.instagram.com/example",
  "linkedin": "https://linkedin.com/in/example"
}

Attribute	Type	Description
facebook	string
twitter	string
instagram	string
linkedin	string

The Skin object

The Skin object example:

{
  "id": 1,
  "object": "skin",
  "main_color": "#8f8f8f",
  "buy_color": "#a3a3a3",
  "background_color": "#ffffff",
  "header": {
    "en": "Welcome to our gift shop"
  },
  "header_font_size": 40,
  "header_line_height": 1.2,
  "header_link_color": "#ffffff",
  "header_background_color": "#1f1f1f",
  "header_background_color_opacity": 100,
  "header_text_font": "joehand2",
  "header_text_color": "#ffffff",
  "header_image_mask_opacity": 40,
  "header_image_mask_color": "#000000",
  "header_image_bottom_shape": "curve-asym-opacity",
  "header_image_bottom_shape_height": 75,
  "logo": "https://images.vouchercart.com/clients/842e2ae4e1911a96a31bfd59c9cabdfc/1204ca9471c74301662dd897b5444d86.png",
  "footer_logo": "https://images.vouchercart.com/clients/842e2ae4e1911a96a31bfd59c9cabdfc/1204ca9471c74301662dd897b5444d86.png",
  "footer_color": "#1f1f1f",
  "header_image": "https://images.vouchercart.com/clients/842e2ae4e1911a96a31bfd59c9cabdfc/4cca9423a5cae432ddf071a0d7cd0774.jpg",
  "logo_alt": "https://images.vouchercart.com/clients/842e2ae4e1911a96a31bfd59c9cabdfc/137af39db364e563ab94eb3cdaab75d9.png",
  "logo_position": "center",
  "logo_size": "normal",
  "top_banner_displayed": false,
  "featured_voucher_overlapped_on_header_image": false,
  "top_banner_background_color": "#e67e22",
  "top_subnav_displayed": false,
  "top_subnav_background_color": "#f0f0f0",
  "num_of_columns": 3,
  "font_primary": "Open Sans",
  "font_secondary": "Open Sans",
  "header_border_displayed": false,
  "available_languages": [
    "en"
  ],
  "menu_position": "horizontal",
  "favicon": "",
  "remaining_quantity_background_color": "#e67e22",
  "remaining_quantity_text_color": "#ffffff",
  "days_to_show_voucher_end_sale_counter": 30,
  "vrm_background_image": null,
  "vrm_background_color": "#ffffff",
  "vrm_content_bg_color": "#ffffff",
  "vrm_header_bg_color": "#1f1f1f",
  "vrm_primary_color": "#8f8f8f",
  "vrm_privacy_policy_url": null,
  "vrm_terms_and_conditions_url": null
}

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `skin`	Skin object identifier
main_color	string	HEX color code incl. `#`
buy_color	string	HEX color code incl. `#`
background_color	string	HEX color code incl. `#`
header	Translation hash	Header text
header_font_size	integer	Min: 0, Max: 100
header_line_height	number	Min: 0, Max: 100
header_link_color	string	HEX color code incl. `#`
header_background_color	string	HEX color code incl. `#`
header_background_color_opacity	integer	Min: 0, Max: 100
header_text_font	string
header_text_color	string	HEX color code incl. `#`
header_image_mask_opacity	integer	Min: 0, Max: 100
header_image_mask_color	string	HEX color code incl. `#`
header_image_bottom_shape	string
header_image_bottom_shape_height	integer
logo	string	Image URL
footer_logo	string	Image URL
footer_color	string	HEX color code incl. `#`
header_image	string	Image URL
logo_alt	string	Image URL
logo_position	enum: `left`, `center`
logo_size	enum: `extra_small`, `small`, `normal`, `large`, `extra_large`
top_banner_displayed	boolean
featured_voucher_overlapped_on_header_image	boolean
top_banner_background_color	string	HEX color code incl. `#`
top_subnav_displayed	boolean
top_subnav_background_color	string	HEX color code incl. `#`
num_of_columns	integer
font_primary	string
font_secondary	string
header_border_displayed	boolean
available_languages	array	array of ISO 639-1:2002 Locale Codes, e.g. `en`
menu_position	enum: `vertical`, `horizontal`
favicon	string	Image URL, empty when not set
remaining_quantity_background_color	string	HEX color code incl. `#`
remaining_quantity_text_color	string	HEX color code incl. `#`
days_to_show_voucher_end_sale_counter	integer	Number of days before the end of a voucher's sale from which a countdown is shown
vrm_background_image	string or null	Image URL. The `vrm_*` attributes style the room booking (VRM) pages
vrm_background_color	string	HEX color code incl. `#`; falls back to `background_color`
vrm_content_bg_color	string	HEX color code incl. `#`; falls back to `background_color`
vrm_header_bg_color	string	HEX color code incl. `#`; falls back to `header_background_color`
vrm_primary_color	string	HEX color code incl. `#`; falls back to `main_color`
vrm_privacy_policy_url	string or null	URL
vrm_terms_and_conditions_url	string or null	URL

Reports

Orders Export

GET https://api.vouchercart.com/v2.1/reports/orders-export?start_date={StartDate}&end_date={EndDate}

Every voucher ordered on any of your sales pages between start_date and end_date, one row per voucher. It is the same report as the orders CSV export in the dashboard, returned as JSON.

Requires a token of a signed-in user of your account. A guest token gets 401.

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/reports/orders-export?start_date=2021-06-01T00%3A00%3A00%2B00%3A00&end_date=2021-06-30T23%3A59%3A59%2B00%3A00&include_redeemed=0" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
start_date Required	string	ISO 8601 date string ex. `2019-08-19T11:00:39Z`
end_date Required	string	ISO 8601 date string ex. `2019-08-19T11:00:39Z`
include_refunded_or_cancelled	boolean	`1` or `0`. Default: `1`
include_not_refunded_or_cancelled	boolean	`1` or `0`. Default: `1`
include_redeemed	boolean	`1` or `0`. Default: `1`
include_partially_redeemed	boolean	`1` or `0`. Default: `1`
include_not_redeemed	boolean	`1` or `0`. Default: `1`
expired_only	boolean	`1` or `0`. Default: `0`. Cannot be `1` together with `not_expired_only`
not_expired_only	boolean	`1` or `0`. Default: `0`. Cannot be `1` together with `expired_only`

In the query string, send the boolean parameters as 1 or 0. The words true and false are rejected with 400.

HTTP Response

Response example:

[
  {
    "Order ID": "2-AVR-1GB-1",
    "Voucher ID": "2",
    "Voucher Code": "YNNNG8",
    "Status": "In Progress",
    "Voucher Title": "Custom voucher: Meal for two",
    "Voucher Description": "Custom desc",
    "Price paid, £": "100.00",
    "Regular price, £": "100.00",
    "Voucher Liability": "100.00",
    "Discount Value": "0.00",
    "Discount Name": "",
    "Discount Type": "",
    "Discount Code": "",
    "Sales Channel": "Online",
    "Check Number": "-",
    "Sold as": "Standard Sale",
    "Charity": "No",
    "Complimentary\/Free": "No",
    "Manual Payment Type": "",
    "Manual Payment Reference": "",
    "Manual Payment User Full Name": "",
    "Redeemed": "0",
    "Last Redeem Date": "",
    "Last Redeemed By": "",
    "Monetary Total Value, £": "100",
    "Monetary Remaining Value, £": "100",
    "Monetary Redeemed Value, £": "0",
    "Total Units": "1",
    "Remaining Units": "1",
    "Redeemed Units": "0",
    "Multiple Use": "0",
    "Customer Name": "Buyer Name",
    "Customer Email": "[email protected]",
    "Customer Phone": "",
    "Customer Address": "",
    "Delivery type": "postal",
    "Delivery price": "10.00",
    "Collection Fee": "",
    "Was Sent To": "buyer",
    "Recipient name": "",
    "Recipient email": "",
    "Voucher Message": "Happy birthday\nMy dear friend!",
    "Order Date": "01\/07\/2021 10:25",
    "Redeemable from": "01\/07\/2021 10:25",
    "Redeemable to": "01\/07\/2022 10:25",
    "Subdomain": "client1",
    "Card Number": "",
    "Payment Gateway": "Stripe",
    "Payment Reference": "pi_3PZx2kAoRqCdB7Ak0f1gH2iJ",
    "Payment Reference Url": "https:\/\/dashboard.stripe.com\/payments\/pi_3PZx2kAoRqCdB7Ak0f1gH2iJ",
    "Internal note": "",
    "Buyer consent to promotions": "1",
    "Stripe Payout Id": "",
    "Stripe Payout Initiated At": "",
    "Stripe Payout Estimated Arrival Date": "",
    "Stripe Payout Amount": "",
    "Stripe Payout Link": "",
    "Tax name (1)": "VAT",
    "Tax amount (1), £": "16.67",
    "Service Fee, £": "1.50"
  },
  {
    "Order ID": "2-AVR-1GB-2",
    "Voucher ID": "3",
    "Voucher Code": "ZNNN7Y",
    "Status": "In Progress",
    "Voucher Title": "Fixed voucher: Meal for two",
    "Voucher Description": "Fixed desc",
    "Price paid, £": "50.00",
    "Regular price, £": "50.00",
    "Voucher Liability": "50.00",
    "Discount Value": "0.00",
    "Discount Name": "",
    "Discount Type": "",
    "Discount Code": "",
    "Sales Channel": "Online",
    "Check Number": "-",
    "Sold as": "Standard Sale",
    "Charity": "No",
    "Complimentary\/Free": "No",
    "Manual Payment Type": "",
    "Manual Payment Reference": "",
    "Manual Payment User Full Name": "",
    "Redeemed": "0",
    "Last Redeem Date": "",
    "Last Redeemed By": "",
    "Monetary Total Value, £": "50",
    "Monetary Remaining Value, £": "50",
    "Monetary Redeemed Value, £": "0",
    "Total Units": "1",
    "Remaining Units": "1",
    "Redeemed Units": "0",
    "Multiple Use": "0",
    "Customer Name": "Buyer Name",
    "Customer Email": "[email protected]",
    "Customer Phone": "",
    "Customer Address": "",
    "Delivery type": "electronic",
    "Delivery price": "",
    "Collection Fee": "",
    "Was Sent To": "recipient",
    "Recipient name": "",
    "Recipient email": "[email protected]",
    "Voucher Message": "Happy birthday\nMy dear friend!",
    "Order Date": "01\/07\/2021 10:25",
    "Redeemable from": "01\/07\/2021 10:25",
    "Redeemable to": "01\/07\/2022 10:25",
    "Subdomain": "client1",
    "Card Number": "",
    "Payment Gateway": "Stripe",
    "Payment Reference": "pi_3PZx2kAoRqCdB7Ak0f1gH2iJ",
    "Payment Reference Url": "https:\/\/dashboard.stripe.com\/payments\/pi_3PZx2kAoRqCdB7Ak0f1gH2iJ",
    "Internal note": "",
    "Buyer consent to promotions": "0",
    "Stripe Payout Id": "",
    "Stripe Payout Initiated At": "",
    "Stripe Payout Estimated Arrival Date": "",
    "Stripe Payout Amount": "",
    "Stripe Payout Link": "",
    "Tax name (1)": "VAT",
    "Tax amount (1), £": "8.33",
    "Service Fee, £": "1.50"
  }
]

An array of rows. Each row is an object keyed by the column names of the CSV export, and every value is a string. Money values are in major units ("100.00", not 10000).

The currency symbol in the column names (£ above) is the sale currency of your account, for example Price paid, €.
Delivery price is filled for postal delivery, Collection Fee for collection.
Check Number is the check number of an order placed through a Simphony POS, otherwise -.
Buyer consent to promotions is "1" or "0".
The five Stripe Payout … columns are present only when your account has an active Stripe payment gateway.
Tax name (n) and Tax amount (n), £ are present when the orders in the report have taxes, one pair for each tax, up to the largest number of taxes on one order. A row with fewer taxes has empty values in the extra columns.
A service fee column is present when an order in the report has a service fee. It is named after the fee (Service Fee, £ when it has no name) and holds the order's fee split equally between the order's products.

Refunds Report

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/reports/refunds

Requires the manage.products.refund permission, otherwise the response is 401.

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/reports/refunds" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)

Pagination parameters

See Pagination

Available order_by:

created_at

Expandables

See Expanding objects

Available expand[]:

product
order
order.payments

HTTP Response

Response example:

{
  "object": "list",
  "data": [
    {
      "id": 27784,
      "object": "refund",
      "total": {
        "amount": 1999,
        "currency": "GBP"
      },
      "product": 32,
      "order": 18,
      "created_by": "Jon Smith",
      "created_at": "2019-10-14T08:43:21+0000",
      "reason": "Reasonable refund reason",
      "through_payment_gateway": true,
      "gateway": "Stripe",
      "gateway_name": "Stripe",
      "gateway_refund_status": "completed",
      "gateway_refund_transaction_id": "ch_1FTP98AoRqCdB7Aku4oi7Xgd"
    }
  ],
  "count": 1,
  "previous": "eyJkaXIiOiJwcmV2aW91cyIsImN1cnNvciI6IjIiLCJvcmRlcl9ieSI6Im92ci5jcmVhdGVkX2F0Iiwib3JkZXIiOiJERVNDIiwibGltaXQiOjEwfQ==",
  "has_previous": false,
  "next": "eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiMiIsIm9yZGVyX2J5Ijoib3ZyLmNyZWF0ZWRfYXQiLCJvcmRlciI6IkRFU0MiLCJsaW1pdCI6MTB9",
  "has_next": false,
  "per_page": 10
}

List object containing Refund objects. Each refund also carries gateway_name, which holds the same value as gateway.

Webhooks

Webhooks resource

The Webhook object

The Webhook object example:

{
  "id": 1,
  "object": "sales-page-webhook",
  "url": "https://www.example.com/webhooks/vouchercart",
  "secret": null,
  "enabled_events": [
    "order.created"
  ],
  "description": "Webhook description",
  "active": true,
  "last_used_at": "2021-10-08T06:26:56.000000Z"
}

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `sales-page-webhook`	sales-page-webhook object identifier
url Required	string	URL the events are sent to. It must point at the public internet. A URL without `http://` or `https://` is saved with `http://`.
secret	string or null	Adds a header called `Signature`, which the receiving app can use to check that the payload has not been tampered with. The signature is the HMAC-SHA256 of the raw request body, keyed with the secret, as a lowercase hex string. Without a secret the header is not sent.
enabled_events Required	array	Names of the events to send, any of: `order.created`, `order-product.redeemed`, `order-product.redeem_cancelled`, `order-product.refunded`, `order-product.cancelled`, `order-product.regenerated`, `order-product.expiration_changed`. See The Event object.
description	string	Empty when left out of a create or update request.
active	boolean	Only active webhooks are sent events. `false` when left out of a create or update request.
last_used_at Read Only	string or null	ISO 8601 date format

Delivery and retries

Events are sent as a POST with a JSON body. Any 2xx response counts as delivered. Any other status, or no response within 3 seconds, counts as a failure, and the event is sent again: 3 attempts in total, the second about 10 seconds after the first and the third about 100 seconds after the second. After the third failure the event is not sent again.

Answer with 200 as soon as the event is received and process it afterwards, so that slow processing does not hit the 3-second limit. Past deliveries are listed by Webhook history.

The Event object

The Event object example:

{
  "id": "00bbbb71-563e-4542-a1d8-49481ed41f85",
  "object": "event",
  "name": "order.created",
  "created_at": "2021-10-08 06:26:56",
  "sales_page_id": 1337,
  "data": {
    "id": 18,
    "object": "order",
    "language": "en",
    "purchaser": {
      "name": "John Doe",
      "email": "[email protected]",
      "phone": ""
    },
    "reference": "813713-WRB-1335GB",
    "products": [
      {
        "id": 423664,
        "object": "order-product"
      }
    ],
    "deliveries": [],
    "payments": [4389],
    "is_manual_order": false,
    "created_at": "2019-08-19T11:00:39Z",
    "buyer_consent_to_promotion_offers": false
  }
}

The example is shortened: data holds the full Order object, and each entry of products the full Product object.

An Event is the JSON body of a webhook request.

Attribute	Type	Description
id Read Only	string	UUID of the event
object Read Only	string, value = `event`	event identifier
name Read Only	string	Event name, see the table below
created_at Read Only	string	Date and time in UTC, format `YYYY-MM-DD HH:MM:SS`
sales_page_id Read Only	integer	ID of the Sales Page the webhook belongs to
data Read Only	object	Order object or Product object, see the table below

Event name	Sent when	`data`
`order.created`	an order has been paid (unpaid orders are not sent)	Order object with `products` expanded
`order-product.redeemed`	a voucher has been redeemed	Product object with an extra `redemption` attribute holding the Redemption object
`order-product.redeem_cancelled`	a redemption has been cancelled	Product object with an extra `redemption` attribute holding the Redemption object
`order-product.refunded`	a voucher has been refunded	Product object
`order-product.cancelled`	a voucher has been cancelled	Product object
`order-product.regenerated`	a voucher has been regenerated	Product object of the voucher after regeneration
`order-product.expiration_changed`	the expiry date of a voucher has changed	Product object

List all webhooks

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/webhooks

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/webhooks" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)

HTTP Response

Response example:

[
  {
    "id": 18,
    "object": "sales-page-webhook",
    "url": "https://www.example.com/webhooks/vouchercart",
    "secret": null,
    "enabled_events": [
      "order.created"
    ],
    "description": "Webhook description",
    "active": true,
    "last_used_at": "2021-10-08T06:26:56.000000Z"
  }
]

A plain array of Webhook objects. This list is not paginated.

Retrieve Webhook

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/webhooks/{WebhookId}

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/webhooks/18" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
WebhookId Required	integer	Path parameter

HTTP Response

Response example:

  {
    "id": 18,
    "object": "sales-page-webhook",
    "url": "https://www.example.com/webhooks/vouchercart",
    "secret": null,
    "enabled_events": [
      "order.created"
    ],
    "description": "Webhook description",
    "active": true,
    "last_used_at": "2021-10-08T06:26:56.000000Z"
  }

The Webhook object. A webhook that does not exist on the Sales Page returns 404.

Create Webhook

POST https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/webhooks

HTTP Request

Request example:

curl -X POST 'https://api.vouchercart.com/v2.1/sales-pages/1337/webhooks' \
  -H 'Authorization: Bearer JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary '
    {
        "url": "https://www.example.com/webhooks/vouchercart",
        "secret": null,
        "enabled_events": [
            "order.created"
        ],
        "description": "Webhook description",
        "active": true
    }
'

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)

Request body

Webhook object without the read-only attributes. url and enabled_events are required. When left out, description is saved empty and active as false, so the webhook is not sent any events.

HTTP Response

Successful response: code 204, with no body. Use List all webhooks to find the ID of the new webhook.

Update Webhook

PUT https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/webhooks/{WebhookId}

HTTP Request

Request example:

curl -X PUT 'https://api.vouchercart.com/v2.1/sales-pages/1337/webhooks/18' \
  -H 'Authorization: Bearer JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary '
    {
        "url": "https://www.example.com/webhooks/vouchercart",
        "secret": null,
        "enabled_events": [
            "order.created"
        ],
        "description": "Webhook description",
        "active": true
    }
'

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
WebhookId Required	integer	Path parameter

Request body

Webhook object without the read-only attributes. The update replaces the whole webhook: url and enabled_events are required, and a description or active left out is saved as empty or false. Send every attribute on each update.

HTTP Response

Successful response: code 204, with no body. A webhook that does not exist on the Sales Page returns 404.

Delete Webhook

DELETE https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/webhooks/{WebhookId}

HTTP Request

Request example:

curl -X DELETE "https://api.vouchercart.com/v2.1/sales-pages/1337/webhooks/18" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
WebhookId Required	integer	Path parameter

HTTP Response

Successful response: code 204, with no body. A webhook that does not exist on the Sales Page returns 404.

Webhook history

GET https://api.vouchercart.com/v2.1/sales-pages/{SalesPageId}/webhooks/{WebhookId}/history

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/webhooks/18/history" \
  -H "Authorization: Bearer JWT_TOKEN"

Parameter	Type	Description
SalesPageId Required	integer	Path parameter, Sales Page ID (a.k.a. Domain ID)
WebhookId Required	integer	Path parameter

HTTP Response

Response example:

[
  {
    "id": "a5b4cd7c-124c-499e-8a5a-fe9975c29387",
    "object": "sales-page-webhook-history",
    "http_verb": "post",
    "url": "https:\/\/webhook.example.com\/1da9916e-282d-4fd9-9ebc-730d0989a6c3",
    "payload": {
      "id": "a5b4cd7c-124c-499e-8a5a-fe9975c29387",
      "object": "event",
      "name": "order.created",
      "created_at": "2021-10-08 09:03:26",
      "sales_page_id": 1337,
      "data": {
        "id": 16,
        "object": "order",
        "language": "en",
        "purchaser": {
          "name": "Faye Khan",
          "email": "[email protected]",
          "phone": "+441234567890"
        },
        "reference": "19-PG5-1GB",
        "products": [
          {
            "id": 26,
            "object": "order-product"
          }
        ],
        "deliveries": [],
        "payments": [
          16
        ],
        "is_manual_order": false,
        "created_at": "2021-10-08T09:03:20+0000",
        "buyer_consent_to_promotion_offers": false
      }
    },
    "response": null,
    "response_status": null,
    "created_at": "2021-10-08T09:05:27.000000Z"
  },
  {
    "id": "b1944b38-a5ec-489e-9079-3401ee9a0848",
    "object": "sales-page-webhook-history",
    "http_verb": "post",
    "url": "https:\/\/webhook.example.com\/1da9916e-282d-4fd9-9ebc-730d0989a6c3",
    "payload": {
      "id": "b1944b38-a5ec-489e-9079-3401ee9a0848",
      "object": "event",
      "name": "order.created",
      "created_at": "2021-10-08 08:59:03",
      "sales_page_id": 1337,
      "data": {
        "id": 15,
        "object": "order",
        "language": "en",
        "purchaser": {
          "name": "Phoebe Scott",
          "email": "[email protected]",
          "phone": "01234567890"
        },
        "reference": "16-GMF-1GB",
        "products": [
          {
            "id": 25,
            "object": "order-product"
          }
        ],
        "deliveries": [],
        "payments": [
          15
        ],
        "is_manual_order": false,
        "created_at": "2021-10-08T08:58:57+0000",
        "buyer_consent_to_promotion_offers": false
      }
    },
    "response": [],
    "response_status": "200",
    "created_at": "2021-10-08T08:59:16.000000Z"
  }
]

The example is shortened: each payload holds the full Event object.

A plain array of webhook history entries, newest first. There is one entry per event, written once the event has been delivered or after its last attempt has failed (see Delivery and retries). This list is not paginated.

Attribute	Type	Description
id	string	UUID of the event, the same as `payload.id`
object	string, value = `sales-page-webhook-history`	webhook history identifier
http_verb	string	HTTP method used, `post`
url	string	URL the event was sent to
payload	object	Event object that was sent
response	array or null	Does not hold the response body: an empty array when a response was received, otherwise `null`
response_status	string or null	HTTP status code of the response; `null` when no response was received
created_at	string	ISO 8601 date format

Introduction

Authentication

Get JWT Token

HTTP Request

HTTP Response

The Profile object

Refresh token

HTTP Request

HTTP Response

Responses

Expanding objects

Pagination

The List object

First call

HTTP Request

HTTP Response

Subsequent calls

HTTP Request

HTTP Response

Common objects

The Money hash

The Translation hash

Categories

The Category object

List all Categories

HTTP Request

Pagination parameters

HTTP Response

Redeem Locations

The Redeem Location object

List all Redeem Locations

HTTP Request

Pagination parameters

HTTP Response

Vouchers

The Voucher object

The Layout object

The Display Options hash

The Voucher Option object

The Shipping Method hash

The Shipping Method Calculator hash

List all Vouchers

HTTP Request

Pagination parameters

Expandables

HTTP Response

Retrieve a Voucher

HTTP Request

Expandables

HTTP Response

Orders

The Order object

The Purchaser hash

The Product object

The Recipient object

The Shipping Address object

The Delivery object

The Payment object

The Refund object

Create an Order

HTTP Request

Request body

HTTP Response

Retrying safely with external_reference

Record a Manual Payment

HTTP Request

HTTP Response

List all Orders

HTTP Request

Pagination parameters

Expandables

HTTP Response

Retrieve an Order

HTTP Request

Expandables

HTTP Response

Refund a Product

HTTP Request

HTTP Response

Cancel a Product

Retrying safely with `external_reference`