Addresses

Address objects represent postal addresses associated with a Customer. Each Customer can own several addresses (shipping, billing), with one address marked as the default address.

Typical use cases: pre-filling the shipping form at checkout, displaying the billing address on PDF invoices, managing a multi-site address book.

Default address

When you create an address with is_default: true, the previous default address is automatically demoted. A Customer can have only one default address at a time.

Endpoints

Méthode	Endpoint	Description
POST	`/customers/{id}/addresses/`	Add an address to a Customer
GET	`/customers/{id}/addresses/`	List a Customer's addresses
GET	`/customers/{id}/addresses/{addr_id}/`	Retrieve an address by its ID
PATCH	`/customers/{id}/addresses/{addr_id}/`	Update an address
DELETE	`/customers/{id}/addresses/{addr_id}/`	Permanently delete an address

Is this introduction clear?

Object schema

ResponseAddress object

Full structure returned by all endpoints of this resource.

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"
}

Add an address

Creates a new address and associates it with the Customer identified by {id} in the URL. The address is immediately available for use in a CheckoutSession or an Invoice.

POSTRequest body

line1Requis

string

First address line — street number and name, PO box, etc. Visible to the buyer on receipts and PDF invoices.

line2Optionnel

string

Additional address details — building, floor, apartment, industrial zone, etc.

cityRequis

stringex :Libreville

City name. Displayed on billing documents and shipping labels.

stateOptionnel

stringex :Estuaire

Province, region, or state. Optional for countries that do not use administrative subdivisions in postal addresses.

postal_codeOptionnel

string

Postal code. Can be null for Central African countries where the postal system does not require one.

countryRequis

stringISO 3166-1 alpha-2ex :GA

Country code in ISO 3166-1 alpha-2 format. Must correspond to a country covered by your App.

Examples: GA (Gabon), CG (Republic of the Congo), CM (Cameroon), CI (Côte d’Ivoire). Two-letter uppercase codes are required — plain-text country names are rejected.

is_defaultOptionnel

booleandéfaut :false

Marks this address as the Customer’s default address. If a default address already exists, it is automatically demoted.

The default address is pre-selected in payment forms hosted by Sangho. It is also used as the billing address on Invoices when no address is explicitly specified.

Are the address parameters clear?

Add an address

bash

curl -X POST https://api.sangho.ga/v1/customers/cust_xxx/addresses/ \
  -H "Authorization: Bearer sk_prod_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
  }'

Response201 Created

The address is created and associated with the Customer. If is_default was true, the previous default address was automatically demoted.

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"
}

List addresses

Returns all addresses associated with the Customer, sorted by creation date descending. The default address appears first.

Update an address

Updates one or more fields of an existing address. Only the fields provided are modified.

PATCHUpdate body (PATCH)

line1Optionnel

string

New first address line.

line2Optionnel

string

New additional address details. Pass null to remove the field.

cityOptionnel

string

New city.

stateOptionnel

string

New province/region. Pass null to remove it.

postal_codeOptionnel

string

New postal code. Pass null to remove it.

countryOptionnel

stringISO 3166-1 alpha-2

New ISO 3166-1 alpha-2 country code.

is_defaultOptionnel

boolean

Pass true to promote this address to be the default address. The previous default address is automatically demoted.

Delete an address

Permanently deletes the address. This action is irreversible.

Permanent deletion

Unlike Products, deleting an Address is a hard delete — it cannot be restored. If the deleted address was the default address, no other address is automatically promoted: you will need to designate a new one via PATCH.

Are the address operations well documented?

List addresses

bash

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

Update an address

bash

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

Response200 OK — Address updated

Returns the full Address object with the modified fields.

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"
}

Delete an address

bash

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

Response204 No Content — Deleted

The deletion succeeded. No response body is returned.