Addresses API - OpenCart

Overview

The Addresses API provides functionality for managing customer addresses including adding, editing, retrieving, and deleting addresses. Addresses are used for both payment (billing) and shipping (delivery) purposes. Model Location: catalog/model/account/address.php

Add Address

Create a new address for a customer.

Method

$this->load->model('account/address');
$address_id = $this->model_account_address->addAddress($customer_id, $data);

Parameters

customer_id

integer

required

Customer ID who owns this address

firstname

string

required

First name (1-32 characters)

lastname

string

required

Last name (1-32 characters)

company

string

Company name

address_1

string

required

Address line 1 (3-128 characters)

address_2

string

Address line 2

city

string

required

City (2-128 characters)

postcode

string

Postal/ZIP code (2-10 characters, if required by country)

country_id

integer

required

Country ID

zone_id

integer

required

Zone/State/Province ID

custom_field

object

Custom address fields

default

boolean

default:false

Set as default address

Example Request

$address_data = [
    'firstname'    => 'John',
    'lastname'     => 'Doe',
    'company'      => 'Acme Corporation',
    'address_1'    => '123 Main Street',
    'address_2'    => 'Suite 100',
    'postcode'     => '10001',
    'city'         => 'New York',
    'zone_id'      => 3655,  // New York state
    'country_id'   => 223,   // United States
    'custom_field' => [],
    'default'      => 1
];

$this->load->model('account/address');
$address_id = $this->model_account_address->addAddress($customer_id, $address_data);

echo "New address ID: " . $address_id;

Response

Returns the new address ID (integer).

42  // New address_id

Edit Address

Update an existing address.

Method

$this->load->model('account/address');
$this->model_account_address->editAddress($customer_id, $address_id, $data);

Parameters

customer_id

integer

required

Customer ID who owns the address

address_id

integer

required

Address ID to update

data

object

required

Address data (same fields as Add Address)

Example

$updated_address = [
    'firstname'    => 'John',
    'lastname'     => 'Doe',
    'company'      => 'New Company Inc',
    'address_1'    => '456 Oak Avenue',
    'address_2'    => 'Apt 5B',
    'postcode'     => '10002',
    'city'         => 'New York',
    'zone_id'      => 3655,
    'country_id'   => 223,
    'custom_field' => [],
    'default'      => 0
];

$this->model_account_address->editAddress($customer_id, $address_id, $updated_address);

Get Address

Retrieve a specific address by ID.

Method

$this->load->model('account/address');
$address_info = $this->model_account_address->getAddress($customer_id, $address_id);

Parameters

customer_id

integer

required

Customer ID

address_id

integer

required

Address ID to retrieve

Response

address_id

integer

Address identifier

customer_id

integer

Customer owner

firstname

string

First name

lastname

string

Last name

company

string

Company name

address_1

string

Address line 1

address_2

string

Address line 2

city

string

City

postcode

string

Postal code

country_id

integer

Country ID

country

string

Country name

iso_code_2

string

Country ISO code (2 letters)

iso_code_3

string

Country ISO code (3 letters)

zone_id

integer

Zone/State ID

zone

string

Zone/State name

zone_code

string

Zone/State code

address_format

string

Address format template

custom_field

string

JSON-encoded custom fields

default

boolean

Whether this is the default address

Example Response

{
  "address_id": 42,
  "customer_id": 123,
  "firstname": "John",
  "lastname": "Doe",
  "company": "Acme Corporation",
  "address_1": "123 Main Street",
  "address_2": "Suite 100",
  "city": "New York",
  "postcode": "10001",
  "country_id": 223,
  "country": "United States",
  "iso_code_2": "US",
  "iso_code_3": "USA",
  "zone_id": 3655,
  "zone": "New York",
  "zone_code": "NY",
  "address_format": "{firstname} {lastname}\n{company}\n{address_1}\n{address_2}\n{city}, {zone} {postcode}\n{country}",
  "custom_field": "{}",
  "default": true
}

Get Addresses

Retrieve all addresses for a customer.

Method

$this->load->model('account/address');
$addresses = $this->model_account_address->getAddresses($customer_id);

Parameters

customer_id

integer

required

Customer ID

Response

Returns an array of address objects.

Example

$customer_id = 123;
$addresses = $this->model_account_address->getAddresses($customer_id);

foreach ($addresses as $address) {
    echo $address['address_id'] . ': ';
    echo $address['firstname'] . ' ' . $address['lastname'] . ', ';
    echo $address['city'] . ', ' . $address['zone'];
    
    if ($address['default']) {
        echo ' (Default)';
    }
    
    echo "\n";
}

Delete Address

Delete an address.

Method

$this->load->model('account/address');
$this->model_account_address->deleteAddresses($customer_id, $address_id);

Parameters

customer_id

integer

required

Customer ID

address_id

integer

required

Address ID to delete

Example

$this->model_account_address->deleteAddresses($customer_id, $address_id);

Get Total Addresses

Get count of addresses for a customer.

Method

$this->load->model('account/address');
$total = $this->model_account_address->getTotalAddresses($customer_id);

