Create a role

RolesPreview feature

Endpoints to manage custom roles. Custom roles allow you to tailor roles from individual permissions to match your needs. Once created, you can assign your custom roles to your merchant account members using the memberships.

The Role object

A custom role that can be used to assign set of permissions to members.

Role

id string required

Unique identifier of the role.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
name string required

User-defined name of the role.

Example: "Senior Shop Manager II"
description string

User-defined description of the role.

Example: "Manges the shop and the employees."
permissions []string max items: 100 required

Permissions include only legacy permissions, please use roles instead. Member access is based on their roles within a given resource and the permissions these roles grant.

List of permission granted by this role.
is_predefined boolean required

True if the role is provided by SumUp.

Example: true
metadata object max properties: 64

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

Example: {}
created_at string date-time required

The timestamp of when the role was created.

Example: "2023-01-20T15:16:17Z"
updated_at string date-time required

The timestamp of when the role was last updated.

Example: "2023-01-20T15:16:17Z"

1
{
2
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
3
  "name": "Senior Shop Manager II",
4
  "description": "Manges the shop and the employees.",
5
  "permissions": [],
6
  "is_predefined": true,
7
  "metadata": {},
8
  "created_at": "2023-01-20T15:16:17Z",
9
  "updated_at": "2023-01-20T15:16:17Z"
10
}

Roles

List roles

List merchant's custom roles.

Required permissions: roles_list

Path Parameters

merchant_code string required

Short unique identifier for the merchant.

Example: "MK10CL2A"

Response 200

items []object required

A custom role that can be used to assign set of permissions to members.
Show attributes
Close

Role
- id string required
  
  Unique identifier of the role.
  
  Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
- name string required
  
  User-defined name of the role.
  
  Example: "Senior Shop Manager II"
- description string
  
  User-defined description of the role.
  
  Example: "Manges the shop and the employees."
- permissions []string max items: 100 required
  
  Permissions include only legacy permissions, please use roles instead. Member access is based on their roles within a given resource and the permissions these roles grant.
  
  List of permission granted by this role.
- is_predefined boolean required
  
  True if the role is provided by SumUp.
  
  Example: true
- metadata object max properties: 64
  
  Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.
  
  Example: {}
- created_at string date-time required
  
  The timestamp of when the role was created.
  
  Example: "2023-01-20T15:16:17Z"
- updated_at string date-time required
  
  The timestamp of when the role was last updated.
  
  Example: "2023-01-20T15:16:17Z"

1
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.roles.list("MK10CL2A");

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Roles.ListAsync(
6
    "MK10CL2A"
7
);

1
import com.sumup.sdk.SumUpClient;
2

3
SumUpClient client = SumUpClient.builder().build();
4

5
var result = client.roles().listMerchantRoles(
6
  "MK10CL2A"
7
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.roles.list("MK10CL2A")

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->roles->list('MK10CL2A');

1
client := sumup.NewClient()
2

3
result, err := client.Roles.List(context.Background(), "MK10CL2A")

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.roles().list("MK10CL2A").await;

1
{
2
  "items": [
3
    {
4
      "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
5
      "name": "Senior Shop Manager II",
6
      "description": "Manges the shop and the employees.",
7
      "permissions": [],
8
      "is_predefined": true,
9
      "metadata": {},
10
      "created_at": "2023-01-20T15:16:17Z",
11
      "updated_at": "2023-01-20T15:16:17Z"
12
    }
13
  ]
14
}

Roles

Create a custom role for the merchant. Roles are defined by the set of permissions that they grant to the members that they are assigned to.

Required permissions: roles_create

Path Parameters

merchant_code string required

Short unique identifier for the merchant.

Example: "MK10CL2A"

Body Parameters

name string required

User-defined name of the role.

Example: "Senior Shop Manager II"
permissions []string max items: 100 required

User's permissions.
metadata object max properties: 64

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

Example: {}
description string

User-defined description of the role.

Example: "Manges the shop and the employees."

Role

id string required

Unique identifier of the role.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
name string required

User-defined name of the role.

Example: "Senior Shop Manager II"
description string

User-defined description of the role.

Example: "Manges the shop and the employees."
permissions []string max items: 100 required

Permissions include only legacy permissions, please use roles instead. Member access is based on their roles within a given resource and the permissions these roles grant.

List of permission granted by this role.
is_predefined boolean required

True if the role is provided by SumUp.

Example: true
metadata object max properties: 64

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

Example: {}
created_at string date-time required

The timestamp of when the role was created.

Example: "2023-01-20T15:16:17Z"
updated_at string date-time required

The timestamp of when the role was last updated.

Example: "2023-01-20T15:16:17Z"

1
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles \
2
 -X POST \
3
 -H "Authorization: Bearer $SUMUP_API_KEY" \
4
 --json '{
5
    "name": "Senior Shop Manager II",
6
    "permissions": [
7
      "catalog_access",
8
      "taxes_access",
9
      "members_access"
10
    ]
11
  }'

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.roles.create("MK10CL2A", {
6
  name: "Senior Shop Manager II",
7
  permissions: ["catalog_access","taxes_access","members_access"],
8
});

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Roles.CreateAsync(
6
    "MK10CL2A",
7
    new CreateMerchantRoleBody
8
    {
9
        Name = "Senior Shop Manager II",
10
        Permissions = new[] { "catalog_access", "taxes_access", "members_access" },
11
    }
12
);

