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": "VoucherCart2 Demo",
    "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	Look for Profile Object section for more details
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	string	A JWT token supposed to expired (or 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 will slightly change with each /refresh request (they are rotating). In the next refresh request you cannot use refreshToken which have been already used.

Parameter	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
400 - Bad Request
401 - Unauthorized
402 - Request Failed
404 - Not Found
409 - Conflict
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.

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. This parameter is available on all API requests, and applies to the response of that request only.

Pagination

VoucherCart API v2.1 uses cursor based pagination. Only first API call fetching an index of resource has to specify parameters like order_by, order, limit etc. Responses to index resources contain cursors which allow to fetch next/previous pages.

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
}

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	string	true if the next page is not empty at the time of response

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
}

List object

Subsequent calls

Subsequent calls has to use the cursor returned by the first/previous call to retrieve next or previous page.

When cursor parameter provided other pagination parameters like order_by or limit will be ignored.

HTTP Request

Pagination first 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 (eg cents)
currency	string	ISO 4217 Currency Code, ex. `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 ex. `en`
value	string	Translated text

Redeem Locations

Vouchers resource

The Redeem Location object

The Redeem Location object example:

{
  "id": 786322,
  "object": "redeem_location",
  "name": "Adara Hotel",
  "address": "Adara Hotel, 302 George Street, Edinburgh, EH2 3TY",
  "city": "Edinburgh",
  "region": null,
  "latitude": "55.952910",
  "longitude": "-3.200390"
}

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `redeem_location`	redeem location object identifier
name Required	string
address Required	string
city	string
region	string
latitude	string
longitude	string

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"

Pagination parameters

See Pagination

Available order_by:

created_at

HTTP Response

Response example:

{
  "object": "list",
  "data": [
    {
      "id": 786322,
      "object": "redeem_location",
      "name": "Adara Hotel",
      "address": "Adara Hotel, 302 George Street, Edinburgh, EH2 3TY"
    },
    {
      "id": 789912,
      "object": "redeem_location",
      "name": "Mayfair Demo Hotel",
      "address": "Mayfair Demo Hotel, Mayfair Lane, London, W1K W1J"
    }
  ],
  "count": 2,
  "previous": "eyJkaXIiOiJwcmV2aW91cyIsImN1cnNvciI6IjIiLCJvcmRlcl9ieSI6InJsLmNyZWF0ZWRfYXQiLCJvcmRlciI6IkRFU0MiLCJsaW1pdCI6MTB9",
  "has_previous": false,
  "next": "eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiMSIsIm9yZGVyX2J5IjoicmwuY3JlYXRlZF9hdCIsIm9yZGVyIjoiREVTQyIsImxpbWl0IjoxMH0=",
  "has_next": false
}

List object containing Redeem Location objects

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": true,
  "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`, `VCCVCard`
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
quantity	integer
sold	integer
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, available only if `sale_period_is_unlimited` = `true`
sale_period_to	string	ISO 8601 date format, available only if `sale_period_is_unlimited` = `true`
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_cart\\_application\\_query\\_voucher\\_voucher_layout_data",
  "image": "https://images.vouchercart.com/assets/XXXXXXXX.png"
}

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `voucher_cart\_application\_query\_voucher\_voucher_layout_data`	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
description	Translation hash
quantity	integer
quantity_weight	integer
sold	integer
sold_out	boolean
sell_price	Money hash
leaf	boolean
level	integer
real_value	Money hash
display_price	Money hash
max_sell_price	Money hash
redeem_stock	integer
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

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}

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,
  "sales_page_name": 'sales_page'
}

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
discount_urls Write Only	array	array of strings
is_paid Write Only	boolean	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.
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
sales_page_name Read Only	string

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
  ],
}

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": "123-74",
    "county": "",
    "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
  ],
}

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`
price_paid_calculator	enum: `regular`, `free`, `charity`, `vc_card_voucher`	Default: `regular`
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	Required if `delivery_method` = `postal`
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`
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	How many redeems are possible for this voucher (`1` if `is_multiuse` = `false`)
redeem_used Read Only	integer	How many redeems were already performed
redeem_remaining Read Only	integer	Remaining redeems count
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 on Redeem Locations of those ids

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": "123-74",
  "county": "",
  "country": "us"
}

