← API Documentation

Customer Addresses API

Manage shipping and billing addresses for customers. Each customer can have multiple addresses for different purposes.

Endpoints

List Customer Addresses - GET /api/v1/customers/{id}/addresses
Create Customer Address - POST /api/v1/customers/{id}/addresses
Get Customer Address - GET /api/v1/customers/{id}/addresses/{address_id}
Update Customer Address - PUT /api/v1/customers/{id}/addresses/{address_id}
Delete Customer Address - DELETE /api/v1/customers/{id}/addresses/{address_id}

List Customer Addresses

Retrieve all addresses for a specific customer.

Endpoint: GET /api/v1/customers/{id}/addresses

Permission Required: Read

Path Parameters

Parameter	Type	Description
`id`	string	Customer public ID (e.g., `cus_abc123`)

Request

curl -X GET "https://studio.easel.engineering/api/v1/customers/cus_abc123/addresses" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

{
  "addresses": [
    {
      "id": "adr_def456",
      "first_name": "John",
      "last_name": "Doe",
      "street1": "123 Main St",
      "street2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "country_id": 1,
      "zip": "10001",
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:15:00Z"
    },
    {
      "id": "adr_ghi789",
      "first_name": "John",
      "last_name": "Doe",
      "street1": "456 Oak Avenue",
      "street2": null,
      "city": "Los Angeles",
      "state": "CA",
      "country_id": 1,
      "zip": "90210",
      "created_at": "2023-01-02T14:30:00Z",
      "updated_at": "2023-01-02T14:30:00Z"
    }
  ]
}

Error Responses

Missing customer ID

Status: 400 Bad Request

{
  "error": "Customer ID is required",
  "code": "MISSING_FIELD"
}

Failed to list addresses

Status: 500 Internal Server Error

{
  "error": "Failed to list addresses",
  "code": "LIST_ERROR"
}

Create Customer Address

Create a new address for a specific customer.

Endpoint: POST /api/v1/customers/{id}/addresses

Permission Required: Write

Path Parameters

Parameter	Type	Description
`id`	string	Customer public ID (e.g., `cus_abc123`)

Request Body

{
  "first_name": "John",
  "last_name": "Doe",
  "street1": "123 Main St",
  "street2": "Apt 4B",
  "city": "New York",
  "state": "NY",
  "country_id": 1,
  "zip": "10001"
}

Fields

Field	Type	Required	Description
`first_name`	string	Yes	First name for this address
`last_name`	string	Yes	Last name for this address
`street1`	string	Yes	Primary street address
`street2`	string	No	Secondary street address (apartment, suite, etc.)
`city`	string	Yes	City name
`state`	string	Yes	State/province code
`country_id`	integer	Yes	Country ID
`zip`	string	No	ZIP or postal code

Request

curl -X POST "https://studio.easel.engineering/api/v1/customers/cus_abc123/addresses" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "street1": "123 Main St",
    "street2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "country_id": 1,
    "zip": "10001"
  }'

Response

Returns the created address.

Status: 201 Created

{
  "id": "adr_def456",
  "first_name": "John",
  "last_name": "Doe",
  "street1": "123 Main St",
  "street2": "Apt 4B",
  "city": "New York",
  "state": "NY",
  "country_id": 1,
  "zip": "10001",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Error Responses

Missing customer ID

Status: 400 Bad Request

{
  "error": "Customer ID is required",
  "code": "MISSING_FIELD"
}

Invalid JSON body

Status: 400 Bad Request

{
  "error": "Invalid JSON body",
  "code": "INVALID_JSON"
}

Missing required field

Status: 400 Bad Request

{
  "error": "First name is required",
  "code": "MISSING_FIELD"
}

Failed to create address

Status: 500 Internal Server Error

{
  "error": "Failed to create address",
  "code": "CREATE_ERROR"
}

Address created but failed to retrieve

Status: 500 Internal Server Error

{
  "error": "Address created but failed to retrieve",
  "code": "GET_ERROR"
}

Get Customer Address

Retrieve a single customer address by its ID.

Endpoint: GET /api/v1/customers/{id}/addresses/{address_id}

Permission Required: Read

Path Parameters

Parameter	Type	Description
`id`	string	Customer public ID (e.g., `cus_abc123`)
`address_id`	string	Address public ID (e.g., `adr_def456`)

Request

curl -X GET "https://studio.easel.engineering/api/v1/customers/cus_abc123/addresses/adr_def456" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

{
  "id": "adr_def456",
  "first_name": "John",
  "last_name": "Doe",
  "street1": "123 Main St",
  "street2": "Apt 4B",
  "city": "New York",
  "state": "NY",
  "country_id": 1,
  "zip": "10001",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:15:00Z"
}

Error Responses

Missing customer ID

Status: 400 Bad Request

{
  "error": "Customer ID is required",
  "code": "MISSING_FIELD"
}

Missing address ID

Status: 400 Bad Request

{
  "error": "Address ID is required",
  "code": "MISSING_FIELD"
}

Address not found

Status: 404 Not Found

{
  "error": "Address not found",
  "code": "NOT_FOUND"
}

Failed to get address

Status: 500 Internal Server Error

{
  "error": "Failed to get address",
  "code": "GET_ERROR"
}

Update Customer Address

Update an existing customer address.

Endpoint: PUT /api/v1/customers/{id}/addresses/{address_id}

Permission Required: Write

Path Parameters

Parameter	Type	Description
`id`	string	Customer public ID (e.g., `cus_abc123`)
`address_id`	string	Address public ID (e.g., `adr_def456`)

Request Body

{
  "first_name": "John",
  "last_name": "Smith",
  "street1": "456 Oak Avenue",
  "street2": null,
  "city": "Los Angeles",
  "state": "CA",
  "country_id": 1,
  "zip": "90210"
}

Fields

Field	Type	Required	Description
`first_name`	string	Yes	First name for this address
`last_name`	string	Yes	Last name for this address
`street1`	string	Yes	Primary street address
`street2`	string	No	Secondary street address (apartment, suite, etc.)
`city`	string	Yes	City name
`state`	string	Yes	State/province code
`country_id`	integer	Yes	Country ID
`zip`	string	No	ZIP or postal code

Request

curl -X PUT "https://studio.easel.engineering/api/v1/customers/cus_abc123/addresses/adr_def456" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "street1": "456 Oak Avenue",
    "city": "Los Angeles",
    "state": "CA",
    "country_id": 1,
    "zip": "90210"
  }'

