Get Customer Groups

Get the groups that a customer belongs to, and their role in each group.

URL

GET https://api.storekit.apple.com/groups/v1/currentGroups/{anyTransactionId}

Sandbox URL

GET https://api.storekit-sandbox.apple.com/groups/v1/currentGroups/{anyTransactionId}

Path Parameters

Name	Type	Description
`anyTransactionId` Required	`anyTransactionId`	Any originalTransactionId, transactionId, or appTransactionId that belongs to the customer for your app.

Response Codes

Status	Reason	Type	Description
200	OK Content-Type: application/json	`GetCustomerGroupsResponse`	Request succeeded.
400	Bad Request Content-Type: application/json	`InvalidTransactionIdError`	Invalid request.
401	Unauthorized		The JSON Web Token (JWT) in the authorization header is invalid. For more information, see Generating JSON Web Tokens for API requests.
404	Not Found Content-Type: application/json	`TransactionIdNotFoundError`	The transaction identifier doesn’t exist.
429	Content-Type: application/json	`RateLimitExceededError`	The request exceeded the rate limit.
500	Internal Server Error Content-Type: application/json	`GeneralInternalError`	Server error. Try again later.

Mentioned in

Discussion

Call this endpoint to determine whether a customer has access to your app or its in-app purchases through an organization or group, and what role they hold in it. A group consists of customers whose access is purchased and managed centrally by a single account, rather than individually. Groups come from multiseat purchases: an organization buys seats through Volume Purchasing, or a subscriber buys seats through Group Purchases and invites others to join.

Use this endpoint only if your app offers a group experience where a customer’s group or role changes what you present — for example, exposing extra controls to a customer with the ADMIN role, or grouping members into that administrator’s shared workspace. Group membership is separate from entitlement. To unlock content for a customer, read their transactions; don’t depend on group membership.

Provide any transaction identifier that belongs to the customer for your app. The response, GetCustomerGroupsResponse, contains a GroupEntry for each group the customer currently belongs to. Each entry identifies the group with a groupId and indicates the kind of group with a groupType. For a group with a groupType of ORGANIZATION, the entry also lists the customer’s role for each of your products in a RoleEntry array. If the customer doesn’t belong to any group, the response contains an empty groups array.

A customer can belong to more than one group, and can hold a different role in each.

To list the members of a group, call the Get Group Members endpoint.

Test in the sandbox environment

In the sandbox environment, if the customer doesn’t belong to any groups with a groupType of CONSUMER, this endpoint returns a placeholder group with a groupType of ORGANIZATION:

{
  "groups": [
    {
      "groupId": "900000000000000000",
      "groupType": "ORGANIZATION",
      "roles": [
        {
          "productId": "example.productId.one",
          "role": "ADMIN"
        },
        {
          "productId": "example.productId.two",
          "role": "NONE"
        }
      ]
    }
  ]
}

Send the placeholder groupId of 900000000000000000 to the Get Group Members endpoint to get its corresponding placeholder response.

For more information about configuring your subscription for multiseat purchases, see Manage purchase options for an auto-renewable subscription.