Addresses

Addresses can be associated to orders as their shipping or billing addresses. Add a Google or Bing geocoder to a market if you want its addresses to be automatically geocoded. Customers can save their most used addresses in their address books (as customer addresses).

The address object

An address object is returned as part of the response body of each successful create, list, retrieve or update API call. The following table contains the list of all its fields along with their type, description and example values.
Object fields:
business
boolean
Indicates if it's a business or a personal address
Example:
false
first_name
string
Address first name (personal)
Example:
John
last_name
string
Address last name (personal)
Example:
Smith
company
string
Address company name (business)
Example:
The Red Brand Inc.
full_name
string
Company name (business) of first name and last name (personal)
Example:
John Smith
line_1
string
Address line 1, i.e. Street address, PO Box
Example:
2883 Geraldine Lane
line_2
string
Address line 2, i.e. Apartment, Suite, Building
Example:
Apt.23
city
string
Address city
Example:
New York
zip_code
string
ZIP or postal code
Example:
10013
state_code
string
State, province or region code.
Example:
NY
country_code
string
The international 2-letter country code as defined by the ISO 3166-1 standard
Example:
US
phone
string
Phone number (including extension).
Example:
(212) 646-338-1228
full_address
string
Compact description of the address location, without the full name
Example:
2883 Geraldine Lane Apt.23, 10013 New York NY (US) (212) 646-338-1228
name
string
Compact description of the address location, including the full name
Example:
John Smith, 2883 Geraldine Lane Apt.23, 10013 New York NY (US) (212) 646-338-1228
email
string
Email address.
notes
string
A free notes attacched to the address. When used as a shipping address, this can be useful to let the customers add specific delivery instructions.
Example:
Please ring the bell twice
lat
float
The address geocoded latitude. This is automatically generated when creating a shipping/billing address for an order and a valid geocoder is attached to the order's market.
Example:
40.6971494
lng
float
The address geocoded longitude. This is automatically generated when creating a shipping/billing address for an order and a valid geocoder is attached to the order's market.
Example:
-74.2598672
is_localized
boolean
Indicates if the latitude and logitude are present, either geocoded or manually updated
Example:
true
is_geocoded
boolean
Indicates if the address has been successfully geocoded
Example:
true
provider_name
string
The geocoder provider name (either Google or Bing)
Example:
google
map_url
string
The map url of the geocoded address (if geocoded)
Example:
https://www.google.com/maps/search/?api=1&query=40.6971494,-74.2598672
static_map_url
string
The static map image url of the geocoded address (if geocoded)
Example:
https://maps.googleapis.com/maps/api/staticmap?center=40.6971494,-74.2598672&size=640x320&zoom=15
billing_info
string
Customer's billing information (i.e. VAT number, codice fiscale)
Example:
VAT ID IT02382940977
id
integer
Unique identifier for the resource.
Example:
1234
created_at
datetime
Time at which the resource was created.
Example:
2018-01-01T12:00:00.000Z
updated_at
datetime
Time at which the resource was last updated.
Example:
2018-01-01T12:00:00.000Z
reference
string
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
object
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
{"foo":"bar"}
relationship (N:1)
The geocoder attached to the address, to be used for geocoding.

Create an address

