# Subscription Groups ## The SubscriptionGroup object A subscription group represents a collection of subscriptions. > #### Preview > > This schema is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `subscriptionGroup`. | | `id` | string | Yes | Unique identifier for the subscription group. | | `subscriptions` | string[] | Yes | List of subscription identifiers that belong to this group. | | `createdAt` | string | Yes | Time when the subscription group was created. | --- ## List all subscription groups `GET /projects/{project}/subscriptionGroups` Returns a list of subscription groups. The subscription groups returned are sorted by creation date, with the most recently created subscription groups appearing first. > **Info** > #### Preview > > This endpoint is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | ### Query Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `subscription` | string[] | No | A comma-separated list of subscriptions by which to filter the subscription groups. | | `after` | string | No | A cursor for use in pagination. The `after` parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned. | | `before` | string | No | A cursor for use in pagination. The `before` parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned. | | `limit` | integer | No | The limit of items to be returned in the list, between 0 and 200. | ### Responses #### 200 — Returns a dictionary with an items property that contains an array of subscription groups. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `list`. | | `items` | object[] | Yes | List of objects of type `subscriptionGroup`. | | `moreItemsAfter` | string,null | Yes | A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items. | | `moreItemsBefore` | string,null | Yes | A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items. | --- ## Create a subscription group `POST /projects/{project}/subscriptionGroups` Creates a new subscription group in the specified project. > **Info** > #### Preview > > This endpoint is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | ### Responses #### 201 — Returns the newly created subscription group. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `subscriptionGroup`. | | `id` | string | Yes | Unique identifier for the subscription group. | | `subscriptions` | string[] | Yes | List of subscription identifiers that belong to this group. | | `createdAt` | string | Yes | Time when the subscription group was created. | --- ## Retrieve a subscription group `GET /projects/{project}/subscriptionGroups/{subscriptionGroup}` Retrieves the details of an existing subscription group. > **Info** > #### Preview > > This endpoint is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `subscriptionGroup` | string | Yes | The unique identifier for the subscription group. | ### Responses #### 200 — Returns the subscription group object if it exists. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `subscriptionGroup`. | | `id` | string | Yes | Unique identifier for the subscription group. | | `subscriptions` | string[] | Yes | List of subscription identifiers that belong to this group. | | `createdAt` | string | Yes | Time when the subscription group was created. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Delete a subscription group `DELETE /projects/{project}/subscriptionGroups/{subscriptionGroup}` Deletes a subscription group. Subscriptions in the group are not deleted; they are detached from the group and continue independently. > **Info** > #### Preview > > This endpoint is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `subscriptionGroup` | string | Yes | The unique identifier for the subscription group. | ### Responses #### 200 — Returns the deleted subscription group. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `subscriptionGroup`. | | `id` | string | Yes | Unique identifier for the subscription group. | | `subscriptions` | string[] | Yes | List of subscription identifiers that belong to this group. | | `createdAt` | string | Yes | Time when the subscription group was created. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Add subscriptions to a subscription group `POST /projects/{project}/subscriptionGroups/{subscriptionGroup}/addSubscriptions` Adds one or more existing subscriptions to the specified subscription group. The operation is atomic: if any subscription cannot be added, none are added and the response identifies the offending subscriptions. > **Info** > #### Preview > > This endpoint is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. ### Body | Property | Type | Required | Description | |----------|------|----------|-------------| | `subscriptions` | string[] | Yes | Unique identifiers of the subscriptions to add to the group. All subscriptions are added atomically: if any one cannot be added, none are. | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `subscriptionGroup` | string | Yes | The unique identifier for the subscription group. | ### Responses #### 200 — Returns the updated subscription group. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `subscriptionGroup`. | | `id` | string | Yes | Unique identifier for the subscription group. | | `subscriptions` | string[] | Yes | List of subscription identifiers that belong to this group. | | `createdAt` | string | Yes | Time when the subscription group was created. | #### 403 — The authenticated user doesn't have permissions to perform the request. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | --- ## Remove subscriptions from a subscription group `POST /projects/{project}/subscriptionGroups/{subscriptionGroup}/removeSubscriptions` Removes one or more subscriptions from a subscription group. The subscriptions are not deleted and continue independently. The operation is atomic: if any subscription cannot be removed, none are removed and the response identifies the offending subscriptions. > **Info** > #### Preview > > This endpoint is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. ### Body | Property | Type | Required | Description | |----------|------|----------|-------------| | `subscriptions` | string[] | Yes | Unique identifiers of the subscriptions to remove from the group. All subscriptions are removed atomically: if any one cannot be removed, none are. | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `subscriptionGroup` | string | Yes | The unique identifier for the subscription group. | ### Responses #### 200 — Returns the updated subscription group. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `subscriptionGroup`. | | `id` | string | Yes | Unique identifier for the subscription group. | | `subscriptions` | string[] | Yes | List of subscription identifiers that belong to this group. | | `createdAt` | string | Yes | Time when the subscription group was created. | #### 403 — The authenticated user doesn't have permissions to perform the request. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 404 — The requested resource doesn't exist. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | #### 422 — The request can't be processed, often due to an invalid parameter or incompatible system state. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `error`. | | `code` | string | No | An optional machine-readable description of the error. Present for errors that could be handled programmatically. | | `details` | object[] | No | Optional array containing specific information for the current error. > #### Preview > > This property is currently in preview and might change in the future. > > We’re excited to hear your feedback and ideas. Please send an email > to [support@gigs.com](mailto:support@gigs.com) to share your thoughts. | | `documentation` | string[] | No | An optional list of URLs providing further information to resolve the error. | | `hint` | string | No | An optional explanation how to resolve the error. | | `message` | string | Yes | A human readable description of the error. | | `type` | string | Yes | The type of [error](https://developers.gigs.com/api/error-handling) returned. | ---