Response

Returns the updated address.

Status: 200 OK

{
  "id": "adr_def456",
  "first_name": "John",
  "last_name": "Smith",
  "street1": "456 Oak Avenue",
  "street2": null,
  "city": "Los Angeles",
  "state": "CA",
  "country_id": 1,
  "zip": "90210",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T11:30:00Z"
}

Error Responses

Missing customer ID

Status: 400 Bad Request

{
  "error": "Customer ID is required",
  "code": "MISSING_FIELD"
}

Missing address ID

Status: 400 Bad Request

{
  "error": "Address ID is required",
  "code": "MISSING_FIELD"
}

Invalid JSON body

Status: 400 Bad Request

{
  "error": "Invalid JSON body",
  "code": "INVALID_JSON"
}

Missing required field

Status: 400 Bad Request

{
  "error": "First name is required",
  "code": "MISSING_FIELD"
}

Address not found

Status: 404 Not Found

{
  "error": "Address not found",
  "code": "NOT_FOUND"
}

Failed to update address

Status: 500 Internal Server Error

{
  "error": "Failed to update address",
  "code": "UPDATE_ERROR"
}

Address updated but failed to retrieve

Status: 500 Internal Server Error

{
  "error": "Address updated but failed to retrieve",
  "code": "GET_ERROR"
}

Delete Customer Address

Delete a customer address permanently.

Endpoint: DELETE /api/v1/customers/{id}/addresses/{address_id}

Permission Required: Write

Path Parameters

Parameter	Type	Description
`id`	string	Customer public ID (e.g., `cus_abc123`)
`address_id`	string	Address public ID (e.g., `adr_def456`)

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/customers/cus_abc123/addresses/adr_def456" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

No response body is returned for successful deletions.

Error Responses

Missing customer ID

Status: 400 Bad Request

{
  "error": "Customer ID is required",
  "code": "MISSING_FIELD"
}

Missing address ID

Status: 400 Bad Request

{
  "error": "Address ID is required",
  "code": "MISSING_FIELD"
}

Address not found

Status: 404 Not Found

{
  "error": "Address not found",
  "code": "NOT_FOUND"
}

Failed to delete address

Status: 500 Internal Server Error

{
  "error": "Failed to delete address",
  "code": "DELETE_ERROR"
}

Customer Address Object

Fields

Field	Type	Description
`id`	string	Address public ID
`first_name`	string	First name for this address
`last_name`	string	Last name for this address
`street1`	string	Primary street address
`street2`	string\|null	Secondary street address
`city`	string	City name
`state`	string	State/province code
`country_id`	integer	Country ID
`zip`	string\|null	ZIP or postal code
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Country IDs

Country IDs are integers that correspond to countries in your system. Common values:

1 - United States
2 - Canada
(Refer to your country lookup table for complete list)

Address Format

Addresses follow standard postal address conventions:

street1 contains the primary address (house number, street name)
street2 is optional and contains apartment, suite, unit numbers, etc.
state should use standard state/province codes (e.g., "NY", "CA", "ON")
zip can be null for countries that don't use postal codes