comecerodocs
Roles

Get a role

GET
/roles/{role_id}

Gets one role. A role of the other mode is not found (404).

Secret and trusted tokens may call this with the roles read permission.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

role_id*string

The role's role_id.

Query Parameters

formatted?boolean

When true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.

Defaultfalse
show?string

Comma-separated fields to return; all others are left out. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

hide?string

Comma-separated fields to leave out of the response. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

timezone?string

An IANA time zone name, such as America/New_York or UTC. It sets how date_start and date_end are read and the time zone of every date in the response. The default is the account's time zone (Settings, Technical), or UTC when it has none. A name that is not known is a 400.

Response Body

The role.

application/json
  1. response

A named set of permissions that you give to users and secret tokens. Roles are kept per mode: a test token sees only test roles.

object?"role"

The object type. Always role.

Value in"role"
url?string

The URL of this role.

Formaturi
role_id?string

The role's ID. You may choose it when you create the role. Otherwise it is made from the name, in lower case with dashes for spaces.

date_created?string

When the role was created.

Formatdate-time
date_modified?string

When the role was last changed.

Formatdate-time
test?boolean

True for a test role.

account_id?string

The account the role belongs to.

name?string

The role's name.

Lengthlength <= 25
comments?|

Your own notes about the role.

Lengthlength <= 150
permission_type?|

An older label kept for roles that have one. Comecero does not use it.

permissions?array<>

The permissions the role gives.

formatted?

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

Example Request
curl -X GET 'https://api.comecero.com/api/v1/roles/support'
Example Response
{  "object": "role",  "url": "https://api.comecero.com/api/v1/roles/support",  "role_id": "support",  "date_created": "2026-10-01T14:36:52Z",  "date_modified": "2026-10-01T14:36:52Z",  "test": true,  "account_id": "AB1234",  "name": "Support",  "comments": "Can look up and update orders and customers.",  "permission_type": null,  "permissions": [    {      "resource": "orders",      "methods": [        "read",        "update"      ],      "allow": true    },    {      "resource": "customers",      "methods": [        "read"      ],      "allow": true    }  ]}

Create a role POST

Creates a role in the mode of the token you call with. Give it to users and secret tokens through their `roles` list. Secret and trusted tokens may call this with the `roles` create permission.

Delete a role DELETE

Deletes a role. Users and tokens that list it keep the `role_id` but no longer get its permissions. Secret and trusted tokens may call this with the `roles` delete permission.