Sync Commerces

POST /api/commerces/sync

Bulk upsert commerces with addresses and users. Uses external_id as the match key — creates new commerces or updates existing ones.

Auth: Required — SYNC_COMMERCES permission

Request Body

Field	Type	Required	Description
`items`	array	Yes	Array of commerce objects to sync

Each commerce object:

Field	Type	Required	Description
`external_id`	string	Yes	External system identifier (match key)
`name`	string	Yes	Commerce name
`global_external_id`	string	No	Global external ID across systems
`tax_id`	string	No	Tax ID
`metadata`	object	No	Arbitrary JSON
`addresses`	array	No	Addresses to sync
`users`	array	No	Users to sync

Each address object:

Field	Type	Required	Description
`address_alias`	string	No	Alias or label for this address
`is_primary`	boolean	No	Set as primary address
`country_code`	string	No	Country code
`region`	string	No	State or region
`commune`	string	No	Commune or district
`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
`source_ref`	string	No	External reference from the source system

Each user object:

Field	Type	Required	Description
`external_id`	string	Yes	External system identifier for the user
`name`	string	No	Full name
`roles`	string[]	No	Commerce user roles
`contacts`	array	No	User contacts

Each contact object:

Field	Type	Required	Description
`contact_type`	string	Yes	`PHONE`, `EMAIL`, `WHATSAPP`, or `OTHER`
`value`	string	Yes	Contact value
`is_primary`	boolean	No	Set as primary for this type

Example

curl -X POST https://api.reten.ai/api/commerces/sync \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "external_id": "store-001",
        "name": "Main Street Store",
        "tax_id": "12345678-9",
        "addresses": [
          {
            "street": "123 Main St",
            "city": "Santiago",
            "region": "Metropolitana",
            "country_code": "CL",
            "is_primary": true,
            "latitude": -33.4489,
            "longitude": -70.6693
          }
        ],
        "users": [
          {
            "external_id": "usr-001",
            "name": "Maria Garcia",
            "roles": ["OWNER"],
            "contacts": [
              {
                "contact_type": "PHONE",
                "value": "+56912345678",
                "is_primary": true
              }
            ]
          }
        ]
      }
    ]
  }'

import axios from 'axios';

const response = await axios.post(
  'https://api.reten.ai/api/commerces/sync',
  {
    items: [
      {
        external_id: 'store-001',
        name: 'Main Street Store',
        tax_id: '12345678-9',
        addresses: [
          {
            street: '123 Main St',
            city: 'Santiago',
            region: 'Metropolitana',
            country_code: 'CL',
            is_primary: true,
            latitude: -33.4489,
            longitude: -70.6693,
          },
        ],
        users: [
          {
            external_id: 'usr-001',
            name: 'Maria Garcia',
            roles: ['OWNER'],
            contacts: [
              {
                contact_type: 'PHONE',
                value: '+56912345678',
                is_primary: true,
              },
            ],
          },
        ],
      },
    ],
  },
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

const { created, updated, total } = response.data;

Response `201 Created`

{
  "created": 1,
  "updated": 0,
  "total": 1
}

Notes

Uses external_id as match key for idempotent upsert
Placeholder commerces (isPlaceholder = true) are created for referenced but undefined entries
Metadata uses merge semantics on update