SumUp Memberships API

openapi: 3.2.0
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
          - 'null'
      - 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'
      - 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:
    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
    MembershipStatus:
      description: The status of the membership.
      type: string
      enum:
      - accepted
      - pending
      - expired
      - disabled
      - unknown
    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
    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
    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
    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
    Attributes:
      description: Object attributes that are modifiable only by SumUp applications.
      type: object
      example: {}
      additionalProperties: true
  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.