Apply Voucher

​

Overview

​

Apply Voucher Code

​

Request

curl -X POST https://api.example.com/api/v1/cart/apply/vouchers/ \
  -H "Content-Type: application/json" \
  -H "Cookie: sessionid=your_session_id" \
  -d '{
    "voucher_code": "SAVE20"
  }'

​

Response

{
  "success": "Voucher applied successfully"
}

​

Error Responses

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

{
  "error": "Invalid voucher code"
}

{
  "error": "Voucher has expired"
}

{
  "error": "No item in your cart is eligible for the voucher offer"
}

• "Minimum purchase amount not met"
• "Voucher usage limit reached"
• "Voucher not valid for your account"
• "Voucher is not currently active"

​

Remove Voucher

​

Request

curl -X DELETE https://api.example.com/api/v1/cart/apply/vouchers/ \
  -H "Cookie: sessionid=your_session_id"

​

Response

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

​

Error Responses

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

​

Voucher Validation Rules

​

Basic Validation

• Voucher code must exist and be active
• Voucher must not be expired
• Customer must meet eligibility requirements

​

Purchase Requirements

• Minimum purchase amount (if configured)
• Specific products or categories (for product-specific vouchers)
• Customer group or account restrictions

​

Usage Limits

• Total usage limit across all customers
• Per-customer usage limit
• Date range restrictions

​

Voucher Types

​

Product-Specific Vouchers

• Only eligible items in cart receive discount
• Items with existing automatic offers are excluded
• Discount calculated per eligible item

​

Order-Level Vouchers

• Percentage discount: X% off the subtotal
• Fixed amount discount: $X off the subtotal (capped at subtotal amount)

​

Discount Calculation

​

Product Vouchers

• Percentage: item_price × quantity × (discount_percentage / 100)
• Fixed amount: min(discount_amount, item_total)

​

Order Vouchers

• Percentage: subtotal × (discount_percentage / 100)
• Fixed amount: min(discount_amount, subtotal)

​

Voucher Storage

{
  "id": 123,
  "code": "SAVE20",
  "offer": "20% Off Electronics",
  "offer_type": "product",
  "discount_type": "percentage"
}

• Display voucher details to the user
• Calculate discounts on eligible items
• Revalidate voucher during cart refresh
• Track voucher usage

​

Automatic Revalidation

• Cart items are added, updated, or removed
• Cart is refreshed (every 5 minutes)
• Prices or availability change

• Voucher is automatically removed
• Customer is notified (implementation-dependent)
• Cart totals are recalculated without discount

​

Interaction with Offers

​

Automatic Offers

• Items with automatic offers are excluded from product-specific voucher discounts
• Order-level vouchers apply to the subtotal (including items with offers)

​

Offer Priority

1. Automatic product offers (highest priority)
2. Product-specific voucher discounts
3. Order-level voucher discounts

​

Multiple Vouchers

• Applying a new voucher replaces the existing one
• No stacking of voucher discounts
• To change vouchers, remove current voucher and apply new one

​

Best Practices

​

Code Formatting

• Voucher codes are automatically converted to uppercase
• Leading/trailing whitespace is trimmed
• Use clear, memorable codes (e.g., SAVE20, WELCOME10)

​

Error Handling

• Always check error messages for specific validation failures
• Display clear error messages to users
• Allow users to easily remove and try different codes

​

User Experience

• Show applied voucher details in cart summary
• Display discount amount clearly
• Allow easy removal of vouchers
• Notify users if voucher becomes invalid

​

Related Endpoints

• GET /api/v1/cart/ - View cart with applied discounts
• PUT /api/v1/cart/items/ - Update items (triggers discount recalculation)