Discounts

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/products/thumb.jpg",
        "cover": "https://cdn.chariow.com/products/cover.jpg"
      },
      "category": {
        "value": "education_and_learning",
        "label": "Education and Learning"
      },
      "pricing": {
        "type": "one_time",
        "price": {
          "value": 99,
          "formatted": "$99.00",
          "short": "99",
          "currency": "USD"
        },
        "effective": {
          "value": 99,
          "formatted": "$99.00",
          "short": "99",
          "currency": "USD"
        }
      },
      "bundle": null,
      "metadata": null
    }
  ],
  "store": {
    "id": "store_xyz789",
    "name": "My Store",
    "logo_url": "https://cdn.chariow.com/stores/xyz789/logo.png",
    "url": "https://mystore.mychariow.com"
  },
  "customer_email": null,
  "usage_limit": 100,
  "usage_limit_per_customer": 1,
  "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

Type	Description	Example
`percentage`	Percentage off the price	20% off
`fixed`	Fixed amount off	$10 off

Discount Statuses

Status	Description
`active`	Discount is valid and can be used (within date range and under usage limit)
`expired`	Discount 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"

const response = await fetch('https://api.chariow.com/v1/discounts', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

const { data } = await response.json();

import requests

response = requests.get(
    'https://api.chariow.com/v1/discounts',
    headers={'Authorization': 'Bearer sk_live_your_api_key'}
)

discounts = response.json()['data']

Query Parameters

Parameter	Type	Description
`per_page`	integer	Number of discounts per page (max 100, default 10)
`cursor`	string	Pagination cursor from previous response
`status`	string	Filter by status (`active`, `expired`)
`search`	string	Search by discount code, name, or public ID
`from`	string	Only discounts created on or after this date (Y-m-d format). Send it with `to`
`to`	string	Only discounts created on or before this date (Y-m-d format). Send it with `from`
`period`	string	Preset creation date range used instead of `from` and `to`: `today`, `yesterday`, `last7days`, `last30days`, `thisWeek`, `lastWeek`, `thisMonth`, `lastMonth`, `thisYear`, `lastYear`

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?from=2025-01-01&to=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

{
  "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",
          "type": "course",
          "pictures": {
            "thumbnail": "https://cdn.chariow.com/products/thumb.jpg",
            "cover": "https://cdn.chariow.com/products/cover.jpg"
          },
          "category": {
            "value": "education_and_learning",
            "label": "Education and Learning"
          },
          "pricing": {
            "type": "one_time",
            "price": {
              "value": 99,
              "formatted": "$99.00",
              "short": "99",
              "currency": "USD"
            },
            "effective": {
              "value": 99,
              "formatted": "$99.00",
              "short": "99",
              "currency": "USD"
            }
          },
          "bundle": null,
          "metadata": null
        }
      ],
      "store": {
        "id": "store_xyz789",
        "name": "My Store",
        "logo_url": "https://cdn.chariow.com/stores/xyz789/logo.png",
        "url": "https://mystore.mychariow.com"
      },
      "customer_email": null,
      "usage_limit": 100,
      "usage_limit_per_customer": 1,
      "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"
    }
  ],
  "pagination": {
    "count": 1,
    "path": "https://api.chariow.com/v1/discounts",
    "per_page": 10,
    "next_cursor": null,
    "next_page_url": null,
    "prev_cursor": null,
    "prev_page_url": null,
    "has_more_pages": false,
    "has_pages": false
  }
}

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"

const response = await fetch('https://api.chariow.com/v1/discounts/dis_abc123', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

const { data } = await response.json();

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": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": {
      "number": "1234567890",
      "country_code": "US"
    },
    "discount_code": "SUMMER20"
  }'

Discount Restrictions

Discounts can have various restrictions:

Usage Limits

Limit how many times a discount can be used:

{
  "usage_limit": 100,
  "usage_limit_per_customer": 1,
  "usage_count": 45
}

When usage_count reaches usage_limit, the discount is rejected at checkout. usage_limit_per_customer caps the successful uses by a single customer email.

Date Restrictions

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.

Product Restrictions

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.

Customer Restrictions

Limit the discount to a specific customer:

{
  "customer_email": "vip@example.com"
}

Only the specified customer can use this discount.

Discount Validation

When applying a discount at checkout, it’s automatically validated against these criteria:

Status - Must be active
Date range - Current date must be within start_date and end_date (if specified)
Usage limit - usage_count must not have reached usage_limit (if specified)
Per-customer limit - The customer must not have reached usage_limit_per_customer successful uses (if specified)
Product eligibility - Product must be in the products array (if not empty, applies to all products)
Customer eligibility - Customer email must match customer_email (if specified)
Fixed amount - A fixed discount cannot exceed the product’s current price

The discount status changes to expired once its end_date has passed (a scheduled task updates it). A discount that has reached its usage limit, or whose start_date is still in the future, keeps its active status but is rejected at checkout. If validation fails during checkout, the API will return an appropriate error message.

Common Use Cases

Promotional Campaigns

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) + '%'
}));

Affiliate Codes

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`);

VIP Customers

Create single-use discounts for VIP customers:

{
  "code": "VIP_CUSTOMER_ABC",
  "customer_email": "vip@example.com",
  "usage_limit": 1
}

Checkout Guide

Apply discounts during checkout

Discounts API

View the complete Discounts API reference

Introduction

Guides

MCP Integration

n8n Integration

Resources

Discount Object

Discount Types

Discount Statuses

Listing Discounts

Query Parameters

Filtering Examples

Example Response

Getting a Single Discount

Applying Discounts at Checkout

Discount Restrictions

Discount Validation

Common Use Cases

Checkout Guide

Discounts API

​Discount Object

​Discount Types

​Discount Statuses

​Listing Discounts

​Query Parameters

​Filtering Examples

​Example Response

​Getting a Single Discount

​Applying Discounts at Checkout

​Discount Restrictions

​Discount Validation

​Common Use Cases

​Related Resources

Checkout Guide

Discounts API

Discount Object

Discount Types

Discount Statuses

Listing Discounts

Query Parameters

Filtering Examples

Example Response

Getting a Single Discount

Applying Discounts at Checkout

Discount Restrictions

Discount Validation

Common Use Cases

Related Resources