Vouchers API

Create and manage voucher codes with descriptions, terms, and expiry dates.

GET/v1/vouchers

List your vouchers with optional filtering and pagination.

Required Scope

vouchers:read

Query Parameters

pagenumberPage number (default: 1)

limitnumberItems per page (default: 20, max: 100)

statusstringFilter by status: active, needs_review, expired

codestringSearch by voucher code (case insensitive)

Example Request

curl "https://api.thevirtualmall.co.uk/v1/vouchers?page=1&limit=20" \
  -H "Authorization: Bearer tvm_your_api_key"

POST/v1/vouchers

Create a new voucher code. All new vouchers are created with needs_review status.

Required Scope

vouchers:write

Request Body

codestringThe voucher code (will be uppercased)Required

titlestringDisplay title for the voucher

descriptionstringDetailed description

termsstringTerms and conditions

restrictionsstringUsage restrictions

imageUrlstringURL to an image for the voucher (product photo, promotional banner, etc.)

landingUrlstringURL where the code can be used

discountTypestringpercentage, fixed_amount, free_shipping, bogof, multibuy, other

discountValuenumberDiscount amount (e.g., 15 for 15% or £15 off)

minSpendnumberMinimum spend required

startsAtdatetimeWhen the voucher becomes valid (ISO 8601)

expiresAtdatetimeWhen the voucher expires (ISO 8601)

isSitewidebooleanWhether it works across the entire site

isStackablebooleanWhether it can be combined with other codes

isExclusivebooleanWhether this is an exclusive voucher

Example Request

curl -X POST https://api.thevirtualmall.co.uk/v1/vouchers \
  -H "Authorization: Bearer tvm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SAVE15",
    "title": "15% Off Your Order",
    "description": "Use code SAVE15 at checkout for 15% off",
    "landingUrl": "https://yourshop.com",
    "discountType": "percentage",
    "discountValue": 15,
    "minSpend": 50,
    "isSitewide": true,
    "expiresAt": "2026-03-31T23:59:59Z"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "voucher_abc123",
    "slug": "example-store-save15-m1abc",
    "code": "SAVE15",
    "title": "15% Off Your Order",
    "status": "needs_review",
    "shop": {
      "id": "shop_xyz",
      "slug": "example-store",
      "name": "Example Store"
    },
    "createdAt": "2026-02-06T10:30:00Z"
  }
}

GET/v1/vouchers/:id

Get a specific voucher by ID.

Required Scope

vouchers:read

Example Request

curl https://api.thevirtualmall.co.uk/v1/vouchers/voucher_abc123 \
  -H "Authorization: Bearer tvm_your_api_key"

PUT/v1/vouchers/:id

Update an existing voucher. Only provided fields will be updated. Note: The code field cannot be changed after creation.

Required Scope

vouchers:write

Example Request

curl -X PUT https://api.thevirtualmall.co.uk/v1/vouchers/voucher_abc123 \
  -H "Authorization: Bearer tvm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "expiresAt": "2026-04-30T23:59:59Z"
  }'

DELETE/v1/vouchers/:id

Delete a voucher. This action cannot be undone.

Required Scope

vouchers:write

Example Request

curl -X DELETE https://api.thevirtualmall.co.uk/v1/vouchers/voucher_abc123 \
  -H "Authorization: Bearer tvm_your_api_key"

Example Response

{
  "success": true,
  "data": {
    "deleted": true
  }
}