NAV Navbar
API v2.1
shell

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

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

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.

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

Categories

Categories resource

The Category object

The Category object example:

{
  "id": 63526,
  "object": "category",
  "title": {
    "en": "Food"
  },
  "description": {
    "en": "A category with all food related vouchers"
  },
  "banner_text": {
    "en": null
  },
  "header_text": {
    "en": null
  },
  "header_image": "",
  "category_image": "",
  "slug": "food-5",
  "parent_id": 1337,
  "lft": 63524,
  "lvl": 1,
  "rgt": 63529
}
Attribute Type Description
id

Read Only

integer
object

Read Only

string, value = category category object identifier
title Translation hash
description Translation hash
banner_text Translation hash
header_text Translation hash
header_image string URL
category_image string URL
slug string
parent_id int
lft int Nested set model parameter
lvl int Nested set model parameter
rgt int Nested set model parameter

List all Categories

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

HTTP Request

Request example:

curl -X GET "https://api.vouchercart.com/v2.1/sales-pages/1337/categories" \
  -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:

HTTP Response

Response example:

{
  "object": "list",
  "data": [
    {
      "id": 5,
      "object": "category",
      "title": {
        "en": "Food"
      },
      "description": {
        "en": "A category with all food related vouchers"
      },
      "banner_text": {
        "en": null
      },
      "header_text": {
        "en": null
      },
      "header_image": "",
      "category_image": "",
      "slug": "food-5",
      "parent_id": 1,
      "lft": 2,
      "lvl": 1,
      "rgt": 11
    },
    {
      "id": 6,
      "object": "category",
      "title": {
        "en": "Fruits"
      },
      "description": {
        "en": "A category with all Fruits related vouchers"
      },
      "banner_text": {
        "en": null
      },
      "header_text": {
        "en": null
      },
      "header_image": "",
      "category_image": "",
      "slug": "fruits-6",
      "parent_id": 5,
      "lft": 3,
      "lvl": 2,
      "rgt": 4
    }
  ],
  "count": 2,
  "previous": "eyJkaXIiOiJwcmV2aW91cyIsImN1cnNvciI6IjUiLCJvcmRlcl9ieSI6ImNhdC5jcmVhdGVkX2F0Iiwib3JkZXIiOiJERVNDIiwibGltaXQiOjEwfQ==",
  "has_previous": false,
  "next": "eyJkaXIiOiJuZXh0IiwiY3Vyc29yIjoiMSIsIm9yZGVyX2J5IjoiY2F0LmNyZWF0ZWRfYXQiLCJvcmRlciI6IkRFU0MiLCJsaW1pdCI6MTB9",
  "has_next": false
}

List object containing Category objects

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:

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:

Expandables

See Expanding objects

Available expand[]:

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[]:

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:

Expandables

See Expanding objects

Available expand[]:

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[]:

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:

Expandables

See Expanding objects

Available expand[]:

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:

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

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:

Expandables

See Expanding objects

Available expand[]:

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]