Skip to content
SumUp Developer

Roles

SumUp API reference and code samples.

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.

  • 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 required max items: 100

    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 required format: date-time

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

    Example: "2023-01-20T15:16:17Z"
The Role object
{
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}
Roles

List roles

GET /v0.1/merchants/{merchant_code}/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

Returns a list of Role objects. See Role object .

  • items []Role 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 required max items: 100

      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 required format: date-time

      The timestamp of when the role was created.

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

      The timestamp of when the role was last updated.

      Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/roles 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


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


var client = new SumUpClient();


var result = await client.Roles.ListAsync(
    "MK10CL2A"
);
import com.sumup.sdk.SumUpClient;


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


var result = client.roles().listMerchantRoles(
  "MK10CL2A"
);
from sumup import Sumup


client = Sumup()


result = client.roles.list("MK10CL2A")
$sumup = new \SumUp\SumUp();


$result = $sumup->roles->list('MK10CL2A');
client := sumup.NewClient()


result, err := client.Roles.List(context.Background(), "MK10CL2A")
use sumup::Client;


let client = Client::default();


let result = client.roles().list("MK10CL2A").await;
List roles response
{
  "items": [
    {
      "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
      "name": "Senior Shop Manager II",
      "description": "Manges the shop and the employees.",
      "permissions": [],
      "is_predefined": true,
      "metadata": {},
      "created_at": "2023-01-20T15:16:17Z",
      "updated_at": "2023-01-20T15:16:17Z"
    }
  ]
}

Content-Type: application/problem+json

Merchant not found.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 404
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}
Roles

Create a role

POST /v0.1/merchants/{merchant_code}/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 required max items: 100

    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."

Response

Returns the Role object after successful custom role creation. See Role object .

  • 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 required max items: 100

    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 required format: date-time

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

    Example: "2023-01-20T15:16:17Z"
POST /v0.1/merchants/{merchant_code}/roles 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles \
 -X POST \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "name": "Senior Shop Manager II",
    "permissions": [
      "catalog_access",
      "taxes_access",
      "members_access"
    ]
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


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


var client = new SumUpClient();


var result = await client.Roles.CreateAsync(
    "MK10CL2A",
    new CreateMerchantRoleBody
    {
        Name = "Senior Shop Manager II",
        Permissions = new[] { "catalog_access", "taxes_access", "members_access" },
    }
);
import com.sumup.sdk.SumUpClient;


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


var result = client.roles().createMerchantRole(
  "MK10CL2A",
  CreateMerchantRoleBody.builder()
    .name("Senior Shop Manager II")
    .permissions(java.util.List.of(
        "catalog_access",
        "taxes_access",
        "members_access"
      ))
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.roles.create("MK10CL2A", CreateMerchantRoleBody(
  name="Senior Shop Manager II",
  permissions=["catalog_access","taxes_access","members_access"],
))
$sumup = new \SumUp\SumUp();


$result = $sumup->roles->create('MK10CL2A', [
  'name' => 'Senior Shop Manager II',
  'permissions' => [    'catalog_access',     'taxes_access',     'members_access'],
]);
client := sumup.NewClient()


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


let client = Client::default();


let result = client.roles().create("MK10CL2A", sumup::CreateMerchantRoleBody{
  name: "Senior Shop Manager II".to_string(),
  permissions: vec!["catalog_access", "taxes_access", "members_access"],
}).await;
Create a role response
{
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}

Content-Type: application/problem+json

Invalid request.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 400
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}
Roles

Retrieve a role

GET /v0.1/merchants/{merchant_code}/roles/{role_id}

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"

Response

Returns the Role object for a valid identifier. See Role object .

  • 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 required max items: 100

    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 required format: date-time

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

    Example: "2023-01-20T15:16:17Z"