Example

$count = $this->model_account_address->getTotalAddresses(123);
echo "Customer has {$count} saved addresses";

Default Address

When an address is set as default:

The new address gets default = 1
All other addresses for that customer get default = 0
Only one address per customer can be default

// Source: address.php:46-48
if (!empty($data['default'])) {
    $this->db->query("UPDATE `" . DB_PREFIX . "address` SET `default` = '0' 
        WHERE `address_id` != '" . (int)$address_id . "' 
        AND `customer_id` = '" . (int)$customer_id . "'");
}

Use in API Orders

Set Payment Address

// Get saved address
$this->load->model('account/address');
$address = $this->model_account_address->getAddress($customer_id, $address_id);

if ($address) {
    // Use for payment address
    $payment_data = [
        'payment_firstname'  => $address['firstname'],
        'payment_lastname'   => $address['lastname'],
        'payment_company'    => $address['company'],
        'payment_address_1'  => $address['address_1'],
        'payment_address_2'  => $address['address_2'],
        'payment_city'       => $address['city'],
        'payment_postcode'   => $address['postcode'],
        'payment_country_id' => $address['country_id'],
        'payment_zone_id'    => $address['zone_id'],
        'payment_custom_field' => json_decode($address['custom_field'], true)
    ];
    
    $this->load->controller('api/payment_address', $payment_data);
}

Set Shipping Address

// Use saved address for shipping
$address = $this->model_account_address->getAddress($customer_id, $address_id);

if ($address) {
    $shipping_data = [
        'shipping_firstname'  => $address['firstname'],
        'shipping_lastname'   => $address['lastname'],
        'shipping_company'    => $address['company'],
        'shipping_address_1'  => $address['address_1'],
        'shipping_address_2'  => $address['address_2'],
        'shipping_city'       => $address['city'],
        'shipping_postcode'   => $address['postcode'],
        'shipping_country_id' => $address['country_id'],
        'shipping_zone_id'    => $address['zone_id'],
        'shipping_custom_field' => json_decode($address['custom_field'], true)
    ];
    
    $this->load->controller('api/shipping_address', $shipping_data);
}

Address Format

Address format is country-specific:

// Example US format
"{firstname} {lastname}
{company}
{address_1}
{address_2}
{city}, {zone} {postcode}
{country}"

// Example UK format  
"{firstname} {lastname}
{company}
{address_1}
{address_2}
{city}
{postcode}
{country}"

Complete Address Management Example

class AddressManager {
    public function manageCustomerAddresses($customer_id) {
        $this->load->model('account/address');
        
        // Get all addresses
        $addresses = $this->model_account_address->getAddresses($customer_id);
        
        if (empty($addresses)) {
            // Add first address
            $address_id = $this->addNewAddress($customer_id);
        } else {
            // Use existing default address
            $default_address = null;
            
            foreach ($addresses as $address) {
                if ($address['default']) {
                    $default_address = $address;
                    break;
                }
            }
            
            if (!$default_address) {
                $default_address = $addresses[0];
            }
            
            return $default_address;
        }
    }
    
    private function addNewAddress($customer_id) {
        $data = [
            'firstname' => 'John',
            'lastname' => 'Doe',
            'address_1' => '123 Main St',
            'city' => 'New York',
            'postcode' => '10001',
            'country_id' => 223,
            'zone_id' => 3655,
            'default' => 1
        ];
        
        return $this->model_account_address->addAddress($customer_id, $data);
    }
}

Addresses are customer-specific. The customer_id parameter ensures addresses can only be accessed by their owner.

Validation

Address validation is performed by the API address controllers:

First name: 1-32 characters
Last name: 1-32 characters
Address: 3-128 characters
City: 2-128 characters
Country: Must exist and be active
Zone: Must exist if country has zones
Postcode: 2-10 characters (if required by country)

Next Steps

Orders API

Use addresses in orders

Countries API

Get country information

Zones API

Get zone/state information

Customers API

Manage customer data

Overview

Catalog API

Sales API

Account API

Localization API

​Overview

​Add Address

​Method

​Parameters

​Example Request

​Response

​Edit Address

​Method

​Parameters

​Example

​Get Address

​Method

​Parameters

​Response

​Example Response

​Get Addresses

​Method

​Parameters

​Response

​Example

​Delete Address

​Method

​Parameters

​Example

​Get Total Addresses

​Method

​Example

​Default Address

​Use in API Orders

​Set Payment Address

​Set Shipping Address

​Address Format

​Complete Address Management Example

​Validation

​Next Steps

Orders API

Countries API

Zones API

Customers API

Build docs developers (and LLMs) love

Overview

Add Address

Method

Parameters

Example Request

Response

Edit Address

Method

Parameters

Example

Get Address

Method

Parameters

Response

Example Response

Get Addresses

Method

Parameters

Response

Example

Delete Address

Method

Parameters

Example

Get Total Addresses

Method

Example

Default Address

Use in API Orders

Set Payment Address

Set Shipping Address

Address Format

Complete Address Management Example

Validation

Next Steps