Update a role

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

Updates a custom role's name, description, or permissions and returns the updated role.

Providing permissions replaces the role's permission list and changes the access granted to members assigned to that role. Omitted fields remain unchanged.

OAuth scopes: Requires one of: user.subaccounts, roles.write.

Required permissions:

roles_update

Authorization

Use one of the following alternatives:

apiKey
oauth2 with scopes user.subaccountsroles.write

Authorization guide

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

application/jsonrequired

namestring
User-defined name of the role.

Example: "Senior Shop Manager II"
permissionsarray<string>
User's permissions.

Example: ["catalog_access","taxes_access","members_access"]
descriptionstring
User-defined description of the role.

Example: "Manges the shop and the employees."

Responses

200application/json

Returns the updated Role object if the update succeeded.

idstringrequired
Unique identifier of the role.

Example: "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
namestringrequired
User-defined name of the role.

Example: "Senior Shop Manager II"
permissionsarray<string>required
List of permission granted by this role.

Example: []
is_predefinedbooleanrequired
True if the role is provided by SumUp.

Example: true
created_atstringrequired
format: date-time
The timestamp of when the role was created.

Example: "2023-01-20T15:16:17Z"
updated_atstringrequired
format: date-time
The timestamp of when the role was last updated.

Example: "2023-01-20T15:16:17Z"
descriptionstring
User-defined description of the role.

Example: "Manges the shop and the employees."
metadataobject
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: {}

400application/problem+json

Invalid request.

typestringrequired
format: 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."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

404application/problem+json

Merchant not found.

typestringrequired
format: 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."
instancestring
format: uri
A URI reference that identifies the specific occurrence of the problem.

Example: "https://api.sumup.com/v0.1/checkouts/4e425463-3e1b-431d-83fa-1e51c2925e99"

PATCH

Code sample

curl --request PATCH \
  --url https://api.sumup.com/v0.1/merchants/MK10CL2A/roles/role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Senior Shop Manager III",
  "permissions": [
    "catalog_edit",
    "taxes_access",
    "members_edit"
  ]
}
'

sumup roles update "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP" \
  --merchant-code "MK10CL2A" \
  --name "Senior Shop Manager III" \
  --permission "catalog_edit" \
  --permission "taxes_access" \
  --permission "members_edit"

import SumUp from "@sumup/sdk";

async function main() {
  const client = new SumUp({ apiKey: "sup_sk_your_api_key" });

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

main().catch(console.error);

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using SumUp;

public static class Program
{
    public static async Task Main()
    {
        using var client = new SumUpClient();
        var response = await client.Roles.UpdateAsync(
            "your-merchant-code",
            "example-id",
            new RolesUpdateRequest
            {
                Name = "Senior Shop Manager III",
                Permissions = new string[]
                {
                    "catalog_edit",
                    "taxes_access",
                    "members_edit",
                },
            });

        Console.WriteLine(response.StatusCode);
    }
}

import com.sumup.sdk.SumUpClient;

public final class UpdateMerchantRoleSample {
  public static void main(String[] args) throws Exception {
    var client = new SumUpClient();

    var result = client.roles().update(
            "MK10CL2A",
            "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
            com.sumup.sdk.models.UpdateMerchantRoleRequest.builder()
                .name("Senior Shop Manager III")
                .permissions(java.util.List.of("catalog_edit", "taxes_access", "members_edit"))
                .build()
        );
    System.out.println(result);
  }
}

import os

import sumup

client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
result = client.roles.update(
    "MK10CL2A",
    "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
    name="Senior Shop Manager III",
    permissions=[
        "catalog_edit",
        "taxes_access",
        "members_edit",
    ],
)
print(result)

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

$sumup = new \SumUp\SumUp('sup_sk_your_api_key');

$body = [
    'name' => 'Senior Shop Manager III',
    'permissions' => [
        'catalog_edit',
        'taxes_access',
        'members_edit',
    ],
];

$result = $sumup->roles()->update(
    'MK10CL2A',
    'role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP',
    $body,
);

var_dump($result);

package main

import (
	"context"
	"fmt"

	"github.com/sumup/sumup-go"
)

func main() {
	client := sumup.NewClient()
	result, err := client.Roles.Update(context.TODO(), "MK10CL2A", "role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP", sumup.RolesUpdateParams{
		Name:        new("Senior Shop Manager III"),
		Permissions: []string{"catalog_edit", "taxes_access", "members_edit"},
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Printf("%+v\n", result)
}

use sumup::{Authorization, Client};
#[tokio::main]
async fn main() {
    let client = Client::default()
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
    let body = sumup::resources::roles::UpdateRequest::builder()
        .name("Senior Shop Manager III")
        .permissions(
            vec![
                "catalog_edit".to_string(), "taxes_access".to_string(), "members_edit"
                .to_string()
            ],
        )
        .build();
    let response = client
        .roles()
        .update("MERCHANT_CODE", "ROLE_ID", body)
        .await
        .expect("update request failed");
    println!("{response:#?}");
}

Response example

{
  "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"
}

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

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