Skip to main content
Discounts allow you to offer promotional pricing to your customers. Create percentage or fixed-amount discounts with optional usage limits, expiration dates, product restrictions, and customer-specific codes.

​
Discount Object

A discount contains the following information: 
{
  "id": "dis_abc123",
  "name": "Summer Sale",
  "code": "SUMMER20",
  "type": "percentage",
  "status": "active",
  "value_off": {
    "raw": 20,
    "formatted": "20%"
  },
  "products": [
    {
      "id": "prd_def456",
      "name": "Premium Course",
      "type": "course",
      "pictures": {
        "thumbnail": "https://cdn.chariow.com/thumb.jpg",
        "cover": "https://cdn.chariow.com/cover.jpg"
      },
      "category": {
        "value": "education",
        "label": "Education"
      },
      "pricing": {
        "type": "one_time",
        "price": {
          "raw": 99.99,
          "formatted": "$99.99"
        }
      },
      "bundle": null
    }
  ],
  "store": {
    "id": "str_xyz789",
    "name": "My Store"
  },
  "customer_email": null,
  "usage_limit": 100,
  "usage_count": 45,
  "start_date": "2025-06-01T00:00:00+00:00",
  "end_date": "2025-08-31T23:59:59+00:00",
  "is_auto_generated": false,
  "created_at": "2025-05-15T10:00:00+00:00",
  "updated_at": "2025-06-20T15:30:00+00:00"
}

​
Discount Types

TypeDescriptionExample
percentagePercentage off the price20% off
fixedFixed amount off$10 off

​
Discount Statuses

StatusDescription
activeDiscount is valid and can be used (within date range and under usage limit)
expiredDiscount has passed its end date or usage limit has been reached

​
Listing Discounts

Retrieve all discounts for your store: 
curl -X GET "https://api.chariow.com/v1/discounts" \
  -H "Authorization: Bearer sk_live_your_api_key"

​
Query Parameters

ParameterTypeDescription
per_pageintegerNumber of discounts per page (max 100, default 15)
cursorstringPagination cursor from previous response
statusstringFilter by status (active, expired)
searchstringSearch by discount code, name, or public ID
start_datestringFilter discounts created from this date (Y-m-d format)
end_datestringFilter discounts created until this date (Y-m-d format)

​
Filtering Examples

# Get active discounts only
curl -X GET "https://api.chariow.com/v1/discounts?status=active" \
  -H "Authorization: Bearer sk_live_your_api_key"

# Search for a specific code or name
curl -X GET "https://api.chariow.com/v1/discounts?search=SUMMER" \
  -H "Authorization: Bearer sk_live_your_api_key"

# Filter by date range
curl -X GET "https://api.chariow.com/v1/discounts?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer sk_live_your_api_key"

# Combine multiple filters
curl -X GET "https://api.chariow.com/v1/discounts?status=active&search=VIP&per_page=50" \
  -H "Authorization: Bearer sk_live_your_api_key"

​
Example Response

{
  "message": "success",
  "data": {
    "data": [
      {
        "id": "dis_abc123",
        "name": "Summer Sale",
        "code": "SUMMER20",
        "type": "percentage",
        "status": "active",
        "value_off": {
          "raw": 20,
          "formatted": "20%"
        },
        "products": [
          {
            "id": "prd_def456",
            "name": "Premium Course"
          }
        ],
        "store": {
          "id": "str_xyz789",
          "name": "My Store"
        },
        "customer_email": null,
        "usage_count": 45,
        "usage_limit": 100,
        "start_date": "2025-06-01T00:00:00+00:00",
        "end_date": "2025-08-31T23:59:59+00:00",
        "is_auto_generated": false,
        "created_at": "2025-05-15T10:00:00+00:00",
        "updated_at": "2025-06-20T15:30:00+00:00"
      }
    ],
    "pagination": {
      "next_cursor": "eyJpZCI6NTB9",
      "prev_cursor": null,
      "has_more": true
    }
  },
  "errors": []
}

​
Getting a Single Discount

Retrieve a specific discount by its public ID: 
curl -X GET "https://api.chariow.com/v1/discounts/dis_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"

​
Applying Discounts at Checkout

Use a discount code when initiating checkout: 
curl -X POST "https://api.chariow.com/v1/checkout" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_abc123",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "phone": {
      "number": "1234567890",
      "country_code": "US"
    },
    "discount_code": "SUMMER20"
  }'

​
Discount Restrictions

Discounts can have various restrictions:
Limit how many times a discount can be used:
{
  "usage_limit": 100,
  "usage_count": 45
}
When usage_count reaches usage_limit, the discount becomes invalid.
Set start and end dates for the discount:
{
  "start_date": "2025-06-01T00:00:00+00:00",
  "end_date": "2025-08-31T23:59:59+00:00"
}
The discount is only valid between these dates.
Limit the discount to specific products:
{
  "products": [
    { "id": "prd_abc123", "name": "Course A" },
    { "id": "prd_def456", "name": "Course B" }
  ]
}
If products is empty, the discount applies to all products.
Limit the discount to a specific customer:
{
  "customer_email": "[email protected]"
}
Only the specified customer can use this discount.

​
Discount Validation

When applying a discount at checkout, it’s automatically validated against these criteria:
  1. Status - Must be active
  2. Date range - Current date must be within start_date and end_date (if specified)
  3. Usage limit - usage_count must not have reached usage_limit (if specified)
  4. Product eligibility - Product must be in the products array (if not empty, applies to all products)
  5. Customer eligibility - Customer email must match customer_email (if specified)
The discount status is automatically updated to expired when:
  • The end_date has passed
  • The current date is before start_date
  • The usage_limit has been reached
If validation fails during checkout, the API will return an appropriate error message.

​
Common Use Cases

Track discount performance for marketing campaigns:
const discounts = await getDiscounts({ status: 'active' });

const campaignStats = discounts.map(d => ({
  code: d.code,
  uses: d.usage_count,
  remaining: d.usage_limit - d.usage_count,
  conversionRate: (d.usage_count / d.usage_limit * 100).toFixed(1) + '%'
}));
Create unique discount codes for affiliates and track usage:
// Fetch discount by public ID
const response = await fetch('https://api.chariow.com/v1/discounts/dis_affiliate123', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

const { data: discount } = await response.json();
console.log(`Affiliate code ${discount.code} has been used ${discount.usage_count} times`);
Create single-use discounts for VIP customers:
{
  "code": "VIP_CUSTOMER_ABC",
  "customer_email": "[email protected]",
  "usage_limit": 1
}

Checkout Guide

Apply discounts during checkout

Discounts API

View the complete Discounts API reference