Subscriptions

The Subscription resource

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.

Properties

Name
object
Type
string
Description
Type of object is always subscription.
Name
id
Type
string
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
PREVIEW
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
currentPeriod
Type
nullable object
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: 2021-01-21T19:32:13Z
Name
end
Type
string
required
Description
End of the period.
Example: 2021-02-20T19:38:34Z
Name
phoneNumber
Type
nullable string
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: +19591234567
Name
plan
Type
object
Description
Name
object
Type
string
required
Description
Type of object is always plan.
Name
id
Type
string
required
Description
Unique identifier for the plan.
Example: pln_0SNlurA049MEWV3V0q7gjQbM4EVo
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
allowances
Type
object
required
Description
The allowances included in the plan.
Name
coverage
Type
object
required
Description
The geographic coverage of the plan.
Name
data
Type
integer
DEPRECATED
required
Description
The data allowance in bytes included in this plan. A value of -1 indicates unlimited data.
Example: 10000000000
Name
dataUnit
Type
string
DEPRECATED
required
Description
The unit of the data value is always byte.
Name
description
Type
nullable string
required
Description
The plan's description, meant to be displayable to the users.
Example: A data plan you will love! Operates in most countries of the world.
Name
image
Type
nullable string
required
Description
The plan's image, meant to be displayable to the users.
Example: https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
Name
limits
Type
object
required
Description
The limitations of the plan.
Name
name
Type
string
required
Description
The plan's name, meant to be displayable to the users.
Example: Gigs Global
Name
price
Type
object
required
Description
The price of the plan.
Name
provider
Type
string
required
Description
The ID of the network provider supported by this plan.
Example: p5
Name
requirements
Type
object
required
Description
Name
simTypes
Type
array
required
Description
List of SIM types supported by this plan. Can be eSIM, pSIM, or both.
Example: eSIM,pSIM
Name
sms
Type
integer
DEPRECATED
required
Description
The sms allowance included in this plan. A value of -1 indicates unlimited sms.
Example: 100
Name
smsUnit
Type
string
DEPRECATED
required
Description
The unit of the sms value is always message.
Name
status
Type
string
required
Description
Allowed values: available, archived, pending, draft
Name
validity
Type
object
required
Description
The validity of the plan.
Name
voice
Type
integer
DEPRECATED
required
Description
The voice allowance included in this plan. A value of -1 indicates unlimited voice.
Example: 30000
Name
voiceUnit
Type
string
DEPRECATED
required
Description
The unit of the voice value is always second.
Name
createdAt
Type
string
required
Description
Time when the plan was created.
Example: 2021-01-21T19:38:34Z
Name
porting
Type
nullable object
Description
Current porting (if any) related with the subscription.
Name
object
Type
string
required
Description
Type of object is always porting.
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: 123456789
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: 2017-07-21
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: portingPhoneNumberPortProtected
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: The phone number has port protection on the provider.
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: Seinfeld
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: +19591234567
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: p9
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
Name
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
user
Type
string
required
Description
Unique identifier for the user this porting is for.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: 2021-01-21T19:39:53Z
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: 2021-01-21T19:36:57Z
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: 2021-01-21T19:12:28Z
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z
Name
sim
Type
nullable object
Description
Name
object
Type
string
required
Description
Type of object is always sim.
Name
id
Type
string
required
Description
Unique identifier for the SIM.
Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
iccid
Type
string
required
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: 89883070000007537119
Name
provider
Type
string
required
Description
The ID of the network provider of the SIM.
Example: p9
Name
status
Type
string
required
Description
The status of the SIM. Can be active or inactive.
Allowed values: inactive, active, retired
Name
type
Type
string
required
Description
The type of the SIM. Can be eSIM or pSIM.
Allowed values: eSIM, pSIM
Name
createdAt
Type
string
required
Description
Time when the SIM was created.
Example: 2021-01-21T19:38:34Z
Name
status
Type
string
Description
The current status of the subscription.
Allowed values: pending, active, ended
Name
user
Type
object
Description
Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: 2017-07-21
Name
email
Type
string
required
Description
The primary email address of the user.
Example: jerry@example.com
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: Jerry Seinfeld
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: en-US
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z
Name
activatedAt
Type
nullable string
Description
Time when the subscription was activated.
Example: 2021-01-21T19:38:34Z
Name
canceledAt
Type
nullable string
Description
Time when the subscription was canceled.
Example: 2021-01-29T13:22:51Z
Name
createdAt
Type
string
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
Name
earliestEndAt
Type
nullable string
PREVIEW
Description
Earliest time at which the subscription can currently be ended. It depends on the minimum period of the plan. Only present if the subscription has not yet been ended.
Example: 2021-02-20T19:38:34Z
Name
endedAt
Type
nullable string
Description
Time when the subscription was ended.
Example: 2021-02-20T19:38:34Z
Name
firstUsageAt
Type
nullable string
Description
Time when the subscription was first used.
Example: 2021-01-21T19:38:34Z

Response

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T"
    },
    "donorProviderApproval": true,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T"
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

POST/projects/{project}/subscriptions/{id}/cancel

Cancel an active subscription

If when is set to "now" then the subscription will be ended immediately.

Otherwise, the subscription will end on the earliestEndAt date. This is generally at the conclusion of the current period (currentPeriod.end). If the subscription's plan has a minimum required number of periods (plan.validity.minimumPeriods), and that minimum has not yet been reached, this date will instead fall at the end of the minimum periods.

We begin the renewal process for a subscription one hour before the currentPeriod.end. At this point the earliestEndAt will change to the end of the following period. As such, canceling a subscription less than one hour before the period end will schedule the end of the subscription for after the following period.

Body

Name
when
Type
string
DEPRECATED
Description
When to end the subscription.

now: End the subscription immediately.

periodEnd: End the subscription at the earliest possible time, considering the length of the billing period and any minimum required periods specified in the plan.
Example: now
Default: periodEnd
Allowed values: now, periodEnd
Name
cancellationDetails
Type
nullable object
Description
Details about the cancellation of the subscription.
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
string
required
Description
Reason for the user to cancel the subscription.
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: gigs
Name
id
Type
string
required
Description
The unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi

