# Subscriptions

## The Subscription object

Subscriptions are tied to a user and are created once a user has a plan and SIM. This allows connectivity for their device and SIM.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscription`. |
| `id` | string | Yes | Unique identifier for the subscription. |
| `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `activatedAt` | string,null | Yes | Time when the subscription was activated. |
| `billing` | object,null | Yes | Billing details for the subscription. Present when Billing is enabled on your project. |
| `canceledAt` | string,null | Yes | Time when the subscription was canceled. |
| `cancellationDetails` | object,null | Yes | Details about the cancellation of the subscription. |
| `createdAt` | string | Yes | Time when the subscription was created. |
| `currentPeriod` | mixed | Yes | Current subscription period. Only present for active subscriptions. |
| `earliestEndAt` | string,null | Yes | Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."  |
| `endedAt` | string,null | Yes | Time when the subscription will end or has ended. This field is populated in different scenarios: - When a subscription is canceled, this represents the future date when it will be terminated - When a subscription has already ended, this represents the past date when it was terminated - For active subscriptions, this field is null  |
| `firstUsageAt` | string,null | Yes | Time when the subscription was first used. |
| `lastPorting` | mixed | Yes | Last porting (if any) related with the subscription. |
| `phoneNumber` | string,null | Yes | The phone number attached to the SIM in E.164 string_format. Only available for voice plans. |
| `plan` | object | Yes | Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users. |
| `restrictedAt` | string,null | Yes | Time when the subscription was restricted. |
| `restrictionDetails` | object,null | Yes | Details about the restriction applied to the subscription. Present when the subscription is restricted. |
| `sim` | mixed | Yes |  |
| `status` | pending | initiated | active | restricted | ended | Yes | The current status of the subscription. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.  |
| `user` | object | Yes | Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions. |
| `userAddress` | string,null | Yes | Current [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) identifier (if any) related with the subscription. |
| `porting` | mixed | Yes | First porting requested by the user. Refer to `lastPorting` to get the latest porting information. |

---

## List all subscriptions

`GET /projects/{project}/subscriptions`