To create a new address, send a POST request to the /api/addresses endpoint, passing the resource arguments in the request body. The following table contains the list of all the possible arguments, along with their type, description and examples values. All the arguments marked as required must be present in the request.
Arguments:
business
optional, default is 'false'
Indicates if it's a business or a personal address
Example:
false
first_name
required if 'business' is 'false'
Address first name (personal)
Example:
John
last_name
required if 'business' is 'false'
Address last name (personal)
Example:
Smith
company
required if 'business' is 'true'
Address company name (business)
Example:
The Red Brand Inc.
line_1
required
Address line 1, i.e. Street address, PO Box
Example:
2883 Geraldine Lane
line_2
optional
Address line 2, i.e. Apartment, Suite, Building
Example:
Apt.23
city
required
Address city
Example:
New York
zip_code
required
ZIP or postal code
Example:
10013
state_code
required
State, province or region code.
Example:
NY
country_code
required
The international 2-letter country code as defined by the ISO 3166-1 standard
Example:
US
phone
required
Phone number (including extension).
Example:
(212) 646-338-1228
email
optional
Email address.
Example:
notes
optional
A free notes attacched to the address. When used as a shipping address, this can be useful to let the customers add specific delivery instructions.
Example:
Please ring the bell twice
lat
optional
The address geocoded latitude. This is automatically generated when creating a shipping/billing address for an order and a valid geocoder is attached to the order's market.
Example:
40.6971494
lng
optional
The address geocoded longitude. This is automatically generated when creating a shipping/billing address for an order and a valid geocoder is attached to the order's market.
Example:
-74.2598672
billing_info
configurable
Customer's billing information (i.e. VAT number, codice fiscale)
Example:
VAT ID IT02382940977
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
#
optional
The geocoder attached to the address, to be used for geocoding.
Example request:
POST /api/addresses HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "addresses",
    "attributes": {
      "line_1": "2883 Geraldine Lane",
      "city": "New York",
      "zip_code": "10013",
      "state_code": "NY",
      "country_code": "US",
      "phone": "(212) 646-338-1228"
    }
  }
}
Example response: 201 Created
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "addresses",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/addresses/1234"
    },
    "attributes": {
      "business": "false",
      "first_name": "John",
      "last_name": "Smith",
      "company": "The Red Brand Inc.",
      "full_name": "John Smith",
      "line_1": "2883 Geraldine Lane",
      "line_2": "Apt.23",
      "city": "New York",
      "zip_code": "10013",
      "state_code": "NY",
      "country_code": "US",
      "phone": "(212) 646-338-1228",
      "full_address": "2883 Geraldine Lane Apt.23, 10013 New York NY (US) (212) 646-338-1228",
      "name": "John Smith, 2883 Geraldine Lane Apt.23, 10013 New York NY (US) (212) 646-338-1228",
      "email": "[email protected]",
      "notes": "Please ring the bell twice",
      "lat": "40.6971494",
      "lng": "-74.2598672",
      "is_localized": "true",
      "is_geocoded": "true",
      "provider_name": "google",
      "map_url": "https://www.google.com/maps/search/?api=1&query=40.6971494,-74.2598672",
      "static_map_url": "https://maps.googleapis.com/maps/api/staticmap?center=40.6971494,-74.2598672&size=640x320&zoom=15",
      "billing_info": "VAT ID IT02382940977",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "geocoder": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/addresses/1234/relationships/geocoder",
          "related": "https://your-brand.commercelayer.io/api/addresses/1234/geocoder"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

List all addresses

To fetch a collection of addresses, send a GET request to the /api/addresses endpoint.

Example request:
GET /api/addresses HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "id": "1234",
      "type": "addresses",
      "links": {
        "self": "https://your-brand.commercelayer.io/api/addresses/1234"
      },
      "attributes": {
        "business": "false",
        "first_name": "John",
        "last_name": "Smith",
        "company": "The Red Brand Inc.",
        "full_name": "John Smith",
        "line_1": "2883 Geraldine Lane",
        "line_2": "Apt.23",
        "city": "New York",
        "zip_code": "10013",
        "state_code": "NY",
        "country_code": "US",
        "phone": "(212) 646-338-1228",
        "full_address": "2883 Geraldine Lane Apt.23, 10013 New York NY (US) (212) 646-338-1228",
        "name": "John Smith, 2883 Geraldine Lane Apt.23, 10013 New York NY (US) (212) 646-338-1228",
        "email": "[email protected]",
        "notes": "Please ring the bell twice",
        "lat": "40.6971494",
        "lng": "-74.2598672",
        "is_localized": "true",
        "is_geocoded": "true",
        "provider_name": "google",
        "map_url": "https://www.google.com/maps/search/?api=1&query=40.6971494,-74.2598672",
        "static_map_url": "https://maps.googleapis.com/maps/api/staticmap?center=40.6971494,-74.2598672&size=640x320&zoom=15",
        "billing_info": "VAT ID IT02382940977",
        "id": "1234",
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "ANYREFEFERNCE",
        "metadata": {
          "foo": "bar"
        }
      },
      "relationships": {
        "geocoder": {
          "links": {
            "self": "https://your-brand.commercelayer.io/api/addresses/1234/relationships/geocoder",
            "related": "https://your-brand.commercelayer.io/api/addresses/1234/geocoder"
          }
        }
      },
      "meta": {
        "mode": "test"
      }
    },
    {
      "other": "... 24 addresses (first page)"
    }
  ],
  "meta": {
    "record_count": 125,
    "page_count": 5
  },
  "links": {
    "first": "/api/addresses?page[number]=1&page[size]=25",
    "prev": "/api/addresses?page[number]=2&page[size]=25",
    "next": "/api/addresses?page[number]=4&page[size]=25",
    "last": "/api/addresses?page[number]=5&page[size]=25"
  }
}
Available filters
idbusinesscountry_codereferenceidscreated_at_fromcreated_at_toupdated_at_fromupdated_at_to
Sortable attributes
citycountry_codeidcreated_atupdated_atreference

Retrieve an address

