Skip to content
SumUpSumUp 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.

  • idstringrequired

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • namestringrequired

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • descriptionstring

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions[]stringrequiredmax items: 100

    List of permission granted by this role.

  • is_predefinedbooleanrequired

    True if the role is provided by SumUp.

    Example: true
  • metadataobjectmax 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_atstringrequiredformat: date-time

    The timestamp of when the role was created.

    Example: "2023-01-20T15:16:17Z"
  • updated_atstringrequiredformat: 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_codestringrequired

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Response

Returns a list of Role objects. See Role object.

  • items[]Rolerequired

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

     Show attributes
     Close
    Role
    • idstringrequired

      Unique identifier of the role.

      Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
    • namestringrequired

      User-defined name of the role.

      Example: "Senior Shop Manager II"
    • descriptionstring

      User-defined description of the role.

      Example: "Manges the shop and the employees."
    • permissions[]stringrequiredmax items: 100

      List of permission granted by this role.

    • is_predefinedbooleanrequired

      True if the role is provided by SumUp.

      Example: true
    • metadataobjectmax 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_atstringrequiredformat: date-time

      The timestamp of when the role was created.

      Example: "2023-01-20T15:16:17Z"
    • updated_atstringrequiredformat: 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.

  • typestringrequiredformat: uri

    A URI reference that identifies the problem type.

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

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

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

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

    Example: 404
  • detailstring

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

    Example: "The requested resource doesn't exist or does not belong to you."
  • instancestringformat: 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."
}
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_codestringrequired

    Short unique identifier for the merchant.

    Example: "MK10CL2A"

Body Parameters

  • namestringrequired

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • permissions[]stringrequiredmax items: 100

    User's permissions.

  • metadataobjectmax 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: {}
  • descriptionstring

    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.

  • idstringrequired

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • namestringrequired

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • descriptionstring

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions[]stringrequiredmax items: 100

    List of permission granted by this role.

  • is_predefinedbooleanrequired

    True if the role is provided by SumUp.

    Example: true
  • metadataobjectmax 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_atstringrequiredformat: date-time

    The timestamp of when the role was created.

    Example: "2023-01-20T15:16:17Z"
  • updated_atstringrequiredformat: 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.

  • typestringrequiredformat: uri

    A URI reference that identifies the problem type.

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

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

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

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

    Example: 404
  • detailstring

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

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

    A URI reference that identifies the specific occurrence of the problem.

Error 400
{
  "type": "https://developer.sumup.com/problem/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed."
}
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_codestringrequired

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • role_idstringrequired

    The ID of the role to retrieve.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"

Response

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

  • idstringrequired

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • namestringrequired

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • descriptionstring

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions[]stringrequiredmax items: 100

    List of permission granted by this role.

  • is_predefinedbooleanrequired

    True if the role is provided by SumUp.

    Example: true
  • metadataobjectmax 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_atstringrequiredformat: date-time

    The timestamp of when the role was created.

    Example: "2023-01-20T15:16:17Z"
  • updated_atstringrequiredformat: 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.

  • typestringrequiredformat: uri

    A URI reference that identifies the problem type.

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

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

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

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

    Example: 404
  • detailstring

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

    Example: "The requested resource doesn't exist or does not belong to you."
  • instancestringformat: 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."
}
Roles

Update a role

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

Update a custom role.

Required permissions:roles_update

Path Parameters

  • merchant_codestringrequired

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • role_idstringrequired

    The ID of the role to retrieve.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"

Body Parameters

  • namestring

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • permissions[]stringmax items: 100

    User's permissions.

  • descriptionstring

    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.

  • idstringrequired

    Unique identifier of the role.

    Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
  • namestringrequired

    User-defined name of the role.

    Example: "Senior Shop Manager II"
  • descriptionstring

    User-defined description of the role.

    Example: "Manges the shop and the employees."
  • permissions[]stringrequiredmax items: 100

    List of permission granted by this role.

  • is_predefinedbooleanrequired

    True if the role is provided by SumUp.

    Example: true
  • metadataobjectmax 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_atstringrequiredformat: date-time

    The timestamp of when the role was created.

    Example: "2023-01-20T15:16:17Z"
  • updated_atstringrequiredformat: 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.

  • typestringrequiredformat: uri

    A URI reference that identifies the problem type.

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

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

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

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

    Example: 404
  • detailstring

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

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

    A URI reference that identifies the specific occurrence of the problem.

Error 400
{
  "type": "https://developer.sumup.com/problem/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed."
}
Roles

Delete a role

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

Delete a custom role.

Required permissions:roles_delete

Path Parameters

  • merchant_codestringrequired

    Short unique identifier for the merchant.

    Example: "MK10CL2A"
  • role_idstringrequired

    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.

  • typestringrequiredformat: uri

    A URI reference that identifies the problem type.

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

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

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

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

    Example: 404
  • detailstring

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

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

    A URI reference that identifies the specific occurrence of the problem.

Error 400
{
  "type": "https://developer.sumup.com/problem/bad-request",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed."
}