# Plans ## The Plan object 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. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `plan`. | | `id` | string | Yes | Unique identifier for the plan. | | `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `activationTrigger` | creation | usageStarted | Yes | Indicates when a subscription will activate. - `creation`: As soon as it is created. The user does not need to take any further action. - `usageStarted`: When the user starts using subscription allowance on their device. | | `allowances` | object | Yes | Usage allowances included in the plan - i.e. how many bytes of data, voice minutes & sms messages the user has access to. | | `coverage` | object | Yes | The geographic coverage of the plan. | | `createdAt` | string | Yes | Time when the plan was created. | | `description` | string,null | Yes | The plan's description, meant to be displayable to the users. | | `firstPeriodTrigger` | activation | creation | Yes | Indicates when a subscription's first period will start. - `creation`: As soon as the subscription is created. - `activation`: When the subscription's status transitions from `pending` to `active`. > #### 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. | | `image` | string,null | Yes | The plan's image, meant to be displayable to the users. | | `limits` | object | Yes | Usage limits for the plan - i.e. the maximum available bandwidth, fair-use data limits and throttling threshold. | | `name` | string | Yes | The plan's name, meant to be displayable to the users. | | `price` | object | Yes | The price of the plan. | | `provider` | string | Yes | The ID of the network provider supported by this plan. | | `requirements` | object | Yes | Required information that must be collected from the user in order to create a subscription with this plan. | | `simTypes` | string[] | Yes | List of SIM types supported by this plan. Can be `eSIM`, `pSIM`, or both. | | `status` | available | archived | pending | draft | Yes | | | `validity` | object | Yes | Plan validity information - i.e. subscription period length, and the minimum number of periods before the plan can be ended. | | `data` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The data allowance in bytes included in this plan. A value of `-1` indicates unlimited data. | | `dataUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the data value is always `byte`. | | `sms` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The sms allowance included in this plan. A value of `-1` indicates unlimited sms. | | `smsUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the sms value is always `message`. | | `voice` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The voice allowance included in this plan. A value of `-1` indicates unlimited voice. | | `voiceUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the voice value is always `second`. | --- ## List all plans `GET /projects/{project}/plans` Returns a list of plans. ### 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 | |------|------|----------|-------------| | `provider` | string[] | No | The network provider ID to filter the plans by. | | `simType` | string[] | No | The type of SIM card to filter the plans by. | | `status` | string[] | No | The status to filter the plans by. Only available plans are returned by default. | | `coverageCountry` | string[] | No | The ISO3166 alpha-2 country code to filter the plans 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 list of plan objects. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `list`. | | `items` | object[] | Yes | List of objects of type `plan`. | | `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. > #### 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 plan `GET /projects/{project}/plans/{plan}` Retrieve the details of an existing 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). | | `plan` | string | Yes | The unique identifier for the plan. | ### Responses #### 200 — Returns the plan if it exists. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `plan`. | | `id` | string | Yes | Unique identifier for the plan. | | `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `activationTrigger` | creation | usageStarted | Yes | Indicates when a subscription will activate. - `creation`: As soon as it is created. The user does not need to take any further action. - `usageStarted`: When the user starts using subscription allowance on their device. | | `allowances` | object | Yes | Usage allowances included in the plan - i.e. how many bytes of data, voice minutes & sms messages the user has access to. | | `coverage` | object | Yes | The geographic coverage of the plan. | | `createdAt` | string | Yes | Time when the plan was created. | | `description` | string,null | Yes | The plan's description, meant to be displayable to the users. | | `firstPeriodTrigger` | activation | creation | Yes | Indicates when a subscription's first period will start. - `creation`: As soon as the subscription is created. - `activation`: When the subscription's status transitions from `pending` to `active`. > #### 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. | | `image` | string,null | Yes | The plan's image, meant to be displayable to the users. | | `limits` | object | Yes | Usage limits for the plan - i.e. the maximum available bandwidth, fair-use data limits and throttling threshold. | | `name` | string | Yes | The plan's name, meant to be displayable to the users. | | `price` | object | Yes | The price of the plan. | | `provider` | string | Yes | The ID of the network provider supported by this plan. | | `requirements` | object | Yes | Required information that must be collected from the user in order to create a subscription with this plan. | | `simTypes` | string[] | Yes | List of SIM types supported by this plan. Can be `eSIM`, `pSIM`, or both. | | `status` | available | archived | pending | draft | Yes | | | `validity` | object | Yes | Plan validity information - i.e. subscription period length, and the minimum number of periods before the plan can be ended. | | `data` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The data allowance in bytes included in this plan. A value of `-1` indicates unlimited data. | | `dataUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the data value is always `byte`. | | `sms` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The sms allowance included in this plan. A value of `-1` indicates unlimited sms. | | `smsUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the sms value is always `message`. | | `voice` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The voice allowance included in this plan. A value of `-1` indicates unlimited voice. | | `voiceUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the voice value is always `second`. | #### 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. | #### 501 — The type of request is not supported. | 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. | --- ## Update a plan `PATCH /projects/{project}/plans/{plan}` Updates the specified plan by setting the values of the parameters passed. ### Body | Property | Type | Required | Description | |----------|------|----------|-------------| | `name` | string | No | The plan's name, meant to be displayable to the user. | | `description` | string,null | No | The plan's description, meant to be displayable to the user. | | `image` | string,null | No | The plan's image, meant to be displayable to the user. | | `metadata` | object | No | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `plan` | string | Yes | The unique identifier for the plan. | ### Responses #### 200 — Returns the updated plan. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `plan`. | | `id` | string | Yes | Unique identifier for the plan. | | `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `activationTrigger` | creation | usageStarted | Yes | Indicates when a subscription will activate. - `creation`: As soon as it is created. The user does not need to take any further action. - `usageStarted`: When the user starts using subscription allowance on their device. | | `allowances` | object | Yes | Usage allowances included in the plan - i.e. how many bytes of data, voice minutes & sms messages the user has access to. | | `coverage` | object | Yes | The geographic coverage of the plan. | | `createdAt` | string | Yes | Time when the plan was created. | | `description` | string,null | Yes | The plan's description, meant to be displayable to the users. | | `firstPeriodTrigger` | activation | creation | Yes | Indicates when a subscription's first period will start. - `creation`: As soon as the subscription is created. - `activation`: When the subscription's status transitions from `pending` to `active`. > #### 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. | | `image` | string,null | Yes | The plan's image, meant to be displayable to the users. | | `limits` | object | Yes | Usage limits for the plan - i.e. the maximum available bandwidth, fair-use data limits and throttling threshold. | | `name` | string | Yes | The plan's name, meant to be displayable to the users. | | `price` | object | Yes | The price of the plan. | | `provider` | string | Yes | The ID of the network provider supported by this plan. | | `requirements` | object | Yes | Required information that must be collected from the user in order to create a subscription with this plan. | | `simTypes` | string[] | Yes | List of SIM types supported by this plan. Can be `eSIM`, `pSIM`, or both. | | `status` | available | archived | pending | draft | Yes | | | `validity` | object | Yes | Plan validity information - i.e. subscription period length, and the minimum number of periods before the plan can be ended. | | `data` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The data allowance in bytes included in this plan. A value of `-1` indicates unlimited data. | | `dataUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the data value is always `byte`. | | `sms` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The sms allowance included in this plan. A value of `-1` indicates unlimited sms. | | `smsUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the sms value is always `message`. | | `voice` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The voice allowance included in this plan. A value of `-1` indicates unlimited voice. | | `voiceUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the voice value is always `second`. | #### 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. | --- ## Archive a plan `POST /projects/{project}/plans/{plan}/archive` Set the status of a plan to archived. An archived plan can not be used to create new subscriptions. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `plan` | string | Yes | The unique identifier for the plan. | ### Responses #### 200 — Returns the archived plan. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `plan`. | | `id` | string | Yes | Unique identifier for the plan. | | `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `activationTrigger` | creation | usageStarted | Yes | Indicates when a subscription will activate. - `creation`: As soon as it is created. The user does not need to take any further action. - `usageStarted`: When the user starts using subscription allowance on their device. | | `allowances` | object | Yes | Usage allowances included in the plan - i.e. how many bytes of data, voice minutes & sms messages the user has access to. | | `coverage` | object | Yes | The geographic coverage of the plan. | | `createdAt` | string | Yes | Time when the plan was created. | | `description` | string,null | Yes | The plan's description, meant to be displayable to the users. | | `firstPeriodTrigger` | activation | creation | Yes | Indicates when a subscription's first period will start. - `creation`: As soon as the subscription is created. - `activation`: When the subscription's status transitions from `pending` to `active`. > #### 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. | | `image` | string,null | Yes | The plan's image, meant to be displayable to the users. | | `limits` | object | Yes | Usage limits for the plan - i.e. the maximum available bandwidth, fair-use data limits and throttling threshold. | | `name` | string | Yes | The plan's name, meant to be displayable to the users. | | `price` | object | Yes | The price of the plan. | | `provider` | string | Yes | The ID of the network provider supported by this plan. | | `requirements` | object | Yes | Required information that must be collected from the user in order to create a subscription with this plan. | | `simTypes` | string[] | Yes | List of SIM types supported by this plan. Can be `eSIM`, `pSIM`, or both. | | `status` | available | archived | pending | draft | Yes | | | `validity` | object | Yes | Plan validity information - i.e. subscription period length, and the minimum number of periods before the plan can be ended. | | `data` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The data allowance in bytes included in this plan. A value of `-1` indicates unlimited data. | | `dataUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the data value is always `byte`. | | `sms` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The sms allowance included in this plan. A value of `-1` indicates unlimited sms. | | `smsUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the sms value is always `message`. | | `voice` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The voice allowance included in this plan. A value of `-1` indicates unlimited voice. | | `voiceUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the voice value is always `second`. | #### 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. | --- ## Publish a plan `POST /projects/{project}/plans/{plan}/publish` Set the status of a plan to available. Available plans can be used to create new subscriptions. ### Path Parameters | Name | Type | Required | Description | |------|------|----------|-------------| | `project` | string | Yes | The unique identifier for the [project](https://developers.gigs.com/core/projects#the-project-resource). | | `plan` | string | Yes | The unique identifier for the plan. | ### Responses #### 200 — Returns the available plan. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `plan`. | | `id` | string | Yes | Unique identifier for the plan. | | `metadata` | object | Yes | A set of key-value pairs, to store [metadata](https://developers.gigs.com/docs/core/metadata) related to the resource. | | `activationTrigger` | creation | usageStarted | Yes | Indicates when a subscription will activate. - `creation`: As soon as it is created. The user does not need to take any further action. - `usageStarted`: When the user starts using subscription allowance on their device. | | `allowances` | object | Yes | Usage allowances included in the plan - i.e. how many bytes of data, voice minutes & sms messages the user has access to. | | `coverage` | object | Yes | The geographic coverage of the plan. | | `createdAt` | string | Yes | Time when the plan was created. | | `description` | string,null | Yes | The plan's description, meant to be displayable to the users. | | `firstPeriodTrigger` | activation | creation | Yes | Indicates when a subscription's first period will start. - `creation`: As soon as the subscription is created. - `activation`: When the subscription's status transitions from `pending` to `active`. > #### 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. | | `image` | string,null | Yes | The plan's image, meant to be displayable to the users. | | `limits` | object | Yes | Usage limits for the plan - i.e. the maximum available bandwidth, fair-use data limits and throttling threshold. | | `name` | string | Yes | The plan's name, meant to be displayable to the users. | | `price` | object | Yes | The price of the plan. | | `provider` | string | Yes | The ID of the network provider supported by this plan. | | `requirements` | object | Yes | Required information that must be collected from the user in order to create a subscription with this plan. | | `simTypes` | string[] | Yes | List of SIM types supported by this plan. Can be `eSIM`, `pSIM`, or both. | | `status` | available | archived | pending | draft | Yes | | | `validity` | object | Yes | Plan validity information - i.e. subscription period length, and the minimum number of periods before the plan can be ended. | | `data` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The data allowance in bytes included in this plan. A value of `-1` indicates unlimited data. | | `dataUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the data value is always `byte`. | | `sms` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The sms allowance included in this plan. A value of `-1` indicates unlimited sms. | | `smsUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the sms value is always `message`. | | `voice` | integer | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The voice allowance included in this plan. A value of `-1` indicates unlimited voice. | | `voiceUnit` | string | Yes | > #### Deprecated > > This property is deprecated and will be removed in the future. > Use `allowances` instead. The unit of the voice value is always `second`. | #### 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. | --- ## Search for Plans `POST /projects/{project}/plans/search` Searches for plans matching the given parameters. ### Body | Property | Type | Required | Description | |----------|------|----------|-------------| | `status` | string[] | No | The status to filter plans by. | | `simType` | array,null | No | The type of the SIM card to filter the plans by. | | `provider` | array,null | No | The network provider ID to filter the plans by. | | `coverageCountry` | array,null | No | The ISO3166 alpha-2 country code to filter the plans by. | | `compatibleWith` | object | No | Compatibility requirements for the plans. Only plans compatible with all requirements are returned. At least one requirement must be specified. | ### 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 Plans. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `list`. | | `items` | object[] | Yes | List of objects of type `plan`. | | `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. > #### 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. | #### 503 — The network provider required to perform the request is currently unavailable. Please check [documentation](https://developers.gigs.com/api/error-handling#common-errors) for details on how to handle this error. | 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. | --- ## List all plan documents `GET /projects/{project}/planDocuments` Returns a list of documents related to the given plan. The documents returned are sorted by creation date, with the most recently created documents 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 | |------|------|----------|-------------| | `plan` | string | No | The unique identifier for the plan to be filtered by. | ### Responses #### 200 — Returns a list of document objects. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `list`. | | `items` | object[] | Yes | List of objects of type `planDocument`. | | `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. | #### 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. | --- ## Retrieve a plan document `GET /projects/{project}/planDocuments/{planDocument}` Retrieves the details of an existing document for a given 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). | | `planDocument` | string | Yes | The unique identifier for the document. | ### Responses #### 200 — Returns the plan if it exists and is owned by the plan. | Property | Type | Required | Description | |----------|------|----------|-------------| | `object` | string | Yes | Type of object is always `planDocument`. | | `id` | string | Yes | Unique identifier for the given document. | | `createdAt` | string | Yes | The time the document was created. | | `language` | null,string | Yes | The language of the document. The values follow the BCP 47 standard. That means, for instance, that a region can be specified in addition to the language. > #### 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. | | `name` | string | Yes | The name of the document. | | `plan` | string | Yes | Unique identifier for the plan associated to this document. | | `type` | string | Yes | The MIME type for the given document. | | `url` | string | Yes | The URL at which the document can be retrieved. | #### 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. | ---