SumUp Memberships API
Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles.
OpenAPI Specification
openapi: 3.0.1
info:
title: SumUp REST Checkouts Memberships 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: Memberships
description: Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles.
x-core-objects:
- $ref: '#/components/schemas/Membership'
x-beta: true
paths:
/v0.1/memberships:
get:
operationId: ListMemberships
summary: List memberships
description: List memberships of the current user.
parameters:
- name: offset
in: query
description: Offset of the first member to return.
schema:
type: integer
example: 0
default: 0
minimum: 0
- name: limit
in: query
description: Maximum number of members to return.
schema:
type: integer
example: 10
default: 10
maximum: 25
minimum: 1
- name: kind
in: query
description: Filter memberships by resource kind.
schema:
$ref: '#/components/schemas/ResourceType'
- name: status
in: query
description: Filter the returned memberships by the membership status.
schema:
$ref: '#/components/schemas/MembershipStatus'
- name: resource.type
in: query
description: Filter memberships by resource kind.
schema:
$ref: '#/components/schemas/ResourceType'
- name: resource.attributes.sandbox
in: query
description: Filter memberships by the sandbox status of the resource the membership is in.
schema:
type: boolean
- name: resource.name
in: query
description: Filter memberships by the name of the resource the membership is in.
schema:
type: string
- name: resource.parent.id
in: query
description: 'Filter memberships by the parent of the resource the membership is in.
When filtering by parent both `resource.parent.id` and `resource.parent.type` must be present. Pass explicit null to filter for resources without a parent.'
schema:
type: string
nullable: true
- name: resource.parent.type
in: query
description: 'Filter memberships by the parent of the resource the membership is in.
When filtering by parent both `resource.parent.id` and `resource.parent.type` must be present. Pass explicit null to filter for resources without a parent.'
schema:
allOf:
- $ref: '#/components/schemas/ResourceType'
nullable: true
- name: roles
in: query
description: Filter the returned memberships by role.
schema:
type: array
items:
type: string
example:
- role_employee
- role_accountant
explode: true
style: form
responses:
'200':
description: Returns a list of Membership objects.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/Membership'
total_count:
type: integer
example: 3
required:
- total_count
- items
'400':
description: Invalid query parameter combination.
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.
'401':
description: Authentication failed or missing required scope.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
example:
type: https://developer.sumup.com/problem/unauthorized
title: Unauthorized
status: 401
detail: Authentication credentials are missing or invalid.
security:
- apiKey: []
- oauth2: []
tags:
- Memberships
x-codegen:
method_name: list
x-scopes: []
components:
schemas:
Membership:
description: A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles.
type: object
properties:
id:
description: ID of the membership.
type: string
example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
resource_id:
description: ID of the resource the membership is in.
type: string
example: M2DDT39A
type:
$ref: '#/components/schemas/ResourceType'
roles:
description: User's roles.
type: array
items:
type: string
example:
- role_admin
permissions:
description: User's permissions.
type: array
items:
type: string
example:
- members_read
- members_write
- create_moto_payments
- full_transaction_history_view
- refund_transactions
- create_referral
- developer_settings_edit
- developer_settings_access
deprecated: true
x-deprecation-notice: 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.
created_at:
description: The timestamp of when the membership was created.
type: string
format: date-time
example: 2023-01-20 15:16:17+00:00
updated_at:
description: The timestamp of when the membership was last updated.
type: string
format: date-time
example: 2023-01-20 15:16:17+00:00
invite:
$ref: '#/components/schemas/Invite'
status:
$ref: '#/components/schemas/MembershipStatus'
metadata:
$ref: '#/components/schemas/Metadata'
attributes:
$ref: '#/components/schemas/Attributes'
resource:
$ref: '#/components/schemas/MembershipResource'
required:
- id
- resource_id
- type
- roles
- permissions
- created_at
- updated_at
- status
- resource
title: Membership
Invite:
description: Pending invitation for membership.
type: object
properties:
email:
description: Email address of the invited user.
type: string
format: email
example: boaty.mcboatface@sumup.com
expires_at:
type: string
format: date-time
example: 2023-01-20 15:16:17+00:00
required:
- email
- expires_at
title: Invite
Attributes:
description: Object attributes that are modifiable only by SumUp applications.
type: object
example: {}
additionalProperties: true
MembershipStatus:
description: The status of the membership.
type: string
enum:
- accepted
- pending
- expired
- disabled
- unknown
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
ResourceType:
description: 'The type of the membership resource.
Possible values are:
* `merchant` - merchant account(s)
* `organization` - organization(s)'
type: string
example: merchant
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
MembershipResource:
description: Information about the resource the membership is in.
type: object
properties:
id:
description: ID of the resource the membership is in.
type: string
example: M2DDT39A
type:
$ref: '#/components/schemas/ResourceType'
name:
description: Display name of the resource.
type: string
example: Acme Corp
logo:
description: Logo fo the resource.
type: string
format: uri
example: https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png
maxLength: 256
created_at:
description: The timestamp of when the membership resource was created.
type: string
format: date-time
example: 2023-01-20 15:16:17+00:00
updated_at:
description: The timestamp of when the membership resource was last updated.
type: string
format: date-time
example: 2023-01-20 15:16:17+00:00
attributes:
$ref: '#/components/schemas/Attributes'
required:
- id
- type
- name
- created_at
- updated_at
title: Resource
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.