Skip to main content

​
Overview

Vouchers are discount codes that customers can apply during checkout to redeem associated offers. Each voucher is linked to a specific offer and controls how many times it can be used through various usage patterns.

​
Voucher Usage Types

Vouchers support three different usage patterns:

​
Single Use

The voucher can only be used once total, across all customers. Once redeemed, it becomes invalid for everyone.

​
Multiple Use

The voucher can be used multiple times by any customer until it reaches its max_usage_limit.

​
Once Per Customer

Each customer can use the voucher once. The voucher remains valid for other customers until it reaches its max_usage_limit.

​
Voucher Validation

When a voucher is applied, the system validates:
  1. Usage Limits:
    • For single use: Voucher must not have been used before (num_of_usage must be 0)
    • For multiple use: num_of_usage must be less than max_usage_limit
    • For once_per_customer use: Customer must not have redeemed this voucher before
  2. Validity Period: Current time must be between valid_from and valid_to
  3. Associated Offer: The linked offer must be active and not expired
  4. Order Value: If the offer has a minimum order value condition, the cart subtotal must meet it
  5. Offer Conditions: All conditions of the associated offer must be satisfied

​
Apply Voucher to Cart

Applies a voucher code to the customer’s shopping cart. The voucher discount will be calculated based on the associated offer’s discount type and value.

​
Request Body

​
voucher_code
string
required
The voucher code to apply (case-insensitive, will be converted to uppercase)

​
Request Example

{
  "voucher_code": "WELCOME10"
}

​
Response

​
success
string
Success message confirming the voucher was applied

​
Success Response Example

{
  "success": "Voucher WELCOME10 has been successfully applied to your cart"
}

​
Error Responses

​
error
string
Error message explaining why the voucher could not be applied
​
voucher_code
string
Validation error for missing voucher code

​
Missing Voucher Code (400)

{
  "voucher_code": "Voucher code is required"
}

​
Invalid Voucher (400)

{
  "error": "Voucher code does not exist"
}

​
Usage Limit Reached (400)

{
  "error": "Voucher has reached its usage limit"
}

​
Expired Voucher (400)

{
  "error": "Voucher offer has expired"
}

​
Minimum Order Value Not Met (400)

{
  "error": "Your order is below the required minimum purchase"
}

​
Customer Already Used Voucher (400)

For once_per_customer vouchers: 
{
  "error": "You have already used this voucher"
}

​
Offer Conditions Not Met (400)

{
  "error": "Offer is only valid for first-time buyers"
}

{
  "error": "Order value must be more than minimum spend: 50.00"
}

​
Remove Voucher from Cart

Removes the currently applied voucher from the customer’s shopping cart.

​
Response

​
success
string
Success message confirming the voucher was removed
​
error
string
Error message if no voucher is currently applied

​
Success Response Example

{
  "success": "Applied voucher has been successfully removed"
}

​
Error Response Example (400)

{
  "error": "No applied voucher to remove"
}

​
Voucher Model Structure

Vouchers are returned as part of the Offers endpoint response in the voucher_set array.
​
id
integer
Unique identifier for the voucher
​
name
string
Display name of the voucher
​
description
string
Detailed description of what the voucher offers
​
code
string
Unique voucher code that customers use to redeem the offer (always uppercase)
​
usage_type
string
Usage pattern: single, multiple, or once_per_customer
​
max_usage_limit
integer
Maximum number of times this voucher can be used in total
​
num_of_usage
integer
Current number of times this voucher has been used
​
valid_from
datetime
Start date and time when the voucher becomes valid
​
valid_to
datetime
End date and time when the voucher expires
​
is_active
boolean
Whether the voucher is currently active

​
Redemption Flow

  1. Customer enters voucher code at checkout
  2. System validates voucher:
    • Checks if voucher exists and is active
    • Verifies usage limits based on usage_type
    • Confirms voucher is within validity period
    • Validates associated offer conditions
  3. Discount is applied to cart if all validations pass
  4. Usage count is updated when order is completed:
    • num_of_usage is incremented
    • Redemption is recorded in RedeemedVoucher table with customer and timestamp
  5. Offer discount tracking is updated:
    • total_discount_offered on the offer is increased by the discount amount
    • Customer is added to claimed_by list on the offer

​
Best Practices

​
For Single-Use Vouchers

  • Set usage_type to single
  • Set max_usage_limit to 1
  • Use for exclusive or high-value promotions

​
For Multi-Use Vouchers

  • Set usage_type to multiple
  • Set appropriate max_usage_limit based on campaign budget
  • Monitor num_of_usage to track campaign performance

​
For Once-Per-Customer Vouchers

  • Set usage_type to once_per_customer
  • Set max_usage_limit based on expected customer reach
  • Ideal for welcome offers and customer acquisition campaigns
  • Requires customer authentication to track usage
  • Offers - View available offers and their associated vouchers
  • Cart - View cart with applied discounts

Build docs developers (and LLMs) love

Get started for freeTalk to us