Back to Home

Offers API

Create and manage special offers, discounts, and promotions for your shop.

GET/v1/offers

List your offers with optional filtering and pagination.

Required Scope

offers:read

Query Parameters

pagenumberPage number (default: 1)
limitnumberItems per page (default: 20, max: 100)
statusstringFilter by status: active, needs_review, expired

Example Request

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

Create a new offer. All new offers are created with needs_review status.

Required Scope

offers:write

Request Body

titlestringOffer titleRequired
descriptionstringDetailed description
termsstringTerms and conditions
imageUrlstringURL to an image for the offer (product photo, promotional banner, etc.)
landingUrlstringURL where the offer applies
discountTypestringpercentage, fixed_amount, free_shipping, bogof, multibuy, other
discountValuenumberDiscount amount (e.g., 20 for 20% or £20 off)
minSpendnumberMinimum spend required
startsAtdatetimeWhen the offer starts (ISO 8601)
expiresAtdatetimeWhen the offer expires (ISO 8601)
isExclusivebooleanWhether this is an exclusive offer

Example Request

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-01T23:59:59Z"
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "offer_abc123",
    "slug": "example-store-20-off-everything-m1abc",
    "title": "20% Off Everything",
    "status": "needs_review",
    "shop": {
      "id": "shop_xyz",
      "slug": "example-store",
      "name": "Example Store"
    },
    "createdAt": "2026-02-06T10:30:00Z"
  }
}
GET/v1/offers/:id

Get a specific offer by ID.

PUT/v1/offers/:id

Update an existing offer. Only provided fields will be updated.

DELETE/v1/offers/:id

Delete an offer. This action cannot be undone.