Memberships | SumUp Developer

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.

Endpoints

List memberships
GET/v0.1/memberships

The Membership object

A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles.

idstringrequired
ID of the membership.

Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
resource_idstringrequired
ID of the resource the membership is in.

Example: "M2DDT39A"
typestringrequired
The type of the membership resource. Possible values are:
- merchant - merchant account(s)
- organization - organization(s)
Example: "merchant"
roles[]stringrequired
User's roles.
permissions[]stringrequireddeprecated
Caution
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.

User's permissions.
created_atstringrequiredformat: date-time
The timestamp of when the membership was created.

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

Example: "2023-01-20T15:16:17Z"
inviteInvite
Pending invitation for membership.
Show attributes
Close
Invite
- emailstringrequiredformat: email
  Email address of the invited user.
  
  Example: "boaty.mcboatface@sumup.com"
- expires_atstringrequiredformat: date-time
  Example: "2023-01-20T15:16:17Z"
statusstringrequired
Options: acceptedpendingexpireddisabledunknown
The status of the membership.
metadataobjectmax properties: 64
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: {}
attributesobject
Object attributes that are modifiable only by SumUp applications.

Example: {}
resourceResourcerequired
Information about the resource the membership is in.
Show attributes
Close
Resource
- idstringrequired
  ID of the resource the membership is in.
  
  Example: "M2DDT39A"
- typestringrequired
  The type of the membership resource. Possible values are:
  
  merchant - merchant account(s)
  
  organization - organization(s)
  
  Example: "merchant"
- namestringrequired
  Display name of the resource.
  
  Example: "Acme Corp"
- logostringmax length: 256, format: uri
  Logo fo the resource.
  
  Example: "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png"
- created_atstringrequiredformat: date-time
  The timestamp of when the membership resource was created.
  
  Example: "2023-01-20T15:16:17Z"
- updated_atstringrequiredformat: date-time
  The timestamp of when the membership resource was last updated.
  
  Example: "2023-01-20T15:16:17Z"
- attributesobject
  Object attributes that are modifiable only by SumUp applications.
  
  Example: {}

1
{
2
  "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
3
  "resource_id": "M2DDT39A",
4
  "type": "merchant",
5
  "roles": [
6
    "role_admin"
7
  ],
8
  "permissions": [
9
    "members_read",
10
    "members_write",
11
    "create_moto_payments",
12
    "full_transaction_history_view",
13
    "refund_transactions",
14
    "create_referral",
15
    "developer_settings_edit",
16
    "developer_settings_access"
17
  ],
18
  "created_at": "2023-01-20T15:16:17Z",
19
  "updated_at": "2023-01-20T15:16:17Z",
20
  "invite": {
21
    "email": "boaty.mcboatface@sumup.com",
22
    "expires_at": "2023-01-20T15:16:17Z"
23
  },
24
  "status": "",
25
  "metadata": {},
26
  "attributes": {},
27
  "resource": {
28
    "id": "M2DDT39A",
29
    "type": "merchant",
30
    "name": "Acme Corp",
31
    "logo": "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png",
32
    "created_at": "2023-01-20T15:16:17Z",
33
    "updated_at": "2023-01-20T15:16:17Z",
34
    "attributes": {}
35
  }
36
}

Memberships

List memberships

GET/v0.1/memberships

List memberships of the current user.

Requires one of scopes:user.profileuser.profile_readonly

Query Parameters

offsetintegerminimum: 0, default: 0
Offset of the first member to return.

Example: 0
limitintegerminimum: 1, maximum: 25, default: 10
Maximum number of members to return.

Example: 10
kindstring
Filter memberships by resource kind.

Example: "merchant"
statusstring
Options: acceptedpendingexpireddisabledunknown
Filter the returned memberships by the membership status.
resource.typestring
Filter memberships by resource kind.

