Addresses API

The Addresses API allows you to manage billing and shipping addresses for customers.

Base URL

https://your-instance.pubflow.com/bridge-payment

Authentication

Include one of the following in your requests:

Header: X-Session-ID: <session_id> (recommended)
Header: Authorization: Bearer <token>
Query Parameter: ?session_id=<session_id>
Guest: Provide guest_data in request body (no auth required)

Endpoints Overview

Method	Endpoint	Description
POST	`/addresses`	Create address
GET	`/addresses`	List addresses
GET	`/addresses/:id`	Get address
PUT	`/addresses/:id`	Update address
DELETE	`/addresses/:id`	Delete address
POST	`/addresses/:id/set-default`	Set as default

Create Address

Create a new address for a customer.

Request

http

POST /bridge-payment/addresses
Content-Type: application/json
X-Session-ID: <session_id>

Request Body

Field	Type	Required	Description
`country`	string	Yes	Country code (ISO 3166-1 alpha-2) — always required
`is_partial`	boolean	No	Default `false`. When `true`, minimal address: only `country` strictly required; `line1` / `city` / `postal_code` / `name` optional (AVS / fast checkout). When `false` (full), `line1` and `city` are required unless B2B rules apply.
`line1`	string	Conditional	Street line (required for full non-partial)
`line2`	string	No	Address line 2
`city`	string	Conditional	City (required for full default)
`state`	string	No	State/Province
`postal_code`	string	Conditional	Postal/ZIP
`name`	string	Conditional	Contact / cardholder name (personal context)
`is_business`	boolean	No	Default `false`. B2B billing: requires `business_name` when `true`.
`business_name`	string	Conditional	Legal entity name when `is_business`
`tax_id`	string	No	Tax identifier (raw value, jurisdiction-agnostic)
`tax_id_type`	string	No	Qualifier for `tax_id` (see table below)
`type`	string	No	Address type (billing, shipping)
`is_default`	boolean	No	Set as default (default: false)
`alias`	string	No	Friendly name (`nickname` is not valid—use `alias`)
`organization_id`	string	No	Optional organization scope (access-checked)
Guest Data
`guest_data`	object	No*	Guest customer data (*required for guests)
`guest_data.email`	string	Yes	Guest email
`guest_data.name`	string	Yes	Guest name

Response

json

{
  "id": "addr_1234567890",
  "line1": "123 Main St",
  "line2": "Apt 4B",
  "city": "New York",
  "state": "NY",
  "postal_code": "10001",
  "country": "US",
  "type": "billing",
  "is_default": false,
  "alias": "Home Address",
  "is_guest_address": false,
  "created_at": "2025-01-15T10:30:00Z"
}

Examples

Authenticated User Address

bash

curl -X POST "https://your-instance.pubflow.com/bridge-payment/addresses" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US",
    "type": "billing",
    "alias": "Home Address"
  }'

Guest Address

bash

curl -X POST "https://your-instance.pubflow.com/bridge-payment/addresses" \
  -H "Content-Type: application/json" \
  -d '{
    "line1": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90001",
    "country": "US",
    "guest_data": {
      "email": "[email protected]",
      "name": "Guest User"
    }
  }'

List Addresses

List all addresses for authenticated user.

Request

http

GET /bridge-payment/addresses
X-Session-ID: <session_id>

Query Parameters

Parameter	Type	Description
`type`	string	Filter by type (billing, shipping)
`organization_id`	string	Optional organization scope (access-checked)
`project_id`	string	Not supported on this endpoint (`GET /addresses`)
`completeness`	string	Filter by completeness (`full`, `partial`, `any`). Default is `any`.
`limit`	number	Limit results (default: 100)
`offset`	number	Offset for pagination

Response

json

[
  {
    "id": "addr_123",
    "line1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postal_code": "10001",
    "country": "US",
    "type": "billing",
    "is_default": true,
    "alias": "Home Address",
    "created_at": "2025-01-15T10:30:00Z"
  },
  {
    "id": "addr_456",
    "line1": "789 Business Blvd",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94102",
    "country": "US",
    "type": "billing",
    "is_default": false,
    "alias": "Office Address",
    "created_at": "2025-01-10T08:20:00Z"
  }
]

Example

bash

curl -X GET "https://your-instance.pubflow.com/bridge-payment/addresses?type=billing" \
  -H "X-Session-ID: session_abc123"

Get Address

Retrieve a specific address by ID.

Request

http

GET /bridge-payment/addresses/:id
X-Session-ID: <session_id>

Response

Returns complete address object.

Example

