TWIGZ Backend API Documentation

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.

Id<'customers'>

required

The ID of the customer to create the address for

string

required

A descriptive name for the address (e.g., “Home”, “Office”)

string

required

The complete address string

Id<'cities'>

required

The ID of the city for this address

Id<'areas'>

required

The ID of the area within the city

string

Flat or villa number

string

Building name or number

string

Nearby landmark for easier location

string

GPS latitude coordinate

string

GPS longitude coordinate

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
});

const addressId = await convex.mutation("customers.addresses.createAddress", {
  customerId: "k123456789",
  name: "Office",
  fullAddress: "456 Business District",
  city: "c987654321",
  area: "a789123456",
  isDefault: false
});

import requests

response = requests.post(
    f"{CONVEX_URL}/api/mutation",
    json={
        "path": "customers.addresses.createAddress",
        "args": {
            "customerId": "k123456789",
            "name": "Home",
            "fullAddress": "123 Main Street, Apartment 2B",
            "city": "c987654321",
            "area": "a456789123",
            "isDefault": True
        }
    },
    headers={"Authorization": f"Bearer {token}"}
)

address_id = response.json()

Returns: Id<'customerAddresses'> - The ID of the newly created address

Update Address

Update an existing customer address. Only provided fields will be updated.

Id<'customerAddresses'>

required

The ID of the address to update

string

Updated address name

string

Updated full address

Id<'cities'>

Updated city ID

Id<'areas'>

Updated area ID

string

Updated flat/villa number

string

Updated building name/number

string

Updated landmark

string

Updated latitude

string

Updated longitude

boolean

Whether this should be the default address

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
});

await convex.mutation("customers.addresses.updateAddress", {
  addressId: "a123456789",
  fullAddress: "789 New Street, Updated Location",
  city: "c111222333",
  area: "a333222111"
});

import requests

response = requests.post(
    f"{CONVEX_URL}/api/mutation",
    json={
        "path": "customers.addresses.updateAddress",
        "args": {
            "addressId": "a123456789",
            "name": "Updated Office",
            "isDefault": False
        }
    },
    headers={"Authorization": f"Bearer {token}"}
)

Returns: null

Delete Address

Delete a customer address.

Id<'customerAddresses'>

required

The ID of the address to delete

await convex.mutation(api.customers.addresses.deleteAddress, {
  addressId: "a123456789"
});

await convex.mutation("customers.addresses.deleteAddress", {
  addressId: "a123456789"
});

import requests

response = requests.post(
    f"{CONVEX_URL}/api/mutation",
    json={
        "path": "customers.addresses.deleteAddress",
        "args": {
            "addressId": "a123456789"
        }
    },
    headers={"Authorization": f"Bearer {token}"}
)

Returns: null

Get Customer Addresses

Retrieve all active addresses for a customer, sorted with default address first.

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
});

// Get addresses for authenticated user
const addresses = await convex.query("customers.addresses.getCustomerAddresses", {});

// Get addresses for specific customer
const specificAddresses = await convex.query("customers.addresses.getCustomerAddresses", {
  customerId: "k123456789"
});

import requests

response = requests.post(
    f"{CONVEX_URL}/api/query",
    json={
        "path": "customers.addresses.getCustomerAddresses",
        "args": {
            "customerId": "k123456789"  # Optional
        }
    },
    headers={"Authorization": f"Bearer {token}"}
)

addresses = response.json()

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.

Id<'customerAddresses'>

required

The ID of the address to retrieve

const address = await convex.query(api.customers.addresses.getAddress, {
  addressId: "a123456789"
});

const address = await convex.query("customers.addresses.getAddress", {
  addressId: "a123456789"
});

import requests

response = requests.post(
    f"{CONVEX_URL}/api/query",
    json={
        "path": "customers.addresses.getAddress",
        "args": {
            "addressId": "a123456789"
        }
    },
    headers={"Authorization": f"Bearer {token}"}
)

address = response.json()

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.

Id<'customerAddresses'>

required

The ID of the address to set as default

await convex.mutation(api.customers.addresses.setDefaultAddress, {
  addressId: "a123456789"
});

await convex.mutation("customers.addresses.setDefaultAddress", {
  addressId: "a123456789"
});

import requests

response = requests.post(
    f"{CONVEX_URL}/api/mutation",
    json={
        "path": "customers.addresses.setDefaultAddress",
        "args": {
            "addressId": "a123456789"
        }
    },
    headers={"Authorization": f"Bearer {token}"}
)

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

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Customer Addresses

Overview

Create Address

Update Address

Delete Address

Get Customer Addresses

Get Address

Set Default Address

Authentication & Authorization

Default Address Management

Geographic Information

Error Handling

​Overview

​Create Address

​Update Address

​Delete Address

​Get Customer Addresses

​Get Address

​Set Default Address

​Authentication & Authorization

​Default Address Management

​Geographic Information

​Error Handling

Overview

Create Address

Update Address

Delete Address

Get Customer Addresses

Get Address

Set Default Address

Authentication & Authorization

Default Address Management

Geographic Information

Error Handling