> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pulse-sell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ventes

> Lister les commandes, comprendre les statuts, livrer ou annuler.

Une **vente** est une commande de votre boutique, avec ses articles, ses paiements et son client.

> [!NOTE]
>
> Permissions : `sales.read` pour lire, `sales.write` pour livrer ou annuler. Référence : [Ventes](https://docs.pulse-sell.com/api-reference/ventes).

## Lister

Sans filtre `status`, seules les ventes **encaissées** sont listées : c'est ce que la plupart des intégrations veulent. Avec `status`, vous obtenez toutes les commandes de ce statut, payées ou non.

```bash theme={null}
curl "https://api.pulse-sell.com/v1/sales?from=2026-10-01T00:00:00Z&to=2026-10-31T23:59:59Z&per_page=100" \
  -H "Authorization: Bearer $PULSESELL_API_KEY"
```

| Filtre | Rôle |
| - | - |
| `status` | `pending`, `processing`, `completed`, `fulfilled`, `cancelled`, `refunded`, `failed`, `awaiting_fulfillment` |
| `customer_email` | E-mail exact du client |
| `product_id` | Ventes contenant ce produit |
| `from`, `to` | Période de création (ISO 8601) |

## L'objet vente

```json theme={null}
{
  "id": "cm1sale001",
  "number": "PS-20261029-0042",
  "status": "completed",
  "payment_status": "completed",
  "amount": {
    "subtotal": { "value": 25000, "currency": "XOF" },
    "discount": { "value": 5000, "currency": "XOF" },
    "fees": { "value": 0, "currency": "XOF" },
    "total": { "value": 20000, "formatted": "20 000 F CFA", "currency": "XOF" }
  },
  "customer": { "email": "awa@example.com", "name": "Awa Koné", "phone": "+2250700000000" },
  "items": [ { "product_id": "cm1prod001", "name": "Guide complet", "quantity": 1 } ],
  "payments": [ { "status": "completed", "method": "mobile_money", "gateway": "…" } ],
  "affiliate_id": null,
  "created_at": "2026-10-29T16:17:10.000Z"
}
```

`payment_status` résume les paiements : `completed`, `refunded`, `processing`, `failed` ou `pending`. C'est lui qu'il faut regarder pour savoir si l'argent est encaissé.

## Livrer une vente

`POST /sales/{id}/fulfill` marque la commande livrée et déclenche la livraison numérique habituelle (accès au téléchargement, e-mail). Elle n'est possible que pour une commande **encaissée** et non encore livrée (`409 invalid_state` sinon). Une clé ne peut donc jamais livrer un produit non payé.

## Annuler une commande

`POST /sales/{id}/cancel` annule une commande **impayée**. Si un paiement est déjà encaissé, l'API refuse (`409`) : un remboursement est un mouvement d'argent et reste dans le tableau de bord.

## Suivre les ventes en continu

Plutôt que d'interroger l'API toutes les minutes, utilisez les Pulses : [`sale.completed`](https://docs.pulse-sell.com/pulses/events#sale-completed), [`sale.failed`](https://docs.pulse-sell.com/pulses/events#sale-failed), [`sale.abandoned`](https://docs.pulse-sell.com/pulses/events#sale-abandoned) et [`sale.refunded`](https://docs.pulse-sell.com/pulses/events#sale-refunded).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.