Example: "merchant"
resource.attributes.sandboxboolean
Filter memberships by the sandbox status of the resource the membership is in.
resource.namestring
Filter memberships by the name of the resource the membership is in.
resource.idstring
Filter memberships by the ID of the resource the membership is in.
resource.parent.idstring
Filter memberships by the parent of the resource the membership is in. Omit both resource.parent.id and resource.parent.type to skip parent filtering. When filtering by parent, both parameters must be present. To select resources without a parent, set each parameter to an empty value. Otherwise, both parameters must identify a parent.
resource.parent.typestring
Filter memberships by the parent of the resource the membership is in. Omit both resource.parent.id and resource.parent.type to skip parent filtering. When filtering by parent, both parameters must be present. To select resources without a parent, set each parameter to an empty value. Otherwise, both parameters must identify a parent.

Example: "merchant"
roles[]string
Filter the returned memberships by role.

Example: ["role_employee","role_accountant"]

Response

Returns a list of Membership objects. See Membership object.

items[]Membershiprequired
A membership associates a user with a resource, memberships is defined by user, resource, resource type, and associated roles.
Show attributes
Close
Membership
- idstringrequired
  ID of the membership.
  
  Example: "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP"
- resource_idstringrequired
  ID of the resource the membership is in.
  
  Example: "M2DDT39A"
- typestringrequired
  The type of the membership resource. Possible values are:
  
  merchant - merchant account(s)
  
  organization - organization(s)
  
  Example: "merchant"
- roles[]stringrequired
  User's roles.
- permissions[]stringrequireddeprecated
  Caution
  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.
  
  User's permissions.
- created_atstringrequiredformat: date-time
  The timestamp of when the membership was created.
  
  Example: "2023-01-20T15:16:17Z"
- updated_atstringrequiredformat: date-time
  The timestamp of when the membership was last updated.
  
  Example: "2023-01-20T15:16:17Z"
- inviteInvite
  Pending invitation for membership.
  
  Show attributes
  Close
  Invite
  emailstringrequiredformat: email
  Email address of the invited user.
  
  Example: "boaty.mcboatface@sumup.com"
  expires_atstringrequiredformat: date-time
  Example: "2023-01-20T15:16:17Z"
- statusstringrequired
  Options: acceptedpendingexpireddisabledunknown
  The status of the membership.
- metadataobjectmax properties: 64
  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: {}
- attributesobject
  Object attributes that are modifiable only by SumUp applications.
  
  Example: {}
- resourceResourcerequired
  Information about the resource the membership is in.
  
  Show attributes
  Close
  Resource
  idstringrequired
  ID of the resource the membership is in.
  
  Example: "M2DDT39A"
  typestringrequired
  The type of the membership resource. Possible values are:
  
  merchant - merchant account(s)
  
  organization - organization(s)
  
  Example: "merchant"
  namestringrequired
  Display name of the resource.
  
  Example: "Acme Corp"
  logostringmax length: 256, format: uri
  Logo fo the resource.
  
  Example: "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png"
  created_atstringrequiredformat: date-time
  The timestamp of when the membership resource was created.
  
  Example: "2023-01-20T15:16:17Z"
  updated_atstringrequiredformat: date-time
  The timestamp of when the membership resource was last updated.
  
  Example: "2023-01-20T15:16:17Z"
  attributesobject
  Object attributes that are modifiable only by SumUp applications.
  
  Example: {}
total_countintegerrequired
Example: 3

1
curl https://api.sumup.com/v0.1/memberships \
2
 -X GET \
3
 -H "Authorization: Bearer $SUMUP_API_KEY"

1
sumup memberships list

1
import SumUp from "@sumup/sdk";
2

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

6
  const result = await client.memberships.list(
7
    {
8
      "offset": 0
9
    }
10
  );
11
  console.log(result);
12
}
13

14
main().catch(console.error);

1
using System;
2
using System.Collections.Generic;
3
using System.Threading.Tasks;
4
using SumUp;
5

6
public static class Program
7
{
8
    public static async Task Main()
9
    {
10
        using var client = new SumUpClient();
11
        var response = await client.Memberships.ListAsync(
12
            new MembershipsListOptions
13
            {
14
                Offset = 10,
15
                Limit = 10,
16
                Kind = "example",
17
                Status = MembershipStatus.Accepted,
18
                ResourceType = "example",
19
                ResourceAttributesSandbox = true,
20
                ResourceName = "example",
21
                ResourceParentId = OptionalQuery<string>.From("example-id"),
22
                ResourceParentType = OptionalQuery<string>.From("example"),
23
                Roles = Array.Empty<string>(),
24
            });
25

26
        Console.WriteLine(response.StatusCode);
27
    }
28
}