Response Schemas

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: 2021-01-21T19:32:13Z
Name
end
Type
string
required
Description
End of the period.
Example: 2021-02-20T19:38:34Z
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: +19591234567
Name
plan
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always plan.
Name
id
Type
string
required
Description
Unique identifier for the plan.
Example: pln_0SNlurA049MEWV3V0q7gjQbM4EVo
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
allowances
Type
object
required
Description
The allowances included in the plan.
Name
coverage
Type
object
required
Description
The geographic coverage of the plan.
Name
data
Type
integer
DEPRECATED
required
Description
The data allowance in bytes included in this plan. A value of -1 indicates unlimited data.
Example: 10000000000
Name
dataUnit
Type
string
DEPRECATED
required
Description
The unit of the data value is always byte.
Name
description
Type
nullable string
required
Description
The plan's description, meant to be displayable to the users.
Example: A data plan you will love! Operates in most countries of the world.
Name
image
Type
nullable string
required
Description
The plan's image, meant to be displayable to the users.
Example: https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
Name
limits
Type
object
required
Description
The limitations of the plan.
Name
name
Type
string
required
Description
The plan's name, meant to be displayable to the users.
Example: Gigs Global
Name
price
Type
object
required
Description
The price of the plan.
Name
provider
Type
string
required
Description
The ID of the network provider supported by this plan.
Example: p5
Name
requirements
Type
object
required
Description
Name
simTypes
Type
array
required
Description
List of SIM types supported by this plan. Can be eSIM, pSIM, or both.
Example: eSIM,pSIM
Name
sms
Type
integer
DEPRECATED
required
Description
The sms allowance included in this plan. A value of -1 indicates unlimited sms.
Example: 100
Name
smsUnit
Type
string
DEPRECATED
required
Description
The unit of the sms value is always message.
Name
status
Type
string
required
Description
Allowed values: available, archived, pending, draft
Name
validity
Type
object
required
Description
The validity of the plan.
Name
voice
Type
integer
DEPRECATED
required
Description
The voice allowance included in this plan. A value of -1 indicates unlimited voice.
Example: 30000
Name
voiceUnit
Type
string
DEPRECATED
required
Description
The unit of the voice value is always second.
Name
createdAt
Type
string
required
Description
Time when the plan was created.
Example: 2021-01-21T19:38:34Z
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
object
Type
string
required
Description
Type of object is always porting.
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: 123456789
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: 2017-07-21
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: portingPhoneNumberPortProtected
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: The phone number has port protection on the provider.
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: Seinfeld
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: +19591234567
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: p9
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
Name
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
user
Type
string
required
Description
Unique identifier for the user this porting is for.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: 2021-01-21T19:39:53Z
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: 2021-01-21T19:36:57Z
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: 2021-01-21T19:12:28Z
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z
Name
sim
Type
nullable object
required
Description
Name
object
Type
string
required
Description
Type of object is always sim.
Name
id
Type
string
required
Description
Unique identifier for the SIM.
Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
iccid
Type
string
required
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: 89883070000007537119
Name
provider
Type
string
required
Description
The ID of the network provider of the SIM.
Example: p9
Name
status
Type
string
required
Description
The status of the SIM. Can be active or inactive.
Allowed values: inactive, active, retired
Name
type
Type
string
required
Description
The type of the SIM. Can be eSIM or pSIM.
Allowed values: eSIM, pSIM
Name
createdAt
Type
string
required
Description
Time when the SIM was created.
Example: 2021-01-21T19:38:34Z
Name
status
Type
string
required
Description
The current status of the subscription.
Allowed values: pending, active, ended
Name
user
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: 2017-07-21
Name
email
Type
string
required
Description
The primary email address of the user.
Example: jerry@example.com
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: Jerry Seinfeld
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: en-US
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: 2021-01-21T19:38:34Z
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: 2021-01-29T13:22:51Z
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
Name
earliestEndAt
Type
nullable string
PREVIEW
required
Description
Earliest time at which the subscription can currently be ended. It depends on the minimum period of the plan. Only present if the subscription has not yet been ended.
Example: 2021-02-20T19:38:34Z
Name
endedAt
Type
nullable string
required
Description
Time when the subscription was ended.
Example: 2021-02-20T19:38:34Z
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: 2021-01-21T19:38:34Z

Request

POST

/projects/{project}/subscriptions/{id}/cancel

curl https://api.gigs.com/projects/{project}/subscriptions/{id}/cancel \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"when\":\"now\",\"cancellationDetails\":{\"userReason\":\"connectivityIssues\"}}"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

POST/projects/{project}/subscriptions/{id}/end

End an active subscription

Ends an active plan subscription immediately. You only need to supply the unique subscription identifier which was generated on subscription creation.

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

Body

Name
cancellationDetails
Type
nullable object
Description
Details about the cancellation of the subscription.
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
string
required
Description
Reason for the user to cancel the subscription.
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: gigs
Name
id
Type
string
required
Description
The unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi

Response Schemas

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: 2021-01-21T19:32:13Z
Name
end
Type
string
required
Description
End of the period.
Example: 2021-02-20T19:38:34Z
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: +19591234567
Name
plan
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always plan.
Name
id
Type
string
required
Description
Unique identifier for the plan.
Example: pln_0SNlurA049MEWV3V0q7gjQbM4EVo
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
allowances
Type
object
required
Description
The allowances included in the plan.
Name
coverage
Type
object
required
Description
The geographic coverage of the plan.
Name
data
Type
integer
DEPRECATED
required
Description
The data allowance in bytes included in this plan. A value of -1 indicates unlimited data.
Example: 10000000000
Name
dataUnit
Type
string
DEPRECATED
required
Description
The unit of the data value is always byte.
Name
description
Type
nullable string
required
Description
The plan's description, meant to be displayable to the users.
Example: A data plan you will love! Operates in most countries of the world.
Name
image
Type
nullable string
required
Description
The plan's image, meant to be displayable to the users.
Example: https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
Name
limits
Type
object
required
Description
The limitations of the plan.
Name
name
Type
string
required
Description
The plan's name, meant to be displayable to the users.
Example: Gigs Global
Name
price
Type
object
required
Description
The price of the plan.
Name
provider
Type
string
required
Description
The ID of the network provider supported by this plan.
Example: p5
Name
requirements
Type
object
required
Description
Name
simTypes
Type
array
required
Description
List of SIM types supported by this plan. Can be eSIM, pSIM, or both.
Example: eSIM,pSIM
Name
sms
Type
integer
DEPRECATED
required
Description
The sms allowance included in this plan. A value of -1 indicates unlimited sms.
Example: 100
Name
smsUnit
Type
string
DEPRECATED
required
Description
The unit of the sms value is always message.
Name
status
Type
string
required
Description
Allowed values: available, archived, pending, draft
Name
validity
Type
object
required
Description
The validity of the plan.
Name
voice
Type
integer
DEPRECATED
required
Description
The voice allowance included in this plan. A value of -1 indicates unlimited voice.
Example: 30000
Name
voiceUnit
Type
string
DEPRECATED
required
Description
The unit of the voice value is always second.
Name
createdAt
Type
string
required
Description
Time when the plan was created.
Example: 2021-01-21T19:38:34Z
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
object
Type
string
required
Description
Type of object is always porting.
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: 123456789
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: 2017-07-21
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: portingPhoneNumberPortProtected
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: The phone number has port protection on the provider.
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: Seinfeld
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: +19591234567
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: p9
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
Name
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
user
Type
string
required
Description
Unique identifier for the user this porting is for.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: 2021-01-21T19:39:53Z
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: 2021-01-21T19:36:57Z
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: 2021-01-21T19:12:28Z
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z
Name
sim
Type
nullable object
required
Description
Name
object
Type
string
required
Description
Type of object is always sim.
Name
id
Type
string
required
Description
Unique identifier for the SIM.
Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
iccid
Type
string
required
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: 89883070000007537119
Name
provider
Type
string
required
Description
The ID of the network provider of the SIM.
Example: p9
Name
status
Type
string
required
Description
The status of the SIM. Can be active or inactive.
Allowed values: inactive, active, retired
Name
type
Type
string
required
Description
The type of the SIM. Can be eSIM or pSIM.
Allowed values: eSIM, pSIM
Name
createdAt
Type
string
required
Description
Time when the SIM was created.
Example: 2021-01-21T19:38:34Z
Name
status
Type
string
required
Description
The current status of the subscription.
Allowed values: pending, active, ended
Name
user
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: 2017-07-21
Name
email
Type
string
required
Description
The primary email address of the user.
Example: jerry@example.com
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: Jerry Seinfeld
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: en-US
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: 2021-01-21T19:38:34Z
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: 2021-01-29T13:22:51Z
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
Name
earliestEndAt
Type
nullable string
PREVIEW
required
Description
Earliest time at which the subscription can currently be ended. It depends on the minimum period of the plan. Only present if the subscription has not yet been ended.
Example: 2021-02-20T19:38:34Z
Name
endedAt
Type
nullable string
required
Description
Time when the subscription was ended.
Example: 2021-02-20T19:38:34Z
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: 2021-01-21T19:38:34Z

