Commerce Addresses

POST /api/commerces/:cId/addresses

Add a new address to a commerce.

Auth: Required — commerce:manage permission

Request Body

Field	Type	Required	Description
`source`	string	Yes	Source of the address: `RETEN` or `INTEGRATION`
`address_alias`	string	No	Friendly name for the address
`is_primary`	boolean	No	Set as primary address
`country_code`	string	No	Country code (e.g., `CL`, `MX`)
`region`	string	No	Region or state
`commune`	string	No	Commune or municipality
`city`	string	No	City
`street`	string	No	Street name
`street_number`	string	No	Street number
`unit`	string	No	Apartment, suite, or unit
`formatted_address`	string	No	Full formatted address string
`latitude`	number	No	Latitude coordinate
`longitude`	number	No	Longitude coordinate

Example

curl -X POST https://api.reten.ai/api/commerces/<cId>/addresses \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "RETEN",
    "address_alias": "Main Office",
    "street": "Av. Providencia",
    "street_number": "1234",
    "commune": "Providencia",
    "city": "Santiago",
    "region": "Metropolitana",
    "country_code": "CL",
    "latitude": -33.4500,
    "longitude": -70.6700,
    "is_primary": true
  }'

const commerceId = "<cId>";
const response = await fetch(`https://api.reten.ai/api/commerces/${commerceId}/addresses`, {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "x-tenant-id": "<tenant-id>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    source: "RETEN",
    address_alias: "Main Office",
    street: "Av. Providencia",
    street_number: "1234",
    commune: "Providencia",
    city: "Santiago",
    region: "Metropolitana",
    country_code: "CL",
    latitude: -33.4500,
    longitude: -70.6700,
    is_primary: true,
  }),
});
const address = await response.json();

import requests

commerce_id = "<cId>"
response = requests.post(
    f"https://api.reten.ai/api/commerces/{commerce_id}/addresses",
    headers={
        "Authorization": "Bearer <token>",
        "x-tenant-id": "<tenant-id>",
    },
    json={
        "source": "RETEN",
        "address_alias": "Main Office",
        "street": "Av. Providencia",
        "street_number": "1234",
        "commune": "Providencia",
        "city": "Santiago",
        "region": "Metropolitana",
        "country_code": "CL",
        "latitude": -33.4500,
        "longitude": -70.6700,
        "is_primary": True,
    },
)
address = response.json()

Response `201 Created`

Returns the created address object.

PATCH /api/commerces/:cId/addresses/:aId

Update an existing address.

Auth: Required — commerce:manage permission

Request Body

Field	Type	Required	Description
`address_alias`	string	No	Friendly name for the address
`country_code`	string	No	Country code
`region`	string	No	Region or state
`commune`	string	No	Commune or municipality
`city`	string	No	City
`street`	string	No	Street name
`street_number`	string	No	Street number
`unit`	string	No	Apartment, suite, or unit
`formatted_address`	string	No	Full formatted address string
`latitude`	number	No	Latitude coordinate
`longitude`	number	No	Longitude coordinate
`is_active`	boolean	No	Whether the address is active

POST /api/commerces/:cId/addresses/:aId/set-primary

Set an address as the primary address for the commerce. Automatically unsets the previous primary address.

Response `200 OK`

Returns the updated address.

Notes

Only one address can be primary per commerce (among active addresses)
Setting a new primary automatically unsets the previous one