Attribute	Type	Description
name Required	string
address_line_1 Required	string
address_line_2	string
city Required	string
postcode Required	string
county	string
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_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_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/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": [
      {
        "object": "product",
        "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": "123-74",
          "county": "",
          "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

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/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 PUT 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": 'sales_page'
    },
    {
      "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": 'sales_page'
    }
  ],
  "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

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": 'sales_page'
}

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 voucher that has been redeemed cannot be 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/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
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 redeemed; the message says why
`404`	The order or the product does not exist on this sales page

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 this sales page

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_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

See Expanding objects

Available expand[]:

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": 11,
  "previous": "eyJkaXIiOiJwcmV2aW91cyIsImN1cnNvciI6IjM0Iiwib3JkZXJfYnkiOiJyYi5jcmVhdGVkX2F0Iiwib3JkZXIiOiJERVNDIiwibGltaXQiOjEwfQ==",
  "has_previous": false,
  "next": "eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiMjUiLCJvcmRlcl9ieSI6InJiLmNyZWF0ZWRfYXQiLCJvcmRlciI6IkRFU0MiLCJsaW1pdCI6MTB9",
  "has_next": true
}

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 Expandable Required	Redeem Location object or integer	Related Redeem Location object or Redeem Location ID (see Expanding Objects)
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	integer	Min value = 1
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/sales-pages/1337/redemptions' \
  -H 'Authorization: Bearer JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --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)

Request body

Redemption object

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

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

VC Cards

