Créer un abonnement avec l'API Recharge
Crée un abonnement sur une adresse d'un client et le renvoie. Le produit doit avoir au moins un plan dans Recharge. Les champs de fréquence, la date du premier prélèvement, la variante, la quantité et l'adresse sont obligatoires.
- Identifiant
- recharge_create_subscription
L'appel
POST https://connect.reportei.com/api/tools/recharge_create_subscription/execute
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Content-Type: application/json
Accept: application/json
{
"customer_toolkit": "<connection UUID>",
"arguments": {
"address_id": 1,
"external_variant_id": {},
"quantity": 1,
"next_charge_scheduled_at": "<next_charge_scheduled_at>",
"order_interval_unit": "day",
"order_interval_frequency": 1,
"charge_interval_frequency": 1
}
}Votre système envoie l'id de la connexion de votre client et les arguments de la tool. Les headers sont les mêmes que pour toute l'API Connect : le token de votre produit et celui de votre client.
Paramètres
Les descriptions des paramètres suivent la documentation officielle de l'app, en anglais.
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| address_id | integer | Oui | Id of an address of the customer, from the addresses of Get customer with include addresses, or the address_id of a subscription in List subscriptions. |
| external_variant_id | object | Oui | Product variant in the store platform. The variant id comes from external_variant_id of a subscription in List subscriptions, or from the product page in the store admin. |
| quantity | integer | Oui | Number of units in each order. |
| next_charge_scheduled_at | string | Oui | Date of the first charge, as YYYY-MM-DD. |
| order_interval_unit | string | Oui | Unit of the order and charge frequencies.Valeurs : day, week, month |
| order_interval_frequency | integer | Oui | Number of order_interval_unit between orders, such as 1 for a monthly order. |
| charge_interval_frequency | integer | Oui | Number of order_interval_unit between charges. Equal to order_interval_frequency when each order is paid on its own; a multiple of it for a prepaid subscription. |
| order_day_of_month | integer | Non | Day of the month the orders are created on, when order_interval_unit is month. |
| order_day_of_week | integer | Non | Day of the week the orders are created on, when order_interval_unit is week. |
| expire_after_specific_number_of_charges | integer | Non | Number of charges after which the subscription expires. Without it, the subscription runs until it is cancelled. |
| price | string | Non | Price of one unit, such as 10.00. |
| product_title | string | Non | Name of the product. |
| properties | array | Non | Line item properties of the subscription, such as a color or an engraving text. |
Connexions possibles
Votre client connecte son compte Recharge une seule fois, avec l'un des modes ci-dessous. La même connexion sert à toutes les tools du toolkit.
Clé d'API
Votre client colle la clé de l'app sur un écran de Connect, ou votre système envoie la clé avec POST /api/customer-toolkits, sans écran.
La réponse
En cas de succès, Connect conserve le statut et le corps de la réponse de l'app. Les erreurs HTTP renvoyées par l'app utilisent l'objet {error, api_error} ; l'authentification ou la validation peuvent échouer avant l'exécution. Le header X-Toolkit-Execution-Id identifie l'exécution enregistrée, consultable avec GET /api/tools/executions/{uuid}.
Prête pour les agents IA
L'input de cette tool est un JSON Schema, disponible via GET /api/tools/recharge_create_subscription. Il devient la définition de tool de votre agent sans conversion.
Autres tools Recharge
- Lister les abonnementsGETListe les abonnements de la boutique avec client, adresse, produit, quantité, prix, fréquence, statut et next_charge_scheduled_at. Jusqu'à 250 par page : passez le next_cursor de la réponse en cursor pour lire la page suivante.
- Consulter un abonnementGETRenvoie un abonnement avec produit, quantité, prix, fréquence, statut, motif d'annulation et next_charge_scheduled_at.
- Mettre à jour un abonnementPUTModifie un abonnement actif et le renvoie. Changer order_interval_unit, order_interval_frequency ou charge_interval_frequency exige les trois, recalcule la date du prochain prélèvement et supprime les prélèvements sautés et modifiés manuellement. Pour ne déplacer que le prochain prélèvement, utilisez Set subscription next charge date.
- Annuler un abonnementPOSTAnnule un abonnement actif et le renvoie. Recharge peut envoyer un e-mail au client et au propriétaire de la boutique à ce sujet, sauf si send_email vaut false.
- Réactiver un abonnementPOSTRéactive un abonnement annulé et le renvoie, en effaçant la date et le motif d'annulation.
- Définir la date du prochain prélèvementPOSTDéplace le prochain prélèvement d'un abonnement à une autre date et renvoie l'abonnement. Quand deux abonnements actifs de la même adresse se retrouvent à la même date, leurs prélèvements sont fusionnés en un nouveau prélèvement avec un nouvel id.
- Lister les clientsGETListe les clients de la boutique avec e-mail, nom, le nombre d'abonnements actifs et si le moyen de paiement est valide ou en relance (dunning). Filtrez par e-mail pour retrouver un client. Jusqu'à 250 par page : passez le next_cursor de la réponse en cursor.
- Consulter un clientGETRenvoie un client. Avec include, la réponse contient aussi les adresses, abonnements ou moyens de paiement du client ; l'id de chaque adresse est l'address_id que prend Create subscription.
Voyez Connect appliqué à votre produit.
Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.
