Commerce Users

POST /api/commerces/:cId/users

Create a user for a commerce.

Auth: Required — MANAGE_COMMERCES permission

Request Body

Field	Type	Required	Description
`name`	string	No	Full name of the commerce user
`external_id`	string	No	External system identifier
`source`	string	No	Contact source: `RETEN` or `INTEGRATION`
`roles`	string[]	No	Initial roles: `OWNER`, `ORDERS`, `FINANCE`, `ATTENTION`, `ADMIN`, `COMMERCE_REP`, `OTHER`

Example

curl -X POST https://api.reten.ai/api/commerces/<cId>/users \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Garcia",
    "external_id": "usr-001",
    "source": "RETEN",
    "roles": ["OWNER"]
  }'

import axios from 'axios';

const response = await axios.post(
  'https://api.reten.ai/api/commerces/<cId>/users',
  {
    name: 'Maria Garcia',
    external_id: 'usr-001',
    source: 'RETEN',
    roles: ['OWNER'],
  },
  {
    headers: {
      Authorization: 'Bearer <token>',
      'x-tenant-id': '<tenant-id>',
    },
  }
);

const user = response.data;

Response `201 Created`

Returns the created user object.

PATCH /api/commerces/:cId/users/:uId

Update a commerce user.

POST /api/commerces/:cId/users/:uId/roles

Add a role to a commerce user.

Request Body

Field	Type	Required	Description
`role`	string	Yes	One of: `OWNER`, `ORDERS`, `FINANCE`, `ATTENTION`, `ADMIN`, `COMMERCE_REP`, `OTHER`

Response `201 Created`

DELETE /api/commerces/:cId/users/:uId/roles/:role

Remove a role from a commerce user.

Response `204 No Content`

POST /api/commerces/:cId/users/:uId/contacts

Add a contact to a commerce user.

Request Body

Field	Type	Required	Description
`contact_type`	string	Yes	`EMAIL`, `PHONE`, `WHATSAPP`, or `OTHER`
`value`	string	Yes	Contact value (validated by type)
`source`	string	Yes	Contact source: `RETEN` or `INTEGRATION`
`is_primary`	boolean	No	Set as primary contact for this type

Validation

Type	Format
`EMAIL`	Valid email regex
`PHONE`	E.164 format (e.g., `+56912345678`)
`WHATSAPP`	E.164 format

Response `201 Created`

PATCH /api/commerces/:cId/users/:uId/contacts/:contactId

Update a contact.

POST /api/commerces/:cId/users/:uId/contacts/:contactId/set-primary

Set a contact as primary for its type.

Notes

Only one primary contact per type per commerce user (among active contacts)
Setting a new primary automatically unsets the previous one for that type