Address book

An address book is a digital store for addresses. It stores addresses and helps you update, retrieve, and delete addresses. Using the Addresses API means you do not need to create your own storage solution for this common challenge. Using an address book is also a great way to improve the customer checkout experience. Enabling your customers to save their addresses during checkout simplifies future purchases with your business.

Note

Address object IDs cannot be used with previous versions of the Shippo API. There is a limit of 3,000 addresses that can be stored.

Create an address book entry

To store an address for later use in the Addresses API, follow this example. Note, you cannot save identical addresses.

cURLCreate address response
Copy
Copied
curl -i -X POST \
  https://api.goshippo.com/v2/addresses \
  -H 'Authorization: ShippoToken <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Wilson",
    "organization": "Shippo",
    "email": "user@shippo.com",
    "phone": "+1-4155550132",
    "address_line_1": "731 Market Street",
    "address_line_2": "#200",
    "city_locality": "San Francisco",
    "state_province": "CA",
    "postal_code": "94103",
    "country_code": "US",
    "address_type": "residential"
  }'
Copy
Copied
{
        "id": "7cf70f716ad0459cbd0de8652689192b",
        "address": {
        "name": "Wilson",
        "email": "user@shippo.com",
        "phone": "+1-4155550132",
        "organization": "Shippo",
        "address_line_1": "731 Market Street",
        "address_line_2": "#200",
        "city_locality": "San Francisco",
        "state_province": "CA",
        "postal_code": "94103",
        "country_code": "US",
        "address_type": "residential"
},
    "updated_at": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z"
}

Retrieve addresses

You can retrieve an address using an address object ID. If you don't know the object ID for an address, see the example to retrieve multiple addresses. To retrieve a single address using an object ID, follow this example.

cURLRetrieve single address response
Copy
Copied
curl -i -X GET \
  'https://api.goshippo.com/v2/addresses/{address_id}' \
  -H 'Authorization: ShippoToken <API_TOKEN>'
Copy
Copied
{
  "id": "5029d2e1d0994bd0a8efd7d12485539d",
  "address": {
  "name": "Wilson",
  "email": "user@shippo.com",
  "phone": "+1-4155550132",
  "organization": "Shippo",
  "address_line_1": "731 Market Street",
  "address_line_2": "#200",
  "city_locality": "San Francisco",
  "state_province": "CA",
  "postal_code": "94103",
  "country_code": "US",
  "address_type": "residential"
},
  "updated_at": "2023-11-16T10:13:59.887946Z",
  "created_at": "2023-11-16T10:13:59.887946Z"
}

To retrieve multiple addresses with a single call, follow this example. You can reduce the number of returned results using the following parameters.

Parameter Description
limit Limits the number of returned addresses. For example, if 20 records match your query and limit is set to 5, only the first 5 addresses are returned
offset The number of addresses to skip in the result set. For example, if 100 addresses match your query, if you offset 50 and limit 20, then you get addresses 50-70
search Only addresses that contains this string anywhere in the address will be returned
cURLRetrieve multiple addresses response
Copy
Copied
curl -i -X GET \
  'https://api.goshippo.com/v2/addresses?offset=0&limit=30&search=string' \
  -H 'Authorization: ShippoToken <API_TOKEN>'
Copy
Copied
{
  "offset": 0,
  "limit": 30,
  "count": 3,
  "results": [
    {
      "id": "5029d2e1d0994bd0a8efd7d12485539d",
      "address": {
        "name": "Wilson",
        "email": "user@shippo.com",
        "phone": "+1-4155550132",
        "organization": "Shippo",
        "address_line_1": "731 Market Street",
        "address_line_2": "#200",
        "city_locality": "San Francisco",
        "state_province": "CA",
        "postal_code": "94103",
        "country_code": "US",
        "address_type": "residential"
      },
      "updated_at": "2023-11-16T10:13:59.887946Z",
      "created_at": "2023-11-16T10:13:59.887946Z"
    },
    {
      "id": "45472328338149bda583cd6abec7fd75",
      "address": {
        "name": "Wilson 2",
        "email": "user@shippo.com",
        "phone": "+1-4155550132",
        "organization": "Shippo",
        "address_line_1": "731 Market Street",
        "address_line_2": "#200",
        "city_locality": "San Francisco",
        "state_province": "CA",
        "postal_code": "94103",
        "country_code": "US",
        "address_type": "residential"
      },
      "updated_at": "2023-11-17T16:26:53.951934Z",
      "created_at": "2023-11-17T16:26:53.951934Z"
    },
    {
      "id": "81c1dc22258344dea6a78565797ffd44",
      "address": {
        "name": "Wilson 2",
        "email": "user@shippo.com",
        "phone": "+1-4155550132",
        "organization": "Shippo 2",
        "address_line_1": "731 Market Street",
        "address_line_2": "#200",
        "city_locality": "San Francisco",
        "state_province": "CA",
        "postal_code": "94103",
        "country_code": "US",
        "address_type": "residential"
      },
      "updated_at": "2023-11-17T16:27:13.130576Z",
      "created_at": "2023-11-17T16:27:13.130576Z"
    }
  ]
}

Update an address

To update an existing address, follow this example.

Copy
Copied
curl -i -X PUT \
  'https://api.goshippo.com/v2/addresses/{address_id}' \
  -H 'Authorization: ShippoToken <API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Wilson",
    "organization": "Shippo",
    "email": "user@shippo.com",
    "phone": "+1-4155550132",
    "address_line_1": "731 Market Street",
    "address_line_2": "#200",
    "city_locality": "San Francisco",
    "state_province": "CA",
    "postal_code": "94103",
    "country_code": "US",
    "address_type": "residential"
  }'

Delete addresses

To delete an address that you have created, follow this example.

Copy
Copied
curl -i -X DELETE \
  'https://api.goshippo.com/v2/addresses/{address_id}' \
  -H 'Authorization: ShippoToken <API_TOKEN>'