To fetch a single address, send a GET request to the /api/addresses/{{id}} endpoint, where {{id}} is the id of the resource that you want to retrieve.
Example request:
GET /api/addresses/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "addresses",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/addresses/1234"
    },
    "attributes": {
      "business": "false",
      "first_name": "John",
      "last_name": "Smith",
      "company": "The Red Brand Inc.",
      "full_name": "John Smith",
      "line_1": "2883 Geraldine Lane",
      "line_2": "Apt.23",
      "city": "New York",
      "zip_code": "10013",
      "state_code": "NY",
      "country_code": "US",
      "phone": "(212) 646-338-1228",
      "full_address": "2883 Geraldine Lane Apt.23, 10013 New York NY (US) (212) 646-338-1228",
      "name": "John Smith, 2883 Geraldine Lane Apt.23, 10013 New York NY (US) (212) 646-338-1228",
      "email": "[email protected]",
      "notes": "Please ring the bell twice",
      "lat": "40.6971494",
      "lng": "-74.2598672",
      "is_localized": "true",
      "is_geocoded": "true",
      "provider_name": "google",
      "map_url": "https://www.google.com/maps/search/?api=1&query=40.6971494,-74.2598672",
      "static_map_url": "https://maps.googleapis.com/maps/api/staticmap?center=40.6971494,-74.2598672&size=640x320&zoom=15",
      "billing_info": "VAT ID IT02382940977",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "geocoder": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/addresses/1234/relationships/geocoder",
          "related": "https://your-brand.commercelayer.io/api/addresses/1234/geocoder"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Update an address

To update an existing address, send a PATCH request to the /api/addresses/{{id}} endpoint, where {{id}} is the id of the resource that you want to update. The following table contains the list of all the possible arguments that you can pass with the request body, along with their type, description and examples values. Please note that all arguments are optional.
Arguments:
business
optional
Indicates if it's a business or a personal address
Example:
false
first_name
optional
Address first name (personal)
Example:
John
last_name
optional
Address last name (personal)
Example:
Smith
company
optional
Address company name (business)
Example:
The Red Brand Inc.
line_1
optional
Address line 1, i.e. Street address, PO Box
Example:
2883 Geraldine Lane
line_2
optional
Address line 2, i.e. Apartment, Suite, Building
Example:
Apt.23
city
optional
Address city
Example:
New York
zip_code
optional
ZIP or postal code
Example:
10013
state_code
optional
State, province or region code.
Example:
NY
country_code
optional
The international 2-letter country code as defined by the ISO 3166-1 standard
Example:
US
phone
optional
Phone number (including extension).
Example:
(212) 646-338-1228
email
optional
Email address.
notes
optional
A free notes attacched to the address. When used as a shipping address, this can be useful to let the customers add specific delivery instructions.
Example:
Please ring the bell twice
lat
optional
The address geocoded latitude. This is automatically generated when creating a shipping/billing address for an order and a valid geocoder is attached to the order's market.
Example:
40.6971494
lng
optional
The address geocoded longitude. This is automatically generated when creating a shipping/billing address for an order and a valid geocoder is attached to the order's market.
Example:
-74.2598672
billing_info
optional
Customer's billing information (i.e. VAT number, codice fiscale)
Example:
VAT ID IT02382940977
reference
optional
A string that you can use to add your own identifier to the resource. This can be useful for intergrating the resource to an external system, like an ERP, a marketing tool or a CRM.
Example:
ANYREFEFERNCE
metadata
optional
Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
Example:
#
optional
The geocoder attached to the address, to be used for geocoding.
Example request:
PATCH /api/addresses/1234 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

{
  "data": {
    "type": "addresses",
    "id": 1234,
    "attributes": {
      "business": "false"
    },
    "relationships": {
    }
  }
}
Example response: 200 OK
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "addresses",
    "links": {
      "self": "https://your-brand.commercelayer.io/api/addresses/1234"
    },
    "attributes": {
      "business": "false",
      "first_name": "John",
      "last_name": "Smith",
      "company": "The Red Brand Inc.",
      "full_name": "John Smith",
      "line_1": "2883 Geraldine Lane",
      "line_2": "Apt.23",
      "city": "New York",
      "zip_code": "10013",
      "state_code": "NY",
      "country_code": "US",
      "phone": "(212) 646-338-1228",
      "full_address": "2883 Geraldine Lane Apt.23, 10013 New York NY (US) (212) 646-338-1228",
      "name": "John Smith, 2883 Geraldine Lane Apt.23, 10013 New York NY (US) (212) 646-338-1228",
      "email": "[email protected]",
      "notes": "Please ring the bell twice",
      "lat": "40.6971494",
      "lng": "-74.2598672",
      "is_localized": "true",
      "is_geocoded": "true",
      "provider_name": "google",
      "map_url": "https://www.google.com/maps/search/?api=1&query=40.6971494,-74.2598672",
      "static_map_url": "https://maps.googleapis.com/maps/api/staticmap?center=40.6971494,-74.2598672&size=640x320&zoom=15",
      "billing_info": "VAT ID IT02382940977",
      "id": "1234",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": "ANYREFEFERNCE",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "geocoder": {
        "links": {
          "self": "https://your-brand.commercelayer.io/api/addresses/1234/relationships/geocoder",
          "related": "https://your-brand.commercelayer.io/api/addresses/1234/geocoder"
        }
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

Delete an address

To delete a address, send a DELETE request to the /api/addresses/{{id}} endpoint, where {{id}} is the id of the resource that you want to delete.
Example request:
DELETE /api/addresses/1234 HTTP/1.1
Accept: application/vnd.api+json
Example response: 204 No Content
HTTP/1.1 204 No Content

Get our machine-readable JSON schema that follows the OpenAPI Specification (formerly Swagger).

Get our Postman collection in one click and start making real calls to Commerce Layer API in minutes.

Get in touch with our support team if you have any questions or want to learn more about Commerce Layer.