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 "staffuser@example.com: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": "tom+client@vouchercart.com",
    "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": "jon@example.com",
        "phone": ""
      },
      "products": [
        32
      ],
      "deliveries": [],
      "payments": [
        47
      ]
    },
    {
      "id": 17,
      "object": "order",
      "language": "en",
      "purchaser": {
        "name": "Meghan Smith",
        "email": "meghan.smith@example.com",
        "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": "dioslioc-buyer@dodsi.com",
    "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,
  "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
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
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": "dioslioc-buyer@dodsi.com",
  "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": "dioslioc-buyer@dodsi.com"
  },
  "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": "dioslioc-buyer@dodsi.com"
}

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": "VoucherCartSecureTrading",
  "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": "jon@example.com",
      "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

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)

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": "jon@example.com",
        "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": "meghan.smith@example.com",
        "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": "jon@example.com",
    "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

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

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": "test@example.com",
    "hide_email": false,
    "website": "https://test.example.com",
    "hide_website": false
  },
  "social_media": {
    "facebook": "https://www.facebook.com/example/",
    "twitter": "https://twitter.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": "test@example.com",
  "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://twitter.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/reseller-vouchers?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 Value": "£1.30",
    "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, £": "1",
    "Monetary Remaining Value, £": "1",
    "Monetary Redeemed Value, £": "0",
    "Quantity Total": "1",
    "Quantity  Remaining": "1",
    "Quantity Redeemed": "0",
    "Multiple Use": "0",
    "Customer Name": "Buyer Name",
    "Customer Email": "buyer@devvouhcercart.com",
    "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",
    "Expiry date": "Expires: 01\/10\/2021",
    "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 Value": "£130.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",
    "Quantity Total": "1",
    "Quantity  Remaining": "1",
    "Quantity Redeemed": "0",
    "Multiple Use": "0",
    "Customer Name": "Buyer Name",
    "Customer Email": "buyer@devvouhcercart.com",
    "Customer Phone": "",
    "Customer Address": "",
    "Delivery type": "electronic",
    "Delivery price": "",
    "Was Sent To": "recipient",
    "Recipient name": "",
    "Recipient email": "lost@devvouhcercart.com",
    "Voucher Message": "Happy birthday\nMy dear friend!",
    "Order Date": "01\/07\/2021 10:25",
    "Expiry date": "Expires: 01\/10\/2021",
    "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": "test@example.com",
      "hide_email": false,
      "website": "https://test.example.com",
      "hide_website": false
    },
    "social_media": {
      "facebook": "https://www.facebook.com/example/",
      "twitter": "https://twitter.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 that will contain a signature the receiving app can use the payload has not been tampered with. Signature is calculated with hmac-sha256 using a payload json and secret.
enabled_events	array	Event object name
description	string
active	boolean
last_used_at Read Only	string	ISO 8601 date format

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": "dioslioc-buyer@dodsi.com",
         "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`
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": "stefan.mason@brown.com",
          "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": "hunter.lisa@hall.com",
          "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

List all Orders

HTTP Request

Pagination parameters

Expandables

HTTP Response

Retrieve an Order

HTTP Request

Expandables

HTTP Response

Product Refunds List

HTTP Request

Pagination parameters

Expandables

HTTP Response

Product Redemptions List

HTTP Request

Pagination parameters