SumUp Members API

openapi: 3.0.1
info:
  title: SumUp REST Checkouts Members 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: Members
  description: Endpoints to manage account members. Members are users that have membership within merchant accounts.
  x-core-objects:
  - $ref: '#/components/schemas/Member'
  x-beta: true
paths:
  /v0.1/merchants/{merchant_code}/members:
    get:
      operationId: ListMerchantMembers
      summary: List members
      description: Lists merchant members.
      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: scroll
        in: query
        description: Indicates to skip count query.
        schema:
          type: boolean
          example: true
          default: false
        x-document: false
      - name: email
        in: query
        description: Filter the returned members by email address prefix.
        schema:
          type: string
          example: user
      - name: user.id
        in: query
        description: Search for a member by user id.
        schema:
          type: string
          format: uuid
          example: 245b2ead-85bf-45ff-856f-311a88a5d454
      - name: status
        in: query
        description: Filter the returned members by the membership status.
        schema:
          $ref: '#/components/schemas/MembershipStatus'
      - name: roles
        in: query
        description: Filter the returned members by role.
        schema:
          type: array
          items:
            type: string
          example:
          - role_employee
          - role_accountant
        explode: true
        style: form
      - 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 Member objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Member'
                  total_count:
                    type: integer
                    example: 3
                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:
      - Members
      x-codegen:
        method_name: list
      x-permissions:
      - relation: merchant_read
        object_type: merchant
        object_id_param: merchant_code
      x-scopes: []
    post:
      operationId: CreateMerchantMember
      summary: Create a member
      description: Create a merchant member.
      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:
                is_managed_user:
                  description: True if the user is managed by the merchant. In this case, we'll created a virtual user with the provided password and nickname.
                  type: boolean
                email:
                  description: Email address of the member to add.
                  type: string
                  format: email
                password:
                  description: Password of the member to add. Only used if `is_managed_user` is true. In the case of service accounts, the password is not used and can not be defined by the caller.
                  type: string
                  format: password
                  minLength: 8
                nickname:
                  description: Nickname of the member to add. Only used if `is_managed_user` is true. Used for display purposes only.
                  type: string
                  example: Test User
                roles:
                  description: List of roles to assign to the new member.
                  type: array
                  items:
                    type: string
                metadata:
                  $ref: '#/components/schemas/Metadata'
                attributes:
                  $ref: '#/components/schemas/Attributes'
              example:
                email: karl.berg@example.com
                roles:
                - role_employee
              required:
              - email
              - roles
      responses:
        '201':
          description: Returns the Member object if the creation succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '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.
        '429':
          description: Too many invitations were sent to that user and the rate limit was exceeded. The Retry-After header indicates when the client can retry.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/too-many-requests
                title: Too Many Requests
                status: 429
                detail: Too many requests were sent. Please try again later.
      security:
      - apiKey: []
      - oauth2: []
      tags:
      - Members
      x-codegen:
        method_name: create
      x-permissions:
      - relation: members_create
        object_type: merchant
        object_id_param: merchant_code
      x-scopes: []
  /v0.1/merchants/{merchant_code}/members/{member_id}:
    get:
      operationId: GetMerchantMember
      summary: Retrieve a member
      description: Retrieve a merchant member.
      parameters:
      - name: merchant_code
        in: path
        description: Short unique identifier for the merchant.
        required: true
        schema:
          type: string
          example: MK10CL2A
      - name: member_id
        in: path
        description: The ID of the member to retrieve.
        required: true
        schema:
          type: string
          example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
      responses:
        '200':
          description: Returns the Member object for a valid identifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '404':
          description: Merchant or member 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:
      - Members
      x-codegen:
        method_name: get
      x-permissions:
      - relation: members_view
        object_type: merchant
        object_id_param: merchant_code
      x-scopes: []
    put:
      operationId: UpdateMerchantMember
      summary: Update a member
      description: Update the merchant member.
      parameters:
      - name: merchant_code
        in: path
        description: Short unique identifier for the merchant.
        required: true
        schema:
          type: string
          example: MK10CL2A
      - name: member_id
        in: path
        description: The ID of the member to retrieve.
        required: true
        schema:
          type: string
          example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                roles:
                  type: array
                  items:
                    type: string
                metadata:
                  $ref: '#/components/schemas/Metadata'
                attributes:
                  $ref: '#/components/schemas/Attributes'
                user:
                  description: Allows you to update user data of managed users.
                  type: object
                  properties:
                    nickname:
                      description: User's preferred name. Used for display purposes only.
                      type: string
                      example: Test User
                    password:
                      description: Password of the member to add. Only used if `is_managed_user` is true.
                      type: string
                      format: password
                      minLength: 8
              example:
                Update member's role:
                  roles:
                  - role_manager
                Update managed user:
                  user:
                    nickname: New Employee Name
      responses:
        '200':
          description: Returns the updated Member object if the update succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '400':
          description: Cannot set password or nickname for an invited user.
          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.
        '403':
          description: Cannot change password for managed user. Password was already used before.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to perform this action.
        '404':
          description: Merchant or member 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.
        '409':
          description: Cannot update member as some data conflict with existing members.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
              example:
                type: https://developer.sumup.com/problem/conflict
                title: Conflict
                status: 409
                detail: The request conflicts with the current state of the resource.
      security:
      - apiKey: []
      - oauth2: []
      tags:
      - Members
      x-codegen:
        method_name: update
      x-permissions:
      - relation: members_update
        object_type: merchant
        object_id_param: merchant_code
      x-scopes: []
    delete:
      operationId: DeleteMerchantMember
      summary: Delete a member
      description: Deletes a merchant member.
      parameters:
      - name: merchant_code
        in: path
        description: Short unique identifier for the merchant.
        required: true
        schema:
          type: string
          example: MK10CL2A
      - name: member_id
        in: path
        description: The ID of the member to retrieve.
        required: true
        schema:
          type: string
          example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
      responses:
        '200':
          description: Returns an empty response if the deletion succeeded.
        '404':
          description: Merchant or member 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:
      - Members
      x-codegen:
        method_name: delete
      x-permissions:
      - relation: members_delete
        object_type: merchant
        object_id_param: merchant_code
      x-scopes: []
