Link Search Menu Expand Document

Voucher Resource

The Voucher resource represents a digital entitlement that can be redeemed for discounts or rewards within the Spaaza platform. Each voucher has properties for amount information, status tracking, campaign association, and redemption details.

Contents

Introduction

The Voucher resource represents a digital entitlement that can be redeemed for discounts or rewards within the Spaaza platform. Vouchers support multiple types through a discriminator mapping system:

  • basket - Fixed amount discount vouchers
  • basket_pct - Percentage-based discount vouchers
  • honour - Third-party honour code vouchers
  • basket_fixed_unit - Fixed unit basket vouchers

Vouchers have a comprehensive status tracking system with three possible states: generated, claimed, and redeemed. Once a voucher reaches redeemed status, it cannot be changed to any other status.

Available Paths

Single Resource Operations

  • GET /resources/voucher/{id} - Retrieve a voucher by ID
  • GET /resources/voucher?{identifier parameter}={value} - Retrieve a voucher (by identifier parameter)
  • POST /resources/voucher - Create a new voucher
  • PATCH /resources/voucher/{id} - Update a voucher by ID
  • PATCH /resources/voucher?{identifier parameter}={value} - Update a voucher (by identifier parameter)
  • PUT /resources/voucher/{id} - Replace a voucher by ID
  • PUT /resources/voucher?{identifier parameter}={value} - Replace a voucher (by identifier parameter)
  • DELETE /resources/voucher/{id} - Delete a voucher by ID
  • DELETE /resources/voucher?{identifier parameter}={value} - Delete a voucher (by identifier parameter)

Multiple Resource Operations

  • GET /resources/vouchers - Retrieve multiple vouchers with filtering, sorting, and pagination support

Properties

Name Description Standard Attributes(details) Spaaza Vendor Attributes(details)
amount Voucher amount type: float
nullable: true		 recursionLevel: 1
operations: [“post”, “put”, “patch”]
amount_redeemed The amount of the voucher which was redeemed type: float
nullable: true		 recursionLevel: 2
operations: [“post”, “put”, “patch”]
basket Basket which redeemed the voucher type: object
nullable: true
required: id		 recursionLevel: 2
immutable: true
basket_owner_code_exclusive If set, a locked voucher can only be redeemed using this retailer_basket_code type: string
nullable: true
maxLength: 255		 recursionLevel: 2
immutable: false
operations: [“post”, “put”, “patch”]
campaign Campaign with which the voucher is associated type: object
nullable: false
required: id		 recursionLevel: 1
filter-property: true
sort-by-property: true
immutable: true
operations: [“post”, “get”]
created_date Voucher created date type: date-time
nullable: false
readOnly: true		 recursionLevel: 2
immutable: true
sort-by-property: true
creating_user User to whom the voucher belongs type: object
nullable: true
required: id		 recursionLevel: 2
filter-property: true
immutable: true
operations: [“get”, “delete”]
currency Currency associated with the voucher type: object
nullable: true
required: id		 recursionLevel: 2
immutable: true
db_redeemed_date Voucher redeemed date in the Spaaza database type: date-time
readOnly: true		 recursionLevel: 2
immutable: true
deleted Voucher deleted. Once deleted, a voucher cannot be undeleted. type: boolean
nullable: false		 recursionLevel: 1
operations: [“get”]
description Voucher description type: string
nullable: true
maxLength: 4096		 recursionLevel: 2
discount_ratio The discount percentage associated with the voucher type: float
nullable: true
readOnly: true
minimum: 0
maximum: 1		 recursionLevel: 2
operations: [“post”, “put”, “patch”]
expiry_date Date the voucher expires type: date-time
nullable: true
readOnly: false		 recursionLevel: 1
immutable: false
sort-by-property: true
operations: [“post”, “put”, “patch”, “get”]
required-in: [“post”]
generating_return_transaction Return transaction which caused the voucher to be created type: object
nullable: true
required: id		 recursionLevel: 2
immutable: true
honour_code Voucher honour code type: string
nullable: true
maxLength: 255		 recursionLevel: 2
immutable: false
operations: [“post”, “put”, “patch”]
id Voucher Spaaza ID type: integer
readOnly: true
nullable: false		 recursionLevel: 0
filter-property: true
sort-by-property: true
operations: [“get”, “put”, “patch”, “delete”]
image_url Voucher image URL type: string
nullable: true
maxLength: 4096		 recursionLevel: 2
key Voucher key type: string
readOnly: true
nullable: false
minLength: 64
maxLength: 64		 recursionLevel: 1
filter-property: true
identifier: true
immutable: true
operations: [“get”, “delete”]
last_modified_date Voucher last modified date type: date-time
nullable: false
readOnly: true		 recursionLevel: 2
immutable: true
sort-by-property: true
locked_until Voucher locked until date type: date-time
nullable: false
readOnly: false		 recursionLevel: 2
immutable: true
locking_code Voucher locking code type: string
nullable: true
maxLength: 255		 recursionLevel: 2
immutable: false
operations: [“post”, “put”, “patch”]
notes Voucher notes type: string
nullable: true
maxLength: 4096		 recursionLevel: 2
parent_voucher The parent voucher, if this voucher was created to replace a previous one. type: object
nullable: true		 recursionLevel: 2
filter-property: true
immutable: true
operations: [“get”]
redeemed_date Voucher redeemed date type: date-time
readOnly: true		 recursionLevel: 2
immutable: true
redemption_exclusive_business Business (branch) which the voucher can only be redeemed at type: object
nullable: true
required: id		 recursionLevel: 2
shopify_discount_code Shopify Discount Code associated with the voucher type: string
nullable: true
maxLength: 128		 recursionLevel: 2
shopify_discount_code_id Shopify Discount Code ID associated with the voucher type: string
nullable: true
maxLength: 128		 recursionLevel: 2
shopify_price_rule_id Shopify Price Rule ID associated with the voucher type: integer
format: int64
nullable: true		 recursionLevel: 2
status Voucher status: generated, claimed, redeemed. Once status is redeemed, it cannot be changed. type: string
enum: [“generated”, “claimed”, “redeemed”]
nullable: false		 recursionLevel: 1
filter-property: true
sort-by-property: true
operations: [“post”, “put”, “patch”, “get”, “delete”]
required-in: [“post”]
task Task which caused the voucher to be created type: object
nullable: true
required: id		 recursionLevel: 2
immutable: true
text Voucher text type: string
nullable: true
maxLength: 255		 recursionLevel: 2
immutable: false
operations: [“post”, “put”, “patch”]
third_party_id Third party ID associated with the voucher type: integer
format: int64
nullable: true
readOnly: true		 recursionLevel: 2
title Voucher title type: string
nullable: true
maxLength: 255		 recursionLevel: 2
immutable: false
operations: [“post”, “put”, “patch”]
type Voucher type type: string
nullable: false
minLength: 1
maxLength: 255		 recursionLevel: 1
filter-property: true
immutable: true
operations: [“post”, “get”]
user User to whom the voucher belongs type: object
nullable: false
required: id		 recursionLevel: 1
filter-property: true
sort-by-property: true
immutable: true
operations: [“post”, “get”, “delete”]

