Skip to main content

​
Overview

The Customer Addresses API provides comprehensive address management functionality for customers, including creating, updating, deleting, and managing delivery addresses. This system supports multiple addresses per customer with default address selection and geographic information. Location: convex/customers/addresses.ts

​
Create Address

Create a new delivery address for a customer.
​
customerId
Id<'customers'>
required
The ID of the customer to create the address for
​
name
string
required
A descriptive name for the address (e.g., “Home”, “Office”)
​
fullAddress
string
required
The complete address string
​
city
Id<'cities'>
required
The ID of the city for this address
​
area
Id<'areas'>
required
The ID of the area within the city
​
flatVilaNumber
string
Flat or villa number
​
buildingNameNumber
string
Building name or number
​
landmark
string
Nearby landmark for easier location
​
latitude
string
GPS latitude coordinate
​
longitude
string
GPS longitude coordinate
​
isDefault
boolean
Whether this should be the default address for the customer
const addressId = await convex.mutation(api.customers.addresses.createAddress, {
  customerId: "k123456789",
  name: "Home",
  fullAddress: "123 Main Street, Apartment 2B",
  city: "c987654321",
  area: "a456789123",
  flatVilaNumber: "2B",
  buildingNameNumber: "Al Noor Building",
  landmark: "Near City Mall",
  latitude: "25.2048",
  longitude: "55.2708",
  isDefault: true
});
Returns: Id<'customerAddresses'> - The ID of the newly created address

​
Update Address

Update an existing customer address. Only provided fields will be updated.
​
addressId
Id<'customerAddresses'>
required
The ID of the address to update
​
name
string
Updated address name
​
fullAddress
string
Updated full address
​
city
Id<'cities'>
Updated city ID
​
area
Id<'areas'>
Updated area ID
​
flatVilaNumber
string
Updated flat/villa number
​
buildingNameNumber
string
Updated building name/number
​
landmark
string
Updated landmark
​
latitude
string
Updated latitude
​
longitude
string
Updated longitude
​
isDefault
boolean
Whether this should be the default address
​
isActive
boolean
Whether the address is active
await convex.mutation(api.customers.addresses.updateAddress, {
  addressId: "a123456789",
  name: "Updated Home Address",
  flatVilaNumber: "3A",
  landmark: "Near New Shopping Center",
  isDefault: true
});
Returns: null

​
Delete Address

Delete a customer address.
​
addressId
Id<'customerAddresses'>
required
The ID of the address to delete
await convex.mutation(api.customers.addresses.deleteAddress, {
  addressId: "a123456789"
});
Returns: null

​
Get Customer Addresses

Retrieve all active addresses for a customer, sorted with default address first.
​
customerId
Id<'customers'>
The customer ID. If not provided, uses the authenticated user’s customer profile
const addresses = await convex.query(api.customers.addresses.getCustomerAddresses, {
  customerId: "k123456789" // Optional
});
Returns: Array of address objects with enriched city and area information: 
{
  _id: Id<'customerAddresses'>,
  _creationTime: number,
  name: string,
  fullAddress: string,
  city: {
    _id: Id<'cities'>,
    name: string,
    nameArabic: string
  },
  area: {
    _id: Id<'areas'>,
    name: string,
    city: Id<'cities'>
  },
  flatVilaNumber?: string,
  buildingNameNumber?: string,
  landmark?: string,
  latitude?: string,
  longitude?: string,
  isDefault?: boolean,
  isActive?: boolean
}[]

​
Get Address

Retrieve a specific address by ID with full details.
​
addressId
Id<'customerAddresses'>
required
The ID of the address to retrieve
const address = await convex.query(api.customers.addresses.getAddress, {
  addressId: "a123456789"
});
Returns: Address object with enriched details or null if not found: 
{
  _id: Id<'customerAddresses'>,
  _creationTime: number,
  customerId: Id<'customers'>,
  name: string,
  fullAddress: string,
  city: {
    _id: Id<'cities'>,
    name: string,
    nameArabic: string
  },
  area: {
    _id: Id<'areas'>,
    name: string,
    city: Id<'cities'>
  },
  flatVilaNumber?: string,
  buildingNameNumber?: string,
  landmark?: string,
  latitude?: string,
  longitude?: string,
  isDefault?: boolean,
  isActive?: boolean
} | null

​
Set Default Address

Set a specific address as the default for a customer. This will unset any existing default address.
​
addressId
Id<'customerAddresses'>
required
The ID of the address to set as default
await convex.mutation(api.customers.addresses.setDefaultAddress, {
  addressId: "a123456789"
});
Returns: null

​
Authentication & Authorization

All address operations require authentication and implement proper authorization:
  • User Authentication: All functions verify the user is authenticated through Clerk
  • Ownership Verification: Users can only manage their own addresses
  • Customer Association: Addresses are tied to customer profiles, which are linked to authenticated users

​
Default Address Management

The system automatically manages default addresses:
  • Only one address per customer can be marked as default
  • Setting a new default automatically unsets the previous default
  • Default addresses appear first in address listings
  • Default address logic is handled in createAddress, updateAddress, and setDefaultAddress

​
Geographic Information

Addresses include geographic data for delivery optimization:
  • City and Area References: Links to city and area entities for structured location data
  • GPS Coordinates: Optional latitude/longitude for precise location
  • Address Validation: Ensures referenced cities and areas exist before creating/updating addresses

​
Error Handling

Common error scenarios:
  • Unauthorized: User not authenticated or trying to access another user’s addresses
  • Not Found: Address, city, or area doesn’t exist
  • Invalid References: Invalid city or area IDs provided
  • Ownership Mismatch: Attempting to modify addresses belonging to other customers