Request

POST

/projects/{project}/subscriptions/{id}/end

curl https://api.gigs.com/projects/{project}/subscriptions/{id}/end \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"cancellationDetails\":{\"userReason\":\"connectivityIssues\"}}"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

GET/projects/{project}/subscriptions/{id}

Retrieve a 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
project
Type
string
required
Description
The unique identifier for the project.
Example: gigs
Name
id
Type
string
required
Description
The unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi

Response Schemas

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: 2021-01-21T19:32:13Z
Name
end
Type
string
required
Description
End of the period.
Example: 2021-02-20T19:38:34Z
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: +19591234567
Name
plan
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always plan.
Name
id
Type
string
required
Description
Unique identifier for the plan.
Example: pln_0SNlurA049MEWV3V0q7gjQbM4EVo
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
allowances
Type
object
required
Description
The allowances included in the plan.
Name
coverage
Type
object
required
Description
The geographic coverage of the plan.
Name
data
Type
integer
DEPRECATED
required
Description
The data allowance in bytes included in this plan. A value of -1 indicates unlimited data.
Example: 10000000000
Name
dataUnit
Type
string
DEPRECATED
required
Description
The unit of the data value is always byte.
Name
description
Type
nullable string
required
Description
The plan's description, meant to be displayable to the users.
Example: A data plan you will love! Operates in most countries of the world.
Name
image
Type
nullable string
required
Description
The plan's image, meant to be displayable to the users.
Example: https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
Name
limits
Type
object
required
Description
The limitations of the plan.
Name
name
Type
string
required
Description
The plan's name, meant to be displayable to the users.
Example: Gigs Global
Name
price
Type
object
required
Description
The price of the plan.
Name
provider
Type
string
required
Description
The ID of the network provider supported by this plan.
Example: p5
Name
requirements
Type
object
required
Description
Name
simTypes
Type
array
required
Description
List of SIM types supported by this plan. Can be eSIM, pSIM, or both.
Example: eSIM,pSIM
Name
sms
Type
integer
DEPRECATED
required
Description
The sms allowance included in this plan. A value of -1 indicates unlimited sms.
Example: 100
Name
smsUnit
Type
string
DEPRECATED
required
Description
The unit of the sms value is always message.
Name
status
Type
string
required
Description
Allowed values: available, archived, pending, draft
Name
validity
Type
object
required
Description
The validity of the plan.
Name
voice
Type
integer
DEPRECATED
required
Description
The voice allowance included in this plan. A value of -1 indicates unlimited voice.
Example: 30000
Name
voiceUnit
Type
string
DEPRECATED
required
Description
The unit of the voice value is always second.
Name
createdAt
Type
string
required
Description
Time when the plan was created.
Example: 2021-01-21T19:38:34Z
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
object
Type
string
required
Description
Type of object is always porting.
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: 123456789
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: 2017-07-21
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: portingPhoneNumberPortProtected
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: The phone number has port protection on the provider.
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: Seinfeld
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: +19591234567
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: p9
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
Name
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
user
Type
string
required
Description
Unique identifier for the user this porting is for.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: 2021-01-21T19:39:53Z
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: 2021-01-21T19:36:57Z
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: 2021-01-21T19:12:28Z
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z
Name
sim
Type
nullable object
required
Description
Name
object
Type
string
required
Description
Type of object is always sim.
Name
id
Type
string
required
Description
Unique identifier for the SIM.
Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
iccid
Type
string
required
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: 89883070000007537119
Name
provider
Type
string
required
Description
The ID of the network provider of the SIM.
Example: p9
Name
status
Type
string
required
Description
The status of the SIM. Can be active or inactive.
Allowed values: inactive, active, retired
Name
type
Type
string
required
Description
The type of the SIM. Can be eSIM or pSIM.
Allowed values: eSIM, pSIM
Name
createdAt
Type
string
required
Description
Time when the SIM was created.
Example: 2021-01-21T19:38:34Z
Name
status
Type
string
required
Description
The current status of the subscription.
Allowed values: pending, active, ended
Name
user
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: 2017-07-21
Name
email
Type
string
required
Description
The primary email address of the user.
Example: jerry@example.com
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: Jerry Seinfeld
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: en-US
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: 2021-01-21T19:38:34Z
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: 2021-01-29T13:22:51Z
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
Name
earliestEndAt
Type
nullable string
PREVIEW
required
Description
Earliest time at which the subscription can currently be ended. It depends on the minimum period of the plan. Only present if the subscription has not yet been ended.
Example: 2021-02-20T19:38:34Z
Name
endedAt
Type
nullable string
required
Description
Time when the subscription was ended.
Example: 2021-02-20T19:38:34Z
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: 2021-01-21T19:38:34Z

Request

GET

/projects/{project}/subscriptions/{id}

curl https://api.gigs.com/projects/{project}/subscriptions/{id} \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

DELETE/projects/{project}/subscriptions/{id}

End an active subscription

Ends an active plan subscription immediately. You only need to supply the unique subscription identifier which was generated on subscription creation.

Deprecated