1
import com.sumup.sdk.SumUpClient;
2

3
public final class ListMembershipsSample {
4
  public static void main(String[] args) throws Exception {
5
    var client = new SumUpClient();
6

7
    var result = client.memberships().list();
8
    System.out.println(result);
9
  }
10
}

1
import os
2

3
import sumup
4

5
client = sumup.Sumup(api_key=os.environ["SUMUP_API_KEY"])
6
result = client.memberships.list(
7
    offset=0,
8
    limit=10,
9
    kind="merchant",
10
    status="accepted",
11
    resource_type="merchant",
12
    roles=[
13
        "role_employee",
14
        "role_accountant",
15
    ],
16
)
17
print(result)

1
$sumup = new \SumUp\SumUp();
2

3
$result = $sumup->memberships->list();

1
package main
2

3
import (
4
  "context"
5
  "fmt"
6

7
  "github.com/sumup/sumup-go"
8
)
9

10
func main() {
11
  client := sumup.NewClient()
12
  result, err := client.Memberships.List(context.TODO(), sumup.MembershipsListParams{
13
    Offset:       new(0),
14
    Limit:        new(10),
15
    Kind:         new(sumup.ResourceType("merchant")),
16
    Status:       new(sumup.MembershipStatus("accepted")),
17
    ResourceType: new(sumup.ResourceType("merchant")),
18
    Roles:        []string{"role_employee", "role_accountant"},
19
  })
20
  if err != nil {
21
    panic(err.Error())
22
  }
23

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

1
use sumup::{Authorization, Client};
2
#[tokio::main]
3
async fn main() {
4
    let client = Client::default()
5
        .with_authorization(Authorization::api_key("sup_sk_test_..."));
6
    let response = client
7
        .memberships()
8
        .list(Default::default())
9
        .await
10
        .expect("list request failed");
11
    println!("{response:#?}");
12
}

1
{
2
  "items": [
3
    {
4
      "id": "mem_WZsm7QTPhVrompscmPhoGTXXcrd58fr9MOhP",
5
      "resource_id": "M2DDT39A",
6
      "type": "merchant",
7
      "roles": [
8
        "role_admin"
9
      ],
10
      "permissions": [
11
        "members_read",
12
        "members_write",
13
        "create_moto_payments",
14
        "full_transaction_history_view",
15
        "refund_transactions",
16
        "create_referral",
17
        "developer_settings_edit",
18
        "developer_settings_access"
19
      ],
20
      "created_at": "2023-01-20T15:16:17Z",
21
      "updated_at": "2023-01-20T15:16:17Z",
22
      "invite": {
23
        "email": "boaty.mcboatface@sumup.com",
24
        "expires_at": "2023-01-20T15:16:17Z"
25
      },
26
      "status": "",
27
      "metadata": {},
28
      "attributes": {},
29
      "resource": {
30
        "id": "M2DDT39A",
31
        "type": "merchant",
32
        "name": "Acme Corp",
33
        "logo": "https://images.sumup.com/img_2x4y6z8a0b1c2d3e4f5g6h7j8k.png",
34
        "created_at": "2023-01-20T15:16:17Z",
35
        "updated_at": "2023-01-20T15:16:17Z",
36
        "attributes": {}
37
      }
38
    }
39
  ],
40
  "total_count": 3
41
}

Error 400
Error 401

Content-Type: application/problem+json

Invalid query parameter combination.

typestringrequiredformat: 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."
instancestringformat: 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"

Content-Type: application/problem+json

Authentication failed or missing required scope.

typestringrequiredformat: 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."
instancestringformat: 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"

Error 400
Error 401

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

1
{
2
  "type": "https://developer.sumup.com/problem/unauthorized",
3
  "title": "Unauthorized",
4
  "status": 401,
5
  "detail": "Authentication credentials are missing or invalid."
6
}