> ## Documentation Index
> Fetch the complete documentation index at: https://chariow.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Discounts

> Learn how to manage discount codes via the Chariow API

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:

```json theme={null}
{
  "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": "str_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_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:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/discounts" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

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

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

  ```python Python theme={null}
  import requests

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

  discounts = response.json()['data']
  ```
</CodeGroup>

### Query Parameters

| Parameter    | Type    | Description                                             |
| ------------ | ------- | ------------------------------------------------------- |
| `per_page`   | integer | Number of discounts per page (max 100, default 15)      |
| `cursor`     | string  | Pagination cursor from previous response                |
| `status`     | string  | Filter by status (`active`, `expired`)                  |
| `search`     | string  | Search by discount code, name, or public ID             |
| `start_date` | string  | Filter discounts created from this date (Y-m-d format)  |
| `end_date`   | string  | Filter discounts created until this date (Y-m-d format) |

### Filtering Examples

```bash theme={null}
# 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

```json theme={null}
{
  "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",
            "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": "str_xyz789",
          "name": "My Store",
          "logo_url": "https://cdn.chariow.com/stores/xyz789/logo.png",
          "url": "https://mystore.mychariow.com"
        },
        "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:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/discounts/dis_abc123" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

## Applying Discounts at Checkout

Use a discount code when initiating checkout:

```bash theme={null}
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:

<AccordionGroup>
  <Accordion title="Usage Limits" icon="hashtag">
    Limit how many times a discount can be used:

    ```json theme={null}
    {
      "usage_limit": 100,
      "usage_count": 45
    }
    ```

    When `usage_count` reaches `usage_limit`, the discount becomes invalid.
  </Accordion>

  <Accordion title="Date Restrictions" icon="calendar">
    Set start and end dates for the discount:

    ```json theme={null}
    {
      "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.
  </Accordion>

  <Accordion title="Product Restrictions" icon="box">
    Limit the discount to specific products:

    ```json theme={null}
    {
      "products": [
        { "id": "prd_abc123", "name": "Course A" },
        { "id": "prd_def456", "name": "Course B" }
      ]
    }
    ```

    If `products` is empty, the discount applies to all products.
  </Accordion>

  <Accordion title="Customer Restrictions" icon="user">
    Limit the discount to a specific customer:

    ```json theme={null}
    {
      "customer_email": "vip@example.com"
    }
    ```

    Only the specified customer can use this discount.
  </Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="Promotional Campaigns" icon="bullhorn">
    Track discount performance for marketing campaigns:

    ```javascript theme={null}
    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) + '%'
    }));
    ```
  </Accordion>

  <Accordion title="Affiliate Codes" icon="handshake">
    Create unique discount codes for affiliates and track usage:

    ```javascript theme={null}
    // 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`);
    ```
  </Accordion>

  <Accordion title="VIP Customers" icon="star">
    Create single-use discounts for VIP customers:

    ```json theme={null}
    {
      "code": "VIP_CUSTOMER_ABC",
      "customer_email": "vip@example.com",
      "usage_limit": 1
    }
    ```
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Checkout Guide" icon="shopping-cart" href="/en/guides/checkout">
    Apply discounts during checkout
  </Card>

  <Card title="Discounts API" icon="code" href="/api-reference/discounts/list-discounts">
    View the complete Discounts API reference
  </Card>
</CardGroup>