# Subscription Changes

## The SubscriptionChange object

Any change to a user’s subscription, such as swapping a SIM, or upgrading or downgrading a subscription.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscriptionChange`. |
| `id` | string | Yes | Unique identifier for the subscription change. |
| `appliedAt` | string,null | Yes | Time when the subscription change was applied. |
| `createdAt` | string | Yes | Time when the subscription change was created. |
| `failureCode` | string,null | Yes | An error code indicating the reason for a failed subscription change. |
| `plan` | mixed | Yes | The plan to which the subscription should be changed. |
| `requestedChange` | object | Yes | Object with the requested changes. |
| `scheduledAt` | string,null | Yes | Approximate time when the change should take place. This is typically set for changes scheduled at renewal. For changes that take effect immediately (when `requestedChange.when` is `"now"`), this may be null. |
| `sim` | mixed | Yes | The SIM to which the subscription should be changed. |
| `status` | pending | initiated | applied | failed | deleted | Yes | The current status of the subscription change. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription change invoice has not yet been paid.  |
| `subscription` | string,null | Yes | Unique identifier of the subscription to be changed. |

---

## List all subscription changes

`GET /projects/{project}/subscriptionChanges`

Returns a list of subscription changes. The subscription changes returned are sorted by creation date, with the most recently created subscription changes 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 |
|------|------|----------|-------------|
| `status` | string[] | No | A comma-separated list of statuses to filter the subscription changes 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 changes.

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

`POST /projects/{project}/subscriptionChanges`

Creates a new subscription change for an existing subscription in the specified project.

Note that plan changes cannot be created within the cutoff period of 1 hour before the subscription period ends. In the UK, this cutoff period is extended to 13 hours but only for changes scheduled at renewal.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `plan` | string,null | No | Unique identifier of the target plan, to which the subscription should be changed. |
| `sim` | string,null | No | Unique identifier of the target SIM, to which the subscription should be changed. Can also be set to "auto", in which case an eSIM will be automatically allocated. |
| `subscription` | string | Yes | Unique identifier of the subscription to be changed. |
| `when` | now | renewal | No | When the change should take effect. If set to `"now"`, the change will take effect immediately. If set to `"renewal"`, the change will instead take effect at the next subscription renewal date. Plan changes can always happen on `"renewal"`, but only selected network providers allow `"now"` changes. SIM changes can only happen `"now"`. |

### 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 change.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscriptionChange`. |
| `id` | string | Yes | Unique identifier for the subscription change. |
| `appliedAt` | string,null | Yes | Time when the subscription change was applied. |
| `createdAt` | string | Yes | Time when the subscription change was created. |
| `failureCode` | string,null | Yes | An error code indicating the reason for a failed subscription change. |
| `plan` | mixed | Yes | The plan to which the subscription should be changed. |
| `requestedChange` | object | Yes | Object with the requested changes. |
| `scheduledAt` | string,null | Yes | Approximate time when the change should take place. This is typically set for changes scheduled at renewal. For changes that take effect immediately (when `requestedChange.when` is `"now"`), this may be null. |
| `sim` | mixed | Yes | The SIM to which the subscription should be changed. |
| `status` | pending | initiated | applied | failed | deleted | Yes | The current status of the subscription change. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription change invoice has not yet been paid.  |
| `subscription` | string,null | Yes | Unique identifier of the subscription to be changed. |

#### 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 change

`GET /projects/{project}/subscriptionChanges/{subscriptionChange}`

Retrieve the details of an existing subscription change 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). |
| `subscriptionChange` | string | Yes | The unique identifier for the subscription change. |

### Responses

#### 200 — Returns the subscription change if it exists.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscriptionChange`. |
| `id` | string | Yes | Unique identifier for the subscription change. |
| `appliedAt` | string,null | Yes | Time when the subscription change was applied. |
| `createdAt` | string | Yes | Time when the subscription change was created. |
| `failureCode` | string,null | Yes | An error code indicating the reason for a failed subscription change. |
| `plan` | mixed | Yes | The plan to which the subscription should be changed. |
| `requestedChange` | object | Yes | Object with the requested changes. |
| `scheduledAt` | string,null | Yes | Approximate time when the change should take place. This is typically set for changes scheduled at renewal. For changes that take effect immediately (when `requestedChange.when` is `"now"`), this may be null. |
| `sim` | mixed | Yes | The SIM to which the subscription should be changed. |
| `status` | pending | initiated | applied | failed | deleted | Yes | The current status of the subscription change. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription change invoice has not yet been paid.  |
| `subscription` | string,null | Yes | Unique identifier of the subscription to be changed. |

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

---

## Delete a subscription change

`DELETE /projects/{project}/subscriptionChanges/{subscriptionChange}`

Retrieve the details of an existing subscription change and delete it. Only subscription changes that have not been applied can be deleted.

### Path Parameters

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

### Responses

#### 200 — Returns the subscription change after a successful deletion.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscriptionChange`. |
| `id` | string | Yes | Unique identifier for the subscription change. |
| `appliedAt` | string,null | Yes | Time when the subscription change was applied. |
| `createdAt` | string | Yes | Time when the subscription change was created. |
| `failureCode` | string,null | Yes | An error code indicating the reason for a failed subscription change. |
| `plan` | mixed | Yes | The plan to which the subscription should be changed. |
| `requestedChange` | object | Yes | Object with the requested changes. |
| `scheduledAt` | string,null | Yes | Approximate time when the change should take place. This is typically set for changes scheduled at renewal. For changes that take effect immediately (when `requestedChange.when` is `"now"`), this may be null. |
| `sim` | mixed | Yes | The SIM to which the subscription should be changed. |
| `status` | pending | initiated | applied | failed | deleted | Yes | The current status of the subscription change. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription change invoice has not yet been paid.  |
| `subscription` | string,null | Yes | Unique identifier of the subscription to be changed. |

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

---