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

# Réductions

> Apprenez à gérer les codes de réduction via l'API Chariow

Les réductions vous permettent d'offrir des tarifs promotionnels à vos clients. Créez des réductions en pourcentage ou à montant fixe avec des limites d'utilisation optionnelles, des dates d'expiration, des restrictions de produits et des codes spécifiques aux clients.

## Objet Réduction

Une réduction contient les informations suivantes :

```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"
}
```

## Types de Réduction

| Type         | Description                          | Exemple           |
| ------------ | ------------------------------------ | ----------------- |
| `percentage` | Pourcentage de réduction sur le prix | 20% de réduction  |
| `fixed`      | Montant fixe de réduction            | 10\$ de réduction |

## Statuts de Réduction

| Statut    | Description                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------ |
| `active`  | La réduction est valide et peut être utilisée (dans la plage de dates et sous la limite d'utilisation) |
| `expired` | La réduction a dépassé sa date de fin ou la limite d'utilisation a été atteinte                        |

## Liste des Réductions

Récupérez toutes les réductions de votre boutique :

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

### Paramètres de Requête

| Paramètre    | Type    | Description                                                         |
| ------------ | ------- | ------------------------------------------------------------------- |
| `per_page`   | integer | Nombre de réductions par page (max 100, par défaut 15)              |
| `cursor`     | string  | Curseur de pagination de la réponse précédente                      |
| `status`     | string  | Filtrer par statut (`active`, `expired`)                            |
| `search`     | string  | Rechercher par code de réduction, nom ou ID public                  |
| `start_date` | string  | Filtrer les réductions créées à partir de cette date (format Y-m-d) |
| `end_date`   | string  | Filtrer les réductions créées jusqu'à cette date (format Y-m-d)     |

### Exemples de Filtrage

```bash theme={null}
# Obtenir uniquement les réductions actives
curl -X GET "https://api.chariow.com/v1/discounts?status=active" \
  -H "Authorization: Bearer sk_live_your_api_key"

# Rechercher un code ou un nom spécifique
curl -X GET "https://api.chariow.com/v1/discounts?search=SUMMER" \
  -H "Authorization: Bearer sk_live_your_api_key"

# Filtrer par plage de dates
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"

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

### Exemple de Réponse

```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": []
}
```

## Obtenir une Réduction Spécifique

Récupérez une réduction spécifique par son ID public :

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

## Appliquer des Réductions lors du Paiement

Utilisez un code de réduction lors de l'initiation du paiement :

```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"
  }'
```

## Restrictions de Réduction

Les réductions peuvent avoir diverses restrictions :

<AccordionGroup>
  <Accordion title="Limites d'Utilisation" icon="hashtag">
    Limitez le nombre de fois qu'une réduction peut être utilisée :

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

    Lorsque `usage_count` atteint `usage_limit`, la réduction devient invalide.
  </Accordion>

  <Accordion title="Restrictions de Date" icon="calendar">
    Définissez des dates de début et de fin pour la réduction :

    ```json theme={null}
    {
      "start_date": "2025-06-01T00:00:00+00:00",
      "end_date": "2025-08-31T23:59:59+00:00"
    }
    ```

    La réduction n'est valide qu'entre ces dates.
  </Accordion>

  <Accordion title="Restrictions de Produit" icon="box">
    Limitez la réduction à des produits spécifiques :

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

    Si `products` est vide, la réduction s'applique à tous les produits.
  </Accordion>

  <Accordion title="Restrictions de Client" icon="user">
    Limitez la réduction à un client spécifique :

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

    Seul le client spécifié peut utiliser cette réduction.
  </Accordion>
</AccordionGroup>

## Validation des Réductions

Lors de l'application d'une réduction au moment du paiement, elle est automatiquement validée selon ces critères :

1. **Statut** - Doit être `active`
2. **Plage de dates** - La date actuelle doit être comprise entre `start_date` et `end_date` (si spécifié)
3. **Limite d'utilisation** - `usage_count` ne doit pas avoir atteint `usage_limit` (si spécifié)
4. **Éligibilité du produit** - Le produit doit être dans le tableau `products` (si non vide, s'applique à tous les produits)
5. **Éligibilité du client** - L'email du client doit correspondre à `customer_email` (si spécifié)

Le statut de la réduction est automatiquement mis à jour à `expired` lorsque :

* La `end_date` est dépassée
* La date actuelle est antérieure à `start_date`
* La `usage_limit` a été atteinte

Si la validation échoue lors du paiement, l'API renverra un message d'erreur approprié.

## Cas d'Utilisation Courants

<AccordionGroup>
  <Accordion title="Campagnes Promotionnelles" icon="bullhorn">
    Suivez les performances des réductions pour les campagnes marketing :

    ```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="Codes d'Affiliation" icon="handshake">
    Créez des codes de réduction uniques pour les affiliés et suivez leur utilisation :

    ```javascript theme={null}
    // Récupérer une réduction par son ID public
    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(`Le code d'affiliation ${discount.code} a été utilisé ${discount.usage_count} fois`);
    ```
  </Accordion>

  <Accordion title="Clients VIP" icon="star">
    Créez des réductions à usage unique pour les clients VIP :

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

## Ressources Associées

<CardGroup cols={2}>
  <Card title="Guide de Paiement" icon="shopping-cart" href="/fr/guides/checkout">
    Appliquez des réductions lors du paiement
  </Card>

  <Card title="API Réductions" icon="code" href="/api-reference/discounts/list-discounts">
    Consultez la référence complète de l'API Réductions
  </Card>
</CardGroup>