Returns a list of subscriptions. The subscriptions returned are sorted by creation date, with the most recently created subscriptions 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 |
|------|------|----------|-------------|
| `user` | string | No | The unique identifier for the user to be filtered by. |
| `plan` | string | No | The unique identifier for the plan to be filtered by. |
| `sim` | string | No | The unique identifier for the sim to be filtered by. |
| `status` | string[] | No | A comma-separated list of statuses to filter the subscriptions by. Only pending and active subscriptions are returned by default. |
| `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 list of subscription objects.

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

`POST /projects/{project}/subscriptions`

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

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `billing` | object,null | No | Configuration for this specific subscription billing. Only available when the Billing API is enabled. |
| `device` | string,null | No | The unique identifier for the existing [device](https://developers.gigs.com/core/devices#the-device-resource) to be linked with the passed SIM. Some network providers require this field (or `deviceModel`) for activation. If the exact IMEI of the device is known, then it is recommended to create a device and specify its ID here. See `deviceModel` if the device IMEI is not known. At most one of `device` and `deviceModel` may be specified. Trying to link a pSIM to a second device will cause an error. |
| `deviceModel` | string,null | No | The unique identifier for the [device model](https://developers.gigs.com/core/devices#retrieve-a-device-model) to be linked with the passed SIM. Some network providers require this field (or `device`) for activation. If the device IMEI is not known, but the device model is known, this property can be used in place of `device`. At most one of `device` and `deviceModel` may be specified. |
| `metadata` | object | No | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `fromSubscription` | string,null | No | The unique identifier for an existing ended [subscription](https://developers.gigs.com/core/subscriptions#the-subscription-resource) to base the new subscription on. The referenced subscription must have status `ended` and its SIM must still be usable (not retired, not ported out, and for eSIMs, the profile must not be deleted). When provided, the user, plan, SIM, billing settings, and applicable discounts are copied from the referenced subscription. Cannot be combined with `user`, `plan`, `sim`, `porting`, `device`, `deviceModel`, `userAddress`, or `billing`. |
| `plan` | string,null | No | The unique identifier for the existing [plan](https://developers.gigs.com/core/plans#the-plan-resource) to be used for the subscription. Required if `fromSubscription` is not provided. |
| `porting` | string,null | No | The unique identifier for the existing draft [porting](https://developers.gigs.com/core/portings#the-porting-resource) to be used for the subscription. |
| `sim` | string,null | No | The unique identifier for the existing [SIM](https://developers.gigs.com/core/sims#the-sim-resource) to be used for the subscription. In combination with an eSIM plan, it can be passed as `auto` to request a new eSIM, or `preferLastUsed` to reuse the user's most recently used SIM from an ended subscription. `preferLastUsed` falls back to `auto` if no eligible SIM is found, which only works for eSIM-capable plans; for plans requiring a physical SIM, subscription creation will fail if no eligible SIM is found. |
| `userAddress` | string,null | No | The unique identifier for the existing [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) to be used for the subscription. Only needed if the plan requires an address. |
| `user` | string,null | No | The unique identifier for the existing [user](https://developers.gigs.com/core/users#the-user-resource) to which the subscription will be assigned. Required if `fromSubscription` is not provided. |

### 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 and supporting objects.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscription`. |
| `id` | string | Yes | Unique identifier for the subscription. |
| `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `activatedAt` | string,null | Yes | Time when the subscription was activated. |
| `billing` | object,null | Yes | Billing details for the subscription. Present when Billing is enabled on your project. |
| `canceledAt` | string,null | Yes | Time when the subscription was canceled. |
| `cancellationDetails` | object,null | Yes | Details about the cancellation of the subscription. |
| `createdAt` | string | Yes | Time when the subscription was created. |
| `currentPeriod` | mixed | Yes | Current subscription period. Only present for active subscriptions. |
| `earliestEndAt` | string,null | Yes | Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."  |
| `endedAt` | string,null | Yes | Time when the subscription will end or has ended. This field is populated in different scenarios: - When a subscription is canceled, this represents the future date when it will be terminated - When a subscription has already ended, this represents the past date when it was terminated - For active subscriptions, this field is null  |
| `firstUsageAt` | string,null | Yes | Time when the subscription was first used. |
| `lastPorting` | mixed | Yes | Last porting (if any) related with the subscription. |
| `phoneNumber` | string,null | Yes | The phone number attached to the SIM in E.164 string_format. Only available for voice plans. |
| `plan` | object | Yes | Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users. |
| `restrictedAt` | string,null | Yes | Time when the subscription was restricted. |
| `restrictionDetails` | object,null | Yes | Details about the restriction applied to the subscription. Present when the subscription is restricted. |
| `sim` | mixed | Yes |  |
| `status` | pending | initiated | active | restricted | ended | Yes | The current status of the subscription. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.  |
| `user` | object | Yes | Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions. |
| `userAddress` | string,null | Yes | Current [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) identifier (if any) related with the subscription. |
| `porting` | mixed | Yes | First porting requested by the user. Refer to `lastPorting` to get the latest porting information. |

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

`GET /projects/{project}/subscriptions/{subscription}`

Retrieves the details of an existing subscription. You need only supply the unique subscription identifier that was returned upon purchasing a plan.

### Path Parameters

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

### Responses

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscription`. |
| `id` | string | Yes | Unique identifier for the subscription. |
| `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `activatedAt` | string,null | Yes | Time when the subscription was activated. |
| `billing` | object,null | Yes | Billing details for the subscription. Present when Billing is enabled on your project. |
| `canceledAt` | string,null | Yes | Time when the subscription was canceled. |
| `cancellationDetails` | object,null | Yes | Details about the cancellation of the subscription. |
| `createdAt` | string | Yes | Time when the subscription was created. |
| `currentPeriod` | mixed | Yes | Current subscription period. Only present for active subscriptions. |
| `earliestEndAt` | string,null | Yes | Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."  |
| `endedAt` | string,null | Yes | Time when the subscription will end or has ended. This field is populated in different scenarios: - When a subscription is canceled, this represents the future date when it will be terminated - When a subscription has already ended, this represents the past date when it was terminated - For active subscriptions, this field is null  |
| `firstUsageAt` | string,null | Yes | Time when the subscription was first used. |
| `lastPorting` | mixed | Yes | Last porting (if any) related with the subscription. |
| `phoneNumber` | string,null | Yes | The phone number attached to the SIM in E.164 string_format. Only available for voice plans. |
| `plan` | object | Yes | Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users. |
| `restrictedAt` | string,null | Yes | Time when the subscription was restricted. |
| `restrictionDetails` | object,null | Yes | Details about the restriction applied to the subscription. Present when the subscription is restricted. |
| `sim` | mixed | Yes |  |
| `status` | pending | initiated | active | restricted | ended | Yes | The current status of the subscription. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.  |
| `user` | object | Yes | Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions. |
| `userAddress` | string,null | Yes | Current [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) identifier (if any) related with the subscription. |
| `porting` | mixed | Yes | First porting requested by the user. Refer to `lastPorting` to get the latest porting information. |

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

---

## Update a subscription

`PATCH /projects/{project}/subscriptions/{subscription}`

Updates the specified subscription by setting the values of the parameters passed.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `metadata` | object | No | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `billing` | object | No | Configuration for this specific subscription billing. Only available when the Billing API is enabled. |
| `userAddress` | string | No | The unique identifier for an existing [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) to be used for the subscription.  Once a subscription has a user address it cannot be removed, only updated to a different user address. Only available for active subscriptions.   <!-- 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.  |

### Path Parameters

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

### Responses

#### 200 — Returns the updated subscription.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscription`. |
| `id` | string | Yes | Unique identifier for the subscription. |
| `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `activatedAt` | string,null | Yes | Time when the subscription was activated. |
| `billing` | object,null | Yes | Billing details for the subscription. Present when Billing is enabled on your project. |
| `canceledAt` | string,null | Yes | Time when the subscription was canceled. |
| `cancellationDetails` | object,null | Yes | Details about the cancellation of the subscription. |
| `createdAt` | string | Yes | Time when the subscription was created. |
| `currentPeriod` | mixed | Yes | Current subscription period. Only present for active subscriptions. |
| `earliestEndAt` | string,null | Yes | Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."  |
| `endedAt` | string,null | Yes | Time when the subscription will end or has ended. This field is populated in different scenarios: - When a subscription is canceled, this represents the future date when it will be terminated - When a subscription has already ended, this represents the past date when it was terminated - For active subscriptions, this field is null  |
| `firstUsageAt` | string,null | Yes | Time when the subscription was first used. |
| `lastPorting` | mixed | Yes | Last porting (if any) related with the subscription. |
| `phoneNumber` | string,null | Yes | The phone number attached to the SIM in E.164 string_format. Only available for voice plans. |
| `plan` | object | Yes | Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users. |
| `restrictedAt` | string,null | Yes | Time when the subscription was restricted. |
| `restrictionDetails` | object,null | Yes | Details about the restriction applied to the subscription. Present when the subscription is restricted. |
| `sim` | mixed | Yes |  |
| `status` | pending | initiated | active | restricted | ended | Yes | The current status of the subscription. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.  |
| `user` | object | Yes | Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions. |
| `userAddress` | string,null | Yes | Current [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) identifier (if any) related with the subscription. |
| `porting` | mixed | Yes | First porting requested by the user. Refer to `lastPorting` to get the latest porting information. |

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

---

## Cancel an active subscription

`POST /projects/{project}/subscriptions/{subscription}/cancel`

Cancels a subscription. A canceled subscription still has connectivity,
but is no longer renewed.

A canceled subscription is ended at the end of its contract term (as
defined by its plan) or, if it is already past the term, at the end of
its current period.

Note that the status of a subscription that has been canceled will
remain `active` until the `endedAt` date is reached, at which point it
will be updated to `ended`.

A subscription can only be canceled up to one hour before its renewal.
If it is canceled after this point, it will be ended after the
following period.

A canceled subscription that hasn't yet ended can be [resumed](https://developers.gigs.com/core/subscriptions#resume-a-canceled-subscription).

Note: Cancellation is rejected when the subscription might never
activate on its own, e.g. the porting has not been submitted to
the provider yet. Use the
[end endpoint](https://developers.gigs.com/core/subscriptions#end-a-subscription)
instead to immediately terminate the subscription.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `cancellationDetails` | object,null | No | Details about the cancellation of the subscription. |

### Path Parameters

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

### Responses

#### 200 — Returns the subscription after a successful cancellation.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscription`. |
| `id` | string | Yes | Unique identifier for the subscription. |
| `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `activatedAt` | string,null | Yes | Time when the subscription was activated. |
| `billing` | object,null | Yes | Billing details for the subscription. Present when Billing is enabled on your project. |
| `canceledAt` | string,null | Yes | Time when the subscription was canceled. |
| `cancellationDetails` | object,null | Yes | Details about the cancellation of the subscription. |
| `createdAt` | string | Yes | Time when the subscription was created. |
| `currentPeriod` | mixed | Yes | Current subscription period. Only present for active subscriptions. |
| `earliestEndAt` | string,null | Yes | Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."  |
| `endedAt` | string,null | Yes | Time when the subscription will end or has ended. This field is populated in different scenarios: - When a subscription is canceled, this represents the future date when it will be terminated - When a subscription has already ended, this represents the past date when it was terminated - For active subscriptions, this field is null  |
| `firstUsageAt` | string,null | Yes | Time when the subscription was first used. |
| `lastPorting` | mixed | Yes | Last porting (if any) related with the subscription. |
| `phoneNumber` | string,null | Yes | The phone number attached to the SIM in E.164 string_format. Only available for voice plans. |
| `plan` | object | Yes | Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users. |
| `restrictedAt` | string,null | Yes | Time when the subscription was restricted. |
| `restrictionDetails` | object,null | Yes | Details about the restriction applied to the subscription. Present when the subscription is restricted. |
| `sim` | mixed | Yes |  |
| `status` | pending | initiated | active | restricted | ended | Yes | The current status of the subscription. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.  |
| `user` | object | Yes | Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions. |
| `userAddress` | string,null | Yes | Current [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) identifier (if any) related with the subscription. |
| `porting` | mixed | Yes | First porting requested by the user. Refer to `lastPorting` to get the latest porting information. |

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

---

## Port a phone number into a subscription

`POST /projects/{project}/subscriptions/{subscription}/portIn`

Port a phone number into an active subscription.

The subscription remains activated and connected to the old phone number until the porting is completed.
After the porting is completed, the phone number of this subscription is updated.

> **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 |
|----------|------|----------|-------------|
| `porting` | string | Yes | The unique identifier for the existing draft [porting](https://developers.gigs.com/core/portings#the-porting-resource) to be requested for this subscription. |

### Path Parameters

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

### Responses

#### 200 — Returns the subscription after successfully requesting the port in.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscription`. |
| `id` | string | Yes | Unique identifier for the subscription. |
| `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `activatedAt` | string,null | Yes | Time when the subscription was activated. |
| `billing` | object,null | Yes | Billing details for the subscription. Present when Billing is enabled on your project. |
| `canceledAt` | string,null | Yes | Time when the subscription was canceled. |
| `cancellationDetails` | object,null | Yes | Details about the cancellation of the subscription. |
| `createdAt` | string | Yes | Time when the subscription was created. |
| `currentPeriod` | mixed | Yes | Current subscription period. Only present for active subscriptions. |
| `earliestEndAt` | string,null | Yes | Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."  |
| `endedAt` | string,null | Yes | Time when the subscription will end or has ended. This field is populated in different scenarios: - When a subscription is canceled, this represents the future date when it will be terminated - When a subscription has already ended, this represents the past date when it was terminated - For active subscriptions, this field is null  |
| `firstUsageAt` | string,null | Yes | Time when the subscription was first used. |
| `lastPorting` | mixed | Yes | Last porting (if any) related with the subscription. |
| `phoneNumber` | string,null | Yes | The phone number attached to the SIM in E.164 string_format. Only available for voice plans. |
| `plan` | object | Yes | Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users. |
| `restrictedAt` | string,null | Yes | Time when the subscription was restricted. |
| `restrictionDetails` | object,null | Yes | Details about the restriction applied to the subscription. Present when the subscription is restricted. |
| `sim` | mixed | Yes |  |
| `status` | pending | initiated | active | restricted | ended | Yes | The current status of the subscription. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.  |
| `user` | object | Yes | Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions. |
| `userAddress` | string,null | Yes | Current [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) identifier (if any) related with the subscription. |
| `porting` | mixed | Yes | First porting requested by the user. Refer to `lastPorting` to get the latest porting information. |

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

---

## End a subscription immediately

`POST /projects/{project}/subscriptions/{subscription}/end`

Ends a subscriptions immediately given its identifier.

Additionally, you can pass in optional cancellation details in the
request body, which will be used to provide more context on why the
subscription was ended.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `cancellationDetails` | object,null | No | Details about the cancellation of the subscription. |

### Path Parameters

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

### Responses

#### 200 — Returns the ended subscription after a successful termination.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscription`. |
| `id` | string | Yes | Unique identifier for the subscription. |
| `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `activatedAt` | string,null | Yes | Time when the subscription was activated. |
| `billing` | object,null | Yes | Billing details for the subscription. Present when Billing is enabled on your project. |
| `canceledAt` | string,null | Yes | Time when the subscription was canceled. |
| `cancellationDetails` | object,null | Yes | Details about the cancellation of the subscription. |
| `createdAt` | string | Yes | Time when the subscription was created. |
| `currentPeriod` | mixed | Yes | Current subscription period. Only present for active subscriptions. |
| `earliestEndAt` | string,null | Yes | Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."  |
| `endedAt` | string,null | Yes | Time when the subscription will end or has ended. This field is populated in different scenarios: - When a subscription is canceled, this represents the future date when it will be terminated - When a subscription has already ended, this represents the past date when it was terminated - For active subscriptions, this field is null  |
| `firstUsageAt` | string,null | Yes | Time when the subscription was first used. |
| `lastPorting` | mixed | Yes | Last porting (if any) related with the subscription. |
| `phoneNumber` | string,null | Yes | The phone number attached to the SIM in E.164 string_format. Only available for voice plans. |
| `plan` | object | Yes | Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users. |
| `restrictedAt` | string,null | Yes | Time when the subscription was restricted. |
| `restrictionDetails` | object,null | Yes | Details about the restriction applied to the subscription. Present when the subscription is restricted. |
| `sim` | mixed | Yes |  |
| `status` | pending | initiated | active | restricted | ended | Yes | The current status of the subscription. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.  |
| `user` | object | Yes | Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions. |
| `userAddress` | string,null | Yes | Current [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) identifier (if any) related with the subscription. |
| `porting` | mixed | Yes | First porting requested by the user. Refer to `lastPorting` to get the latest porting information. |

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

---

## Resume a canceled subscription

`POST /projects/{project}/subscriptions/{subscription}/resume`

Removes the cancellation and end times of the subscription. The subscription will continue to auto-renew until canceled 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). |
| `subscription` | string | Yes | The unique identifier for the subscription. |

### Responses

#### 200 — Returns the resumed subscription.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `object` | string | Yes | Type of object is always `subscription`. |
| `id` | string | Yes | Unique identifier for the subscription. |
| `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. |
| `activatedAt` | string,null | Yes | Time when the subscription was activated. |
| `billing` | object,null | Yes | Billing details for the subscription. Present when Billing is enabled on your project. |
| `canceledAt` | string,null | Yes | Time when the subscription was canceled. |
| `cancellationDetails` | object,null | Yes | Details about the cancellation of the subscription. |
| `createdAt` | string | Yes | Time when the subscription was created. |
| `currentPeriod` | mixed | Yes | Current subscription period. Only present for active subscriptions. |
| `earliestEndAt` | string,null | Yes | Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."  |
| `endedAt` | string,null | Yes | Time when the subscription will end or has ended. This field is populated in different scenarios: - When a subscription is canceled, this represents the future date when it will be terminated - When a subscription has already ended, this represents the past date when it was terminated - For active subscriptions, this field is null  |
| `firstUsageAt` | string,null | Yes | Time when the subscription was first used. |
| `lastPorting` | mixed | Yes | Last porting (if any) related with the subscription. |
| `phoneNumber` | string,null | Yes | The phone number attached to the SIM in E.164 string_format. Only available for voice plans. |
| `plan` | object | Yes | Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users. |
| `restrictedAt` | string,null | Yes | Time when the subscription was restricted. |
| `restrictionDetails` | object,null | Yes | Details about the restriction applied to the subscription. Present when the subscription is restricted. |
| `sim` | mixed | Yes |  |
| `status` | pending | initiated | active | restricted | ended | Yes | The current status of the subscription. Note that the `initiated` status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.  |
| `user` | object | Yes | Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions. |
| `userAddress` | string,null | Yes | Current [user address](https://developers.gigs.com/core/user-addresses#the-user-address-resource) identifier (if any) related with the subscription. |
| `porting` | mixed | Yes | First porting requested by the user. Refer to `lastPorting` to get the latest porting information. |

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

---

## Search for subscriptions

`POST /projects/{project}/subscriptions/search`

Searches for existing subscriptions matching the given parameters.

### Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `phoneNumber` | string | Yes | The E.164-formatted phone number associated with the subscription. |

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

#### 200 — Returns a list schema response with all found subscriptions.

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

---