Skip to content

Address book

Contents 26 pages

Two collections, and they work differently because they are different: origins are places you maintain, destinations are places you have shipped to.

A Shopify store's key lists its Shopify locations and saved warehouse with GET /origins but cannot change them, and has no consignee book: those endpoints answer not_available_for_shopify. See Shopify stores.

Origins — where you ship from#

Your saved dock doors and warehouses. You create and edit these.

GET/api/v1/originsScope addresses:read
Request
curl https://app.shipeasyco.com/api/v1/origins \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"object": "list",
	"data": [
		{
			"object": "origin",
			"id": "cm2j1d3e5…",
			"label": "Elk Grove — Dock A",
			"company": "Acme Freight",
			"address1": "1200 Devon Ave",
			"address2": null,
			"city": "Elk Grove Village",
			"state": "IL",
			"postal_code": "60007",
			"contact_name": "Dock supervisor",
			"phone": "+1-847-555-0100",
			"email": "dock@acme.example",
			"is_default": true,
			"created_at": "2026-03-04T16:22:10.000Z",
			"updated_at": "2026-07-19T11:02:44.000Z"
		}
	],
	"has_more": false,
	"next_cursor": null
}

Default first, then alphabetical — the same order the web app's picker uses, so a picker built on this API matches the one in the browser. Origins are not paged; the whole list comes back.

Requires addresses:read.

Create one#

POST/api/v1/originsScope addresses:write
Shell
curl -X POST https://app.shipeasyco.com/api/v1/origins \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Dallas — Dock 2",
    "company": "Acme Freight",
    "address1": "4100 Commerce St",
    "city": "Dallas",
    "state": "TX",
    "postal_code": "75201",
    "contact_name": "Rita Chen",
    "phone": "+1-214-555-0188",
    "is_default": false
  }'

Returns 201 with the created origin.

Field
label required How it appears in a picker.
city, state, postal_code required state is a two-letter code; the five-digit ZIP must be in it.
address1, address2, company, contact_name, phone, email optional Needed to book from this origin, so fill them in.
is_default optional Setting one default clears the previous one. Your first origin is the default whatever you send.

The street details are optional here and required at booking. That is deliberate: you can seed a list of locations from a system that only knows city/state/ZIP, then complete them later, rather than being blocked at import.

Update and delete#

GET/api/v1/origins/{originId}Scope addresses:read
Shell
curl https://app.shipeasyco.com/api/v1/origins/cm2j1d3e5… \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
PATCH/api/v1/origins/{originId}Scope addresses:write
Shell
curl -X PATCH https://app.shipeasyco.com/api/v1/origins/cm2j1d3e5… \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Elk Grove — Dock A", "city": "Elk Grove Village",
        "state": "IL", "postal_code": "60007", "phone": "+1-847-555-0199" }'
DELETE/api/v1/origins/{originId}Scope addresses:write
Shell
curl -X DELETE https://app.shipeasyco.com/api/v1/origins/cm2j1d3e5… \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"

PATCH takes the same body as create and replaces the record — send the whole origin, not just the changed field. The exception is is_default: false does not clear it; set true on another origin to move it. DELETE removes it; shipments already booked from it are untouched, because a shipment keeps its own copy of the address it shipped from. If you delete the default, your newest remaining origin becomes the default.

Writes require addresses:write, and the key must have been minted by an owner or admin — the same gate the web app applies, not a looser one.

Import many#

POST/api/v1/origins/importsScope addresses:write

The web app's ship-from CSV upload, as JSON: send up to 200 locations in rows, each as POST /origins takes one, with street, contact and phone filled in. Run it with dry_run: true first: nothing is added, and the answer says what would be.

Request
curl -X POST https://app.shipeasyco.com/api/v1/origins/imports \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "dry_run": true, "rows": [
        { "label": "Montebello Warehouse", "address1": "1400 Greenwood Ave",
          "city": "Montebello", "state": "CA", "postal_code": "90640",
          "contact_name": "Ana Ruiz", "phone": "323-555-0118" } ] }'
Response
{
	"object": "origin_import",
	"dry_run": true,
	"added": 1,
	"rows": [
		{ "index": 0, "label": "Montebello Warehouse", "result": "add", "problem": null }
	]
}

Each row is checked on its own, as the web app's upload checks them: good rows are added, and a row with a bad field, or a name already in your book, comes back as problem with the reason. A real run that adds nothing is refused with validation_failed, one issue per row.

Destinations — where you ship to#

Your consignees. Some are recorded for you, some you save on purpose, and curated_at tells the two apart:

curated_at What it means
null Recorded automatically from a quote or booking in the web app. Later ones fill in details still empty and refresh residential; none replaces a detail.
a timestamp Someone saved or edited it on purpose, in the web app or through this API. Quotes and bookings no longer change its details, only use_count and last_used_at.

A consignee quoted or booked in the web app lands here without a call of its own. Quotes and bookings made through this API do not: save a consignee with POST /destinations.

