Skip to main content

Addresses

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

List Shipping Addresses​

GET/api/v1/address/shipping/

Get all shipping addresses for the current user.

Example Request​

curl -X GET https://api.axro.com/api/v1/address/shipping/ \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response​

[
{
"id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
"company": "Example Corp",
"department": "Warehouse",
"firstname": null,
"lastname": null,
"street": "123 Shipping St",
"zip": "10001",
"city": "New York",
"country": "US",
"phone": "+491234567890",
"email": "mail@example.com",
"status": "approved",
"info": null
}
]

Get Shipping Address by ID​

GET/api/v1/address/shipping/{id}

Return a single shipping address by its UUID.

Status values:

  • WAITING_APPROVAL: The address is pending approval.
  • USABLE: The address can be used for shipping.

Example Request (cURL)​

curl -X GET "https://api.axro.com/api/v1/address/shipping/a1b2c3d4-e5f6-7890-abcd-1234567890ab" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response​

{
"id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
"company": "Example Corp",
"department": "Warehouse",
"firstname": null,
"lastname": null,
"street": "123 Shipping St",
"zip": "10001",
"city": "New York",
"country": "US",
"phone": "+491234567890",
"email": "mail@example.com",
"status": "USABLE",
"info": "Can be used for shipping."
}

Create Shipping Address​

POST/api/v1/address/shipping/

Create a shipping address for the current user.

Query parameters

  • check (boolean, optional): If true, the address is validated/normalized and a suggestion is returned without saving.

Request body

NameTypeRequiredDescription
companystring✅Company name (max 35 chars)
departmentstring✅Department name (max 35 chars)
firstnamestring❌Contact first name
lastnamestring❌Contact last name
streetstring✅Street and number (max 35 chars)
zipstring✅ZIP/Postal code
citystring✅City (max 35 chars)
countrystring✅Country code (ISO 3166-1 alpha-2)
phonestring❌Phone number, normalized to E.164 (see Validation)
emailstring❌Email address

Attention!

  • You must provide at least firstname and lastname or company and department.
  • Not possible combinations: only firstname, only lastname, only company, only department, firstname + department, lastname + department, firstname + company, lastname + company.

Validation

  • company, department, street, and city must be at most 35 characters. Exceeding this limit results in HTTP 422 with a field-specific error.
  • phone is normalized before it is stored. Common notations are accepted and rewritten to E.164: 0170 1234567, 0170-123 45 67, (0170) 1234567 and 0049 170 1234567 all become +491701234567.
  • A number written without + or 00 is read as a national number of the address country. On an Austrian address 0664 1234567 becomes +436641234567, on a German one +496641234567. A number given in international form keeps its own country code, so a German +49 number on an Austrian address stays as it is.
  • The normalized number must exist in the numbering plan of the country its own dialling code belongs to, which is not necessarily the address country. Values such as 123, a number with too many digits, or +901234772821 whose Turkish area code does not exist, are rejected with HTTP 422 and a field-specific error under body.detail[].loc = ["body", "phone"]. The address country plays no part in this check: an international number is judged the same way on a French address as on a German one.
  • The error names the recognized country, the reason and an example, so the two cases can be told apart: Phone number +901234772821 is not a valid number in Turkey (+90). A valid number looks like +902123456789. for a number that does not exist, and ... does not have a valid length for Turkey (+90) ... when only the number of digits is wrong.
  • The stored value is always the normalized one, so the response of a create or update can differ from what was sent.

Example Request​

# Normal create (persists address)
curl -X POST "https://api.axro.com/api/v1/address/shipping/" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"company": "Example Corp",
"department": "Warehouse",
"street": "123 Shipping St",
"zip": "10001",
"city": "New York",
"country": "US"
}'

# Check-only (validates/normalizes, does NOT persist, no id in response)
curl -X POST "https://api.axro.com/api/v1/address/shipping/?check=true" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"company": "Example Corp",
"department": "Warehouse",
"street": "123 Shipping St",
"zip": "10001",
"city": "New York",
"country": "US"
}'

Example Response (create, persisted)​

{
"id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
"company": "Example Corp",
"department": "Warehouse",
"firstname": null,
"lastname": null,
"street": "123 Shipping St",
"zip": "10001",
"city": "New York",
"country": "US",
"phone": "+491234567890",
"email": "mail@example.com",
"status": "USABLE",
"info": "Can be used for shipping."
}

Example Response (check=true, suggestion only)​

{
"company": "Example Corp",
"department": "Warehouse",
"street": "123 Shipping St",
"zip": "10001",
"city": "New York",
"country": "US",
"phone": "+491234567890",
"email": "mail@example.com",
"status": "CHECK_ONLY",
"info": "Suggested validated/normalized address. Not saved."
}

Example Response (duplicate address - HTTP 409)​

{
"message":"Shipping address already exists.",
"address_id":"145df5c9-f2b6-54c8-979a-3cab913c1a17",
"request_id":"6f13384e-481e-41ed-b5a9-7448976bb68f"
}

Info: If a shipping address already exists, the API responds with HTTP 409 Conflict and provides the existing address ID.

Use existing address ID to place your order.


Update Shipping Address (Phone and Email)​

PUT/api/v1/address/shipping/{shipping-address-id}

Update email and phone for shipping service provider

NameTypeRequiredDescription
phonestring❌Phone number, normalized like on create. Omit it to keep the stored number, send null or "" to remove it
emailstring❌Email address

Validation

  • phone is normalized against the country stored on the address, so a national number such as 0170 1234567 can be sent without repeating the country.
  • If the stored address has no country, only the international form (+49... or 0049...) is accepted; a national number is rejected with HTTP 422 rather than assumed to be German.
  • country is an admin-only field. A regular user cannot send it, so the number is always resolved against the country already stored on the address.

Example Request​

curl -X PUT https://api.axro.com/api/v1/address/shipping/a1b2c3d4-e5f6-7890-abcd-1234567890ab \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"phone": "+491234567890",
"email": "mail@example.com"
}'

Example Response​

{
"id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
"company": "Example Corp",
"department": "Warehouse",
"firstname": "John",
"lastname": "Doe",
"street": "123 Shipping St",
"zip": "10001",
"city": "New York",
"country": "US",
"phone": "+491234567890",
"email": "mail@example.com",
"status": "pending",
"info": null
}

List Billing Address​

GET/api/v1/address/billing/

Get the billing address for the current user

Example Request​

curl -X GET https://api.axro.com/api/v1/address/billing/ \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response​

{
"company": "Example Corp",
"department": "Accounting",
"street": "456 Billing Ave",
"zip": "10002",
"city": "New York",
"country": "US"
}