Back to Home

Introduction

Welcome to The Virtual Mall API. This API allows shops to manage their presence on The Virtual Mall - push offers, vouchers, and keep your shop profile up to date.

Base URL

https://api.thevirtualmall.co.uk/v1

Authentication

All API requests require authentication using an API key. Include your key in the Authorization header:

Authorization: Bearer tvm_your_api_key

See the Authentication guide to learn how to get an API key.

Response Format

All responses are JSON and follow a consistent structure:

{
  "success": true,
  "data": { ... },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-02-06T12:00:00Z"
  }
}

Content Review

When you create offers or vouchers via the API, they are submitted with a needs_review status. Our team will review and approve content before it goes live.

Error Handling

When an error occurs, the response includes an error object:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "url", "message": "Must be a valid URL" }
    ]
  }
}

Error Codes

UNAUTHORIZED401Missing or invalid API key
FORBIDDEN403Key lacks required scope
RATE_LIMITED429Rate limit exceeded
VALIDATION_ERROR400Request validation failed
NOT_FOUND404Resource not found
SHOP_NOT_FOUND404Shop not found

Quick Example

Create an offer for your shop:

curl -X POST https://api.thevirtualmall.co.uk/v1/offers \
  -H "Authorization: Bearer tvm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "20% Off Everything",
    "description": "Save 20% across our entire range",
    "landingUrl": "https://yourshop.com/sale",
    "discountType": "percentage",
    "discountValue": 20,
    "expiresAt": "2026-03-01"
  }'