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

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

Request Body

Field	Type	Required	Description
line1	string	Yes	Address line 1 (street address)
line2	string	No	Address line 2 (apt, suite, etc.)
city	string	Yes	City
state	string	Yes	State/Province
postal_code	string	Yes	Postal/ZIP code
country	string	Yes	Country code (ISO 3166-1 alpha-2)
type	string	No	Address type (billing, shipping)
is_default	boolean	No	Set as default (default: false)
alias	string	No	Friendly name for address
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

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

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

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

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

Query Parameters

Parameter	Type	Description
type	string	Filter by type (billing, shipping)
limit	number	Limit results (default: 100)
offset	number	Offset for pagination

Response

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

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

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

Response

Returns complete address object.

Example

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

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

Request Body

All fields are optional. Only include fields you want to update.

Field	Type	Description
line1	string	Update address line 1
line2	string	Update address line 2
city	string	Update city
state	string	Update state
postal_code	string	Update postal code
country	string	Update country
type	string	Update type
is_default	boolean	Set as default
alias	string	Update alias

Example

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

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

Response

HTTP/1.1 204 No Content

Example

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

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

Response

Returns updated address with is_default: true.

Example

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:

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

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