bash

curl -X GET "https://your-instance.pubflow.com/bridge-payment/addresses/addr_123" \
  -H "X-Session-ID: session_abc123"

Update Address

Update address information.

Request

http

PUT /bridge-payment/addresses/:id
Content-Type: application/json
X-Session-ID: <session_id>

Request Body

All fields are optional (patch semantics). Validation mirrors create rules when you change mode:

Field	Type	Description
`is_partial`	boolean	Toggle partial vs full. Upgrading to full typically requires `line1`, `city`, `postal_code`, and `name` (or `business_name` for B2B).
`line1`, `line2`, `city`, `state`, `postal_code`, `country`	string	Standard lines (nullable for partial flows)
`name`	string	Contact / cardholder
`is_business`, `business_name`, `tax_id`, `tax_id_type`	mixed	B2B patch — `business_name` required when turning `is_business` on
`type`	string	billing / shipping
`is_default`	boolean	Default flag
`alias`	string	Friendly name

Responses include is_partial, is_business, business_name, tax_id, tax_id_type when stored.

`tax_id_type` values (common)

Value	Typical use
`vat`	EU VAT
`ein`	US EIN
`rfc`	Mexico RFC
`rnc`	Dominican Republic RNC
`cnpj` / `cpf`	Brazil
`gst`	AU / CA / IN GST
`nit`	Colombia
`cuit`	Argentina
`nif`	Spain
`siren`	France
`kvk`	Netherlands
`other`	Anything else

Example

bash

curl -X PUT "https://your-instance.pubflow.com/bridge-payment/addresses/addr_123" \
  -H "Content-Type: application/json" \
  -H "X-Session-ID: session_abc123" \
  -d '{
    "line2": "Suite 100",
    "alias": "Updated Office Address"
  }'

Response

Returns updated address object.

Delete Address

Delete an address.

Request

http

DELETE /bridge-payment/addresses/:id
X-Session-ID: <session_id>

Response

http

HTTP/1.1 204 No Content

Example

bash

curl -X DELETE "https://your-instance.pubflow.com/bridge-payment/addresses/addr_123" \
  -H "X-Session-ID: session_abc123"

Set Default Address

Set an address as the default.

Request

http

POST /bridge-payment/addresses/:id/set-default
X-Session-ID: <session_id>

Response

Returns updated address with is_default: true.

Example

bash

curl -X POST "https://your-instance.pubflow.com/bridge-payment/addresses/addr_123/set-default" \
  -H "X-Session-ID: session_abc123"

Address Types

Billing Address

Used for payment method billing information:

json

{
  "id": "addr_123",
  "type": "billing",
  "line1": "123 Main St",
  "city": "New York",
  "state": "NY",
  "postal_code": "10001",
  "country": "US"
}

Shipping Address

Used for order delivery:

json

{
  "id": "addr_456",
  "type": "shipping",
  "line1": "456 Oak Ave",
  "city": "Los Angeles",
  "state": "CA",
  "postal_code": "90001",
  "country": "US"
}

Country Codes

Use ISO 3166-1 alpha-2 country codes:

US - United States
CA - Canada
GB - United Kingdom
AU - Australia
DE - Germany
FR - France
ES - Spain
IT - Italy
MX - Mexico
BR - Brazil

Full list of country codes

Next Steps

Payment Methods API - Link addresses to payment methods
Customers API - Manage customer information
Payments API - Create payments with billing addresses

Addresses API ​

Base URL ​

Authentication ​

Endpoints Overview ​

Create Address ​

Request ​

Request Body ​

Response ​

Examples ​

Authenticated User Address ​

Guest Address ​

List Addresses ​

Request ​

Query Parameters ​

Response ​

Example ​

Get Address ​

Request ​

Response ​

Example ​

Update Address ​

Request ​

Request Body ​

tax_id_type values (common) ​

Example ​

Response ​

Delete Address ​

Request ​

Response ​

Example ​

Set Default Address ​

Request ​

Response ​

Example ​

Address Types ​

Billing Address ​

Shipping Address ​

Country Codes ​

Next Steps ​

Addresses API

Base URL

Authentication

Endpoints Overview

Create Address

Request

Request Body

Response

Examples

Authenticated User Address

Guest Address

List Addresses

Request

Query Parameters

Response

Example

Get Address

Request

Response

Example

Update Address

Request

Request Body

`tax_id_type` values (common)

Example

Response

Delete Address

Request

Response

Example

Set Default Address

Request

Response

Example

Address Types

Billing Address

Shipping Address

Country Codes

Next Steps