Create and manage subscription groups

This guide walks you through using subscription groups to model related 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.

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.

Building the Group

1. Create the Group

Create a subscription group in the project. The group is created empty.

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"

The response contains the new, empty group:

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

2. Add Subscriptions to the Group

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

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"
    ]
  }'

The response returns the group with its current subscriptions:

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

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:

{
  "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."
    }
  ]
}

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.

3. Remove Subscriptions from the Group

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

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"
    ]
  }'

The response returns the group with the remaining subscriptions:

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

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. Pass one or more subscription IDs (comma-separated) to the subscription query parameter to filter.

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}"

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

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

You can also retrieve a single 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. The subscriptions inside are not deleted or modified; they simply continue as they were, detached from the group.

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

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

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

Events

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

Each event payload contains the full subscription group 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 for details on configuring an endpoint and verifying incoming messages.