## Requête

Un renouvellement crée une **commande** (`Order`) de type `renewal`, en statut `pending`, avec un montant basé sur le plan et la période choisie. Le paiement s’effectue ensuite comme pour une facture (ex. `POST /v1/invoices/{order_uuid}/pay`).

```http
POST /v1/services/{service_uuid}/renew
Authorization: Bearer kh_live_xxxx
Content-Type: application/json
```

### Paramètres de chemin

| Paramètre | Type | Requis | Description |
|-----------|------|--------|-------------|
| `service_uuid` | UUID | Oui | UUID public du service (`Service.uuid`) |

### Corps de la requête

```json
{
  "period_months": 12,
  "payment_method": "auto"
}
```

| Champ | Type | Requis | Description |
|-------|------|--------|-------------|
| `period_months` | integer | Non | `1`, `3`, `6` ou `12` (défaut : `12`). Détermine la période de facturation (`monthly`, `semi-annual`, `annual`). |
| `payment_method` | string | Non | `notchpay`, `mobile_money`, `card` ou `auto` (défaut). Influence le `checkout_mode` de la commande (`auto` ou `manual`). |

## Réponse (201 Created)

```json
{
  "success": true,
  "data": {
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "order_number": "KH-ABCDEFGHIJ",
    "amount": 12000,
    "billing_period": "annual",
    "period_months": 12,
    "status": "pending"
  }
}
```

| Champ | Description |
|-------|-------------|
| `order_id` | UUID de la commande / facture à payer |
| `order_number` | Numéro interne affiché sur la facture |
| `amount` | Montant total (XAF) |
| `billing_period` | `monthly`, `semi-annual` ou `annual` |
| `status` | Statut de la commande (souvent `pending` tant que le paiement n’est pas initié) |

## Consulter une commande de renouvellement

Une fois l’UUID de commande connu (champ `order_id` ci-dessus), vous pouvez suivre l’état du renouvellement :

```http
GET /v1/renewals/{order_uuid}
Authorization: Bearer kh_live_xxxx
```

**Permission :** `services:read`

La réponse inclut notamment `uuid`, `status`, montants, dates, et un objet `service` (domaine, expiration, etc.) **si** un service est lié à cette commande.

## Payer la commande

Utilisez le flux factures :

```http
POST /v1/invoices/{order_uuid}/pay
```

**Permission :** `invoices:pay`

Consultez aussi [Payer une facture](/api/factures/payer) et [Statut d’un paiement](/api/factures/payer#get-paymentsreference).

## Permissions requises

- `POST …/renew` : `services:renew`
- `GET …/renewals/{order_uuid}` : `services:read`

<Warning>
  Les clés **sandbox** (`kh_test_`) sont en **lecture seule** : les `POST` / `PATCH` / `DELETE` retournent `403` avec le code `sandbox_read_only`. Testez les renouvellements avec une clé **live** (`kh_live_`).
</Warning>