This endpoint is deprecated and will be removed in the future. Please use the cancel endpoint instead.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: gigs
Name
id
Type
string
required
Description
The unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi

Response Schemas

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: 2021-01-21T19:32:13Z
Name
end
Type
string
required
Description
End of the period.
Example: 2021-02-20T19:38:34Z
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: +19591234567
Name
plan
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always plan.
Name
id
Type
string
required
Description
Unique identifier for the plan.
Example: pln_0SNlurA049MEWV3V0q7gjQbM4EVo
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
allowances
Type
object
required
Description
The allowances included in the plan.
Name
coverage
Type
object
required
Description
The geographic coverage of the plan.
Name
data
Type
integer
DEPRECATED
required
Description
The data allowance in bytes included in this plan. A value of -1 indicates unlimited data.
Example: 10000000000
Name
dataUnit
Type
string
DEPRECATED
required
Description
The unit of the data value is always byte.
Name
description
Type
nullable string
required
Description
The plan's description, meant to be displayable to the users.
Example: A data plan you will love! Operates in most countries of the world.
Name
image
Type
nullable string
required
Description
The plan's image, meant to be displayable to the users.
Example: https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
Name
limits
Type
object
required
Description
The limitations of the plan.
Name
name
Type
string
required
Description
The plan's name, meant to be displayable to the users.
Example: Gigs Global
Name
price
Type
object
required
Description
The price of the plan.
Name
provider
Type
string
required
Description
The ID of the network provider supported by this plan.
Example: p5
Name
requirements
Type
object
required
Description
Name
simTypes
Type
array
required
Description
List of SIM types supported by this plan. Can be eSIM, pSIM, or both.
Example: eSIM,pSIM
Name
sms
Type
integer
DEPRECATED
required
Description
The sms allowance included in this plan. A value of -1 indicates unlimited sms.
Example: 100
Name
smsUnit
Type
string
DEPRECATED
required
Description
The unit of the sms value is always message.
Name
status
Type
string
required
Description
Allowed values: available, archived, pending, draft
Name
validity
Type
object
required
Description
The validity of the plan.
Name
voice
Type
integer
DEPRECATED
required
Description
The voice allowance included in this plan. A value of -1 indicates unlimited voice.
Example: 30000
Name
voiceUnit
Type
string
DEPRECATED
required
Description
The unit of the voice value is always second.
Name
createdAt
Type
string
required
Description
Time when the plan was created.
Example: 2021-01-21T19:38:34Z
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
object
Type
string
required
Description
Type of object is always porting.
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: 123456789
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: 2017-07-21
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: portingPhoneNumberPortProtected
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: The phone number has port protection on the provider.
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: Seinfeld
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: +19591234567
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: p9
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
Name
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
user
Type
string
required
Description
Unique identifier for the user this porting is for.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: 2021-01-21T19:39:53Z
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: 2021-01-21T19:36:57Z
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: 2021-01-21T19:12:28Z
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z
Name
sim
Type
nullable object
required
Description
Name
object
Type
string
required
Description
Type of object is always sim.
Name
id
Type
string
required
Description
Unique identifier for the SIM.
Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
iccid
Type
string
required
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: 89883070000007537119
Name
provider
Type
string
required
Description
The ID of the network provider of the SIM.
Example: p9
Name
status
Type
string
required
Description
The status of the SIM. Can be active or inactive.
Allowed values: inactive, active, retired
Name
type
Type
string
required
Description
The type of the SIM. Can be eSIM or pSIM.
Allowed values: eSIM, pSIM
Name
createdAt
Type
string
required
Description
Time when the SIM was created.
Example: 2021-01-21T19:38:34Z
Name
status
Type
string
required
Description
The current status of the subscription.
Allowed values: pending, active, ended
Name
user
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: 2017-07-21
Name
email
Type
string
required
Description
The primary email address of the user.
Example: jerry@example.com
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: Jerry Seinfeld
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: en-US
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: 2021-01-21T19:38:34Z
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: 2021-01-29T13:22:51Z
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
Name
earliestEndAt
Type
nullable string
PREVIEW
required
Description
Earliest time at which the subscription can currently be ended. It depends on the minimum period of the plan. Only present if the subscription has not yet been ended.
Example: 2021-02-20T19:38:34Z
Name
endedAt
Type
nullable string
required
Description
Time when the subscription was ended.
Example: 2021-02-20T19:38:34Z
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: 2021-01-21T19:38:34Z

Request

DELETE

/projects/{project}/subscriptions/{id}

curl https://api.gigs.com/projects/{project}/subscriptions/{id} \
-X DELETE \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

PATCH/projects/{project}/subscriptions/{id}

Update a subscription

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

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 to share your thoughts.

Body

Name
metadata
Type
object
PREVIEW
Description
A set of key-value pairs, to store metadata related to the resource.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: gigs
Name
id
Type
string
required
Description
The unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi

