# Subscription Add-ons

## The SubscriptionAddon object

Subscription add-ons are features or top-ups that extend the functionality offered to the end user through their subscription, as defined by the associated add-on.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscriptionAddon`. |
| `id` | string | Yes | Unique identifier for the subscription add-on. |
| `activatedAt` | string,null | Yes | Time when the subscription add-on was activated. |
| `addon` | object | Yes | The add-on associated to the subscription add-on. |
| `canceledAt` | string,null | Yes | Time when the subscription add-on was canceled. |
| `createdAt` | string | Yes | Time when the subscription add-on was created. |
| `currentPeriod` | mixed | Yes | Current subscription add-on period. Only present for active subscription add-ons. |
| `endedAt` | string,null | Yes | Time when the subscription add-on was ended. The value is `null` if the subscription add-on is not ended. |
| `status` | pending | initiated | active | ended | Yes | The current status of the subscription add-on. |
| `subscription` | string | Yes | Unique identifier of the subscription the add-on applies to. |
| `user` | string | Yes | Unique identifier of the user the subscription add-on belongs to. |

---

## List all subscription add-ons

`GET /projects/{project}/subscriptionAddons`

Returns a list of subscription add-ons. The subscription add-ons returned are sorted by creation date, with the most recently created subscription add-ons appearing first.

### 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 |
|------|------|----------|-------------|
| `addon` | string | No | The unique identifier for the add-on to be filtered by. |
| `status` | string[] | No | A comma-separated list of statuses to filter the subscription add-ons by. |
| `subscription` | string | No | The unique identifier for the subscription to be filtered by. |
| `user` | string | No | The unique identifier for the user to be filtered by. |
| `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 add-ons.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `list`. |
| `items` | object[] | Yes | List of objects of type `subscriptionAddon`. |
| `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. |

#### 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.  <!-- theme: info --> > #### 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. |

---

## Create a subscription add-on

`POST /projects/{project}/subscriptionAddons`

Creates a new subscription add-on for an existing subscription in the specified project.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `addon` | string | Yes | Unique identifier of the add-on. |
| `subscription` | string | Yes | Unique identifier of the subscription the add-on applies to. |

### 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 add-on.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscriptionAddon`. |
| `id` | string | Yes | Unique identifier for the subscription add-on. |
| `activatedAt` | string,null | Yes | Time when the subscription add-on was activated. |
| `addon` | object | Yes | The add-on associated to the subscription add-on. |
| `canceledAt` | string,null | Yes | Time when the subscription add-on was canceled. |
| `createdAt` | string | Yes | Time when the subscription add-on was created. |
| `currentPeriod` | mixed | Yes | Current subscription add-on period. Only present for active subscription add-ons. |
| `endedAt` | string,null | Yes | Time when the subscription add-on was ended. The value is `null` if the subscription add-on is not ended. |
| `status` | pending | initiated | active | ended | Yes | The current status of the subscription add-on. |
| `subscription` | string | Yes | Unique identifier of the subscription the add-on applies to. |
| `user` | string | Yes | Unique identifier of the user the subscription add-on belongs to. |

#### 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.  <!-- theme: info --> > #### 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. |

---

## Retrieve a subscription add-on

`GET /projects/{project}/subscriptionAddons/{subscriptionAddon}`

Retrieve the details of an existing subscription add-on which the authenticated user is authorized to view.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `subscriptionAddon` | string | Yes | The unique identifier for the subscription add-on. |

### Responses

#### 200 — Returns the subscription add-on if it exists.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscriptionAddon`. |
| `id` | string | Yes | Unique identifier for the subscription add-on. |
| `activatedAt` | string,null | Yes | Time when the subscription add-on was activated. |
| `addon` | object | Yes | The add-on associated to the subscription add-on. |
| `canceledAt` | string,null | Yes | Time when the subscription add-on was canceled. |
| `createdAt` | string | Yes | Time when the subscription add-on was created. |
| `currentPeriod` | mixed | Yes | Current subscription add-on period. Only present for active subscription add-ons. |
| `endedAt` | string,null | Yes | Time when the subscription add-on was ended. The value is `null` if the subscription add-on is not ended. |
| `status` | pending | initiated | active | ended | Yes | The current status of the subscription add-on. |
| `subscription` | string | Yes | Unique identifier of the subscription the add-on applies to. |
| `user` | string | Yes | Unique identifier of the user the subscription add-on belongs to. |

#### 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.  <!-- theme: info --> > #### 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. |

---

## End a subscription add-on

`DELETE /projects/{project}/subscriptionAddons/{subscriptionAddon}`

Ends a subscription add-on immediately. Subscription add-ons that are already ended cannot be ended again.

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). |
| `subscriptionAddon` | string | Yes | The unique identifier for the subscription add-on. |

### Responses

#### 200 — Returns the ended subscription add-on.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscriptionAddon`. |
| `id` | string | Yes | Unique identifier for the subscription add-on. |
| `activatedAt` | string,null | Yes | Time when the subscription add-on was activated. |
| `addon` | object | Yes | The add-on associated to the subscription add-on. |
| `canceledAt` | string,null | Yes | Time when the subscription add-on was canceled. |
| `createdAt` | string | Yes | Time when the subscription add-on was created. |
| `currentPeriod` | mixed | Yes | Current subscription add-on period. Only present for active subscription add-ons. |
| `endedAt` | string,null | Yes | Time when the subscription add-on was ended. The value is `null` if the subscription add-on is not ended. |
| `status` | pending | initiated | active | ended | Yes | The current status of the subscription add-on. |
| `subscription` | string | Yes | Unique identifier of the subscription the add-on applies to. |
| `user` | string | Yes | Unique identifier of the user the subscription add-on belongs to. |

#### 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.  <!-- theme: info --> > #### 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.  <!-- theme: info --> > #### 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. |

---