Property Notes

  • Voucher Types: Vouchers support four types through a discriminator mapping system: basket (fixed amount), basket_pct (percentage-based), honour (third-party honour codes), and basket_fixed_unit (fixed unit basket vouchers).
  • Status Values: Vouchers have three possible status values: generated (created and available), claimed (claimed but not redeemed), and redeemed (redeemed and immutable). Once redeemed, status cannot be changed.
  • Identifier Properties: The key property can be used as an identifier parameter for single resource operations instead of the numeric id. Properties marked with identifier: true can be used as identifier parameters.
  • Filter Properties: Properties marked with filter-property: true can be used to filter results when retrieving multiple vouchers.
  • Recursion Levels: The recursionLevel attribute controls at which API response detail levels each property is included.
  • Operations: The operations attribute indicates which HTTP methods can use each property as a parameter.

Sample Voucher JSON 

{
  "amount": 10.0,
  "amount_redeemed": null,
  "basket": null,
  "basket_owner_code_exclusive": null,
  "campaign": {
    "id": 12345
  },
  "created_date": "2025-01-15T10:30:00Z",
  "creating_user": null,
  "currency": null,
  "db_redeemed_date": null,
  "deleted": false,
  "description": null,
  "discount_ratio": 0.0,
  "expiry_date": "2025-02-15T23:59:59Z",
  "generating_return_transaction": null,
  "honour_code": null,
  "id": 67890,
  "image_url": null,
  "key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
  "last_modified_date": "2025-01-15T10:30:00Z",
  "locked_until": null,
  "locking_code": null,
  "notes": null,
  "parent_voucher": null,
  "redeemed_date": null,
  "redemption_exclusive_business": null,
  "shopify_discount_code": null,
  "shopify_discount_code_id": null,
  "shopify_price_rule_id": null,
  "status": "generated",
  "task": null,
  "text": "€10 discount voucher",
  "third_party_id": null,
  "title": "Welcome Bonus",
  "type": "basket",
  "user": {
    "id": 54321
  }
}

This example shows a typical Voucher resource with amount, status, campaign association, and expiry details.