GET /v0.1/merchants/{merchant_code}/roles/{role_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
 -X GET \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


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


var client = new SumUpClient();


var result = await client.Roles.GetAsync(
    "MK10CL2A",
    "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
import com.sumup.sdk.SumUpClient;


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


var result = client.roles().getMerchantRole(
  "MK10CL2A",
  "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
from sumup import Sumup


client = Sumup()


result = client.roles.get("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
$sumup = new \SumUp\SumUp();


$result = $sumup->roles->get('MK10CL2A', 'role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP');
client := sumup.NewClient()


result, err := client.Roles.Get(context.Background(), "MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
use sumup::Client;


let client = Client::default();


let result = client.roles().get("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP").await;
Retrieve a role response
{
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}

Content-Type: application/problem+json

Merchant or role not found.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 404
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}
Roles

Update a role

PATCH /v0.1/merchants/{merchant_code}/roles/{role_id}

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."

Response

Returns the updated Role object if the update succeeded. See Role object .

  • 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 required max items: 100

    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 required format: date-time

    The timestamp of when the role was created.

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

    The timestamp of when the role was last updated.

    Example: "2023-01-20T15:16:17Z"
PATCH /v0.1/merchants/{merchant_code}/roles/{role_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
 -X PATCH \
 -H "Authorization: Bearer $SUMUP_API_KEY" \
 --json '{
    "name": "Senior Shop Manager III",
    "permissions": [
      "catalog_edit",
      "taxes_access",
      "members_edit"
    ]
  }'
import SumUp from '@sumup/sdk';


const client = new SumUp();


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


var client = new SumUpClient();


var result = await client.Roles.UpdateAsync(
    "MK10CL2A",
    "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
    new UpdateMerchantRoleBody
    {
        Name = "Senior Shop Manager III",
        Permissions = new[] { "catalog_edit", "taxes_access", "members_edit" },
    }
);
import com.sumup.sdk.SumUpClient;


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


var result = client.roles().updateMerchantRole(
  "MK10CL2A",
  "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  UpdateMerchantRoleBody.builder()
    .name("Senior Shop Manager III")
    .permissions(java.util.List.of(
        "catalog_edit",
        "taxes_access",
        "members_edit"
      ))
    .build()
);
from sumup import Sumup


client = Sumup()


result = client.roles.update("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", UpdateMerchantRoleBody(
  name="Senior Shop Manager III",
  permissions=["catalog_edit","taxes_access","members_edit"],
))
$sumup = new \SumUp\SumUp();


$result = $sumup->roles->update('MK10CL2A', 'role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP', [
  'name' => 'Senior Shop Manager III',
  'permissions' => [    'catalog_edit',     'taxes_access',     'members_edit'],
]);
client := sumup.NewClient()


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


let client = Client::default();


let result = client.roles().update("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", sumup::UpdateMerchantRoleBody{
  name: "Senior Shop Manager III".to_string(),
  permissions: vec!["catalog_edit", "taxes_access", "members_edit"],
}).await;
Update a role response
{
  "id": "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
  "name": "Senior Shop Manager II",
  "description": "Manges the shop and the employees.",
  "permissions": [],
  "is_predefined": true,
  "metadata": {},
  "created_at": "2023-01-20T15:16:17Z",
  "updated_at": "2023-01-20T15:16:17Z"
}

Content-Type: application/problem+json

Invalid request.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 400
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}
Roles

Delete a role

DELETE /v0.1/merchants/{merchant_code}/roles/{role_id}

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"

Response

Returns empty response.

DELETE /v0.1/merchants/{merchant_code}/roles/{role_id} 
curl https://api.sumup.com/v0.1/merchants/{merchant_code}/roles/{role_id} \
 -X DELETE \
 -H "Authorization: Bearer $SUMUP_API_KEY"
import SumUp from '@sumup/sdk';


const client = new SumUp();


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


var client = new SumUpClient();


var result = await client.Roles.DeleteAsync(
    "MK10CL2A",
    "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
import com.sumup.sdk.SumUpClient;


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


var result = client.roles().deleteMerchantRole(
  "MK10CL2A",
  "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
);
from sumup import Sumup


client = Sumup()


result = client.roles.delete("MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
$sumup = new \SumUp\SumUp();


$result = $sumup->roles->delete('MK10CL2A', 'role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP');
client := sumup.NewClient()


result, err := client.Roles.Delete(context.Background(), "MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP")
use sumup::Client;


let client = Client::default();


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

Content-Type: application/problem+json

Invalid request.

  • type string required format: uri

    A URI reference that identifies the problem type.

    Example: "https://developer.sumup.com/problem/not-found"
  • title string

    A short, human-readable summary of the problem type.

    Example: "Requested resource couldn't be found."
  • status integer

    The HTTP status code generated by the origin server for this occurrence of the problem.

    Example: 404
  • detail string

    A human-readable explanation specific to this occurrence of the problem.

    Example: "The requested resource doesn't exist or does not belong to you."
  • instance string format: uri

    A URI reference that identifies the specific occurrence of the problem.
Error 400
{
  "type": "https://developer.sumup.com/problem/not-found",
  "title": "Requested resource couldn't be found.",
  "status": 404,
  "detail": "The requested resource doesn't exist or does not belong to you.",
  "instance": null
}