# Create and manage subscription groups

This guide walks you through using subscription groups to model related [subscriptions][subscriptions] in the Gigs API. For example, the three subscriptions on a household's family plan, or a set of subscriptions administered by a single account holder.

A subscription group is a thin container. It records that a set of subscriptions are related, but does not change their behavior: each subscription keeps its own plan, its own SIM, its own billing, and its own lifecycle.

You only need a subscription group when your product treats multiple subscriptions as a unit. For example, to display related subscriptions together in your dashboard, or to apply your own family-plan discount logic on top of a known set of subscriptions. If you don't have such a use case, you can ignore this resource entirely.

<Note type="info">
  A subscription can belong to at most one group at a time. A group can hold up
  to 10 subscriptions.
</Note>

## Step-by-Step Group Setup

To model a household's three subscriptions as a group:

1. **Create the group.** Start with an empty subscription group. Subscriptions are added separately.
2. **Add the subscriptions.** Send all three in a single call, or in smaller batches if your workflow prefers.
3. **Remove a subscription if it leaves the household.** The subscription continues independently and can later be added to a different group.

Each change emits an event you can listen for. See [Events](#events).

## Building the Group

### 1. Create the Group

[Create a subscription group][create-a-subscription-group] in the project. The group is created empty.

<CodeGroup title="Create a subscription group">

```shell
curl --request "POST" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionGroups" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json"
```

</CodeGroup>

The response contains the new, empty group:

<CodeGroup title="A newly created subscription group">

```json
{
  "object": "subscriptionGroup",
  "id": "sgr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
  "subscriptions": [],
  "createdAt": "2021-01-21T19:32:13Z"
}
```

</CodeGroup>

### 2. Add Subscriptions to the Group

[Add subscriptions to the group][add-subscriptions-to-a-group] by sending their IDs in a single request. You can include between 1 and 10 subscriptions per call.

<CodeGroup title="Add subscriptions to a group">

```shell
curl --request "POST" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionGroups/${GROUP_ID}/addSubscriptions" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "subscriptions": [
      "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "sub_0SNlurA049MEWV3V0q7gjQbM4EVo",
      "sub_0SNlurA049MEWV4iJ3vGZ4kT7Cqs"
    ]
  }'
```

</CodeGroup>

The response returns the group with its current subscriptions:

<CodeGroup title="A subscription group with three subscriptions">

```json
{
  "object": "subscriptionGroup",
  "id": "sgr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
  "subscriptions": [
    "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "sub_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "sub_0SNlurA049MEWV4iJ3vGZ4kT7Cqs"
  ],
  "createdAt": "2021-01-21T19:32:13Z"
}
```

</CodeGroup>

<Note type="info">
  The call is atomic. If any subscription in the request cannot be added, none
  are added and the group is left unchanged.
</Note>

When the call fails with `422 Unprocessable Entity`, the response identifies each offending subscription in the `details` array, with a machine-readable `code` you can branch on:

<CodeGroup title="A 422 response when one subscription is already in another group">

```json
{
  "object": "error",
  "type": "invalid",
  "message": "One or more subscriptions could not be added to the group.",
  "details": [
    {
      "object": "propertyErrorDetail",
      "property": "subscriptions",
      "code": "subscriptionAlreadyInGroup",
      "message": "Subscription sub_0SNlurA049MEWV3V0q7gjQbM4EVo is already in another group."
    }
  ]
}
```

</CodeGroup>

Possible codes are `subscriptionNotFound`, `subscriptionDeleted`, and `subscriptionAlreadyInGroup`. Adding more subscriptions than the per-group limit also returns `422`. If you have a use case that needs larger groups, reach out to [support@gigs.com][gigs-support].

### 3. Remove Subscriptions from the Group

If subscriptions should no longer belong to the group, [remove them from the group][remove-subscriptions-from-a-group]. The subscriptions themselves are not modified. They continue independently and can be added to a different group later.

<CodeGroup title="Remove subscriptions from a group">

```shell
curl --request "POST" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionGroups/${GROUP_ID}/removeSubscriptions" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "subscriptions": [
      "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
    ]
  }'
```

</CodeGroup>

The response returns the group with the remaining subscriptions:

<CodeGroup title="The group after one subscription has been removed">

```json
{
  "object": "subscriptionGroup",
  "id": "sgr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
  "subscriptions": [
    "sub_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "sub_0SNlurA049MEWV4iJ3vGZ4kT7Cqs"
  ],
  "createdAt": "2021-01-21T19:32:13Z"
}
```

</CodeGroup>

As with add, the call is atomic. If any listed subscription does not belong to the group, none are removed and the response names the offenders with `subscriptionNotInGroup` (or `subscriptionNotFound` if the subscription itself doesn't exist).

## Finding Groups

To list every group in the project, or to find which group a given subscription belongs to, use the [list endpoint][list-subscription-groups]. Pass one or more subscription IDs (comma-separated) to the `subscription` query parameter to filter.

<CodeGroup title="List subscription groups filtered by subscription">

```shell
curl --request "GET" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionGroups?subscription=sub_0SNlurA049MEWV3V0q7gjQbM4EVo,sub_0SNlurA049MEWV4iJ3vGZ4kT7Cqs" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"
```

</CodeGroup>

The response is a paginated list of groups that match the filter:

<CodeGroup title="A list of subscription groups">

```json
{
  "object": "list",
  "items": [
    {
      "object": "subscriptionGroup",
      "id": "sgr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
      "subscriptions": [
        "sub_0SNlurA049MEWV3V0q7gjQbM4EVo",
        "sub_0SNlurA049MEWV4iJ3vGZ4kT7Cqs"
      ],
      "createdAt": "2021-01-21T19:32:13Z"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}
```

</CodeGroup>

You can also [retrieve a single group][retrieve-a-subscription-group] by its ID when you already know it.

## Deleting a Group

When the relationship no longer applies (the household disbands, a customer cancels the family plan), [delete the group][delete-a-subscription-group]. The subscriptions inside are **not** deleted or modified; they simply continue as they were, detached from the group.

<CodeGroup title="Delete a subscription group">

```shell
curl --request "DELETE" \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionGroups/${GROUP_ID}" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"
```

</CodeGroup>

The response returns the deleted group with the subscriptions it contained at the time of deletion, so you can record which subscriptions were affected:

<CodeGroup title="A deleted subscription group">

```json
{
  "object": "subscriptionGroup",
  "id": "sgr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
  "subscriptions": [
    "sub_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "sub_0SNlurA049MEWV4iJ3vGZ4kT7Cqs"
  ],
  "createdAt": "2021-01-21T19:32:13Z"
}
```

</CodeGroup>

<Note type="info">
  Deleting a group is permanent. The group ID cannot be reused. If you need to
  rebuild the same relationship, create a new group and add the subscriptions
  to it.
</Note>

## Events

Subscription group changes emit events that you can subscribe to via [webhooks][events-and-webhooks]. Use these to keep your own systems in sync without polling the API.

| Event                                          | When it fires                                                                                |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [`com.gigs.subscriptionGroup.created`][created] | A new subscription group has been created.                                                   |
| [`com.gigs.subscriptionGroup.updated`][updated] | Subscriptions have been added to or removed from the group. One event per call.              |
| [`com.gigs.subscriptionGroup.deleted`][deleted] | A subscription group has been deleted. The payload includes the subscriptions it contained. |

Each event payload contains the full [subscription group][subscription-group-schema] object. For `created` and `updated`, this reflects the state after the change. For `deleted`, this reflects the state at the time of deletion, with the subscriptions the group contained still listed.

See [Events and Webhooks][events-and-webhooks] for details on configuring an endpoint and verifying incoming messages.

[subscriptions]: /core/subscriptions
[create-a-subscription-group]: /core/subscription-groups#create-a-subscription-group
[list-subscription-groups]: /core/subscription-groups#list-all-subscription-groups
[retrieve-a-subscription-group]: /core/subscription-groups#retrieve-a-subscription-group
[delete-a-subscription-group]: /core/subscription-groups#delete-a-subscription-group
[add-subscriptions-to-a-group]: /core/subscription-groups#add-subscriptions-to-a-subscription-group
[remove-subscriptions-from-a-group]: /core/subscription-groups#remove-subscriptions-from-a-subscription-group
[subscription-group-schema]: /core/schemas/subscriptionGroup
[events-and-webhooks]: /docs/core/events/events-webhooks
[created]: /events/schemas/com.gigs.subscriptionGroup.created
[updated]: /events/schemas/com.gigs.subscriptionGroup.updated
[deleted]: /events/schemas/com.gigs.subscriptionGroup.deleted
[gigs-support]: mailto:support@gigs.com