Response Schemas

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: 2021-01-21T19:32:13Z
Name
end
Type
string
required
Description
End of the period.
Example: 2021-02-20T19:38:34Z
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: +19591234567
Name
plan
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always plan.
Name
id
Type
string
required
Description
Unique identifier for the plan.
Example: pln_0SNlurA049MEWV3V0q7gjQbM4EVo
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
allowances
Type
object
required
Description
The allowances included in the plan.
Name
coverage
Type
object
required
Description
The geographic coverage of the plan.
Name
data
Type
integer
DEPRECATED
required
Description
The data allowance in bytes included in this plan. A value of -1 indicates unlimited data.
Example: 10000000000
Name
dataUnit
Type
string
DEPRECATED
required
Description
The unit of the data value is always byte.
Name
description
Type
nullable string
required
Description
The plan's description, meant to be displayable to the users.
Example: A data plan you will love! Operates in most countries of the world.
Name
image
Type
nullable string
required
Description
The plan's image, meant to be displayable to the users.
Example: https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
Name
limits
Type
object
required
Description
The limitations of the plan.
Name
name
Type
string
required
Description
The plan's name, meant to be displayable to the users.
Example: Gigs Global
Name
price
Type
object
required
Description
The price of the plan.
Name
provider
Type
string
required
Description
The ID of the network provider supported by this plan.
Example: p5
Name
requirements
Type
object
required
Description
Name
simTypes
Type
array
required
Description
List of SIM types supported by this plan. Can be eSIM, pSIM, or both.
Example: eSIM,pSIM
Name
sms
Type
integer
DEPRECATED
required
Description
The sms allowance included in this plan. A value of -1 indicates unlimited sms.
Example: 100
Name
smsUnit
Type
string
DEPRECATED
required
Description
The unit of the sms value is always message.
Name
status
Type
string
required
Description
Allowed values: available, archived, pending, draft
Name
validity
Type
object
required
Description
The validity of the plan.
Name
voice
Type
integer
DEPRECATED
required
Description
The voice allowance included in this plan. A value of -1 indicates unlimited voice.
Example: 30000
Name
voiceUnit
Type
string
DEPRECATED
required
Description
The unit of the voice value is always second.
Name
createdAt
Type
string
required
Description
Time when the plan was created.
Example: 2021-01-21T19:38:34Z
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
object
Type
string
required
Description
Type of object is always porting.
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: 123456789
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: 2017-07-21
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: portingPhoneNumberPortProtected
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: The phone number has port protection on the provider.
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: Seinfeld
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: +19591234567
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: p9
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
Name
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
user
Type
string
required
Description
Unique identifier for the user this porting is for.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: 2021-01-21T19:39:53Z
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: 2021-01-21T19:36:57Z
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: 2021-01-21T19:12:28Z
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z
Name
sim
Type
nullable object
required
Description
Name
object
Type
string
required
Description
Type of object is always sim.
Name
id
Type
string
required
Description
Unique identifier for the SIM.
Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
iccid
Type
string
required
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: 89883070000007537119
Name
provider
Type
string
required
Description
The ID of the network provider of the SIM.
Example: p9
Name
status
Type
string
required
Description
The status of the SIM. Can be active or inactive.
Allowed values: inactive, active, retired
Name
type
Type
string
required
Description
The type of the SIM. Can be eSIM or pSIM.
Allowed values: eSIM, pSIM
Name
createdAt
Type
string
required
Description
Time when the SIM was created.
Example: 2021-01-21T19:38:34Z
Name
status
Type
string
required
Description
The current status of the subscription.
Allowed values: pending, active, ended
Name
user
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: 2017-07-21
Name
email
Type
string
required
Description
The primary email address of the user.
Example: jerry@example.com
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: Jerry Seinfeld
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: en-US
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: 2021-01-21T19:38:34Z
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: 2021-01-29T13:22:51Z
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
Name
earliestEndAt
Type
nullable string
PREVIEW
required
Description
Earliest time at which the subscription can currently be ended. It depends on the minimum period of the plan. Only present if the subscription has not yet been ended.
Example: 2021-02-20T19:38:34Z
Name
endedAt
Type
nullable string
required
Description
Time when the subscription was ended.
Example: 2021-02-20T19:38:34Z
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: 2021-01-21T19:38:34Z

Request

PATCH

/projects/{project}/subscriptions/{id}

curl https://api.gigs.com/projects/{project}/subscriptions/{id} \
-X PATCH \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"metadata\":{}}"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

POST/projects/{project}/subscriptions/{id}/resume

Resume a canceled subscription

Removes the cancellation and end times of the subscription. The subscription will continue to auto-renew until canceled again.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: gigs
Name
id
Type
string
required
Description
The unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi

Response Schemas

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: 2021-01-21T19:32:13Z
Name
end
Type
string
required
Description
End of the period.
Example: 2021-02-20T19:38:34Z
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: +19591234567
Name
plan
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always plan.
Name
id
Type
string
required
Description
Unique identifier for the plan.
Example: pln_0SNlurA049MEWV3V0q7gjQbM4EVo
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
allowances
Type
object
required
Description
The allowances included in the plan.
Name
coverage
Type
object
required
Description
The geographic coverage of the plan.
Name
data
Type
integer
DEPRECATED
required
Description
The data allowance in bytes included in this plan. A value of -1 indicates unlimited data.
Example: 10000000000
Name
dataUnit
Type
string
DEPRECATED
required
Description
The unit of the data value is always byte.
Name
description
Type
nullable string
required
Description
The plan's description, meant to be displayable to the users.
Example: A data plan you will love! Operates in most countries of the world.
Name
image
Type
nullable string
required
Description
The plan's image, meant to be displayable to the users.
Example: https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
Name
limits
Type
object
required
Description
The limitations of the plan.
Name
name
Type
string
required
Description
The plan's name, meant to be displayable to the users.
Example: Gigs Global
Name
price
Type
object
required
Description
The price of the plan.
Name
provider
Type
string
required
Description
The ID of the network provider supported by this plan.
Example: p5
Name
requirements
Type
object
required
Description
Name
simTypes
Type
array
required
Description
List of SIM types supported by this plan. Can be eSIM, pSIM, or both.
Example: eSIM,pSIM
Name
sms
Type
integer
DEPRECATED
required
Description
The sms allowance included in this plan. A value of -1 indicates unlimited sms.
Example: 100
Name
smsUnit
Type
string
DEPRECATED
required
Description
The unit of the sms value is always message.
Name
status
Type
string
required
Description
Allowed values: available, archived, pending, draft
Name
validity
Type
object
required
Description
The validity of the plan.
Name
voice
Type
integer
DEPRECATED
required
Description
The voice allowance included in this plan. A value of -1 indicates unlimited voice.
Example: 30000
Name
voiceUnit
Type
string
DEPRECATED
required
Description
The unit of the voice value is always second.
Name
createdAt
Type
string
required
Description
Time when the plan was created.
Example: 2021-01-21T19:38:34Z
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
object
Type
string
required
Description
Type of object is always porting.
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: 123456789
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: 2017-07-21
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: portingPhoneNumberPortProtected
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: The phone number has port protection on the provider.
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: Seinfeld
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: +19591234567
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: p9
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
Name
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
user
Type
string
required
Description
Unique identifier for the user this porting is for.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: 2021-01-21T19:39:53Z
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: 2021-01-21T19:36:57Z
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: 2021-01-21T19:12:28Z
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z
Name
sim
Type
nullable object
required
Description
Name
object
Type
string
required
Description
Type of object is always sim.
Name
id
Type
string
required
Description
Unique identifier for the SIM.
Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
iccid
Type
string
required
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: 89883070000007537119
Name
provider
Type
string
required
Description
The ID of the network provider of the SIM.
Example: p9
Name
status
Type
string
required
Description
The status of the SIM. Can be active or inactive.
Allowed values: inactive, active, retired
Name
type
Type
string
required
Description
The type of the SIM. Can be eSIM or pSIM.
Allowed values: eSIM, pSIM
Name
createdAt
Type
string
required
Description
Time when the SIM was created.
Example: 2021-01-21T19:38:34Z
Name
status
Type
string
required
Description
The current status of the subscription.
Allowed values: pending, active, ended
Name
user
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: 2017-07-21
Name
email
Type
string
required
Description
The primary email address of the user.
Example: jerry@example.com
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: Jerry Seinfeld
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: en-US
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: 2021-01-21T19:38:34Z
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: 2021-01-29T13:22:51Z
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
Name
earliestEndAt
Type
nullable string
PREVIEW
required
Description
Earliest time at which the subscription can currently be ended. It depends on the minimum period of the plan. Only present if the subscription has not yet been ended.
Example: 2021-02-20T19:38:34Z
Name
endedAt
Type
nullable string
required
Description
Time when the subscription was ended.
Example: 2021-02-20T19:38:34Z
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: 2021-01-21T19:38:34Z

