Skip to main content

​
Overview

The Offers API provides access to active promotional campaigns that can be applied to products or orders. Offers support various discount types and can be configured with specific eligibility conditions based on customers, products, categories, or order values.

​
Offer System

​
Offer Types

Offers can be applied at two different levels:
  • Product-level offers: Apply to specific products or categories and are automatically applied for eligible products and customers
  • Order-level offers: Apply to the entire order and are applied at checkout

​
Discount Types

Offers support the following discount types:
  • Percentage: A certain percentage off the price (e.g., 15% off)
  • Fixed: A fixed amount off the price (e.g., $10 off)

​
Offer Conditions

Offers can have multiple conditions that determine when they can be applied:

​
Customer Group Conditions

  • All Customers: Offer is available to everyone
  • First Time Buyers: Restricted to customers making their first purchase

​
Product Conditions (Product-level offers only)

  • Specific Products: Offer applies only to selected products
  • Specific Categories: Offer applies to all products in selected categories

​
Order Conditions (Order-level offers only)

  • Minimum Order Value: Order subtotal must meet or exceed the specified amount

​
Voucher Requirements

Offers can optionally require a voucher code for redemption. When requires_voucher is true, customers must provide a valid voucher code to apply the offer.

​
Discount Limits

Each offer has a max_discount_allowed that caps the total discount amount that can be given across all uses of the offer. The total_discount_offered tracks how much discount has been applied so far.

​
Get Offers

Retrieves all active offers. Returns offers that are currently within their validity period and have is_active set to true.

​
Response

​
id
integer
Unique identifier for the offer
​
title
string
Display name of the offer
​
store
integer
ID of the store this offer is linked to (null if applicable to all stores)
​
offer_type
string
Type of offer: product for product-level or order for order-level
​
discount_type
string
Type of discount: percentage or fixed
​
discount_value
decimal
The discount amount (percentage value for percentage discounts, monetary amount for fixed discounts)
​
requires_voucher
boolean
Whether a voucher code is required to redeem this offer
​
total_discount_offered
decimal
Total discount amount that has been applied using this offer
​
max_discount_allowed
decimal
Maximum total discount that can be given across all uses of this offer
​
valid_from
datetime
Start date and time when the offer becomes active
​
valid_to
datetime
End date and time when the offer expires
​
is_active
boolean
Whether the offer is currently active
​
created
datetime
Timestamp when the offer was created
​
updated
datetime
Timestamp when the offer was last updated
​
claimed_by
array
Array of customer IDs who have claimed this offer
​
conditions
array
Array of condition objects that define eligibility criteria
​
voucher_set
array
Array of voucher objects associated with this offer

​
Response Example

[
  {
    "id": 1,
    "title": "Summer Sale 2026",
    "store": null,
    "offer_type": "product",
    "discount_type": "percentage",
    "discount_value": "15.00",
    "requires_voucher": false,
    "total_discount_offered": "150.00",
    "max_discount_allowed": "5000.00",
    "valid_from": "2026-06-01T00:00:00Z",
    "valid_to": "2026-08-31T23:59:59Z",
    "is_active": true,
    "created": "2026-05-15T10:00:00Z",
    "updated": "2026-06-01T12:30:00Z",
    "claimed_by": [23, 45, 67],
    "conditions": [
      {
        "id": 1,
        "condition_type": "specific_categories",
        "eligible_categories": [5, 8, 12]
      }
    ],
    "voucher_set": []
  },
  {
    "id": 2,
    "title": "First Order Discount",
    "store": null,
    "offer_type": "order",
    "discount_type": "fixed",
    "discount_value": "10.00",
    "requires_voucher": true,
    "total_discount_offered": "450.00",
    "max_discount_allowed": "1000.00",
    "valid_from": "2026-01-01T00:00:00Z",
    "valid_to": "2026-12-31T23:59:59Z",
    "is_active": true,
    "created": "2025-12-15T10:00:00Z",
    "updated": "2026-03-01T08:15:00Z",
    "claimed_by": [12, 34, 56, 78, 90],
    "conditions": [
      {
        "id": 2,
        "condition_type": "customer_groups",
        "eligible_customers": "first_time_buyers"
      },
      {
        "id": 3,
        "condition_type": "min_order_value",
        "min_order_value": "50.00"
      }
    ],
    "voucher_set": [
      {
        "id": 1,
        "name": "Welcome Voucher",
        "description": "Get $10 off your first order over $50",
        "code": "WELCOME10",
        "usage_type": "once_per_customer",
        "max_usage_limit": 1000,
        "num_of_usage": 45,
        "valid_from": "2026-01-01T00:00:00Z",
        "valid_to": "2026-12-31T23:59:59Z",
        "is_active": true
      }
    ]
  }
]

​
Offer Validation Logic

When an offer is applied (either automatically for product-level offers or via voucher for order-level offers), the system validates:
  1. Time Period: Offer must be active and within its validity period (valid_from to valid_to)
  2. Customer Eligibility: Customer must meet any customer group conditions
  3. Product/Category Eligibility: For product-level offers, the product must be in the eligible products or categories
  4. Order Value: For order-level offers, the order subtotal must meet the minimum order value requirement
  5. Voucher Validity: If a voucher is required, it must be valid and within usage limits
  6. Discount Limit: The offer must not have exceeded its max_discount_allowed
  • Vouchers - Apply and manage voucher codes

Build docs developers (and LLMs) love

Get started for freeTalk to us