NAV
Shell

Introduction

Welcome to the VoucherCart API!

Authentication

# With shell, you can just pass the correct header with each request
curl https://api.vouchercart.com/v1/{endpoint}
  -H "Authorization: Bearer VCaccessToken"

VoucherCart uses API key to allow access to the API. You can generate your own API in Client dashboard in Settings / API section.

Almost all VoucherCart endpoints require authorization using the API key (or 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 VCaccessToken

Get JWT token

VoucherCart uses JWT authentication described in RFC-7519 specification.

HTTP Request

curl -X POST "https://api.vouchercart.com/v1/authorize" \
    -u "staffuser@example.com:password" \
    --data "subdomain=my-sales-page"

POST http://api.vouchercart.com/v1/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

{
  "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...

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

Profile Object

Parameter 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

Get user domains

In previous request you will need to provide a subdomain parameter consisting name of one the sales pages where the staff member is already registered. If you do not know that parameter, you may ask for e-mail address which user use to get list of domains where staff member use given mail.

HTTP Request

curl "https://api.vouchercart.com/v1/user-domains?email=staffmember@example.com"

GET http://api.vouchercart.com/v1/user-domains

Parameter Type Description
email string, required An email address

HTTP Response

{
  "status": "success",
  "domains": [
    {
        "id": 8,
        "name": "hello-world",
        "url": "https://hello-world.vouchercart.com/"
    }
  ]
}
Parameter Type Description
domains Array<Domain object> -
status string Should return refreshed, otherwise request has failed.

Domain object

Parameter Type Description
id number ID
name string sales page subdomain
url string link to sales page subdomains

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/v1/refresh" \
    --data "accessToken=my-jwt-token&refreshToken=RTrefreshToken"

PUT http://api.vouchercart.com/v1/refresh

Parameter Type Description
accessToken string, required A JWT token supposed to expired (or already expired)
refreshToken string, required Refresh token acquired during authorization. Starts with RT letters.

HTTP Response

{
  "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.

Client registration

POST https://api.vouchercart.com/v1/register

curl "https://api.vouchercart.com/v1/register" \
    -X POST \
    --data "email=restaurant@example.com&password=N14kYm8Wz1BACcg2fullName=John+Doe&companyName=Doe+Restaurants&subdomain=doe-restaurants&phone=555-555-555&country=US&timezone=EST&cardNumber=4111111111111111&cardCvv=123&cardExpiryMonth=10&cardExpiryYear=2020&cardHolderName=John+Doe"

This request does not require to be authorized

Parameter Type Description
email string Email address.
password string Password used to sign-in as owner.
fullName string Full name of the owner which creates new VoucherCart store.
companyName string Company name, a sub-domain will be generated from this name.
subdomain string Name of sub-domain which will http://{subdomain}.vouchercart.com.
phone string Phone number.
country string Valid country.
timezone string Valid Timezone.
cardNumber string Number on the card.
cardCvv string CVV number of the card.
cardExpiryMonth string Card expiration date, format: MM.
cardExpiryYear string Card expiration date, format: YYYY.
cardHolderName string Holder name of the card.

HTTP Response

{
    "status": "created",
    "clientId": 21295,
    "domainId": 79942
}
Parameter Type Description
status string created whether successfully created new client, otherwise failed
clientId integer ID of newly created Client
subdomainId integer ID of the sub-domain

Domain

Get list of domains

HTTP Request

GET https://api.vouchercart.com/v1/domains

Make sure you replace VCaccessToken with your API key.

curl "https://api.vouchercart.com/v1/domains" \
    -H "Authorization: Bearer VCaccessToken"

HTTP Response

Sample response:

{
    "status": "success",
    "domains": [
        {
            "id": 8,
            "name": "hello-world",
            "url": "https://hello-world.vouchercart.com/"
        },
        {
            "id": 1337,
            "name": "other-sales-page",
            "url": "https://other-sales-page.vouchercart.com/"
        }
    ]
}
Parameter Type Description
status string Should return "success"
domains Array<Domain object> -

Domain object

Parameter Type Description
id number ID
name string sales page sub-domain
url string link to sales page sub-domains

Gift voucher

List gift vouchers

HTTP Request

curl "https://api.vouchercart.com/v1/vouchers?domainId=7531"
    -H "Authorization: Bearer VC.accessToken"

Make sure to replace VC.accessToken with your API key.

GET https://api.vouchercart.com/v1/vouchers

Parameter Type Description
domainId integer Client’s domain ID.
limit integer, optional The maximum number of results to return (default=15).
offset integer, optional Offset of the results (default=0, max=50).

HTTP Response

[
  {
    "voucherId": 22676,
    "type": "fixed",
    "title": "Spa Day with Treatment & Afternoon Tea!",
    "description": "Enjoy a Pamper Day in our Spa!! ...",
    "options": [
      {
        "optionId": 99195,
        "type": "fixed",
        "description": "",
        "displayPrice": "$19.99",
        "optionQuantity": null,
        "sellPrice": 1999,
        "currency": "USD"
      }
    ],
    "price": 1999,
    "currency": "USD",
    "image": "https://assets.vouchercart.../product.jpg",
    "images": [
      "https://assets.vouchercart.../2x.jpg"
    ],
    "categories": [
      {
        "categoryId": 77423,
        "name": "Spa"
      }
    ],
    "accessLevel": "published"
  },
  // ...
]
Parameter Type Description
voucherId integer, required ID of the voucher.
type string Can be: regular, monetary, predefined, ticket.
title string Name of the voucher.
description string Description of the voucher.
options VoucherOption[] objects Voucher Options.
price integer Computed the lowest price of given voucher.
currency string Currency of the voucher.
image string Link to main image of the gift voucher.
images string[] Link to additional images.
categories VoucherCategory[] objects Voucher can relate to multiple categories.
accessLevel string, required Can be: published, secret, unpublished, see description below the table.

Access level

VoucherCategory object

Parameter Type Description
categoryId string ID of the Category
name integer Category title

VoucherOption object

Parameter Type Description
optionId integer
type string
quantity integer, optional -
sellPrice integer, required
realValue integer, optional
redeemStock -
displayPrice string Computed price of the voucher.
description string -
crossedOutPrice -
currency string e.g. GBP

Get gift voucher

HTTP Request

curl "https://api.vouchercart.com/v1/voucher/22676"
    -H "Authorization: Bearer VC.accessToken"

Make sure to replace VC.accessToken with your API key.

GET https://api.vouchercart.com/v1/voucher/:voucherId

Parameter Type Description
voucherId integer, required ID of the voucher.

HTTP Response

{
  "voucherId": 22676,
  "type": "fixed",
  "title": "Spa Day with Treatment & Afternoon Tea!",
  "description": "Enjoy a Pamper Day in our Spa!! ...",
  "terms": "Please note that advance booking is essential when using this gift voucher...",
  "options": [
    {
      "optionId": 99195,
      "type": "fixed",
      "description": "",
      "displayPrice": "$19.99",
      "optionQuantity": null,
      "sellPrice": 1999,
      "currency": "USD"
    }
  ],
  "price": 1999,
  "currency": "USD",
  "image": "https://assets.vouchercart.../product.jpg",
  "images": [
    "https://assets.vouchercart.../2x.jpg"
  ],
  "categories": [
    {
      "categoryId": 77423,
      "name": "Spa"
    }
  ],
  "accessLevel": "published",
  "delivery": [
    {
      "methodId": 52214,
      "type": "electronic",
      "title": "Electronic",
      "options": [
        {
          "title": "Electronic",
          "description": "Deliver instantly via e-mail",
          "amount": 0,
          "currency": "USD"
        }
      ]
    }
  ],
  "expiry": {
    "type": "period",
    "interval": "months",
    "period": 3
  },
  "hidePriceDisabled": false,
  "quantityIsLimited": true
}
Parameter Type Description
voucherId integer, required ID of the voucher.
type string Can be: fixed, monetary, predefined, ticket.
title string, required Name of the voucher.
description string, required Description of the voucher.
terms string, required Terms related to gift voucher.
options VoucherOption[] objects Pricing options of the voucher.
mainImage string Link to main image of the gift voucher.
images string[] Link to additional images.
categories VoucherCategory[] objects Voucher can relates to multiple categories.
accessLevel string, required Can be: published, secret, unpublished.
delivery DeliveryMethod[] objects -
expiry Expiry object -
hidePriceDisabled boolean Should price be always hidden on gift voucher?
quantityIsLimited boolean Does voucher have unlimited stock level?

VoucherExpiry object

Expiry object tells how long purchased voucher will last. There are two types of expiration:

Parameter Type Description
period integer Number of months after voucher purchase during which voucher may be redeemed.
type string period
Parameter Type Description
dateFrom datetime When voucher starts being redeemable,
dateTo datetime When voucher expires - Date/Time after which voucher may no longer be redeemed.
type string time

DeliveryMethod object

Defines how voucher will be delivered to buyer.

Parameter Type Description
methodId integer Voucher delivery method ID
title string -
method string electronic or postal
options VoucherDeliveryOption[] -

DeliveryOption

Buyer may select from a delivery/carrier option from those available.

Parameter Type Description
title string -
description string -
amount integer -
currency string -

Orders

Place an order

HTTP Request

curl "https://api.vouchercart.com/v1/order" \
    -X POST \
    -d domain=5765 \
    -d voucherId=9467 \
    -d optionId=9589 \
    -d monetaryAmount=2000 \
    -d payments[0][amount]=2000 \
    -d payments[0][currency]=GBP \ 
    -d payments[0][title]="EPOS CreditCard" \
    -d payments[0][metadata][reference]="c2a3cc45-6580-4717-9de6-a0a785dc1b41"

POST https://api.vouchercart.com/v1/order

Parameter Type Description
domainId integer Client’s domain ID.
voucherId integer ID of the voucher.
optionId integer ID of the voucher option
monetaryAmount integer, optional When purchasing a monetary voucher this parameter is required. It describes value of the voucher (e.g. $20.00 = 2000).
payments Payment[] objects -
email string, optional If it is set then it will issue an email with order to given e-mail address.

Payment Object

Parameter Type Description
amount integer e.g. $20.00 = 2000
currency string e.g. GBP
title string Payment method title e.g. provider name.
metadata string[] map Additional data related to payment.

HTTP Response

{
    "status": "created",
    "orderId": 763521
}
Parameter Type Description
status string If order was created it will contain success status.
orderId integer ID of placed order.

Redeem voucher

Voucher status

HTTP Request

GET https://api.vouchercart.com/v1/status

curl "https://api.vouchercart.com/v1/status?code=AAAA-BBBB-CCCC-DDDD" \
  -H "Authorization: Bearer VCaccessToken"

Make sure to replace VCaccessToken with your API key.

Parameter Type Description
code string, required Voucher code.
domain integer, required Client’s sales page domain ID.

HTTP Response

Sample response (fixed, single-use):

{
  "code": "AAAA-BBBB-CCCC-DDDD",
  "current": 0,
  "expirations": [
    {
      "from": "2016-12-02T07:57:29+0000",
      "to": "2017-03-02T07:57:29+0000"
    }
  ],
  "monetary": false,
  "multiUsable": false,
  "order": {
    "buyer": {
      "city": null,
      "country": null,
      "county": null,
      "email": "buyer@example.com",
      "guest": true,
      "handDelivery": true,
      "house": null,
      "id": null,
      "name": "Buyer Name",
      "phone": null,
      "postcode": null,
      "street": null,
      "town": null
    },
    "currency": "GBP",
    "voucher": {
      "currency": "GBP",
      "deliveryType": "electronic",
      "description": "Fixed desc",
      "hiddenPriceOnVoucher": true,
      "id": 7,
      "image": null,
      "imageNoPrice": null,
      "isDeliveryDateSet": true,
      "message": "Happy birthday\nMy dear friend!",
      "name": "Fixed voucher: Meal for two",
      "price": 100,
      "priceOnVoucher": "£1.30",
      "type": "voucher",
      "voucherType": "fixed"
    },
    "purchasedAt": "2016-12-02T07:57:29+0000",
    "recipient": {
      "city": null,
      "comment": "<p>Happy birthday</p>\n<p>My dear friend!</p>",
      "country": null,
      "county": null,
      "email": "buyer@example.com",
      "from": null,
      "houseName": null,
      "name": "Buyer Name",
      "postcode": null,
      "streetName": null
    },
    "redeemedDate": null,
    "reference": "OWHCNE-1GB-1",
    "refund": null,
    "shippingTotal": 0,
    "subTotal": 80,
    "taxTotal": 20,
    "total": 100
  },
  "redeemableOn": [
    1
  ],
  "redeemed": false,
  "redeemHistory": [],
  "remainingString": "1 time left",
  "status": "in_progress",
  "stock": 1
}

Sample response (monetary, multi-use, $1.00 / $20.00 used):

{
  "code": "AAAA-BBBB-CCCC-DDDD",
  "current": 100,
  "expirations": [ ... ],
  "monetary": true,
  "multiUsable": true,
  "order": { ... },
  "redeemableOn": [ ... ],
  "redeemed": false,
  "redeemHistory": [ ... ],
  "status": "in_progress",
  "stock": 2000
}

Sample response (redeemed completely):

{
  "code": "AAAA-BBBB-CCCC-DDDD",
  "current": 1,
  "expirations": [ ... ],
  "monetary": false,
  "multiUsable": false,
  "order": { ... },
  "redeemableOn": [ ... ],
  "redeemed": true,
  "redeemHistory": [ ... ],
  "status": "completed",
  "stock": 1
}
Parameter Type Description
code string Voucher code.
current integer Current spent value.
expirations Expiration[] objects -
monetary boolean Is this a monetary voucher type?
multiUsable boolean Can voucher be redeemed multiple times?
order Order object -
redeemableOn integer[] Includes ID of domains (sales pages) where voucher can be redeemed
redeemed boolean Has voucher been redeemed already?
redeemHistory RedeemHistory[] objects -
status string Voucher status (can be: in_progress, completed, refunded, expired, regenerated)
stock integer Value of voucher.

Expiration object

Parameter Type Description
from datetime ISO8601 format
to datetime ISO8601 format

Redeem history

Parameter Type Description
amount integer units used
redeemAt datetime ISO8601 format

Order object

Parameter Type Description
buyer Buyer object -
currency string -
voucher Voucher object -
purchasedAt datetime -
recipient Recipient object -
redeemedDate datetime (optional) -
reference string -
refund integer (optional) -
shippingTotal integer -
subTotal integer -
taxTotal integer -
total integer -

Buyer object

Parameter Type Description
city string (optional) -
country string (optional) -
county string (optional) -
email string -
guest string (optional) -
handDelivery string (optional) -
house string (optional) -
id string (optional) -
name string -
phone string (optional) -
postcode string (optional) -
street string (optional) -
town string (optional) -

Recipient object

Parameter Type Description
city string (optional) -
comment string (optional) -
country string (optional) -
county string (optional) -
email string (optional) -
from string (optional) -
houseName string (optional) -
name string (optional) -
postcode string (optional) -
streetName string (optional) -

Gift voucher object

Parameter Type Description
currency string -
deliveryType string -
description string -
hiddenPriceOnVoucher boolean -
id integer (optional) -
image string (optional) -
imageNoPrice string (optional)
isDeliveryDateSet boolean -
message string -
name string -
price integer -
priceOnVoucher string -
type string -
voucherType string -

Redeem voucher

Notes:

HTTP Request

POST https://api.vouchercart.com/v1/redeem

Make sure to replace VCaccessToken with your API key.

curl "https://api.vouchercart.com/v1/redeem" \
  -X POST \
  -d code="AAAA-BBBB-CCCC-DDDD" \
  -d domain=1 \
  -H "Authorization: Bearer VCaccessToken"

You may also specify additional parameters like reductor or redeemDate:

curl "https://api.vouchercart.com/v1/redeem" \
  -X POST \
  -d code="AAAA-BBBB-CCCC-DDDD" \
  -d domain=1 \
  -d reductor=2 \
  -d redeemDate="2015-12-05 13:37" \
  -H "Authorization: Bearer VCaccessToken"
Parameter Type Description
code string, required Voucher code.
domain integer, required Client’s sales page domain ID.
reductor integer, optional How many units (value) should be reduced from the voucher (used in multi-use vouchers. Default: redeem completely.
redeemDate datetime, optional Format: YYYY-MM-DD HH:SS. Default: now.

HTTP Response

Sample response (fixed, single-use):

{
  "code": "AAAA-BBBB-CCCC-DDDD",
  "current": 1,
  "expirations": [
    {
      "from": "2016-12-02T07:57:29+0000",
      "to": "2017-03-02T07:57:29+0000"
    }
  ],
  "monetary": false,
  "multiUsable": false,
  "order": {
    "buyer": {
      "city": null,
      "country": null,
      "county": null,
      "email": "buyer@example.com",
      "guest": true,
      "handDelivery": true,
      "house": null,
      "id": null,
      "name": "Buyer Name",
      "phone": null,
      "postcode": null,
      "street": null,
      "town": null
    },
    "currency": "GBP",
    "voucher": {
      "currency": "GBP",
      "deliveryType": "electronic",
      "description": "Fixed desc",
      "hiddenPriceOnVoucher": true,
      "id": 7,
      "image": null,
      "imageNoPrice": null,
      "isDeliveryDateSet": true,
      "message": "Happy birthday\nMy dear friend!",
      "name": "Fixed voucher: Meal for two",
      "price": 100,
      "priceOnVoucher": "£1.30",
      "type": "voucher",
      "voucherType": "fixed"
    },
    "purchasedAt": "2016-12-02T07:57:29+0000",
    "recipient": {
      "city": null,
      "comment": "<p>Happy birthday</p>\n<p>My dear friend!</p>",
      "country": null,
      "county": null,
      "email": "buyer@example.com",
      "from": null,
      "houseName": null,
      "name": "Buyer Name",
      "postcode": null,
      "streetName": null
    },
    "redeemedDate": "2016-12-02T13:32:48+0000",
    "reference": "OWHCNE-1GB-1",
    "refund": null,
    "shippingTotal": 0,
    "subTotal": 80,
    "taxTotal": 20,
    "total": 100
  },
  "redeemableOn": [
    1
  ],
  "redeemed": true,
  "redeemHistory": [
    {
      "redeemAt": "2016-12-02T13:32:48+0000",
      "amount": 1
    }
  ],
  "remainingString": "0 time left",
  "status": "completed",
  "stock": 1
}

Sample response (fixed, multi-use):

{
  "code": "AAAA-BBBB-CCCC-DDDD",
  "current": 2,
  "expirations": [ ... ],
  "monetary": false,
  "multiUsable": true,
  "order": { ... },
  "redeemableOn": [ ... ],
  "redeemed": false,
  "redeemHistory": [ ... ],
  "status": "in_progress",
  "stock": 5
}
Parameter Type Description
code string Voucher code.
current integer Current spent value.
expirations Expiration[] objects -
monetary boolean Is this a monetary voucher type?
multiUsable boolean Can voucher be redeemed multiple times?
order Order object -
redeemableOn integer[] Includes ID of domains (sales pages) where voucher can be redeemed.
redeemed boolean Has voucher been redeemed already?
redeemHistory RedeemHistory[] objects -
status string Voucher status (can be: in_progress, completed, refunded, expired, regenerated)
stock integer Value of voucher.

Top-up voucher

If voucher has been created in purpose to use it multiple times (i.e. monetary voucher) you may add specified value (amount) to given voucher.

HTTP Request

curl "https://api.vouchercart.com/v1/top-up" \
  -X POST \
  -d code="AAAA-BBBB-CCCC-DDDD" \
  -d domain=1 \
  -d amount=3 \
  -H "Authorization: Bearer VCaccessToken"

POST https://api.vouchercart.com/v1/top-up

Parameter Type Description
domain string, required Client’s domain name.
code string, required Voucher code.
amount integer, required Top-up amount (in case of monetary vouchers 19.95 GBP becomes 1995).

HTTP Response

{
  "code": "AAAA-BBBB-CCCC-DDDD",
  "current": 2,
  "expirations": [ ... ],
  "monetary": true,
  "multiUsable": true,
  "order": { ... },
  "redeemableOn": [ ... ],
  "redeemed": false,
  "redeemHistory": [ ... ],
  "status": "in_progress",
  "stock": 8
}
Parameter Type Description
code string Voucher code .
current integer Current spent value.
expirations Array<Expiration object> -
monetary boolean Is it the type of monetary voucher?
multiUsable boolean Can voucher be redeemed multiple times?
order Order object -
redeemableOn Array<integer> Consists ID of domains (sales pages) where voucher can be redeemed.
redeemed boolean Has voucher been redeemed already?
redeemHistory Array<RedeemHistory object> -
status string Voucher status (can be: in_progress, completed, refunded, expired, regenerated)
stock integer Value of voucher.

Coupons

Coupon works like simple discount codes. They provide percent discount (e.g. worth 20%) or fixed value (e.g. 100 GBP).

List coupons

HTTP Request

curl "https://api.vouchercart.com/v1/coupons?domainId=8337" \
    -H "Authorization: Bearer VCaccessToken"

GET https://api.vouchercart.com/v1/coupons

Parameter Type Description
domain integer, required Client’s domain ID.

HTTP Response

[
  {
    "couponId": 89899,
    "domainId": 8337,
    "title": "Season sale 25%",
    "terms": "",
    "description": "",
    "type": "percent",
    "amount": 2500,
    "metadata": {
      "ref": "5b11b1w5sk"
    },
    "expiry": {
      "interval": "days",
      "period": 5,
      "type": "period"
    }
  },
  //...
]
Parameter Type Description
couponId string ID of the coupon.
domainId string Client’s domain ID.
title string Title of the coupon.
terms string Terms of the coupon.
description string Description of the coupon.
type string fixed or percent.
amount integer Whether set to fixed, it is amount how much this coupon is worth (e.g. $30 is equal to 3000), percent requires precision up to 2 decimal places away from zero (e.g. 7.50% is equal to 750) but it cannot be higher than 10000.
metadata string[] map, optional You may provide additional data which will identify coupon.
expiry CouponExpiry object -

CouponExpiry object

Expiry object tells how long purchased coupon will last. There are two types of expiration:

Parameter Type Description
interval string months or days
period integer Number of days/months after coupon purchase during which discount may be redeemed.
type string "period"
Parameter Type Description
dateFrom datetime When coupon begins being redeemable
dateTo datetime When coupon ends being redeemable.
type string time

Create a coupon

HTTP Request

curl "https://api.vouchercart.com/v1/coupons" \
    -H "Authorization: Bearer VCaccessToken" \
    -X POST \
    -d domainId="8337" \
    -d title="Season sale 25%" \
    -d terms="" \
    -d description="" \
    -d type="percent" \
    -d amount="2500" \
    -d metadata[ref]="5b11b1w5sk" \
    -d expiry[interval]="days" \
    -d expiry[period]=5 \
    -d expiry[type]="period"

POST https://api.vouchercart.com/v1/coupons

Parameter Type Description
domainId string, required Client’s domain ID.
title string, required Title of the coupon.
terms string, optional Terms of the coupon.
description string, optional Description of the coupon.
type string, required fixed or percent
amount integer Whether set to fixed, it is amount how much this coupon is worth (e.g. $30 is equal to 3000), percent requires precision up to 2 decimal places away from zero (e.g. 7.50% is equal to 750) but it cannot be higher than 10000.
metadata string[] map, optional You may provide additional data which will identify coupon.
expiry CouponExpiry object -

HTTP Response

{
  "couponId": 89899,
  "domainId": 8337,
  "title": "Season sale 25%",
  "terms": "",
  "description": "",
  "type": "percent",
  "amount": 2500,
  "metadata": {
    "ref": "5b11b1w5sk"
  },
  "expiry": {
    "interval": "days",
    "period": 5,
    "type": "period"
  }
}
Parameter Type Description
couponId string ID of the coupon.
domainId string Client’s domain ID.
title string Title of the coupon.
terms string, optional Terms of the coupon.
description string, optional Description of the coupon.
type string fixed or percent.
amount integer Whether set to fixed, it is amount how much this coupon is worth (e.g. $30 is equal to 3000), percent requires precision up to 2 decimal places away from zero (e.g. 7.50% is equal to 750) but it cannot be higher than 10000.
metadata string[] map, optional You may provide additional data which will identify coupon.
expiry CouponExpiry object -

Show coupon

HTTP Request

GET https://api.vouchercart.com/v1/coupon

curl "https://api.vouchercart.com/v1/coupon/:couponId" \
    -H "Authorization: Bearer VCaccessToken"
Parameter Type Description
couponId integer, required ID of the Coupon.

HTTP Response

{
  "couponId": 89899,
  "domainId": 8337,
  "title": "Season sale 25%",
  "terms": "",
  "description": "",
  "type": "percent",
  "amount": 2500,
  "metadata": {
    "ref": "5b11b1w5sk"
  },
  "expiry": {
    "interval": "days",
    "period": 5,
    "type": "period"
  }
}
Parameter Type Description
domainId string Client’s domain ID.
title string Title of the coupon.
terms string, optional Terms of the coupon.
description string, optional Description of the coupon.
type string fixed or percent
amount integer Whether set to fixed, it is amount how much this coupon is worth (e.g. $30 is equal to 3000), percent requires precision up to 2 decimal places away from zero (e.g. 7.50% is equal to 750) but it cannot be higher than 10000.
metadata string[] map, optional You may provide additional data which will identify coupon.
expiry CouponExpiry object -

Discounts

Discount is an instance purchased of Coupon.

Purchase coupon

Creates a discount.

HTTP Request

curl "https://api.vouchercart.com/v1/coupon/89899/purchase" \
    -H "Authorization: Bearer VCaccessToken" \
    -X POST \
    -d payments[0][currency]=GBP \
    -d payments[0][amount]=500 \
    -d payments[0][title]="EPOS CreditCard" \
    -d payments[0][metadata][reference]="0cc18f46-4760-4d34-a1f9-e9a9e1a02353" \
    -d recipients[0][email]="john.doe@example.com" \
    -d recipients[0][label]="John Doe" \
    -d recipients[1][email]="andrew.smith@example.com"

POST https://api.vouchercart.com/v1/coupon/:couponId/purchase

Parameter Type Description
couponId string, required ID of the Coupon.
domainId integer Client’s domain ID.
payments Payment[] objects -
recipients Recipient[] objects List of recipient who should receive a discount code.

Payment Object

Parameter Type Description
amount integer e.g. $20.00 = 2000.
currency string e.g. GBP.
title string Payment method title e.g. provider name.
metadata string[] map Additional data related to payment.

Recipient Object

Parameter Type Description
email string E-mail address of recipient.
label string, optional Name of recipient. When not set then it will use value from email parameter.

HTTP Response

{
  "discountCode": "AAAA-BBBB-CCCC-DDDD",
  "redeemed": false,
  "redeemedAt": null,
  "coupon": {
    "couponId": 89899,
    "domainId": 8337,
    "title": "Season sale 25%",
    "terms": "",
    "description": "",
    "type": "percent",
    "amount": 2500,
    "metadata": {
      "ref": "5b11b1w5sk"
    },
    "expiry": {
      "interval": "days",
      "period": 5,
      "type": "period"
    }
  },
  "recipients": [
    {
      "email": "john.doe@example.com",
      "label": "John Doe"
    },
    {
      "label": null,
      "email": "andrew.smith@example.com"
    }
  ]
}
Parameter Type Description
discountCode string Discount code for the buyer.
redeemed boolean Is discount redeemed?
redeemedAt datetime When was discount redeemed?
coupon Coupon object -
recipients Recipient[] objects List of recipient who should receive a discount code.

Status of discount code

HTTP Request

GET https://api.vouchercart.com/v1/discount/status

curl "https://api.vouchercart.com/v1/discount/status?discountCode=AAAA-BBBB-CCCC-DDDD" \
    -H "Authorization: Bearer VCaccessToken" 
Parameter Type Description
discountCode string Discount code for the buyer

HTTP Response

{
  "discountCode": "AAAA-BBBB-CCCC-DDDD",
  "redeemed": false,
  "redeemedAt": null,
  "coupon": {
    "couponId": 89899,
    "domainId": 8337,
    "title": "Season sale 25%",
    "terms": "",
    "description": "",
    "type": "percent",
    "amount": 2500,
    "metadata": {
      "ref": "5b11b1w5sk"
    },
    "expiry": {
      "interval": "days",
      "period": 5,
      "type": "period"
    }
  },
  "recipients": [
    {
      "email": "john.doe@example.com",
      "label": "John Doe"
    },
    {
      "label": null,
      "email": "andrew.smith@example.com"
    }
  ]
}
Parameter Type Description
discountCode string Discount code for the buyer.
redeemed boolean Is discount redeemed?
redeemedAt datetime When was discount redeemed?
coupon Coupon object -
recipients Recipient[] objects List of recipient who should receive a discount code.

Redeem discount

HTTP Request

POST https://api.vouchercart.com/v1/discount/redeem

curl "https://api.vouchercart.com/v1/discount/redeem" \
    -H "Authorization: Bearer VCaccessToken" \
    -X POST \
    -d discountCode="AAAA-BBBB-CCCC-DDDD"
Parameter Type Description
discountCode string Discount code

HTTP Response

{
  "discountCode": 2218,
  "redeemed": true,
  "redeemedAt": "2016-12-07 14:17:59",
  "coupon": {
    "couponId": 89899,
    "domainId": 8337,
    "title": "Season sale 25%",
    "terms": "",
    "description": "",
    "type": "percent",
    "amount": 2500,
    "metadata": {
      "ref": "5b11b1w5sk"
    },
    "expiry": {
      "interval": "days",
      "period": 5,
      "type": "period"
    }
  },
  "recipients": [
    {
      "email": "john.doe@example.com",
      "label": "John Doe"
    },
    {
      "label": null,
      "email": "andrew.smith@example.com"
    }
  ]
}
Parameter Type Description
discountCode string Discount code for the buyer.
redeemed boolean Is discount redeemed?
redeemedAt datetime When was discount redeemed?
coupon Coupon object -
recipients Recipient[] objects List of recipient who should receive a discount code.