Customer Module — Storefront

HTTP surface for the customer-side address book. The customer identity itself lives in Better-Auth's user table; this module owns the shopping-related customer data on top of that — currently just the address book.

Source: api-modules/customer/src/controllers/store-address.controller.ts.

The address book is read by the order module at place-order (for the shippingAddress / billingAddress snapshot) and by the cart for the address-bound shipping rate. The admin customer picker lives in docs/separated/admin/customer.md.

Conventions

Authentication

Every read and write is scoped to the session's user.id. Cross-user ids return 404 Not Found, never 403 — so existence of another customer's address can't be inferred from the response code.

Response envelope

{
  "data": <payload>,
  "message": "Success",
  "statusCode": 200,
  "metadata": { /* optional, e.g. pagination */ }
}

Error envelope

Domain types

AddressResponse

type AddressResponse = {
  id: string;
  firstName: string;
  lastName: string;
  fullAddress: string;           // 1..500 chars
  city: string;                  // 1..80 chars
  pincode: string;               // Indian 6-digit, /^[1-9]\d{5}$/
  state: string;                 // 1..80 chars
  phone: string;                 // Indian, /^(\+91)?[6-9]\d{9}$/
  country: string;               // ISO-3166 alpha-2; default "IN"
  isDefault: boolean;
  createdAt: string;             // ISO
  updatedAt: string;             // ISO
};

Phone and pincode validation is India-specific today; internationalization swaps these for a country-driven validator.

Default-address rule

A customer has at most one default address. The address book invariants:

Endpoints

GET /store/addresses — List my addresses

Default address comes first; the rest are sorted by most-recently-touched.

Query

The service converts page-based pagination to offset internally; the response uses the standard { data, metadata: { total, limit, offset, hasMore } } envelope.

Response 200 — paginated AddressResponse[].

GET /store/addresses/:id — Get one of my addresses

Response 200 — AddressResponse.

Errors

POST /store/addresses — Create an address

Body

{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "fullAddress": "221B Baker Street",
  "city": "London",
  "pincode": "110001",                 // 6-digit, first digit 1-9
  "state": "Delhi",
  "phone": "+919876543210",            // +91 prefix optional
  "country": "IN",                     // ISO-3166 alpha-2; default "IN"
  "isDefault": false
}

Response 201 — AddressResponse. If this is the caller's first address, the response has isDefault: true even when the body sent false.

Errors

PATCH /store/addresses/:id — Update an address

Body — partial CreateAddressInput. At least one field must be present (no-op writes are rejected at the zod layer to avoid a misleading 200).

{ "city": "Mumbai", "pincode": "400001" }

Response 200 — updated AddressResponse.

Errors

DELETE /store/addresses/:id — Delete an address

Hard delete. Deleting the default address leaves the customer without a default until they explicitly pick one — no auto-promotion.

Response 204 No Content.

Errors

POST /store/addresses/:id/default — Set as default

Flips the chosen address to isDefault: true and the prior default (if any) to false. Idempotent — already-default is a no-op 200.

Response 200 — the new default AddressResponse.

Errors

Related modules

• auth — owns the user table that the address book references via userId.
• order — snapshots shippingAddress / billingAddress from this module at place-order. See order.md.
• cart — PATCH /store/cart/address accepts the address id from this module to pin the cart's delivery target. See cart.md.