GET/api/v1/destinationsScope addresses:read
Request
curl "https://app.shipeasyco.com/api/v1/destinations?limit=50&q=northline" \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"object": "list",
	"data": [
		{
			"object": "destination",
			"id": "cm2j4h6k8…",
			"nickname": "Northline · Dallas dock",
			"pinned": true,
			"company": "Northline Supply",
			"contact_name": "Rita Chen",
			"address1": "4100 Commerce St",
			"address2": null,
			"city": "Dallas",
			"state": "TX",
			"postal_code": "75201",
			"residential": false,
			"phone": "+1-214-555-0188",
			"email": "receiving@northline.example",
			"notes": "Dock 4, call ahead",
			"use_count": 12,
			"last_used_at": "2026-08-12T14:05:01.000Z",
			"curated_at": "2026-08-14T09:12:00.000Z",
			"archived_at": null,
			"created_at": "2026-07-02T18:40:12.000Z",
			"updated_at": "2026-08-14T09:12:00.000Z"
		}
	],
	"has_more": true,
	"next_cursor": "…"
}

Cursor-paged, newest first by creation, and requires addresses:read. With updated_since it is a change feed instead: oldest first by updated_at, as on every list.

Not ordered by use, despite last_used_at. A keyset cursor needs a field that does not move, and last_used_at changes every time anyone quotes — paging on it would show you the same consignee twice and skip another. use_count, last_used_at and pinned are all fields you can read and sort yourself; none of them is this list's order.

Archived consignees are omitted, here and on GET /destinations/{id}. The change feed omits them too, so an archive does not reach you as a change. Send archived=true to list only the archived ones instead; each has archived_at set, and restore puts one back.

q is the web app's own search: it matches nickname, company or city anywhere in the value, or postal_code from its first digit, ignoring case. It takes 2 to 200 characters; anything else is 400 invalid_parameter, rather than a "match" on the whole book.

The street, contact name, phone, email and notes are encrypted at rest, so search does not cover them. To find a consignee by street, page the list and filter on your side, or key your own records on the destination id.

Save one#

POST/api/v1/destinationsScope addresses:write
Shell
curl -X POST https://app.shipeasyco.com/api/v1/destinations \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "Northline · Dallas dock",
    "company": "Northline Supply",
    "contact_name": "Rita Chen",
    "address1": "4100 Commerce St",
    "city": "Dallas",
    "state": "TX",
    "postal_code": "75201",
    "phone": "+1-214-555-0188",
    "notes": "Dock 4, call ahead"
  }'
Field
contact_name, address1, phone required What a booking needs, so the entry can fill one without retyping.
city, state, postal_code required state is a two-letter code; the five-digit ZIP must be in it.
nickname, company, address2, email, notes optional
residential optional Delivery to a home. Defaults to false.

These are the web app form's rules, and they are stricter than origins' on purpose. Saving marks the entry curated, and nothing fills in a curated entry later, so one saved without its street, contact and phone would stay that way.

201 when the consignee is new. 200 when the address is already in your book. An address is its ZIP, street and suite. A match is not an error: the existing entry takes the details you sent, and loses any optional one you left out; it comes back if it was archived, and keeps its id, pinned, use_count and history. This is how the web app's form saves.

pinned keeps the consignee at the front of the web app's picker. Send it to pin or unpin; leave it out and the pin stays as it is, on PATCH too.

Read, replace and archive#

GET/api/v1/destinations/{destinationId}Scope addresses:read
Shell
curl https://app.shipeasyco.com/api/v1/destinations/cm2j4h6k8… \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
PATCH/api/v1/destinations/{destinationId}Scope addresses:write
Shell
curl -X PATCH https://app.shipeasyco.com/api/v1/destinations/cm2j4h6k8… \
  -H "Authorization: Bearer $SHIPEASY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contact_name": "Rita Chen", "address1": "4100 Commerce St",
        "city": "Dallas", "state": "TX", "postal_code": "75201",
        "phone": "+1-214-555-0199" }'
DELETE/api/v1/destinations/{destinationId}Scope addresses:write
Shell
curl -X DELETE https://app.shipeasyco.com/api/v1/destinations/cm2j4h6k8… \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"

PATCH takes the same body as save and replaces the entry: send the whole consignee. A field you leave out is cleared, and that clears its nickname and notes too. notes is the address's note for the delivery driver: the web app fills a booking's delivery instructions from it. A booking through this API takes delivery_instructions itself; see Booking.

A PATCH can answer with a different id. Moving a consignee onto an address another entry already holds tells us the two are the same place, so they are merged, as in the web app. The response is the entry that remains, with the two use_counts added together. That entry keeps the other one's nickname if you send none, stays pinned if either was, and takes the later last_used_at. The id in your path then answers 404. Read id from the response, not from your request.

DELETE archives, the web app's "remove". The consignee leaves this list, GET answers 404, and the web app's pickers stop offering it, but the record is kept. The response says so:

JSON
{ "object": "deleted", "id": "cm2j4h6k8…", "deleted": true, "archived": true }

To bring one back, save the same address again: you get 200 and the original id. It also comes back by itself, with its id, when someone quotes or books to that address in the web app. Shipments already booked are untouched, because a shipment keeps its own copy of the address it shipped to.

Writes require addresses:write, and a key minted by an owner or admin, the same gate as origins.

Restore an archived consignee#

POST/api/v1/destinations/{destinationId}/restoreScope addresses:write
Shell
curl -X POST https://app.shipeasyco.com/api/v1/destinations/cm2j4h6k8…/restore \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"

Puts an archived consignee back in the book with its id, pinned, use_count and history, and answers with it. An id that is not archived answers 404.