SumUp Roles API
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.
OpenAPI Specification
openapi: 3.0.1
info:
title: SumUp REST Checkouts Roles API
version: 1.0.0
description: 'SumUp’s REST API operates with [JSON](https://www.json.org/json-en.html) HTTP requests and responses. The request bodies are sent through resource-oriented URLs and use the standard [HTTP response codes](https://developer.mozilla.org/docs/Web/HTTP/Status).
You can experiment and work on your integration in a sandbox that doesn''t affect your regular data and doesn''t process real transactions. To create a sandbox merchant account visit the [dashboard](https://me.sumup.com/settings/developer). To use the sandbox when interacting with SumUp APIs [create an API](https://me.sumup.com/settings/api-keys) key and use it for [authentication](https://developer.sumup.com/api/authentication).'
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://api.sumup.com
description: Production server
tags:
- name: Roles
description: 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.
x-core-objects:
- $ref: '#/components/schemas/Role'
x-beta: true
paths:
/v0.1/merchants/{merchant_code}/roles:
get:
operationId: ListMerchantRoles
summary: List roles
description: List merchant's custom roles.
parameters:
- name: merchant_code
in: path
description: Short unique identifier for the merchant.
required: true
schema:
type: string
example: MK10CL2A
responses:
'200':
description: Returns a list of Role objects.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Role'
required:
- items
'404':
description: Merchant not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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.
security:
- apiKey: []
- oauth2: []
tags:
- Roles
x-codegen:
method_name: list
x-permissions:
- relation: roles_list
object_type: merchant
object_id_param: merchant_code
x-scopes: []
post:
operationId: CreateMerchantRole
summary: Create a role
description: 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.
parameters:
- name: merchant_code
in: path
description: Short unique identifier for the merchant.
required: true
schema:
type: string
example: MK10CL2A
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: User-defined name of the role.
type: string
example: Senior Shop Manager II
permissions:
description: User's permissions.
type: array
items:
type: string
example:
- catalog_access
- taxes_access
- members_access
maxItems: 100
metadata:
$ref: '#/components/schemas/Metadata'
description:
description: User-defined description of the role.
type: string
example: Manges the shop and the employees.
required:
- name
- permissions
responses:
'201':
description: Returns the Role object after successful custom role creation.
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
'400':
description: Invalid request.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://developer.sumup.com/problem/bad-request
title: Bad Request
status: 400
detail: Request validation failed.
'404':
description: Merchant not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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.
security:
- apiKey: []
- oauth2: []
tags:
- Roles
x-codegen:
method_name: create
x-permissions:
- relation: roles_create
object_type: merchant
object_id_param: merchant_code
x-scopes: []
/v0.1/merchants/{merchant_code}/roles/{role_id}:
get:
operationId: GetMerchantRole
summary: Retrieve a role
description: Retrieve a custom role by ID.
parameters:
- name: merchant_code
in: path
description: Short unique identifier for the merchant.
required: true
schema:
type: string
example: MK10CL2A
- name: role_id
in: path
description: The ID of the role to retrieve.
required: true
schema:
type: string
example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
responses:
'200':
description: Returns the Role object for a valid identifier.
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
'404':
description: Merchant or role not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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.
security:
- apiKey: []
- oauth2: []
tags:
- Roles
x-codegen:
method_name: get
x-permissions:
- relation: roles_view
object_type: merchant
object_id_param: merchant_code
x-scopes: []
delete:
operationId: DeleteMerchantRole
summary: Delete a role
description: Delete a custom role.
parameters:
- name: merchant_code
in: path
description: Short unique identifier for the merchant.
required: true
schema:
type: string
example: MK10CL2A
- name: role_id
in: path
description: The ID of the role to retrieve.
required: true
schema:
type: string
example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
responses:
'200':
description: Returns an empty response if the role deletion succeeded.
'400':
description: Invalid request.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://developer.sumup.com/problem/bad-request
title: Bad Request
status: 400
detail: Request validation failed.
'404':
description: Merchant not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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.
security:
- apiKey: []
- oauth2: []
tags:
- Roles
x-codegen:
method_name: delete
x-permissions:
- relation: roles_delete
object_type: merchant
object_id_param: merchant_code
x-scopes: []
patch:
operationId: UpdateMerchantRole
summary: Update a role
description: Update a custom role.
parameters:
- name: merchant_code
in: path
description: Short unique identifier for the merchant.
required: true
schema:
type: string
example: MK10CL2A
- name: role_id
in: path
description: The ID of the role to retrieve.
required: true
schema:
type: string
example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
description: User-defined name of the role.
type: string
example: Senior Shop Manager II
permissions:
description: User's permissions.
type: array
items:
type: string
example:
- catalog_access
- taxes_access
- members_access
maxItems: 100
description:
description: User-defined description of the role.
type: string
example: Manges the shop and the employees.
example:
name: Senior Shop Manager III
permissions:
- catalog_edit
- taxes_access
- members_edit
responses:
'200':
description: Returns the updated Role object if the update succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Role'
'400':
description: Invalid request.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://developer.sumup.com/problem/bad-request
title: Bad Request
status: 400
detail: Request validation failed.
'404':
description: Merchant not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
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.
security:
- apiKey: []
- oauth2: []
tags:
- Roles
x-codegen:
method_name: update
x-permissions:
- relation: roles_update
object_type: merchant
object_id_param: merchant_code
x-scopes: []
components:
schemas:
Problem:
description: 'A RFC 9457 problem details object.
Additional properties specific to the problem type may be present.'
type: object
properties:
type:
description: A URI reference that identifies the problem type.
type: string
format: uri
example: https://developer.sumup.com/problem/not-found
title:
description: A short, human-readable summary of the problem type.
type: string
example: Requested resource couldn't be found.
status:
description: The HTTP status code generated by the origin server for this occurrence of the problem.
type: integer
example: 404
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
example: The requested resource doesn't exist or does not belong to you.
instance:
description: A URI reference that identifies the specific occurrence of the problem.
type: string
format: uri
additionalProperties: true
required:
- type
title: Problem
Role:
description: A custom role that can be used to assign set of permissions to members.
type: object
properties:
id:
description: Unique identifier of the role.
type: string
example: role_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
name:
description: User-defined name of the role.
type: string
example: Senior Shop Manager II
description:
description: User-defined description of the role.
type: string
example: Manges the shop and the employees.
permissions:
description: List of permission granted by this role.
type: array
items:
type: string
example: []
maxItems: 100
is_predefined:
description: True if the role is provided by SumUp.
type: boolean
example: true
metadata:
$ref: '#/components/schemas/Metadata'
created_at:
description: The timestamp of when the role was created.
type: string
format: date-time
example: 2023-01-20 15:16:17+00:00
updated_at:
description: The timestamp of when the role was last updated.
type: string
format: date-time
example: 2023-01-20 15:16:17+00:00
required:
- id
- name
- permissions
- is_predefined
- created_at
- updated_at
title: Role
Metadata:
description: 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.
type: object
example: {}
additionalProperties: true
maxProperties: 64
securitySchemes:
apiKey:
description: API keys allow you easily interact with SumUp APIs. API keys are static tokens. You can create API keys from the [Dashboard](https://me.sumup.com/settings/api-keys)
type: http
scheme: Bearer
oauth2:
type: oauth2
description: 'SumUp supports [OAuth 2.0](https://tools.ietf.org/html/rfc6749) authentication for platforms that want to offer their services to SumUp users.
To integrate via OAuth 2.0 you will need a client credentials that you can create in the [SumUp Dashboard](https://me.sumup.com/settings/oauth2-applications).
To maintain security of our users, we highly recommend that you use one of the [recommended OAuth 2.0 libraries](https://oauth.net/code/) for authentication.'
flows:
authorizationCode:
authorizationUrl: https://api.sumup.com/authorize
tokenUrl: https://api.sumup.com/token
refreshUrl: https://api.sumup.com/token
scopes:
payments: Make payments by creating and processing checkouts.
transactions.history: View transactions and transaction history.
user.profile_readonly: View user profile details.
user.profile: View and manage your user profile.
user.app-settings: View and manage the SumUp mobile application settings.
payment_instruments: Manage customers and their payment instruments.
user.payout-settings: View and manage your payout settings.
user.subaccounts: View and manage the user profile details of your employees.
clientCredentials:
tokenUrl: https://api.sumup.com/token
scopes:
payments: Make payments by creating and processing checkouts.
transactions.history: View transactions and transaction history.
user.profile_readonly: View user profile details.
user.profile: View and manage your user profile.
user.app-settings: View and manage the SumUp mobile application settings.
payment_instruments: Manage customers and their payment instruments.
user.payout-settings: View and manage your payout settings.
user.subaccounts: View and manage the user profile details of your employee.