Addresses

Manage multiple billing and shipping addresses per customer. Set defaults and query addresses by type.

Important

Addresses require a customer. You must create a customer before adding addresses. Each customer can have multiple addresses of different types.

Address Model

class Address {
  id: string;              // Unique UUID identifier
  customerId: string;      // Associated customer ID (required)
  type: AddressType;       // Address type
  label: string;           // Display label (e.g. "Home", "Office")
  street: string;          // Street address
  city: string;            // City
  postalCode: string;      // Postal/ZIP code
  country: string;         // Country code (e.g. "US", "DE")
  state: string | null;    // State/province (optional)
  isDefault: boolean;      // Whether this is the default address for its type
  isActive: boolean;       // Active status (default: true)
}

enum AddressType {
  BILLING    // Billing address for invoices
  SHIPPING   // Shipping address for deliveries
  BOTH       // Used for both billing and shipping
}

Address Operations

Create Address

Create a billing address:

import { createServices } from "commercio";

const { addressService } = createServices();

// Create a billing address
const billing = await addressService.createAddress({
  customerId: customer.id,
  type: "BILLING",
  label: "Home",
  street: "123 Main St",
  city: "New York",
  postalCode: "10001",
  country: "US",
  state: "NY",
});

console.log(billing.id);        // UUID
console.log(billing.type);      // "BILLING"
console.log(billing.label);     // "Home"
console.log(billing.isDefault); // false
console.log(billing.isActive);  // true

Create a shipping address:

// Create a shipping address
const shipping = await addressService.createAddress({
  customerId: customer.id,
  type: "SHIPPING",
  label: "Office",
  street: "456 Business Ave, Suite 200",
  city: "San Francisco",
  postalCode: "94105",
  country: "US",
  state: "CA",
});

console.log(shipping.type); // "SHIPPING"

Create a dual-purpose address:

// Create an address for both billing and shipping
const both = await addressService.createAddress({
  customerId: customer.id,
  type: "BOTH",
  label: "Primary",
  street: "789 Elm St",
  city: "Austin",
  postalCode: "78701",
  country: "US",
  state: "TX",
});

console.log(both.type); // "BOTH"

Error Handling

Creating an address requires a valid customer:

try {
  await addressService.createAddress({
    customerId: "non-existent-id",
    type: "BILLING",
    label: "Home",
    street: "123 Main St",
    city: "New York",
    postalCode: "10001",
    country: "US",
  });
} catch (error) {
  // Error: Customer not found
}

Complete Example

import { createServices } from "commercio";

const { addressService, customerService } = createServices();

// 1. Create a customer first
const customer = await customerService.createCustomer({
  name: "Alice Johnson",
  email: "alice@example.com",
});

// 2. Create a billing address
const billing = await addressService.createAddress({
  customerId: customer.id,
  type: "BILLING",
  label: "Home",
  street: "123 Main St",
  city: "New York",
  postalCode: "10001",
  country: "US",
  state: "NY",
});

// 3. Create a shipping address
const shipping = await addressService.createAddress({
  customerId: customer.id,
  type: "SHIPPING",
  label: "Office",
  street: "456 Business Ave, Suite 200",
  city: "San Francisco",
  postalCode: "94105",
  country: "US",
  state: "CA",
});

// 4. Set defaults
await addressService.setDefaultAddress(billing.id);
await addressService.setDefaultAddress(shipping.id);

// 5. Query by type
const billingAddresses = await addressService.getAddressesByType(
  customer.id,
  "BILLING"
);
console.log(`Billing addresses: ${billingAddresses.length}`); // 1

const shippingAddresses = await addressService.getAddressesByType(
  customer.id,
  "SHIPPING"
);
console.log(`Shipping addresses: ${shippingAddresses.length}`); // 1

// 6. Get defaults for checkout
const defaultBilling = await addressService.getDefaultAddress(customer.id, "BILLING");
const defaultShipping = await addressService.getDefaultAddress(customer.id, "SHIPPING");

console.log(`Bill to: ${defaultBilling.street}, ${defaultBilling.city}`);
console.log(`Ship to: ${defaultShipping.street}, ${defaultShipping.city}`);

// 7. Get all addresses
const allAddresses = await addressService.getAddressesByCustomer(customer.id);
console.log(`Total addresses: ${allAddresses.length}`); // 2

Best Practices

1. Set Default Addresses Early

Set a default address right after creation for a smooth checkout experience:

// Set as default right after creation
const address = await addressService.createAddress({ ... });
await addressService.setDefaultAddress(address.id);

2. Use Address Types Appropriately

Use BILLING for invoices, SHIPPING for deliveries, and BOTH when the address serves both purposes:

// Separate billing and shipping
const billing = await addressService.createAddress({
  customerId: customer.id,
  type: "BILLING",
  label: "Billing - HQ",
  ...addressFields,
});

// Or use BOTH for a single address
const primary = await addressService.createAddress({
  customerId: customer.id,
  type: "BOTH",
  label: "Primary",
  ...addressFields,
});

3. Deactivate Instead of Delete

Deactivate old addresses rather than deleting to preserve order history references:

// Deactivate old address
await addressService.deactivateAddress(oldAddress.id);

// Only show active addresses to the customer
const addresses = await addressService.getAddressesByCustomer(customer.id);
const active = addresses.filter(a => a.isActive);

4. Use Descriptive Labels

Give addresses clear labels so customers can easily identify them:

// Good: Descriptive labels
await addressService.createAddress({ label: "Home", ... });
await addressService.createAddress({ label: "Office - Downtown", ... });
await addressService.createAddress({ label: "Warehouse", ... });

// Avoid: Generic labels
await addressService.createAddress({ label: "Address 1", ... });