List account addresses across accounts in this entity

curl --request GET \
  --url https://api.arcuserp.com/v1/account-addresses \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.arcuserp.com/v1/account-addresses', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcuserp.com/v1/account-addresses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcuserp.com/v1/account-addresses"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/account-addresses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "label": "<string>",
      "name": "<string>",
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zip": "<string>",
      "country": "US",
      "is_commercial": true,
      "is_default": true,
      "is_default_shipping": true,
      "is_default_billing": true,
      "is_pickup": true,
      "is_verified_shippo": true,
      "external_source": "<string>",
      "external_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ],
  "has_more": true,
  "next_cursor": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "url": "/v1/account-addresses"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

Accounts

List account addresses across accounts in this entity

Returns shipping and billing addresses for ALL accounts in the API key’s entity, with optional filters by account, external_source, or external_id. Stripe-style cursor pagination via starting_after.

Use this endpoint when you need to look up addresses that were imported from an external system (Versa Cloud, Bubble, Shopify, etc.) by their provenance tuple (account_id, external_source, external_id). Powers migration back-read paths and integration sync resolvers.

Layer 1 (multi-tenant isolation): the account_addresses table has no entity_id column; scope is enforced via JOIN to accounts.entity_id. A crafted cursor pointing at a sister-entity address returns 0 rows from the inner cursor SELECT, so no row leak.

Filed by the WSS Versa migration agent (P1 blocker for 97,118 NULL shipping_address_id orders/invoices on Phase 2A.7 backfill). Cross-refs: docs/prompts/completed/MIGRATION-API-V1-GET-ACCOUNT-ADDRESSES-ENDPOINT [COMPLETE].md.

Requires accounts:read OR addresses:read scope.

GET

account-addresses

List account addresses across accounts in this entity

curl --request GET \
  --url https://api.arcuserp.com/v1/account-addresses \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.arcuserp.com/v1/account-addresses', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.arcuserp.com/v1/account-addresses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.arcuserp.com/v1/account-addresses"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/account-addresses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "object": "list",
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "label": "<string>",
      "name": "<string>",
      "line1": "<string>",
      "line2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zip": "<string>",
      "country": "US",
      "is_commercial": true,
      "is_default": true,
      "is_default_shipping": true,
      "is_default_billing": true,
      "is_pickup": true,
      "is_verified_shippo": true,
      "external_source": "<string>",
      "external_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z"
    }
  ],
  "has_more": true,
  "next_cursor": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "url": "/v1/account-addresses"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

Authorizations

Authorization

string

header

required

API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity via Settings > Developers > API Keys.

Query Parameters

account_id

string<uuid>

Filter to addresses belonging to this account.

external_source

string

Filter by provenance source label (e.g. versa_cloud, bubble, shopify). Migration back-read pattern.

external_id

string

Filter by the source system's row identifier. Often combined with external_source for an exact-tuple lookup.

limit

integer

default:25

Number of rows to return. Default 25, max 500.

Required range: 1 <= x <= 500

starting_after

string<uuid>

Cursor: an address id from a previous response. Returns rows ordered before this cursor by (created_at DESC, id DESC).

Response

List of account addresses

object

enum<string>

Available options:

list

data

object[]

Show child attributes

has_more

boolean

next_cursor

string<uuid> | null

url

string

Example:

"/v1/account-addresses"

Deep-merge partial entity settings List account contacts across accounts in this entity

Overview

All Endpoints

List account addresses across accounts in this entity

Authorizations

Query Parameters

Response