1
import com.sumup.sdk.SumUpClient;
2

3
SumUpClient client = SumUpClient.builder().build();
4

5
var result = client.roles().createMerchantRole(
6
  "MK10CL2A",
7
  CreateMerchantRoleBody.builder()
8
    .name("Senior Shop Manager II")
9
    .permissions(java.util.List.of(
10
        "catalog_access",
11
        "taxes_access",
12
        "members_access"
13
      ))
14
    .build()
15
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.roles.create("MK10CL2A", CreateMerchantRoleBody(
6
  name="Senior Shop Manager II",
7
  permissions=["catalog_access","taxes_access","members_access"],
8
))

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->roles->create('MK10CL2A', [
4
  'name' => 'Senior Shop Manager II',
5
  'permissions' => [    'catalog_access',     'taxes_access',     'members_access'],
6
]);

1
client := sumup.NewClient()
2

3
result, err := client.Roles.Create(context.Background(), "MK10CL2A", sumup.RolesCreateParams{
4
  Name: "Senior Shop Manager II",
5
  Permissions: ["catalog_access","taxes_access","members_access"],
6
})

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.roles().create("MK10CL2A", sumup::CreateMerchantRoleBody{
6
  name: "Senior Shop Manager II".to_string(),
7
  permissions: vec!["catalog_access", "taxes_access", "members_access"],
8
}).await;

1
{
2
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
3
  "name": "Senior Shop Manager II",
4
  "description": "Manges the shop and the employees.",
5
  "permissions": [],
6
  "is_predefined": true,
7
  "metadata": {},
8
  "created_at": "2023-01-20T15:16:17Z",
9
  "updated_at": "2023-01-20T15:16:17Z"
10
}

Roles

Retrieve a role

Retrieve a custom role by ID.

Required permissions: roles_view

Path Parameters

merchant_code string required

Short unique identifier for the merchant.

Example: "MK10CL2A"
role_id string required

The ID of the role to retrieve.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"

Role

id string required

Unique identifier of the role.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
name string required

User-defined name of the role.

Example: "Senior Shop Manager II"
description string

User-defined description of the role.

Example: "Manges the shop and the employees."
permissions []string max items: 100 required

Permissions include only legacy permissions, please use roles instead. Member access is based on their roles within a given resource and the permissions these roles grant.

List of permission granted by this role.
is_predefined boolean required

True if the role is provided by SumUp.

Example: true
metadata object max properties: 64

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

Example: {}
created_at string date-time required

The timestamp of when the role was created.

Example: "2023-01-20T15:16:17Z"
updated_at string date-time required

The timestamp of when the role was last updated.

Example: "2023-01-20T15:16:17Z"

1
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.roles.get("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP");

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Roles.GetAsync(
6
    "MK10CL2A",
7
    "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
8
);

1
import com.sumup.sdk.SumUpClient;
2

3
SumUpClient client = SumUpClient.builder().build();
4

5
var result = client.roles().getMerchantRole(
6
  "MK10CL2A",
7
  "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
8
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.roles.get("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->roles->get('MK10CL2A', 'role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP');

1
client := sumup.NewClient()
2

3
result, err := client.Roles.Get(context.Background(), "MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.roles().get("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP").await;

1
{
2
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
3
  "name": "Senior Shop Manager II",
4
  "description": "Manges the shop and the employees.",
5
  "permissions": [],
6
  "is_predefined": true,
7
  "metadata": {},
8
  "created_at": "2023-01-20T15:16:17Z",
9
  "updated_at": "2023-01-20T15:16:17Z"
10
}

Roles

Update a role

Update a custom role.

Required permissions: roles_update

Path Parameters

merchant_code string required

Short unique identifier for the merchant.

Example: "MK10CL2A"
role_id string required

The ID of the role to retrieve.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"

Body Parameters

name string

User-defined name of the role.

Example: "Senior Shop Manager II"
permissions []string max items: 100

User's permissions.
description string

User-defined description of the role.

Example: "Manges the shop and the employees."

Role

id string required

Unique identifier of the role.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
name string required

User-defined name of the role.

Example: "Senior Shop Manager II"
description string

User-defined description of the role.

Example: "Manges the shop and the employees."
permissions []string max items: 100 required

Permissions include only legacy permissions, please use roles instead. Member access is based on their roles within a given resource and the permissions these roles grant.

List of permission granted by this role.
is_predefined boolean required

True if the role is provided by SumUp.

Example: true
metadata object max properties: 64

Set of user-defined key-value pairs attached to the object. Partial updates are not supported. When updating, always submit whole metadata. Maximum of 64 parameters are allowed in the object.

Example: {}
created_at string date-time required

The timestamp of when the role was created.

Example: "2023-01-20T15:16:17Z"
updated_at string date-time required

The timestamp of when the role was last updated.

Example: "2023-01-20T15:16:17Z"

1
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
2
 -X PATCH \
3
 -H "Authorization: Bearer $SUMUP_API_KEY" \
4
 --json '{
5
    "name": "Senior Shop Manager III",
6
    "permissions": [
7
      "catalog_edit",
8
      "taxes_access",
9
      "members_edit"
10
    ]
11
  }'

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.roles.update("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", {
6
  name: "Senior Shop Manager III",
7
  permissions: ["catalog_edit","taxes_access","members_edit"],
8
});

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Roles.UpdateAsync(
6
    "MK10CL2A",
7
    "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
8
    new UpdateMerchantRoleBody
9
    {
10
        Name = "Senior Shop Manager III",
11
        Permissions = new[] { "catalog_edit", "taxes_access", "members_edit" },
12
    }
13
);

1
import com.sumup.sdk.SumUpClient;
2

3
SumUpClient client = SumUpClient.builder().build();
4

5
var result = client.roles().updateMerchantRole(
6
  "MK10CL2A",
7
  "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
8
  UpdateMerchantRoleBody.builder()
9
    .name("Senior Shop Manager III")
10
    .permissions(java.util.List.of(
11
        "catalog_edit",
12
        "taxes_access",
13
        "members_edit"
14
      ))
15
    .build()
16
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.roles.update("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", UpdateMerchantRoleBody(
6
  name="Senior Shop Manager III",
7
  permissions=["catalog_edit","taxes_access","members_edit"],
8
))

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->roles->update('MK10CL2A', 'role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP', [
4
  'name' => 'Senior Shop Manager III',
5
  'permissions' => [    'catalog_edit',     'taxes_access',     'members_edit'],
6
]);

1
client := sumup.NewClient()
2

3
result, err := client.Roles.Update(context.Background(), "MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", sumup.RolesUpdateParams{
4
  Name: "Senior Shop Manager III",
5
  Permissions: ["catalog_edit","taxes_access","members_edit"],
6
})

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.roles().update("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", sumup::UpdateMerchantRoleBody{
6
  name: "Senior Shop Manager III".to_string(),
7
  permissions: vec!["catalog_edit", "taxes_access", "members_edit"],
8
}).await;

1
{
2
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
3
  "name": "Senior Shop Manager II",
4
  "description": "Manges the shop and the employees.",
5
  "permissions": [],
6
  "is_predefined": true,
7
  "metadata": {},
8
  "created_at": "2023-01-20T15:16:17Z",
9
  "updated_at": "2023-01-20T15:16:17Z"
10
}

Roles

Delete a role

Delete a custom role.

Required permissions: roles_delete

Path Parameters

merchant_code string required

Short unique identifier for the merchant.

Example: "MK10CL2A"
role_id string required

The ID of the role to retrieve.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"

1
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
2
 -X DELETE \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
import SumUp from '@sumup/sdk';
2

3
const client = new SumUp();
4

5
const result = await client.roles.delete("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP");

1
using SumUp;
2

3
var client = new SumUpClient();
4

5
var result = await client.Roles.DeleteAsync(
6
    "MK10CL2A",
7
    "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
8
);

1
import com.sumup.sdk.SumUpClient;
2

3
SumUpClient client = SumUpClient.builder().build();
4

5
var result = client.roles().deleteMerchantRole(
6
  "MK10CL2A",
7
  "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
8
);

1
from sumup import Sumup
2

3
client = Sumup()
4

5
result = client.roles.delete("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->roles->delete('MK10CL2A', 'role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP');

1
client := sumup.NewClient()
2

3
result, err := client.Roles.Delete(context.Background(), "MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")

1
use sumup::Client;
2

3
let client = Client::default();
4

5
let result = client.roles().delete("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP").await;