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.

NoteAddress 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.

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"
  }'

{
        "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.

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

{
  "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

curl -i -X GET \
  'https://api.goshippo.com/v2/addresses?offset=0&limit=30&search=string' \
  -H 'Authorization: ShippoToken <API_TOKEN>'

{
  "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.

cURL

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.

cURL

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

Overview

Get started

AI & agents

Guides

Concepts

Create an address book entry

Retrieve addresses

Update an address

Delete addresses

​Create an address book entry

​Retrieve addresses

​Update an address

​Delete addresses

Create an address book entry

Retrieve addresses

Update an address

Delete addresses