Update a user

POST

/users/{user_id}

Changes a user. Only the fields you send change. Fires the user:modified event.

A trusted token may always update its own user with me, even without the users update permission. On me only name, email, password and language are used; other fields are ignored. Updating any other user needs a secret or trusted token with that permission.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

user_id*string

The user's user_id. With a trusted token, me means the signed-in user. me with any other token type is 403.

Request Body

application/json

body

The fields to change. Fields you leave out keep their value. A roles or permissions list you send replaces the old one; an empty list is ignored.

name?string

The user's full name.

Lengthlength <= 75

email?string

The user's email address. It must not belong to another user of the account (409). The old address is told about the change.

Formatemail

Lengthlength <= 100

password?string

A new password, from 8 to 50 characters.

Formatpassword

Length8 <= length <= 50

language?string

A two-letter ISO 639-1 language code.

allow_test_transactions?boolean

True when the user may work in test mode. Ignored on /users/me.

roles?array<string>

The role_id of each role to give the user. Ignored on /users/me.

permissions?array<>

Permissions to give the user directly. Ignored on /users/me.

is_account_owner?boolean

Makes the user an owner, or not. Only a trusted token of a user who is an owner can change it. From any other token it is ignored. Ignored on /users/me.

meta?|

Your own data about the user, any JSON up to 2,048 characters. Ignored on /users/me.

Response Body

The updated user.

application/json

response

A person who can sign in to your dashboard. Users are kept per mode: test users and live users are separate, and a test user's user_id ends in .test. When a user signs in, they get a trusted token with the user's permissions.

object?"user"

The object type. Always user.

Value in"user"

url?string

The URL of this user.

Formaturi

user_id?string

The user's sign-in name, in lower case. A test user's ends in .test.

test?boolean

True for a test user.

date_created?string

When the user was created.

Formatdate-time

date_modified?string

When the user was last changed.

Formatdate-time

account_id?string

The account the user belongs to.

account_alias?|

The alias of your account, which users may sign in with instead of the account ID.

account_live?boolean

True when your account may take live payments.

name?string

The user's full name.

Lengthlength <= 75

email?string

The user's email address. Each user needs their own, across test and live users.

Formatemail

Lengthlength <= 100

is_account_owner?boolean

True for an owner of the account. The user who signed up is an owner.

language?|

The user's language, as a two-letter ISO 639-1 code in lower case.

locale?|

The locale of the user's browser, such as en-US, saved each time they sign in. Null until they first sign in.

date_last_login?|

When the user last signed in. Null if they never have.

Formatdate-time

allow_test_transactions?boolean

True when the user may work in test mode.

roles?array<string>

The role_id of each role given to the user.

permissions?array<>

The permissions given to the user directly. Where a role and a permission disagree, the more generous one wins.

effective_permissions?

What the token or user may really do, after its roles and permissions are combined and cut down to what its token type allows. Each key is a resource and each value says which methods are allowed on it.

meta?|

Your own data about the user, any JSON up to 2,048 characters.

formatted?

Display text for the dates. Only present when you send formatted=true.

Example Request

curl -X POST 'https://api.comecero.com/api/v1/users/jane.smith.test' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Jane Smith-Jones",
  "roles": [
    "support",
    "fulfillment"
  ]
}'

Example Request

curl -X POST 'https://api.comecero.com/api/v1/users/jane.smith.test' \  -H 'Content-Type: application/json' \  -d '{  "name": "Jane Smith-Jones",  "roles": [    "support",    "fulfillment"  ]}'

Example ResponseSchema

{
  "object": "user",
  "url": "https://api.comecero.com/api/v1/users/jane.smith.test",
  "user_id": "jane.smith.test",
  "test": true,
  "date_created": "2026-10-01T14:36:52Z",
  "date_modified": "2026-10-01T14:36:52Z",
  "account_id": "AB1234",
  "account_alias": "example-shop",
  "account_live": true,
  "name": "Jane Smith",
  "email": "jane@example.com",
  "is_account_owner": false,
  "language": "en",
  "locale": "en-US",
  "date_last_login": "2026-11-06T09:12:40Z",
  "allow_test_transactions": true,
  "roles": [
    "support"
  ],
  "permissions": [],
  "effective_permissions": {
    "orders": {
      "create": false,
      "read": true,
      "update": true,
      "delete": false
    }
  },
  "meta": null
}

{  "object": "user",  "url": "https://api.comecero.com/api/v1/users/jane.smith.test",  "user_id": "jane.smith.test",  "test": true,  "date_created": "2026-10-01T14:36:52Z",  "date_modified": "2026-10-01T14:36:52Z",  "account_id": "AB1234",  "account_alias": "example-shop",  "account_live": true,  "name": "Jane Smith",  "email": "jane@example.com",  "is_account_owner": false,  "language": "en",  "locale": "en-US",  "date_last_login": "2026-11-06T09:12:40Z",  "allow_test_transactions": true,  "roles": [    "support"  ],  "permissions": [],  "effective_permissions": {    "orders": {      "create": false,      "read": true,      "update": true,      "delete": false    }  },  "meta": null}

AuthorizationCopy Anchor Link

Path ParametersCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Path Parameters

Request Body

Response Body