VC Cards resource

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, for example `Card Activated`, `Card Deactivated`, `Card Reactivated`, `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

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.

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

Makes the card usable. For an inactive card this is a reactivation: the reason is saved in the card activity and, if the card has an owner, we email the owner. For a card in the initial state it is the first activation.

Requires the vccard.reactivate permission.

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 activated. Saved in the card activity
confirmation Required	boolean	Must be `true`

HTTP Response

Successful response (code 204) has no body. Code 400 when the card cannot be activated in its current state, 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.

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

Sales Pages resource

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
}

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 objects or array of Payment Gateway IDs (see Expanding Objects)
organisation Read Only	string	related Organisation ID
organisation_sale_container Read Only	string	related Organisation ID
skin Expandable Read Only	int or Skin object	Skin object or Skin ID (see Expanding Objects)
reseller_hash Read Only	string	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_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",
  "header_image": "https://images.vouchercart.com/clients/842e2ae4e1911a96a31bfd59c9cabdfc/4cca9423a5cae432ddf071a0d7cd0774.jpg",
  "logo_alt": "https://images.vouchercart.com/clients/842e2ae4e1911a96a31bfd59c9cabdfc/137af39db364e563ab94eb3cdaab75d9.png",
  "logo_position": "center",
  "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"
}

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_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
header_image	string	Image URL
logo_alt	string	Image URL
logo_position	enum: `left`, `center`
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	bool
available_languages	array	array of ISO 639-1:2002 Locale Codes ex. `en`
menu_position

Reports

Reports resource

Orders Export

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

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" \
  -H "Authorization: Bearer guest_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	Default: true
include_not_refunded_or_cancelled	boolean	Default: true
include_redeemed	boolean	Default: true
include_partially_redeemed	boolean	Default: true
include_not_redeemed	boolean	Default: true
expired_only	boolean	Default: false, can only be true if not_expired_only is not
not_expired_only	boolean	Default: false, can only be true if expired_only is not

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, £": "1.00",
    "Regular price, £": "1.00",
    "Voucher Liability": "100.00",
    "Discount Value": "0.00",
    "Discount Name": "",
    "Discount Type": "",
    "Discount Code": "",
    "Sales Channel": "Online",
    "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, £": "1",
    "Monetary Remaining Value, £": "1",
    "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",
    "Was Sent To": "buyer",
    "Recipient name": "",
    "Recipient email": "",
    "Voucher Message": "Happy birthday\nMy dear friend!",
    "Order Date": "01\/07\/2021 10:25",
    "Redeemable from": "10/04/2023 11:51",
    "Redeemable to": "10/07/2023 11:51",
    "Subdomain": "client1",
    "Card Number": "",
    "Payment Gateway": "VoucherCart Payment Gateway",
    "Payment Reference": "TEST-JY4ACXHUEUDS",
    "Payment Reference Url": "https:\/\/myst.securetrading.net\/transactions\/singletransaction?transactionreference=TEST-JY4ACXHUEUDS",
    "Internal note": "",
    "Stripe Payout Id": "",
    "Stripe Payout Initiated At": "",
    "Stripe Payout Estimated Arrival Date": "",
    "Stripe Payout Amount": "",
    "Stripe Payout Link": "",
    "Buyer consent to promotions": 1
  },
  {
    "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, £": "100.00",
    "Regular price, £": "100.00",
    "Voucher Liability": "100.00",
    "Discount Value": "0.00",
    "Discount Name": "",
    "Discount Type": "",
    "Discount Code": "",
    "Sales Channel": "Online",
    "Sold as": "Standard Sale",
    "Charity": "No",
    "Complimentary\/Free": "No",
    "vcCard Reward": "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": "electronic",
    "Delivery price": "",
    "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": "10/04/2023 11:51",
    "Redeemable to": "10/07/2023 11:51",
    "Subdomain": "client1",
    "Card Number": "",
    "Payment Gateway": "VoucherCart Payment Gateway",
    "Payment Reference": "TEST-JY4ACXHUEUDS",
    "Payment Reference Url": "https:\/\/myst.securetrading.net\/transactions\/singletransaction?transactionreference=TEST-JY4ACXHUEUDS",
    "Internal note": "",
    "Stripe Payout Id": "",
    "Stripe Payout Initiated At": "",
    "Stripe Payout Estimated Arrival Date": "",
    "Stripe Payout Amount": "",
    "Stripe Payout Link": "",
    "Buyer consent to promotions": 0
  }
]

JSON containing Orders Export

Refunds Report

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

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_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

Reseller Vouchers Report

GET https://api.vouchercart.com/v2.1/reports/reseller-vouchers?reseller_hash={ResellerHash}

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/reports/reseller-vouchers?reseller_hash=xyz" \
  -H "Authorization: Bearer guest_token"

Parameter	Type	Description
ResellerHash Required	string	Reseller's hash

HTTP Response

Response example:

[
  {
    "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": [
      {
        "id": 18874,
        "object": "category",
        "title": {
          "en": "Spa"
        },
        "description": {
          "en": "Spa vouchers"
        },
        "banner_text": {
          "en": null
        },
        "header_text": {
          "en": null
        },
        "header_image": "",
        "category_image": "",
        "slug": "vegetables-7",
        "parent_id": 5,
        "lft": 5,
        "lvl": 2,
        "rgt": 10
      }
    ],
    "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,
    "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"
  }
]

Array containing Voucher objects

Reseller Sales Pages Report

GET https://api.vouchercart.com/v2.1/reports/reseller-sales-pages?reseller_hash={ResellerHash}

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/reports/reseller-sales-pages?reseller_hash=xyz" \
  -H "Authorization: Bearer guest_token"

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

HTTP Response

Response 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": {
      "id": 1,
      "object": "skin",
      "main_color": "#8f8f8f",
      "buy_color": "#a3a3a3",
      "background_color": "#ffffff",
      "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",
      "header_image": "https://images.vouchercart.com/clients/842e2ae4e1911a96a31bfd59c9cabdfc/4cca9423a5cae432ddf071a0d7cd0774.jpg",
      "logo_alt": "https://images.vouchercart.com/clients/842e2ae4e1911a96a31bfd59c9cabdfc/137af39db364e563ab94eb3cdaab75d9.png",
      "logo_position": "center",
      "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"
    }
  },
]

Array containing Sales Page objects

Webhooks

Webhooks resource

The Webhook object

The Webhook object example:

  {
    "id": 1,
    "object": "sales-page-webhook",
    "url": "http:\/\/www.example.com",
    "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	string	URL
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	array	Event object name
description	string
active	boolean
last_used_at Read Only	string	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 attempts 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-08T06:26:56.000000Z"
    "data": {
       "id": 18,
       "object": "order",
       "language": "en",
       "purchaser": {
         "name": "John Doe",
         "email": "[email protected]",
         "phone": ""
       },
       "reference": "813713-WRB-1335GB",
       "products": [423664, 7545346],
       "deliveries": [42123],
       "payments": [4389],
       "is_manual_order": false,
       "created_at": "2019-08-19T11:00:39Z",
       "buyer_consent_to_promotion_offers": false
    }
  }

Attribute	Type	Description
id Read Only	integer
object Read Only	string, value = `event`	event identifier
name Read Only	string	`order.created,order-product.redeemed,order-product.redeem_cancelled,order-product.refunded,order-product.cancelled,order-product.regenerated,order-product.expiration_changed`
created_at Read Only	string	ISO 8601 date format
data Read Only	Order object or Product object

List all webhooks

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

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2/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": 1,
    "object": "sales-page-webhook",
    "url": "http:\/\/www.example.com",
    "secret": null,
    "enabled_events": [
      "order.created"
    ],
    "description": "Webhook description",
    "active": true,
    "last_used_at": "2021-10-08T06:26:56.000000Z"
  }
]

List containing Webhook objects

Retrieve Webhook

GET https://api.vouchercart.com/v2/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": "http:\/\/www.example.com",
    "secret": null,
    "enabled_events": [
      "order.created"
    ],
    "description": "Webhook description",
    "active": true,
    "last_used_at": "2021-10-08T06:26:56.000000Z"
  }

The Webhook object

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/sales-pages/1337/orders' \
  -H 'Authorization: Bearer JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
    --data-binary '
    {
        "url": "www.example.com",
        "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

HTTP Response

Successful response (code 201)

Update Webhook

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

HTTP Request

Request example:

curl -X POST 'https://api.vouchercart.com/v2/sales-pages/1337/orders' \
  -H 'Authorization: Bearer JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
    --data-binary '
    {
        "url": "www.example.com",
        "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

HTTP Response

Successful response (code 201)

Delete Webhook

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

Successful response (code 201)

Webhook history

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

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2/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:\/\/webhookzz.site\/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",
      "data": {
        "id": 16,
        "object": "order",
        "language": "en",
        "purchaser": {
          "name": "Faye Khan",
          "email": "[email protected]",
          "phone": "+44(0)048703313"
        },
        "reference": "19-PG5-1GB",
        "products": [
          26
        ],
        "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.site\/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",
      "data": {
        "id": 15,
        "object": "order",
        "language": "en",
        "purchaser": {
          "name": "Phoebe Scott",
          "email": "[email protected]",
          "phone": "(0528) 0772236"
        },
        "reference": "16-GMF-1GB",
        "products": [
          25
        ],
        "deliveries": [],
        "payments": [
          15
        ],
        "is_manual_order": false,
        "created_at": "2021-10-08T08:58:57+0000",
        "buyer_consent_to_promotion_offers": false
      }
    },
    "response": null,
    "response_status": "200",
    "created_at": "2021-10-08T08:59:16.000000Z"
  }
]

List containing [Webhook history objects]

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`