# Abonnements > Démarrez, listez, lisez, mettez à jour, résiliez, conservez et changez la formule de l'abonnement d'un client. Source : https://abuna.app/docs/api/subscriptions?hl=fr Les abonnements facturent un client pour un prix, une période de facturation à la fois. Un abonnement démarre `trialing` pendant un essai gratuit, ou `pending` sans essai, devient `active` quand le client paie la première période, est impayé (`past_due`) pendant qu'un renouvellement attend d'être payé, et se termine `canceled`. Voir [Statuts](https://abuna.app/docs/api/subscriptions.md?hl=fr#statuses). ## L'objet subscription **Attributs** - `id` (string): Identifiant unique de l'abonnement. - `app_id` (string): L'application à laquelle appartient l'abonnement. - `customer_id` (string): Le client qui paie. - `price_id` (string): Le prix que le client paie. - `status` (string): `trialing` pendant un essai gratuit. Sans essai, `pending` jusqu'à ce que la première période soit payée, puis `active`. `past_due` quand une période payée est terminée et que son renouvellement n'est pas encore payé, puis de nouveau `active` une fois qu'il l'est. `canceled` une fois qu'il se termine. Voir [Statuts](https://abuna.app/docs/api/subscriptions.md?hl=fr#statuses). - `starts_at` (timestamp): Quand l'abonnement commence, essai gratuit compris s'il y en a un, en secondes Unix. - `activated_at` (timestamp, nullable): Quand l'essai a démarré, ou quand la première période a été payée sans essai. - `trial_ends_at` (timestamp, nullable): La fin de l'essai gratuit, en secondes Unix. Null pour un abonnement sans essai. - `canceled_at` (timestamp, nullable): Quand l'abonnement a été résilié. - `cancel_at` (timestamp, nullable): La fin programmée de l'abonnement, à la fin de la période payée ou de l'essai. Null sinon. Il reste `active` ou `trialing` jusque-là. - `cancel_at_period_end` (boolean): `true` tant qu'une résiliation est programmée pour la fin de la période payée ou de l'essai, donc que `cancel_at` est renseigné. `false` sinon, y compris une fois l'abonnement terminé. - `current_period_start` (timestamp, nullable): Le début de la plus récente période payée ou de l'essai gratuit, en secondes Unix. Un renouvellement payé en avance peut commencer dans le futur. Null avant le premier paiement ou essai. Reste défini après la fin de l'abonnement. - `current_period_end` (timestamp, nullable): La fin de la plus récente période payée ou de l'essai gratuit, en secondes Unix. Null avant le premier paiement ou essai. Reste défini après la fin de l'abonnement. - `ended_reason` (string, nullable): Pourquoi l'abonnement a pris fin. `canceled` quand vous ou le client l'avez résilié, maintenant ou à la fin de la période payée. `unpaid` quand une période de facturation n'a pas été payée avant sa date limite de paiement, y compris une première période jamais payée. Null sauf si `status` est `canceled`. - `metadata` (object): Vos propres clés et valeurs. `{}` quand il n'y en a aucune. Un abonnement démarré par une [session checkout](https://abuna.app/docs/api/sessions.md?hl=fr#create-checkout) reçoit celui de la session. Voir [Métadonnées](https://abuna.app/docs/api/subscriptions.md?hl=fr#metadata). - `created_at` (timestamp): Quand l'abonnement a été créé, en secondes Unix. - `manage_token` (string): Le jeton du lien vers l'espace client. Toute personne qui a le lien peut voir et résilier l'abonnement : gardez-le privé. - `discount` (object, nullable): Le coupon que l'abonnement détient. Null sans coupon. Voir [Organiser une vente avec des codes promotionnels](https://abuna.app/docs/guides/promotion-codes.md?hl=fr). - `coupon` (object): Le [coupon](https://abuna.app/docs/api/coupons.md?hl=fr#object). - `promotion_code` (string, nullable): L'identifiant du code promotionnel qui a apporté le coupon. Null quand vous avez appliqué le coupon directement, sans code. - `start` (timestamp): Quand la réduction a commencé, en secondes Unix. - `end` (timestamp, nullable): Pour `repeating`, quand la réduction s'arrête. Null pour `once` et `forever`. **L'objet subscription** ```json { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null } ``` ## Créer un abonnement `POST /v1/apps/{appID}/subscriptions` Sans essai, démarre un abonnement `pending` et sa première [période de facturation](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#period-object), qui démarre maintenant. Abuna émet la facture de la période et envoie au client un message avec son lien de paiement. Pour que le client s'inscrive et paie plutôt sur la page d'abonnement, utilisez [Créer une session checkout](https://abuna.app/docs/api/sessions.md?hl=fr#create-checkout). Si le client peut bénéficier d'un essai, l'abonnement démarre avec `trialing`, sans paiement immédiat. La première période payante commence à `trial_ends_at`. Voir [Essais gratuits](https://abuna.app/docs/guides/trials.md?hl=fr) pour la facturation, les conditions et les webhooks. **Paramètres** - `customer_id` (string, obligatoire): Le client à facturer. - `price_id` (string, obligatoire): Le prix à lui facturer. - `trial_days` (integer): Remplace la durée du prix par 1 à 365 jours. Envoyez `0` pour désactiver l'essai. Omettez ce champ pour utiliser la durée du prix. Un seul essai par client, produit et application ; après utilisation, la facturation habituelle s'applique sans erreur. - `discounts` (array): Une réduction pour cet abonnement : une entrée avec `coupon` ou `promotion_code`, par identifiant, pas les deux. Une réduction inutilisable renvoie `422` avec le code `coupon_invalid` pour `discounts`. Voir [Organiser une vente avec des codes promotionnels](https://abuna.app/docs/guides/promotion-codes.md?hl=fr). - `metadata` (object): Vos propres clés et valeurs. Voir [Métadonnées](https://abuna.app/docs/api/subscriptions.md?hl=fr#metadata) pour les limites. Renvoie un objet avec l'`subscription` et sa première période (essai gratuit ou facturation), `period`, avec le statut `201`. Si l'application n'a aucun client ou prix avec cet ID, renvoie `404` avec le code `not_found` et un élément `errors` pour `customer_id` ou `price_id`. Si le prix est archivé, renvoie `410` avec le code `price_archived`. Si une application en production ne peut pas encore accepter de paiements, renvoie `422` avec le code `not_accepting_payments`. Si le client dépasse la limite d'abonnés en production du forfait de votre équipe, renvoie `403` avec le code `plan_limit`. **POST /v1/apps/{appID}/subscriptions** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q"}' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ customer_id: "Cu5tM8rA", price_id: "Zt6YbN3q" }), }); const result = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions", headers={"Authorization": "Bearer sk_test_..."}, json={"customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q"}, ) result = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode(["customer_id" => "Cu5tM8rA", "price_id" => "Zt6YbN3q"]), CURLOPT_RETURNTRANSFER => true, ]); $result = json_decode(curl_exec($ch), true); ``` Go : ```go body, _ := json.Marshal(map[string]string{"customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q"}) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var result map[string]any json.NewDecoder(res.Body).Decode(&result) ``` **Réponse** ```json { "subscription": { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "pending", "starts_at": 1727600000, "activated_at": null, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": null, "current_period_end": null, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null }, "period": { "id": "T6yVr3Dp", "subscription_id": "x9QbL2sK", "price_id": "Zt6YbN3q", "pay_token": "3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d", "starts_at": 1727600000, "ends_at": 1730192000, "period_index": 0, "grace_period_ends_at": 1727686400, "paid_at": null, "paused_at": null, "in_force": true, "created_at": 1727600000 } } ``` ## Lister les abonnements `GET /v1/apps/{appID}/subscriptions` Liste les abonnements de l'application, du plus récent au plus ancien, une page à la fois. Chaque élément a les champs de l'abonnement, y compris `cancel_at`, `current_period_start`, `current_period_end`, `ended_reason` et `metadata`, sans `app_id` ni `manage_token`, plus trois autres. **Paramètres de requête** - `status` (string): Renvoie uniquement les abonnements ayant ce statut : `pending`, `trialing`, `active`, `past_due` ou `canceled`. - `customer_id` (string): Renvoie uniquement les abonnements de ce client. - `email` (string): Renvoie uniquement les abonnements dont l'e-mail du client contient ce texte. La casse n'a pas d'importance. - `limit` (integer): Combien d'abonnements renvoyer, de 1 à 100. Par défaut 50. - `cursor` (string): La valeur `next_cursor` de la page précédente. Envoyez les mêmes filtres avec. **Attributs supplémentaires** - `customer` (object): Qui paie. - `name` (string, nullable): Le nom du client. - `email` (string): L'adresse e-mail du client. - `price` (object): Ce qu'il paie. - `name` (string): Le nom du prix. - `amount` (integer): Le montant pour chaque période, dans la plus petite unité de la devise. - `currency` (string): `XAF`, `XOF` ou `USD`. - `interval` (string): `day`, `week`, `month` ou `year`. - `interval_count` (integer): Combien d'intervalles composent une période. - `next_payment_at` (timestamp, nullable): Quand le prochain paiement est dû. Tant que la dernière période est impayée, c'est le début de cette période, même s'il est dans le passé. Une fois qu'elle est payée, c'est le début de la période suivante. Null une fois résilié, et null tant qu'une résiliation est programmée. Renvoie `items` et `next_cursor`, comme décrit dans [Listes et filtres](https://abuna.app/docs/lists-and-filters.md?hl=fr). Un `status` inconnu ou un `limit` hors de 1 à 100 renvoie `422` avec le code `invalid`. **GET /v1/apps/{appID}/subscriptions** cURL : ```bash curl "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA" \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA", { headers: { Authorization: "Bearer sk_test_..." }, }); const page = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA", headers={"Authorization": "Bearer sk_test_..."}, ) page = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $page = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions?status=active&customer_id=Cu5tM8rA", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var page map[string]any json.NewDecoder(res.Body).Decode(&page) ``` **Réponse** ```json { "items": [ { "id": "x9QbL2sK", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "customer": { "name": "Jane Doe", "email": "jane@example.com" }, "price": { "name": "Monthly", "amount": 5000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "next_payment_at": 1730192000 } ], "next_cursor": null } ``` ## Récupérer un abonnement `GET /v1/apps/{appID}/subscriptions/{id}` Récupère un abonnement avec son client, son prix, ses périodes de facturation et ses paiements. **Attributs de réponse** - `subscription` (object): L'objet subscription. - `subscription_page_url` (string): Le lien vers l'espace client, où le client voit et résilie l'abonnement. - `customer` (object): L'[objet customer](https://abuna.app/docs/api/customers.md?hl=fr#object), plus `telegram_connected`. - `price` (object): L'[objet price](https://abuna.app/docs/api/prices.md?hl=fr#object). - `periods` (array): Chaque période de facturation en vigueur, de la plus ancienne à la plus récente. La période d'une mise à niveau en attente de paiement, ou une période échue, n'est pas listée. Celle en attente figure dans `pending_change`, et sa facture reste dans la [liste des factures](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#list). - `id` (string): L'ID de la période de facturation. - `starts_at` (timestamp): Quand la période démarre. - `ends_at` (timestamp): Quand la période se termine. - `grace_period_ends_at` (timestamp): La date limite de paiement. - `paid_at` (timestamp, nullable): Quand la période a été payée. - `pay_url` (string): Le lien de paiement de la période. - `invoice` (object, nullable): L'[objet invoice](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#invoice-object) de la période. - `invoice_url` (string, nullable): Un lien vers la page de la facture. Il expire après 7 jours. - `payments` (array): Chaque [paiement](https://abuna.app/docs/api/invoices-and-payments.md?hl=fr#payment-object) de l'abonnement, du plus récent au plus ancien. - `pending_change` (object, nullable): Le changement de formule en attente : une mise à niveau en attente de paiement, ou une rétrogradation ou une mise à niveau au prochain renouvellement, programmée pour la fin de la période payée. Null quand il n'y en a pas. Une résiliation programmée figure plutôt dans `cancel_at`. - `id` (string): Le changement de formule. - `type` (string): `upgrade` ou `downgrade`. - `price` (object): Le nouveau prix : `id`, `name`, `amount`, `currency`, `interval` et `interval_count`. - `requested_by` (string): `customer` quand le client l'a choisi dans son espace client ou sur une page d'abonnement, ou `merchant` quand il a confirmé un changement que vous lui avez envoyé. - `created_at` (timestamp): Quand le changement a été demandé. - `amount_due` (integer, nullable): Ce que le client paie pour basculer maintenant. Null pour une rétrogradation, et 0 pour une mise à niveau au prochain renouvellement. - `credit` (integer, nullable): Le temps inutilisé de la période en cours déduit du nouveau prix. Null pour une rétrogradation, et 0 pour une mise à niveau au prochain renouvellement. - `expires_at` (timestamp, nullable): Si la mise à niveau n'est pas payée avant, elle expire et la formule actuelle continue. Null pour un changement programmé. - `pay_url` (string, nullable): Le lien de paiement de la mise à niveau. Null pour un changement programmé. - `effective_at` (timestamp, nullable): Quand un changement programmé démarre. Null pour une mise à niveau en attente de paiement. - `plan_offer` (object, nullable): Le [changement de formule](https://abuna.app/docs/api/sessions.md?hl=fr#create-plan-change) en attente de confirmation du client, ou null. Il est null une fois dépassé son `expires_at`. - `id` (string): La proposition. - `price` (object): Le prix proposé : `id`, `name`, `amount`, `currency`, `interval` et `interval_count`. - `status` (string): Toujours `pending` ici. - `url` (string): La page où le client confirme le changement. - `created_at` (timestamp): Quand la proposition a été faite. - `expires_at` (timestamp): Quand la proposition expire si le client ne l'a pas confirmée. - `sent_at` (timestamp, nullable): Quand Abuna a envoyé le lien au client, ou null s'il n'en a pas envoyé. - `plan_changes` (array): Chaque changement de formule de l'abonnement, du plus récent au plus ancien. - `id` (string): Le changement de formule. - `direction` (string): `upgrade` ou `downgrade`. - `status` (string): `awaiting_payment` (une mise à niveau pas encore payée), `scheduled` (une rétrogradation, ou une mise à niveau au prochain renouvellement, en attente de la fin de la période), `applied`, `lapsed` (une mise à niveau non payée à temps), `undone` (un changement programmé repris), `replaced` (un autre changement l'a remplacée), ou `canceled` (l'abonnement a pris fin avant). - `from_price` (object): Le prix d'avant, dans la même forme que ci-dessus. - `to_price` (object): Le nouveau prix. - `requested_by` (string): `customer` ou `merchant`. - `amount` (integer, nullable): Ce que la mise à niveau facture. Null pour une rétrogradation. - `credit` (integer, nullable): Le temps inutilisé déduit de la mise à niveau. Null pour une rétrogradation. - `effective_at` (timestamp, nullable): Quand elle a pris effet, ou pour une rétrogradation, quand elle prendra effet. Null pour une mise à niveau qui n'a pas encore pris effet. - `created_at` (timestamp): Quand elle a été demandée. - `resolved_at` (timestamp, nullable): Quand elle a quitté l'état en attente. Si l'application n'a aucun abonnement avec cet ID, renvoie `404` avec le code `not_found`. **GET /v1/apps/{appID}/subscriptions/{id}** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK", { headers: { Authorization: "Bearer sk_test_..." }, }); const subscription = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK", headers={"Authorization": "Bearer sk_test_..."}, ) subscription = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $subscription = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var subscription map[string]any json.NewDecoder(res.Body).Decode(&subscription) ``` **Réponse** ```json { "subscription": { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null }, "subscription_page_url": "https://app.abuna.app/portal/8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "customer": { "id": "Cu5tM8rA", "app_id": "8ddhXCDW", "name": "Jane Doe", "phone_number": "+237671234567", "email": "jane@example.com", "created_at": 1727600000, "metadata": {}, "language": null, "updates": { "channel": null, "email": { "status": "active" }, "telegram": { "status": "off", "connected_at": null, "connect_url": null }, "whatsapp": { "status": "off", "connected_at": null, "connect_url": null } }, "telegram_connected": false }, "price": { "id": "Zt6YbN3q", "product_id": "pR4dWx9K", "name": "Monthly", "currency": "XAF", "amount": 5000, "interval": "month", "interval_count": 1, "created_at": 1727600000, "archived_at": null }, "periods": [ { "id": "T6yVr3Dp", "starts_at": 1727600000, "ends_at": 1730192000, "grace_period_ends_at": 1727686400, "paid_at": 1727600100, "pay_url": "https://app.abuna.app/pay/3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d", "invoice": { "id": "V2nC8xEi", "app_id": "8ddhXCDW", "period_id": "T6yVr3Dp", "subscription_id": "x9QbL2sK", "number": "MYST-000124", "status": "paid", "kind": "period", "amount": 5000, "credit": 0, "currency": "XAF", "item_label": "Monthly", "buyer_name": "Jane Doe", "buyer_email": "jane@example.com", "seller_name": "My store", "period_start": 1727600000, "period_end": 1730192000, "due_at": 1727686400, "created_at": 1727600000, "paid_at": 1727600100, "voided_at": null, "discount": 0, "coupon_id": null, "promotion_code_id": null }, "invoice_url": "https://app.abuna.app/invoice/V2nC8xEi?exp=1728204800&sig=b4e1c8f2a7d3960e5b1f8c4a2d7e3b9f6a0c5e8d1b4f7a2c9e6d3b0f8a5c1e7d" } ], "payments": [ { "id": "m7Yw4NcJ", "app_id": "8ddhXCDW", "period_id": "T6yVr3Dp", "driver": "sandbox", "provider": "test", "provider_reference": "test_9f3b7d1a5c2e8f4b6d0a", "amount": 5000, "currency": "XAF", "status": "succeeded", "message": null, "created_at": 1727600090, "fee": 100, "net": null, "session_id": null, "note": null, "marked_by_user_id": null, "marked_by_api_key_id": null, "method_label": "Successful payment (test)" } ], "pending_change": { "id": "H3nM8cGb", "type": "downgrade", "price": { "id": "Kw3FgT7e", "name": "Basic monthly", "amount": 2000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "requested_by": "customer", "created_at": 1728464000, "amount_due": null, "credit": null, "expires_at": null, "pay_url": null, "effective_at": 1730192000 }, "plan_offer": null, "plan_changes": [ { "id": "H3nM8cGb", "direction": "downgrade", "status": "scheduled", "from_price": { "id": "Zt6YbN3q", "name": "Monthly", "amount": 5000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "to_price": { "id": "Kw3FgT7e", "name": "Basic monthly", "amount": 2000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "requested_by": "customer", "amount": null, "credit": null, "effective_at": 1730192000, "created_at": 1728464000, "resolved_at": null } ] } ``` ## Modifier un abonnement `PATCH /v1/apps/{appID}/subscriptions/{id}` Définit le `metadata` de l'abonnement. La table que vous envoyez remplace toute la table : les clés que vous omettez sont supprimées. Envoyez `{}` pour l'effacer. **Paramètres** - `metadata` (object, obligatoire): Le nouveau metadata. Voir [Métadonnées](https://abuna.app/docs/api/subscriptions.md?hl=fr#metadata) pour les limites. Renvoie l'abonnement. Un metadata au-delà de ses limites renvoie `422` avec le code `invalid` et un élément `errors` pour `metadata`. Si l'application n'a aucun abonnement avec cet ID, renvoie `404` avec le code `not_found`. **PATCH /v1/apps/{appID}/subscriptions/{id}** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK \ -X PATCH \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"metadata": {"user_id": "42"}}' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK", { method: "PATCH", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ metadata: { user_id: "42" } }), }); const subscription = await response.json(); ``` **Réponse** ```json { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null } ``` ## Résilier un abonnement `POST /v1/apps/{appID}/subscriptions/{id}/cancel` Met fin à l'abonnement, maintenant ou à la fin de la période payée. Envoyez `at_period_end` pour choisir. Un corps vide, ou `false`, résilie maintenant. Pour que le client confirme lui-même la résiliation, utilisez [Créer une session de résiliation](https://abuna.app/docs/api/sessions.md?hl=fr#create-cancel). Pendant un essai, `at_period_end: true` définit `cancel_at` à `trial_ends_at`. L'abonnement reste `trialing` jusque-là, avec accès et sans facture à payer. Une résiliation immédiate par l'API le termine toujours dès maintenant. **Paramètres du corps** - `at_period_end` (boolean): Facultatif, `false` par défaut. Avec `true`, l'abonnement reste `active` jusqu'à la fin de la période payée en cours, puis prend fin tout seul. Une valeur qui n'est pas un booléen renvoie `400` avec le code `invalid_json`. **Maintenant.** L'abonnement est `canceled` immédiatement, avec `canceled_at` défini et `cancel_at` à null. Abuna annule ses factures ouvertes, envoie un événement `subscription.canceled` avec la raison `merchant`, et prévient le client. Résilier maintenant un abonnement qui a une résiliation programmée le termine maintenant et efface la programmation. Cela annule aussi une mise à niveau en attente de paiement et retire une proposition de changement de formule en attente. **À la fin de la période payée.** La réponse a `status` `active` et `cancel_at` défini à la fin de la période payée. Abuna envoie un événement `subscription.updated` et indique au client quand il prend fin et comment le conserver. Jusque-là, il n'émet aucun renouvellement et n'envoie aucun rappel de renouvellement, et `next_payment_at` dans la liste est null. Quand la date arrive, l'abonnement devient `canceled` et Abuna envoie `subscription.canceled`. Envoyer `at_period_end` de nouveau pendant qu'une résiliation est programmée renvoie `200` et ne change rien : aucun nouvel événement et aucun nouvel e-mail. Une résiliation programmée remplace une rétrogradation programmée ou une mise à niveau en attente de paiement. Voir [Un changement à la fois](https://abuna.app/docs/api/subscriptions.md?hl=fr#one-change-at-a-time). Hors essai, si la période en cours n'est pas encore payée, ou est déjà terminée, `at_period_end: true` résilie maintenant à la place. Vérifiez `status` dans la réponse pour voir ce qui s'est passé. Une facture de renouvellement envoyée avant la fin et pas encore payée est annulée, donc le client ne peut pas payer pour une période après la fin. S'il l'a déjà payée, l'abonnement prend fin quand ce renouvellement se termine. > **Attention :** Un abonnement résilié ne peut pas être redémarré. Pour facturer de nouveau le client, créez un nouvel abonnement. Renvoie l'abonnement. Si l'application n'a aucun abonnement avec cet ID, ou s'il est déjà résilié, renvoie `404` avec le code `not_found`. Si `at_period_end` devait remplacer une mise à niveau dont le paiement est en cours, renvoie `409` avec le code `payment_in_progress`. **POST /v1/apps/{appID}/subscriptions/{id}/cancel** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/cancel \ -X POST \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -d '{"at_period_end": true}' ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/cancel", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json" }, body: JSON.stringify({ at_period_end: true }), }); const subscription = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/cancel", headers={"Authorization": "Bearer sk_test_..."}, json={"at_period_end": True}, ) subscription = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode(["at_period_end" => true]), CURLOPT_RETURNTRANSFER => true, ]); $subscription = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/cancel", strings.NewReader(`{"at_period_end": true}`)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var subscription map[string]any json.NewDecoder(res.Body).Decode(&subscription) ``` **Réponse** ```json { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": 1730192000, "cancel_at_period_end": true, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null } ``` ## Conserver un abonnement `POST /v1/apps/{appID}/subscriptions/{id}/resume` Annule une résiliation programmée. La facturation continue comme avant : `cancel_at` est de nouveau null et le prochain renouvellement est émis à temps. Abuna envoie un événement `subscription.updated` et indique au client que l'abonnement continue. Cela retire aussi une [rétrogradation programmée](https://abuna.app/docs/api/subscriptions.md?hl=fr#downgrades), ou une [mise à niveau au prochain renouvellement](https://abuna.app/docs/api/subscriptions.md?hl=fr#upgrades), donc la période suivante reste au prix actuel. Abuna envoie `subscription.updated` avec un changement `downgrade_undone` ou `upgrade_undone`, et aucun e-mail. Si rien n'est programmé sur un abonnement actif, renvoie `200` et ne change rien. Si l'abonnement est déjà résilié, renvoie `409` avec le code `subscription_canceled`. Si l'application n'a aucun abonnement avec cet ID, renvoie `404` avec le code `not_found`. **POST /v1/apps/{appID}/subscriptions/{id}/resume** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/resume \ -X POST \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/resume", { method: "POST", headers: { Authorization: "Bearer sk_test_..." }, }); const subscription = await response.json(); ``` Python : ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/resume", headers={"Authorization": "Bearer sk_test_..."}, ) subscription = response.json() ``` PHP : ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_..."], CURLOPT_POSTFIELDS => "", CURLOPT_RETURNTRANSFER => true, ]); $subscription = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/resume", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var subscription map[string]any json.NewDecoder(res.Body).Decode(&subscription) ``` **Réponse** ```json { "id": "x9QbL2sK", "app_id": "8ddhXCDW", "customer_id": "Cu5tM8rA", "price_id": "Zt6YbN3q", "status": "active", "starts_at": 1727600000, "activated_at": 1727600100, "trial_ends_at": null, "canceled_at": null, "cancel_at": null, "cancel_at_period_end": false, "current_period_start": 1727600000, "current_period_end": 1730192000, "ended_reason": null, "metadata": { "user_id": "42" }, "created_at": 1727600000, "manage_token": "8c1f4a7d2e9b3c6f0a5d8e1b4c7f2a9d3e6b", "discount": null } ``` ## Lister les options de formule `GET /v1/apps/{appID}/subscriptions/{id}/plan-options` Liste les prix vers lesquels l'abonnement peut basculer, chacun chiffré à l'instant présent. Les montants changent à mesure que la période s'écoule, alors chiffrez de nouveau juste avant de les afficher. Voir [Changer de formule](https://abuna.app/docs/api/subscriptions.md?hl=fr#changing-plan) pour la façon dont chaque nombre est calculé. **Chaque option** - `price` (object): Le prix : `id`, `name`, `amount`, `currency`, `interval` et `interval_count`. - `direction` (string): `upgrade` ou `downgrade`. - `amount_due` (integer): Pour une mise à niveau, ce que le client paie maintenant. Il peut être `0`. Toujours `0` pour une rétrogradation. - `credit` (integer): Pour une mise à niveau, le temps inutilisé de la période en cours déduit du nouveau prix. Toujours `0` pour une rétrogradation. - `new_billing_date` (timestamp, nullable): Pour une mise à niveau, quand la nouvelle période se terminerait si elle était payée maintenant. Null pour une rétrogradation. - `effective_at` (timestamp, nullable): Pour une rétrogradation, quand le nouveau prix démarre : la fin de la période payée. Null pour une mise à niveau. Renvoie `{ "data": [...] }`. La liste est vide quand aucun autre prix n'est éligible ou que l'abonnement n'est pas `active` ou `past_due`. Si l'application n'a aucun abonnement avec cet ID, renvoie `404` avec le code `not_found`. **GET /v1/apps/{appID}/subscriptions/{id}/plan-options** cURL : ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/plan-options \ -H "Authorization: Bearer sk_test_..." ``` Node.js : ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/plan-options", { headers: { Authorization: "Bearer sk_test_..." }, }); const options = await response.json(); ``` Python : ```python import requests response = requests.get( "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/plan-options", headers={"Authorization": "Bearer sk_test_..."}, ) options = response.json() ``` PHP : ```php ["Authorization: Bearer sk_test_..."], CURLOPT_RETURNTRANSFER => true, ]); $options = json_decode(curl_exec($ch), true); ``` Go : ```go req, _ := http.NewRequest("GET", "https://api.abuna.app/v1/apps/8ddhXCDW/subscriptions/x9QbL2sK/plan-options", nil) req.Header.Set("Authorization", "Bearer sk_test_...") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var options map[string]any json.NewDecoder(res.Body).Decode(&options) ``` **Réponse** ```json { "data": [ { "price": { "id": "Hc8LmV2s", "name": "Pro monthly", "amount": 10000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "direction": "upgrade", "amount_due": 6666, "credit": 3334, "new_billing_date": 1731142400, "effective_at": null }, { "price": { "id": "Kw3FgT7e", "name": "Basic monthly", "amount": 2000, "currency": "XAF", "interval": "month", "interval_count": 1 }, "direction": "downgrade", "amount_due": 0, "credit": 0, "new_billing_date": null, "effective_at": 1730192000 } ] } ``` ## Statuts - **`trialing`** : accès gratuit jusqu'à `trial_ends_at`. Gardez l'accès pendant l'essai. En Production, ces clients comptent dans la limite d'abonnés de votre équipe ; le mode Test n'a pas de limite d'abonnés. - **`pending`** : créé, et en attente du premier paiement. Si la première période n'est pas payée avant sa date limite de paiement, l'abonnement est `canceled` avec `ended_reason` `unpaid`. - **`active`** : chaque période qui a commencé est payée. - **`past_due`** : impayé. Un renouvellement a commencé et n'est pas encore payé. - **`canceled`** : terminé. `ended_reason` dit pourquoi. Un abonnement résilié ne peut pas être redémarré. ### Renouvellements et abonnements impayés Abuna émet la période de facturation suivante et sa facture avant la fin de la période payée. Le [`renewal_lead_days`](https://abuna.app/docs/api/apps.md?hl=fr#object) de votre application fixe combien de jours avant : de 0 à 7, 3 par défaut, et jamais plus tôt que la moitié de la période. Abuna envoie `subscription.renewed` et `invoice.created`, et envoie au client par e-mail la facture avec son lien de paiement. L'abonnement reste `active`, et le client peut payer tout de suite. La nouvelle période démarre toujours quand la période payée se termine, même si le client paie en avance. Si le renouvellement est encore impayé quand la période payée se termine, l'abonnement devient `past_due` et Abuna envoie `subscription.past_due`. Quand la facture est payée, l'abonnement est de nouveau `active`, et Abuna envoie `subscription.recovered`. Un renouvellement payé avant la fin de la période payée ne passe jamais par `past_due`. Avec `renewal_lead_days` à `0`, ou tant qu'une rétrogradation attend la fin de la période, la facture part à la fin de la période, donc l'abonnement est `past_due` jusqu'à ce que le client paie. Si la période n'est pas payée avant sa date limite de paiement, l'abonnement est `canceled` avec `ended_reason` `unpaid`, et Abuna envoie `subscription.canceled` avec la raison `non_payment`. La date limite de paiement est le`grace_period_ends_at` de la période de facturation : le début de la période plus le délai de paiement de votre application, [`grace_period_days`](https://abuna.app/docs/api/apps.md?hl=fr#object) (de 1 à 14 jours, 3 par défaut), et jamais après la fin de la période. > **Remarque :** Gardez l'accès du client tant que l'abonnement est `past_due`, et coupez-le quand l'abonnement est `canceled`. Un client impayé a encore des jours pour payer. Couper l'accès trop tôt bloque des clients sur le point de payer. `current_period_start` et `current_period_end` continuent de montrer la dernière période payée tant que l'abonnement est `past_due`. Un abonnement `past_due` peut encore : - Être payé via son lien de paiement, une [session de paiement](https://abuna.app/docs/api/sessions.md?hl=fr#create-payment) ou l'espace client. - Être [résilié](https://abuna.app/docs/api/subscriptions.md?hl=fr#cancel). Une résiliation à la fin de la période payée le termine maintenant, parce que la période en cours n'est pas payée. - [Changer de formule](https://abuna.app/docs/api/subscriptions.md?hl=fr#changing-plan). Une mise à niveau démarre tout de suite une période complète au nouveau prix, et une rétrogradation attend la fin de la période en cours. Voir [Mises à niveau](https://abuna.app/docs/api/subscriptions.md?hl=fr#upgrades). ### Paiements qui arrivent en retard Un paiement par mobile money que le client a approuvé peut être confirmé des heures plus tard. Si la facture a été annulée entre-temps, Abuna enregistre quand même le paiement : il est `succeeded`, la facture devient `paid`, Abuna envoie `invoice.paid`, et le client reçoit un reçu. - Si l'abonnement a pris fin uniquement parce que ce paiement n'était pas arrivé (`ended_reason` `unpaid`), et que la période qu'il paie n'est pas encore terminée, l'abonnement revient : `status` est `active`, `canceled_at` et `ended_reason` sont de nouveau null, et Abuna envoie `subscription.recovered`, ou `subscription.paid` pour un premier paiement. Un premier paiement a besoin de place dans la limite d'abonnés en production du forfait de votre équipe, comme sur la page d'abonnement. - Sinon l'abonnement reste tel quel : résilié par vous ou le client, remplacé, au-delà de la période payée, ou une mise à niveau qui a expiré. Vous voudrez peut-être rembourser le client. Dans les deux cas, les membres de l'équipe qui reçoivent les e-mails sur les paiements ou les résiliations en reçoivent un à ce sujet. ## Métadonnées `metadata` contient vos propres clés et valeurs sur un abonnement, par exemple l'ID de votre utilisateur. Définissez-le quand vous [créez l'abonnement](https://abuna.app/docs/api/subscriptions.md?hl=fr#create), transmettez-le à une [session checkout](https://abuna.app/docs/api/sessions.md?hl=fr#create-checkout), ou [mettez-le à jour](https://abuna.app/docs/api/subscriptions.md?hl=fr#update) plus tard. Chaque lecture le renvoie. - Jusqu'à 20 clés. - Chaque clé fait 1 à 40 caractères. - Chaque valeur est une chaîne de 500 caractères au plus. Les nombres, les booléens, les objets et null ne sont pas autorisés. Les événements `subscription`, `invoice` et `plan_offer` portent le metadata de cet abonnement. Les événements de session portent plutôt le metadata de la session. Transmettez le metadata sur chaque session que vous créez. Voir [Types d'événement](https://abuna.app/docs/api/events.md?hl=fr#types). ## Résilier un abonnement Pendant un essai gratuit, la résiliation demandée par le client est programmée à `trial_ends_at`, avec accès jusque-là. Toute première facture encore impayée est annulée, sans rien à payer. L'API permet toujours de [résilier immédiatement](https://abuna.app/docs/api/subscriptions.md?hl=fr#cancel). Une résiliation peut prendre effet maintenant ou à la fin de la période payée. Vous choisissez le moment quand vous résiliez depuis le tableau de bord ou l'API. Pour les clients qui résilient depuis leur espace client, c'est le réglage **Quand les clients résilient** de l'application qui décide, soit [`customer_cancel`](https://abuna.app/docs/api/apps.md?hl=fr#object). Les nouvelles applications démarrent avec `at_period_end`. Une [session d'annulation](https://abuna.app/docs/api/sessions.md?hl=fr#create-cancel) utilise aussi ce réglage, sauf si vous envoyez `at_period_end`. - **Maintenant.** L'abonnement prend fin immédiatement et toute facture impayée est annulée. - **Fin de la période payée.** L'abonnement reste `active` et porte `cancel_at`. Le client garde l'accès qu'il a payé. Abuna n'émet aucun renouvellement et n'envoie aucun rappel de renouvellement, et annule une facture de renouvellement déjà envoyée et qui n'est pas payée. Un renouvellement que le client a déjà payé compte comme période payée, donc l'abonnement prend fin quand elle se termine. Le tableau de bord et l'espace client affichent « Prend fin le » avec la date. À ce moment-là, l'abonnement devient `canceled`. - **Période impayée.** Si la période en cours n'est pas encore payée, une résiliation de fin de période met fin à l'abonnement maintenant et annule la facture impayée. Le tableau de bord et l'espace client le disent avant que la personne confirme. - **Revenir en arrière.** Jusqu'à la date de fin, vous pouvez conserver l'abonnement dans le tableau de bord ou avec [l'endpoint de reprise](https://abuna.app/docs/api/subscriptions.md?hl=fr#resume), et le client peut le conserver dans l'espace client. La facturation continue comme avant. Le client reçoit un e-mail quand une résiliation est programmée, avec la date de fin et comment conserver l'abonnement, un quand elle prend fin, et une courte confirmation si elle est retirée. L'URL de votre webhook reçoit `subscription.updated` quand une résiliation est programmée ou retirée, et `subscription.canceled` quand l'abonnement prend fin. Voir [Notifications aux clients](https://abuna.app/docs/guides/customer-notifications.md?hl=fr). Le mode Test fonctionne de la même façon. Abuna enregistre les e-mails pour un client Test au lieu de les envoyer, et les modes Test et Production gardent chacun leur propre réglage **Quand les clients résilient**. ## Changer de formule Un abonnement `active` ou `past_due` peut passer à un autre prix. Le client le fait dans son espace client, ou confirme un changement que vous lui envoyez avec une [session de changement de formule](https://abuna.app/docs/api/sessions.md?hl=fr#create-plan-change). Un client qui revient sur une page d'abonnement pour un autre prix du même produit se voit aussi proposer le changement : voir [Changer de formule depuis la page d'abonnement](https://abuna.app/docs/api/sessions.md?hl=fr#checkout-switch). Vous ne pouvez pas changer le prix directement, parce qu'une mise à niveau a besoin que le client paie. ### Quels prix Tout autre prix du même produit dans la même devise, sauf s'il est archivé. Jamais un prix d'un autre produit ni dans une autre devise : un changement vers un prix dans une autre devise renvoie `422` avec le code `price_not_eligible`. Si aucun prix n'est éligible, l'espace client n'affiche aucune option de changement de formule. Un abonnement encore `pending` ne peut pas changer de formule. ### Mise à niveau ou rétrogradation Abuna compare le coût par jour : le montant du prix divisé par la durée en jours d'une de ses périodes démarrant maintenant. Un prix qui coûte plus par jour est une mise à niveau. Un prix qui coûte autant ou moins est une rétrogradation. Cela fonctionne entre intervalles, donc passer d'un mensuel à un annuel suit la même règle. ### Mises à niveau Si la période en cours est payée, le client paie la différence maintenant et garde l'ancienne formule jusqu'à ce que ce paiement réussisse. Une facture de renouvellement déjà envoyée pour l'ancien prix et non payée est annulée, et la suivante est émise au nouveau prix. Si le client a déjà payé la période suivante avant qu'elle commence, une mise à niveau attend que cette période démarre : jusque-là, l'espace client ne propose aucune mise à niveau, et un changement renvoie `409` avec le code `renewal_paid_early`. À ce moment-là, la nouvelle formule démarre avec une période complète entière au nouveau prix, et la date de facturation passe à la date de paiement. Le montant est le nouveau prix moins la valeur inutilisée de la période en cours. La valeur inutilisée est la valeur de la période multipliée par les jours entiers restants, divisée par les jours de la période. La valeur de la période est ce que sa facture a facturé plus tout crédit qu'elle porte, donc une deuxième mise à niveau dans la même période ne perd rien. Le résultat est arrondi à l'entier inférieur et ne descend jamais sous `0`. Avec 20 jours restants sur 30 d'une période de 5 000 FCFA, passer à un prix de 10 000 FCFA coûte `10000 − 3334 = 6666`, et `credit` vaut `3334`. Un montant supérieur à `0` mais sous le minimum facturable, 100 FCFA ou 50 centimes US, est porté à ce minimum, et `credit`baisse d'autant. Avec une réduction qui couvre le nouveau prix, le nouveau prix est le prix réduit. - **Rien à payer.** Quand le montant est `0`, la mise à niveau prend effet immédiatement. Sa facture est créée déjà payée. - **Pas payée à temps.** La mise à niveau expire à son `expires_at` : le délai de paiement de votre application à partir de la demande, ou la fin de la période en cours si elle arrive avant. Sa facture est annulée et l'ancienne formule continue. Il n'y a aucune pénalité. Si la mise à niveau a remplacé une résiliation programmée, la résiliation est reprogrammée à sa date d'origine, et `subscription.updated` porte son `cancel_at`. - **Période en cours impayée.** Si la période en cours n'est pas encore payée, comme tant que l'abonnement est `past_due`, Abuna annule sa facture et démarre une période complète au nouveau prix maintenant. La nouvelle formule est en vigueur immédiatement et le client la paie via son lien de paiement, avec le délai de paiement habituel. Il n'y a aucun crédit. Tant qu'un paiement sur l'ancienne facture est en cours, le changement renvoie `409` avec le code `payment_in_progress`. Un changement sur une session checkout créée avec `upgrade_timing` `next_renewal` fait exception : la mise à niveau ne coûte rien maintenant et est programmée pour la fin de la période payée, comme une rétrogradation. Elle figure dans `pending_change` et `scheduled_price_change`, envoie `subscription.updated` avec un changement `upgrade_scheduled`, et peut être retirée de la même façon. La facture d'une mise à niveau a `kind` `plan_change` et le temps inutilisé dans `credit`. Son `amount` est ce que le client paie. Une mise à niveau avec quelque chose à payer exige que votre application accepte les paiements. Jusque-là, le changement renvoie `422` avec le code `not_accepting_payments`. Une mise à niveau sans rien à payer, et une rétrogradation, fonctionnent dans les deux cas. ### Rétrogradations Une rétrogradation ne coûte rien maintenant et ne rembourse rien. Le client garde la formule actuelle jusqu'à la fin de la période payée, et la période suivante est émise au nouveau prix quand la période payée se termine, pas avant. Une facture de renouvellement déjà envoyée pour l'ancien prix et non payée est annulée. Si le client a déjà payé la période suivante, la rétrogradation démarre quand cette période se termine. Jusque-là, le client peut la retirer dans son espace client, et vous pouvez le faire avec [Conserver un abonnement](https://abuna.app/docs/api/subscriptions.md?hl=fr#resume). Une rétrogradation programmée figure dans `pending_change` et dans `scheduled_price_change` sur [`subscription.updated`](https://abuna.app/docs/api/events.md?hl=fr#subscription-updated). Une rétrogradation peut être programmée tant que la période en cours est encore impayée. Elle démarre tout de même à la fin de cette période, et si la période reste impayée, l'abonnement prend fin pour non-paiement comme d'habitude. Tant qu'une rétrogradation est programmée, le rappel de renouvellement indique le nouveau prix. ### Un changement à la fois Un abonnement contient au plus l'un de ces éléments : une résiliation programmée, une rétrogradation ou une mise à niveau programmée, ou une mise à niveau en attente de paiement. En démarrer un remplace l'autre. Une mise à niveau remplacée a sa facture annulée, et le changement remplacé reçoit le statut `replaced`. Tant que le paiement de cette mise à niveau est en cours, elle ne peut pas être remplacée : la requête renvoie `409` avec le code `payment_in_progress`. Redemander le changement déjà en attente, vers le même prix, ne change rien et le renvoie tel quel. Un changement que vous envoyez au client avec une [session de changement de formule](https://abuna.app/docs/api/sessions.md?hl=fr#create-plan-change) attend qu'il le confirme. Un abonnement a au plus un changement en attente d'être confirmé. Un nouveau, ou un changement de formule que le client fait dans l'espace client, le remplace. Le confirmer remplace une résiliation programmée, une rétrogradation programmée ou une mise à niveau en attente de paiement, et la page de confirmation le dit d'abord. Résilier l'abonnement maintenant annule une mise à niveau en attente de paiement et retire le changement en attente d'être confirmé. ### Dans l'espace client L'espace client liste chaque prix éligible avec ce qu'il coûte maintenant : le montant à payer et la nouvelle date de facturation pour une mise à niveau, ou la date à laquelle elle démarre pour une rétrogradation. Une mise à niveau envoie le client vers son lien de paiement, sauf s'il n'y a rien à payer. Tant qu'une mise à niveau attend le paiement, l'espace client l'affiche avec son lien de paiement. Conserver l'abonnement dans l'espace client retire aussi une rétrogradation programmée. Pour envoyer un client vers l'espace client avec un lien de retour vers votre application, utilisez [Créer une session d'espace client](https://abuna.app/docs/api/sessions.md?hl=fr#create-portal). ### La page de confirmation L'`url` d'une [session de changement de formule](https://abuna.app/docs/api/sessions.md?hl=fr#create-plan-change) ouvre une page avec la formule actuelle, la nouvelle, et ce que coûte le changement, calculé au chargement de la page. Le client confirme là, et le changement suit les mêmes règles que dans l'espace client. La page cesse de fonctionner quand la session expire (7 jours, ou la fin de la période en cours si elle arrive avant), quand un changement plus récent la remplace, ou une fois qu'elle est utilisée. Abuna n'envoie pas d'e-mail au client quand vous créez une session de changement de formule, alors envoyez-le vous-même vers son `url`. Le client reçoit un e-mail quand une mise à niveau prend effet et quand une rétrogradation est programmée. Rien n'est envoyé quand une mise à niveau commence à attendre le paiement, quand elle expire, ou quand une rétrogradation est retirée. Voir [Notifications aux clients](https://abuna.app/docs/guides/customer-notifications.md?hl=fr). En mode Test, Abuna enregistre ces e-mails au lieu de les envoyer.