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
• Available Paths
• Authentication
• Properties
• Sample Voucher JSON

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

Authentication

The Voucher resource is available with all three authentication types:

Authentication type	Available operations
Admin	All operations
Privileged	All operations, with an access token holding the chain scope
End-user	GET only, restricted to the authenticated user's own vouchers

End-user access

When a voucher is retrieved with end-user authentication:

• Only vouchers belonging to the authenticated user are returned. Requesting another user's voucher, by ID or by key, returns resource_not_found (544).
• GET /resources/vouchers returns only vouchers with status generated or claimed by default. Redeemed vouchers can be retrieved by filtering explicitly, for example GET /resources/vouchers?status=redeemed. Retrieving a single voucher by ID or key is not restricted by status.
• The creating_user, db_redeemed_date, deleted and user properties are omitted from the response.
• POST, PUT, PATCH and DELETE are not available and return resource_not_found (544).

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:00+00:00",
  "creating_user": null,
  "currency": null,
  "db_redeemed_date": null,
  "deleted": false,
  "description": null,
  "discount_ratio": 0.0,
  "expiry_date": "2025-02-15T23:59:59+00:00",
  "generating_return_transaction": null,
  "honour_code": null,
  "id": 67890,
  "image_url": null,
  "key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
  "last_modified_date": "2025-01-15T10:30:00+00:00",
  "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.