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 http://api.vouchercart.com/v2.1/authorize

Authorization header should consist base64-encoded combination of staff member's email (login) and password separated by 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 will be authenticated successfully you will retrieve 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 of API endpoints requires 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 Address e-mail of the staff member
fullName string Full name
id integer ID of the staff member object
locale string Language code used by staff member

Refresh token

JWT technique used short-lived tokens, it means that the JWT will be valid only by short duration time (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 http://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.

Guest access

TODO

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

Queued resources

TODO

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 Tranlation hash
description Tranlation hash
banner_text Tranlation hash
header_text Tranlation 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"
}
Attribute Type Description
id

Read Only

integer
object

Read Only

string, value = redeem_location redeem location object identifier
name string
address 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",
  "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,
  "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
  ]
}
Attribute Type Description
id

Read Only

integer
object

Read Only

string, value = voucher voucher object identifier
voucher_title Tranlation hash
promotion_title Tranlation hash
description Tranlation 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
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

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)"
  },
  "is_default": false,
  "quantity": null,
  "quantity_weight": 5,
  "sold": 0,
  "sold_out": 0,
  "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
}
Attribute Type Description
id

Read Only

integer
object

Read Only

string, value = voucher_option voucher option object identifier
type
description Tranlation hash
is_default boolean
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

The Shipping Method hash

The Shipping Method hash example:

{
  "voucher_delivery_shipping_method_id": 3225,
  "shipping_method_id": 31225,
  "name": "UK 1st Class",
  "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",
      "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,
      "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",
      "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
      ]
    }
  ],
  "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",
    "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
    ]
  }

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": ""
  },
  "products": [423664, 7545346],
  "deliveries": [42123],
  "payments": [4389]
}
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
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)

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

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"
}
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_address

Conditionally Required

Shipping Address object Required if delivery_method = postal
option_amount

Conditionally Required

Write Only

Money hash Required only for Monetary Vouchers (a.k.a. Buyer Defined / Range Vouchers)
voucher_delivery_shipping_method_id

Conditionally Required

Write Only

integer Required if delivery_method = postal

The 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",
  "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_number": "XXXXXXXXXXXX0211",
  "amount": {
    "amount": 10359,
    "currency": "GBP"
  },
  "gateway": "VoucherCartSecureTrading"
}
Attribute Type Description
transaction_id

Read Only

string
card_number

Read Only

string
amount

Read Only

Money hash
gateway

Read Only

string

Create an Order

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

HTTP Request

Request example:

curl -X POST 'https://api.vouchercart2.local/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.vouchercart2.local/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": ""
      },
      "products": [
        32
      ],
      "deliveries": [],
      "payments": [
        47
      ],
      "voucher_from": "John Smith",
      "voucher_to": "Samantha White"
    },
    {
      "id": 17,
      "object": "order",
      "language": "en",
      "purchaser": {
        "name": "Meghan Smith",
        "email": "meghan.smith@example.com",
        "phone": ""
      },
      "products": [
        31
      ],
      "deliveries": [],
      "payments": [
        46
      ],
      "voucher_from": "John Smith",
      "voucher_to": "Samantha White"
    }
  ],
  "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": ""
  },
  "products": [
    32
  ],
  "deliveries": [],
  "payments": [
    47
  ],
  "voucher_from": "John Smith",
  "voucher_to": "Samantha White"
}

The Order object

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.vouchercart2.local/v2/sales-pages/1337/redemptions' \
  -H 'Authorization: Bearer JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-binary '
  {
    "redeem_location": 786,
    "order_product": 985635,
    "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.vouchercart2.local/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