Request

POST

/projects/{project}/subscriptions/{id}/resume

curl https://api.gigs.com/projects/{project}/subscriptions/{id}/resume \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

POST/projects/{project}/subscriptions/search

Search for subscriptions

Searches for existing subscriptions matching the given parameters.

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 to share your thoughts.

Body

Name
phoneNumber
Type
string
required
Description
The E.164-formatted phone number associated with the subscription.
Example: +12065550123

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: gigs

Response Schemas

Name
object
Type
string
required
Description
Type of object is always list.
Name
items
Type
array
required
Description
List of objects of type subscription.
Name
moreItemsAfter
Type
nullable string
required
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
required
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

POST

/projects/{project}/subscriptions/search

curl https://api.gigs.com/projects/{project}/subscriptions/search \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"phoneNumber\":\"+12065550123\"}"

Responses

{
  "object": "list",
  "items": [
    {
      "object": "subscription",
      "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "metadata": {},
      "cancellationDetails": {
        "cause": "cancellationRequested",
        "userReason": "connectivityIssues"
      },
      "currentPeriod": {
        "number": 1,
        "start": "2021-01-21T19:32:13Z",
        "end": "2021-02-20T19:38:34Z"
      },
      "phoneNumber": "+19591234567",
      "plan": {
        "object": "plan",
        "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
        "metadata": {},
        "allowances": {
          "dataBytes": 10000000000,
          "voiceSeconds": 30000,
          "smsMessages": 100
        },
        "coverage": {
          "object": "coverage",
          "id": "de",
          "countries": [
            "DE",
            "FR",
            "US"
          ],
          "name": "Europe"
        },
        "data": 10000000000,
        "dataUnit": "byte",
        "description": "A data plan you will love! Operates in most countries of the world.",
        "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
        "limits": {
          "dataBytes": 100000000000,
          "bandwidthBitsPerSecond": null,
          "throttling": {
            "thresholdBytes": 10000000000,
            "bandwidthBitsPerSecond": 512000
          }
        },
        "name": "Gigs Global",
        "price": {
          "amount": 999,
          "currency": "USD"
        },
        "provider": "p5",
        "requirements": {
          "address": "present",
          "device": "none",
          "user.birthday": "none",
          "user.fullName": "present"
        },
        "simTypes": [
          "eSIM",
          "pSIM"
        ],
        "sms": 100,
        "smsUnit": "message",
        "status": "available",
        "validity": {
          "minimumPeriods": 12,
          "type": "recurring",
          "unit": "day",
          "value": 7
        },
        "voice": 30000,
        "voiceUnit": "second",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "porting": {
        "object": "porting",
        "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
        "accountNumber": "123456789",
        "accountPinExists": true,
        "address": {
          "city": "New York City",
          "country": "US",
          "line1": "129 West 81st Street",
          "line2": "Apartment 5A",
          "postalCode": "10024",
          "state": "NY"
        },
        "birthday": "2017-07-21",
        "declinedAttempts": 0,
        "declinedCode": "portingPhoneNumberPortProtected",
        "declinedMessage": "The phone number has port protection on the provider.",
        "donorProvider": {
          "object": "serviceProvider",
          "id": "svp_0SNlurA01K6GY5L0XJffY8",
          "name": "AT&T",
          "recipientProviders": [
            "p3"
          ]
        },
        "donorProviderApproval": true,
        "firstName": "Jerry",
        "lastName": "Seinfeld",
        "phoneNumber": "+19591234567",
        "provider": "p9",
        "recipientProvider": {
          "object": "serviceProvider",
          "id": "svp_0SNlurA01K6GY5L0XJffY8",
          "name": "AT&T",
          "recipientProviders": [
            "p3"
          ]
        },
        "required": [
          "accountNumber",
          "accountPin",
          "address",
          "birthday",
          "donorProvider",
          "donorProviderApproval",
          "firstName",
          "lastName"
        ],
        "status": "draft",
        "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
        "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
        "canceledAt": "2021-01-21T19:39:53Z",
        "completedAt": "2021-01-21T19:36:57Z",
        "createdAt": "2021-01-21T19:12:28Z",
        "expiredAt": "2021-01-21T19:39:53Z",
        "lastDeclinedAt": "2021-01-21T19:31:13Z",
        "lastRequestedAt": "2021-01-21T19:22:31Z"
      },
      "sim": {
        "object": "sim",
        "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
        "metadata": {},
        "iccid": "89883070000007537119",
        "provider": "p9",
        "status": "inactive",
        "type": "eSIM",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "status": "pending",
      "user": {
        "object": "user",
        "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
        "metadata": {},
        "birthday": "2017-07-21",
        "email": "jerry@example.com",
        "emailVerified": true,
        "fullName": "Jerry Seinfeld",
        "preferredLocale": "en-US",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "activatedAt": "2021-01-21T19:38:34Z",
      "canceledAt": "2021-01-29T13:22:51Z",
      "createdAt": "2021-01-21T19:32:13Z",
      "earliestEndAt": "2021-02-20T19:38:34Z",
      "endedAt": "2021-02-20T19:38:34Z",
      "firstUsageAt": "2021-01-21T19:38:34Z"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

GET/projects/{project}/subscriptions

List all 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
project
Type
string
required
Description
The unique identifier for the project.
Example: gigs

Query Parameters

Name
user
Type
string
Description
The unique identifier for the user to be filtered by.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
plan
Type
string
Description
The unique identifier for the plan to be filtered by.
Example: pln_0SNlurA049MEWV3V0q7gjQbM4EVo
Name
sim
Type
string
Description
The unique identifier for the sim to be filtered by.
Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
Name
status
Type
array
Description
A comma-separated list of statuses to filter the subscriptions by. Only pending and active subscriptions are returned by default.
Default: pending,active
Name
after
Type
string
Description
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.
Name
before
Type
string
Description
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.
Name
limit
Type
integer
Description
The limit of items to be returned in the list, between 0 and 200.
Default: 10
>= 0
<= 200

Response Schemas

Name
object
Type
string
required
Description
Type of object is always list.
Name
items
Type
array
required
Description
List of objects of type subscription.
Name
moreItemsAfter
Type
nullable string
required
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
required
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/projects/{project}/subscriptions

curl https://api.gigs.com/projects/{project}/subscriptions \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Responses

{
  "object": "list",
  "items": [
    {
      "object": "subscription",
      "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "metadata": {},
      "cancellationDetails": {
        "cause": "cancellationRequested",
        "userReason": "connectivityIssues"
      },
      "currentPeriod": {
        "number": 1,
        "start": "2021-01-21T19:32:13Z",
        "end": "2021-02-20T19:38:34Z"
      },
      "phoneNumber": "+19591234567",
      "plan": {
        "object": "plan",
        "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
        "metadata": {},
        "allowances": {
          "dataBytes": 10000000000,
          "voiceSeconds": 30000,
          "smsMessages": 100
        },
        "coverage": {
          "object": "coverage",
          "id": "de",
          "countries": [
            "DE",
            "FR",
            "US"
          ],
          "name": "Europe"
        },
        "data": 10000000000,
        "dataUnit": "byte",
        "description": "A data plan you will love! Operates in most countries of the world.",
        "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
        "limits": {
          "dataBytes": 100000000000,
          "bandwidthBitsPerSecond": null,
          "throttling": {
            "thresholdBytes": 10000000000,
            "bandwidthBitsPerSecond": 512000
          }
        },
        "name": "Gigs Global",
        "price": {
          "amount": 999,
          "currency": "USD"
        },
        "provider": "p5",
        "requirements": {
          "address": "present",
          "device": "none",
          "user.birthday": "none",
          "user.fullName": "present"
        },
        "simTypes": [
          "eSIM",
          "pSIM"
        ],
        "sms": 100,
        "smsUnit": "message",
        "status": "available",
        "validity": {
          "minimumPeriods": 12,
          "type": "recurring",
          "unit": "day",
          "value": 7
        },
        "voice": 30000,
        "voiceUnit": "second",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "porting": {
        "object": "porting",
        "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
        "accountNumber": "123456789",
        "accountPinExists": true,
        "address": {
          "city": "New York City",
          "country": "US",
          "line1": "129 West 81st Street",
          "line2": "Apartment 5A",
          "postalCode": "10024",
          "state": "NY"
        },
        "birthday": "2017-07-21",
        "declinedAttempts": 0,
        "declinedCode": "portingPhoneNumberPortProtected",
        "declinedMessage": "The phone number has port protection on the provider.",
        "donorProvider": {
          "object": "serviceProvider",
          "id": "svp_0SNlurA01K6GY5L0XJffY8",
          "name": "AT&T",
          "recipientProviders": [
            "p3"
          ]
        },
        "donorProviderApproval": true,
        "firstName": "Jerry",
        "lastName": "Seinfeld",
        "phoneNumber": "+19591234567",
        "provider": "p9",
        "recipientProvider": {
          "object": "serviceProvider",
          "id": "svp_0SNlurA01K6GY5L0XJffY8",
          "name": "AT&T",
          "recipientProviders": [
            "p3"
          ]
        },
        "required": [
          "accountNumber",
          "accountPin",
          "address",
          "birthday",
          "donorProvider",
          "donorProviderApproval",
          "firstName",
          "lastName"
        ],
        "status": "draft",
        "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
        "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
        "canceledAt": "2021-01-21T19:39:53Z",
        "completedAt": "2021-01-21T19:36:57Z",
        "createdAt": "2021-01-21T19:12:28Z",
        "expiredAt": "2021-01-21T19:39:53Z",
        "lastDeclinedAt": "2021-01-21T19:31:13Z",
        "lastRequestedAt": "2021-01-21T19:22:31Z"
      },
      "sim": {
        "object": "sim",
        "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
        "metadata": {},
        "iccid": "89883070000007537119",
        "provider": "p9",
        "status": "inactive",
        "type": "eSIM",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "status": "pending",
      "user": {
        "object": "user",
        "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
        "metadata": {},
        "birthday": "2017-07-21",
        "email": "jerry@example.com",
        "emailVerified": true,
        "fullName": "Jerry Seinfeld",
        "preferredLocale": "en-US",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "activatedAt": "2021-01-21T19:38:34Z",
      "canceledAt": "2021-01-29T13:22:51Z",
      "createdAt": "2021-01-21T19:32:13Z",
      "earliestEndAt": "2021-02-20T19:38:34Z",
      "endedAt": "2021-02-20T19:38:34Z",
      "firstUsageAt": "2021-01-21T19:38:34Z"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

POST/projects/{project}/subscriptions

Create a subscription

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

Body

Name
device
Type
nullable string
Description
The unique identifier for the existing Device to be linked with the passed SIM. Some network providers require this field for activation. Trying to link a pSIM to a second device will cause an error.
Example: dev_0SNlurA049MEWV55CrA9qMvI2FVJ
Name
metadata
Type
object
PREVIEW
Description
A set of key-value pairs, to store metadata related to the resource.
Name
plan
Type
string
required
Description
The unique identifier for the existing plan to be used for the subscription.
Example: pln_0SNlurA049MEWV3V0q7gjQbM4EVo
Name
porting
Type
nullable string
PREVIEW
Description
The unique identifier for the existing draft porting to be used for the subscription.
Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
Name
sim
Type
nullable string
Description
The unique identifier for the existing SIM to be used for the subscription. In combination with an eSIM plan, it can be passed as auto to request a new eSIM.
Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
Default: auto
Name
userAddress
Type
nullable string
Description
The unique identifier for the existing user address to be used for the subscription. Only needed if the plan requires an address.
Example: adr_0SNlurA049MEWV5ELDmnaqVXgTFT
Name
user
Type
string
required
Description
The unique identifier for the existing user to which the subscription will be assigned.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: gigs

Response Schemas

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: 2021-01-21T19:32:13Z
Name
end
Type
string
required
Description
End of the period.
Example: 2021-02-20T19:38:34Z
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: +19591234567
Name
plan
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always plan.
Name
id
Type
string
required
Description
Unique identifier for the plan.
Example: pln_0SNlurA049MEWV3V0q7gjQbM4EVo
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
allowances
Type
object
required
Description
The allowances included in the plan.
Name
coverage
Type
object
required
Description
The geographic coverage of the plan.
Name
data
Type
integer
DEPRECATED
required
Description
The data allowance in bytes included in this plan. A value of -1 indicates unlimited data.
Example: 10000000000
Name
dataUnit
Type
string
DEPRECATED
required
Description
The unit of the data value is always byte.
Name
description
Type
nullable string
required
Description
The plan's description, meant to be displayable to the users.
Example: A data plan you will love! Operates in most countries of the world.
Name
image
Type
nullable string
required
Description
The plan's image, meant to be displayable to the users.
Example: https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
Name
limits
Type
object
required
Description
The limitations of the plan.
Name
name
Type
string
required
Description
The plan's name, meant to be displayable to the users.
Example: Gigs Global
Name
price
Type
object
required
Description
The price of the plan.
Name
provider
Type
string
required
Description
The ID of the network provider supported by this plan.
Example: p5
Name
requirements
Type
object
required
Description
Name
simTypes
Type
array
required
Description
List of SIM types supported by this plan. Can be eSIM, pSIM, or both.
Example: eSIM,pSIM
Name
sms
Type
integer
DEPRECATED
required
Description
The sms allowance included in this plan. A value of -1 indicates unlimited sms.
Example: 100
Name
smsUnit
Type
string
DEPRECATED
required
Description
The unit of the sms value is always message.
Name
status
Type
string
required
Description
Allowed values: available, archived, pending, draft
Name
validity
Type
object
required
Description
The validity of the plan.
Name
voice
Type
integer
DEPRECATED
required
Description
The voice allowance included in this plan. A value of -1 indicates unlimited voice.
Example: 30000
Name
voiceUnit
Type
string
DEPRECATED
required
Description
The unit of the voice value is always second.
Name
createdAt
Type
string
required
Description
Time when the plan was created.
Example: 2021-01-21T19:38:34Z
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
object
Type
string
required
Description
Type of object is always porting.
Name
id
Type
string
required
Description
Unique identifier for the porting.
Example: prt_0SNlurA049MEWV39s2kSYqaat7ZS
Name
accountNumber
Type
nullable string
required
Description
The account number on the donor service provider.
Example: 123456789
Name
accountPinExists
Type
boolean
required
Description
Whether the account PIN has been provided.
Example: true
Name
address
Type
nullable object
required
Description
The address of the account holder on the donor service provider.
Name
birthday
Type
nullable string
required
Description
The birthday of the account holder on the donor service provider.
Example: 2017-07-21
Name
declinedAttempts
Type
integer
required
Description
The number of declined porting attempts so far.
Example: 0
>= 0
Name
declinedCode
Type
nullable string
PREVIEW
required
Description
The code reason for the declined porting.
Example: portingPhoneNumberPortProtected
Name
declinedMessage
Type
nullable string
PREVIEW
required
Description
The reason description for the declined porting.
Example: The phone number has port protection on the provider.
Name
donorProvider
Type
nullable object
required
Description
The service provider from whom the number is ported.
Name
donorProviderApproval
Type
nullable boolean
required
Description
Whether the donor provider has approved or not the porting.
Example: true
Name
firstName
Type
nullable string
required
Description
The first name of the account holder on the donor service provider.
Example: Jerry
Name
lastName
Type
nullable string
required
Description
The last name of the account holder on the donor service provider.
Example: Seinfeld
Name
phoneNumber
Type
string
required
Description
The phone number to port in E.164 format.
Example: +19591234567
Name
provider
Type
string
required
Description
The ID of the recipient network provider.
Example: p9
Name
recipientProvider
Type
object
required
Description
The service provider to whom the number is ported.
Name
required
Type
array
required
Description
List of fields required for the porting to be processable. The fields depend on the donor and recipient providers.
Example: accountNumber,accountPin,address,birthday,donorProvider,donorProviderApproval,firstName,lastName
Name
status
Type
string
required
Description
The current status of the porting.
Allowed values: draft, pending, informationRequired, requested, declined, completed, canceled, expired
Name
subscription
Type
nullable string
required
Description
Unique identifier for the porting subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
user
Type
string
required
Description
Unique identifier for the user this porting is for.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
canceledAt
Type
nullable string
required
Description
Time when the porting was canceled.
Example: 2021-01-21T19:39:53Z
Name
completedAt
Type
nullable string
required
Description
Time when the porting was completed.
Example: 2021-01-21T19:36:57Z
Name
createdAt
Type
string
required
Description
Time when the porting was created.
Example: 2021-01-21T19:12:28Z
Name
expiredAt
Type
nullable string
required
Description
Time when the porting was expired.
Example: 2021-01-21T19:39:53Z
Name
lastDeclinedAt
Type
nullable string
required
Description
Time when the porting was last declined.
Example: 2021-01-21T19:31:13Z
Name
lastRequestedAt
Type
nullable string
required
Description
Time when the porting was last requested.
Example: 2021-01-21T19:22:31Z
Name
sim
Type
nullable object
required
Description
Name
object
Type
string
required
Description
Type of object is always sim.
Name
id
Type
string
required
Description
Unique identifier for the SIM.
Example: sim_0SNlurA049MEWV1BAAmWZULA4lf6
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
iccid
Type
string
required
Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example: 89883070000007537119
Name
provider
Type
string
required
Description
The ID of the network provider of the SIM.
Example: p9
Name
status
Type
string
required
Description
The status of the SIM. Can be active or inactive.
Allowed values: inactive, active, retired
Name
type
Type
string
required
Description
The type of the SIM. Can be eSIM or pSIM.
Allowed values: eSIM, pSIM
Name
createdAt
Type
string
required
Description
Time when the SIM was created.
Example: 2021-01-21T19:38:34Z
Name
status
Type
string
required
Description
The current status of the subscription.
Allowed values: pending, active, ended
Name
user
Type
object
required
Description
Name
object
Type
string
required
Description
Type of object is always user.
Name
id
Type
string
required
Description
Unique identifier for the user.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
metadata
Type
object
PREVIEW
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
birthday
Type
nullable string
required
Description
The birthday of the user.
Example: 2017-07-21
Name
email
Type
string
required
Description
The primary email address of the user.
Example: jerry@example.com
Name
emailVerified
Type
boolean
required
Description
Whether the user's primary email address is verified or not.
Example: true
Name
fullName
Type
nullable string
required
Description
The user's full name. Required for some Plans.
Example: Jerry Seinfeld
Name
preferredLocale
Type
string
required
Description
The user's locale preference represented as an IETF language tag.
Example: en-US
Name
createdAt
Type
string
required
Description
Time when the user was created.
Example: 2021-01-21T19:38:34Z
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: 2021-01-21T19:38:34Z
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: 2021-01-29T13:22:51Z
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
Name
earliestEndAt
Type
nullable string
PREVIEW
required
Description
Earliest time at which the subscription can currently be ended. It depends on the minimum period of the plan. Only present if the subscription has not yet been ended.
Example: 2021-02-20T19:38:34Z
Name
endedAt
Type
nullable string
required
Description
Time when the subscription was ended.
Example: 2021-02-20T19:38:34Z
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: 2021-01-21T19:38:34Z

Request

POST

/projects/{project}/subscriptions

curl https://api.gigs.com/projects/{project}/subscriptions \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"device\":\"dev_0SNlurA049MEWV55CrA9qMvI2FVJ\",\"metadata\":{},\"plan\":\"pln_0SNlurA049MEWV3V0q7gjQbM4EVo\",\"porting\":\"prt_0SNlurA049MEWV39s2kSYqaat7ZS\",\"sim\":\"sim_0SNlurA049MEWV1BAAmWZULA4lf6\",\"userAddress\":\"adr_0SNlurA049MEWV5ELDmnaqVXgTFT\",\"user\":\"usr_0SNlurA049MEWV4OpCwsNyC9Kn2d\"}"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}