components:
  schemas:
    MembershipUser:
      description: Information about the user associated with the membership.
      type: object
      properties:
        id:
          description: Identifier for the End-User (also called Subject).
          type: string
          example: 44ca0f5b-813b-46e1-aee7-e6242010662e
        email:
          description: End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, for unique identification use ID instead.
          type: string
          example: example@sumup.com
        mfa_on_login_enabled:
          description: True if the user has enabled MFA on login.
          type: boolean
          example: true
        virtual_user:
          description: True if the user is a virtual user (operator).
          type: boolean
          example: false
        service_account_user:
          description: True if the user is a service account.
          type: boolean
          example: false
        disabled_at:
          description: 'Time when the user has been disabled. Applies only to virtual users (`virtual_user: true`).'
          type: string
          format: date-time
        nickname:
          description: User's preferred name. Used for display purposes only.
          type: string
          example: Test User
        picture:
          description: URL of the End-User's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image.
          type: string
          format: uri
          example: https://usercontent.sumup.com/44ca0f5b-813b-46e1-aee7-e6242010662e.png
        classic:
          $ref: '#/components/schemas/MembershipUserClassic'
      required:
      - id
      - email
      - mfa_on_login_enabled
      - virtual_user
      - service_account_user
    Member:
      description: A member is user within specific resource identified by resource id, resource type, and associated roles.
      type: object
      properties:
        id:
          description: ID of the member.
          type: string
          example: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
        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 roles within a given resource and the permissions these roles grant.
        created_at:
          description: The timestamp of when the member was created.
          type: string
          format: date-time
          example: 2023-01-20 15:16:17+00:00
        updated_at:
          description: The timestamp of when the member was last updated.
          type: string
          format: date-time
          example: 2023-01-20 15:16:17+00:00
        user:
          $ref: '#/components/schemas/MembershipUser'
        invite:
          $ref: '#/components/schemas/Invite'
        status:
          $ref: '#/components/schemas/MembershipStatus'
        metadata:
          $ref: '#/components/schemas/Metadata'
        attributes:
          $ref: '#/components/schemas/Attributes'
      example:
        id: mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP
        roles:
        - role_admin
        - role_owner
        permissions:
        - members_read
        - members_write
        - create_moto_payments
        - full_transaction_history_view
        - refund_transactions
        - create_referral
        - developer_settings_edit
        - developer_settings_access
        created_at: 2023-01-20 15:16:17+00:00
        updated_at: 2023-02-20 15:16:17+00:00
        user:
          id: 44ca0f5b-813b-46e1-aee7-e6242010662e
          email: example@sumup.com
          mfa_on_login_enabled: true
          virtual_user: false
          service_account_user: false
        status: accepted
      required:
      - id
      - roles
      - permissions
      - created_at
      - updated_at
      - status
      title: Member
    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
    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
    MembershipUserClassic:
      description: Classic identifiers of the user.
      type: object
      properties:
        user_id:
          type: integer
          format: int32
      deprecated: true
      required:
      - user_id
  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.