Addresses

Les objets Address représentent des adresses postales associées à un Customer. Chaque Customer peut posséder plusieurs adresses (livraison, facturation) avec une adresse marquée comme adresse par défaut.

Cas d’usage typiques : pré-remplir le formulaire de livraison lors du checkout, afficher l’adresse de facturation sur les factures PDF, gérer un carnet d’adresses multi-sites.

Adresse par défaut

Lorsque vous créez une adresse avec is_default: true, l’adresse par défaut précédente est automatiquement déclassée. Un Customer ne peut avoir qu’une seule adresse par défaut à la fois.

Endpoints

Méthode	Endpoint	Description
POST	`/customers/{id}/addresses/`	Ajouter une adresse à un Customer
GET	`/customers/{id}/addresses/`	Lister les adresses d'un Customer
GET	`/customers/{id}/addresses/{addr_id}/`	Récupérer une adresse par son ID
PATCH	`/customers/{id}/addresses/{addr_id}/`	Modifier une adresse
DELETE	`/customers/{id}/addresses/{addr_id}/`	Supprimer définitivement une adresse

Cette introduction est-elle claire ?

Schéma de l’objet

Response Objet Address

Structure complète retournée par tous les endpoints de cette ressource.

json

{
  "id": "addr_xxxxxxxxxxxx",
  "object": "address",
  "customer": "cust_xxxxxxxxxxxx",
  "line1": "Boulevard Triomphal Omar Bongo",
  "line2": "Immeuble Les Arcades, 3ème étage",
  "city": "Libreville",
  "state": "Estuaire",
  "postal_code": null,
  "country": "GA",
  "is_default": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Ajouter une adresse

Crée une nouvelle adresse et l’associe au Customer identifié par {id} dans l’URL. L’adresse est immédiatement disponible pour être utilisée dans un CheckoutSession ou une Invoice.

POST Corps de la requête

line1 Requis

string

Première ligne d’adresse — numéro et nom de rue, boîte postale, etc. Visible par l’acheteur sur les reçus et factures PDF.

line2 Optionnel

string

Complément d’adresse — bâtiment, étage, appartement, zone industrielle, etc.

city Requis

string ex : Libreville

Nom de la ville. Affiché sur les documents de facturation et les étiquettes de livraison.

state Optionnel

string ex : Estuaire

Province, région ou État. Optionnel pour les pays qui n’utilisent pas de subdivisions administratives dans les adresses postales.

postal_code Optionnel

string

Code postal. Peut être null pour les pays d’Afrique centrale où le système postal ne l’exige pas.

country Requis

string ISO 3166-1 alpha-2 ex : GA

Code pays au format ISO 3166-1 alpha-2. Doit correspondre à un pays couvert par votre App.

Exemples : GA (Gabon), CG (Congo-Brazzaville), CM (Cameroun), CI (Côte d’Ivoire). Les codes à deux lettres majuscules sont obligatoires — les noms de pays en clair sont rejetés.

is_default Optionnel

boolean défaut : false

Marque cette adresse comme adresse par défaut du Customer. Si une adresse par défaut existe déjà, elle est automatiquement déclassée.

L’adresse par défaut est pré-sélectionnée dans les formulaires de paiement hébergés par Sangho. Elle est aussi utilisée comme adresse de facturation dans les Invoices quand aucune adresse n’est explicitement spécifiée.

Les paramètres de l'adresse sont-ils clairs ?

Ajouter une adresse

bash

curl -X POST https://api.sangho.com/v1/customers/cust_xxx/addresses/ \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "line1": "Boulevard Triomphal Omar Bongo",
    "line2": "Immeuble Les Arcades, 3ème étage",
    "city": "Libreville",
    "state": "Estuaire",
    "country": "GA",
    "is_default": true
  }'

Response 201 Created

L'adresse est créée et associée au Customer. Si is_default était true, l'ancienne adresse par défaut a été automatiquement déclassée.

json

{
  "id": "addr_xxxxxxxxxxxx",
  "object": "address",
  "customer": "cust_xxxxxxxxxxxx",
  "line1": "Boulevard Triomphal Omar Bongo",
  "line2": "Immeuble Les Arcades, 3ème étage",
  "city": "Libreville",
  "state": "Estuaire",
  "postal_code": null,
  "country": "GA",
  "is_default": true,
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

Lister les adresses

Retourne toutes les adresses associées au Customer, triées par date de création décroissante. L’adresse par défaut apparaît en premier.

Modifier une adresse

Met à jour un ou plusieurs champs d’une adresse existante. Seuls les champs fournis sont modifiés.

PATCH Corps de la mise à jour (PATCH)

line1 Optionnel

string

Nouvelle première ligne d’adresse.

line2 Optionnel

string

Nouveau complément d’adresse. Passez null pour supprimer le champ.

city Optionnel

string

Nouvelle ville.

state Optionnel

string

Nouvelle province/région. Passez null pour supprimer.

postal_code Optionnel

string

Nouveau code postal. Passez null pour supprimer.

country Optionnel

string ISO 3166-1 alpha-2

Nouveau code pays ISO 3166-1 alpha-2.

is_default Optionnel

boolean

Passer true pour promouvoir cette adresse comme adresse par défaut. L’ancienne adresse par défaut est automatiquement déclassée.

Supprimer une adresse

Supprime définitivement l’adresse. L’action est irréversible.

Suppression définitive

Contrairement aux Products, la suppression d’une Address est un hard delete — elle ne peut pas être restaurée. Si l’adresse supprimée était l’adresse par défaut, aucune autre adresse n’est automatiquement promue : vous devrez en désigner une nouvelle via PATCH.

Les opérations sur les adresses sont-elles bien documentées ?

Lister les adresses

bash

curl "https://api.sangho.com/v1/customers/cust_xxx/addresses/" \
  -H "Authorization: Bearer sk_live_xxxx"

Modifier une adresse

bash

curl -X PATCH https://api.sangho.com/v1/customers/cust_xxx/addresses/addr_xxx/ \
  -H "Authorization: Bearer sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "line2": "Appartement 4B",
    "is_default": true
  }'

Response 200 OK — Adresse mise à jour

Retourne l'objet Address complet avec les champs modifiés.

json

{
  "id": "addr_xxxxxxxxxxxx",
  "object": "address",
  "customer": "cust_xxxxxxxxxxxx",
  "line1": "Boulevard Triomphal Omar Bongo",
  "line2": "Appartement 4B",
  "city": "Libreville",
  "state": "Estuaire",
  "postal_code": null,
  "country": "GA",
  "is_default": true,
  "updated_at": "2026-04-10T14:00:00Z"
}

Supprimer une adresse

bash

curl -X DELETE https://api.sangho.com/v1/customers/cust_xxx/addresses/addr_xxx/ \
  -H "Authorization: Bearer sk_live_xxxx"

Response 204 No Content — Supprimée

La suppression a réussi. Aucun corps de réponse n'est retourné.