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
- Description
Sequence number of the period.
Example:1
>= 1
required- Name
start
- Type
- string
- Description
Beginning of the period.
Example:2021-01-21T19:32:13Z
required- Name
end
- Type
- string
- Description
End of the period.
Example:2021-02-20T19:38:34Z
required
- 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
- Description
Type of object is always
plan
.
required- Name
id
- Type
- string
- Description
Unique identifier for the plan.
Example:pln_0SNlurA049MEWV3V0q7gjQbM4EVo
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
allowances
- Type
- object
- Description
- The allowances included in the plan.
required- Name
coverage
- Type
- object
- Description
- The geographic coverage of the plan.
required- Name
data
- Type
- integer DEPRECATED
- Description
The data allowance in bytes included in this plan. A value of
-1
indicates unlimited data.Example:10000000000
required- Name
dataUnit
- Type
- string DEPRECATED
- Description
The unit of the data value is always
byte
.
required- Name
description
- Type
- nullable string
- 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.
required- Name
image
- Type
- nullable string
- Description
The plan's image, meant to be displayable to the users.
Example:https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
required- Name
limits
- Type
- object
- Description
- The limitations of the plan.
required- Name
name
- Type
- string
- Description
The plan's name, meant to be displayable to the users.
Example:Gigs Global
required- Name
price
- Type
- object
- Description
- The price of the plan.
required- Name
provider
- Type
- string
- Description
The ID of the network provider supported by this plan.
Example:p5
required- Name
requirements
- Type
- object
- Description
required- Name
simTypes
- Type
- array
- Description
List of SIM types supported by this plan. Can be
eSIM
,pSIM
, or both.Example:eSIM,pSIM
required- Name
sms
- Type
- integer DEPRECATED
- Description
The sms allowance included in this plan. A value of
-1
indicates unlimited sms.Example:100
required- Name
smsUnit
- Type
- string DEPRECATED
- Description
The unit of the sms value is always
message
.
required- Name
status
- Type
- string
- Description
- Allowed values:
available, archived, pending, draft
required- Name
validity
- Type
- object
- Description
- The validity of the plan.
required- Name
voice
- Type
- integer DEPRECATED
- Description
The voice allowance included in this plan. A value of
-1
indicates unlimited voice.Example:30000
required- Name
voiceUnit
- Type
- string DEPRECATED
- Description
The unit of the voice value is always
second
.
required- Name
createdAt
- Type
- string
- Description
Time when the plan was created.
Example:2021-01-21T19:38:34Z
required
- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
- Name
object
- Type
- string
- Description
Type of object is always
porting
.
required- Name
id
- Type
- string
- Description
Unique identifier for the porting.
Example:prt_0SNlurA049MEWV39s2kSYqaat7ZS
required- Name
accountNumber
- Type
- nullable string
- Description
The account number on the donor service provider.
Example:123456789
required- Name
accountPinExists
- Type
- boolean
- Description
Whether the account PIN has been provided.
Example:true
required- Name
address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:2017-07-21
required- Name
declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0
>= 0
required- Name
declinedCode
- Type
- nullable string PREVIEW
- Description
The code reason for the declined porting.
Example:portingPhoneNumberPortProtected
required- Name
declinedMessage
- Type
- nullable string PREVIEW
- Description
The reason description for the declined porting.
Example:The phone number has port protection on the provider.
required- Name
donorProvider
- Type
- nullable object
- Description
- The service provider from whom the number is ported.
required- Name
donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
required- Name
firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:Jerry
required- Name
lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:Seinfeld
required- Name
phoneNumber
- Type
- string
- Description
The phone number to port in E.164 format.
Example:+19591234567
required- Name
provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:p9
required- Name
recipientProvider
- Type
- object
- Description
- The service provider to whom the number is ported.
required- Name
required
- Type
- array
- 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
required- Name
status
- Type
- string
- Description
The current status of the porting.
Allowed values:draft, pending, informationRequired, requested, declined, completed, canceled, expired
required- Name
subscription
- Type
- nullable string
- Description
Unique identifier for the porting subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
user
- Type
- string
- Description
Unique identifier for the user this porting is for.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:2021-01-21T19:39:53Z
required- Name
completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:2021-01-21T19:36:57Z
required- Name
createdAt
- Type
- string
- Description
Time when the porting was created.
Example:2021-01-21T19:12:28Z
required- Name
expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:2021-01-21T19:39:53Z
required- Name
lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:2021-01-21T19:31:13Z
required- Name
lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:2021-01-21T19:22:31Z
required
- Name
sim
- Type
- nullable object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
sim
.
required- Name
id
- Type
- string
- Description
Unique identifier for the SIM.
Example:sim_0SNlurA049MEWV1BAAmWZULA4lf6
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
iccid
- Type
- string
- Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example:89883070000007537119
required- Name
provider
- Type
- string
- Description
The ID of the network provider of the SIM.
Example:p9
required- Name
status
- Type
- string
- Description
The status of the SIM. Can be
active
orinactive
.Allowed values:inactive, active, retired
required- Name
type
- Type
- string
- Description
The type of the SIM. Can be
eSIM
orpSIM
.Allowed values:eSIM, pSIM
required- Name
createdAt
- Type
- string
- Description
Time when the SIM was created.
Example:2021-01-21T19:38:34Z
required
- Name
status
- Type
- string
- Description
The current status of the subscription. Note that the
initiated
status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.Allowed values:pending, initiated, active, ended
- Name
user
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
user
.
required- Name
id
- Type
- string
- Description
Unique identifier for the user.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the user.
Example:2017-07-21
required- Name
email
- Type
- string
- Description
The primary email address of the user.
Example:jerry@example.com
required- Name
emailVerified
- Type
- boolean
- Description
Whether the user's primary email address is verified or not.
Example:true
required- Name
fullName
- Type
- nullable string
- Description
The user's full name. Required for some Plans.
Example:Jerry Seinfeld
required- Name
preferredLocale
- Type
- string
- Description
The user's locale preference represented as an IETF language tag.
Example:en-US
required- Name
createdAt
- Type
- string
- Description
Time when the user was created.
Example:2021-01-21T19:38:34Z
required
- 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"
}
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
- Description
Reason for the user to cancel the subscription.
Allowed values:connectivityIssues, customerService, noDetails, other, tooExpensive, unused
required
Path Parameters
- Name
project
- Type
- string
- Description
The unique identifier for the project.
Example:gigs
required- Name
id
- Type
- string
- Description
The unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required
Response Schemas
- Name
object
- Type
- string
- Description
Type of object is always
subscription
.
required- Name
id
- Type
- string
- Description
Unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- 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
required- Name
currentPeriod
- Type
- nullable object
- Description
- Current subscription period. Only present for active subscriptions.
- Name
number
- Type
- integer
- Description
Sequence number of the period.
Example:1
>= 1
required- Name
start
- Type
- string
- Description
Beginning of the period.
Example:2021-01-21T19:32:13Z
required- Name
end
- Type
- string
- Description
End of the period.
Example:2021-02-20T19:38:34Z
required
required- Name
phoneNumber
- Type
- nullable string
- Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example:+19591234567
required- Name
plan
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
plan
.
required- Name
id
- Type
- string
- Description
Unique identifier for the plan.
Example:pln_0SNlurA049MEWV3V0q7gjQbM4EVo
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
allowances
- Type
- object
- Description
- The allowances included in the plan.
required- Name
coverage
- Type
- object
- Description
- The geographic coverage of the plan.
required- Name
data
- Type
- integer DEPRECATED
- Description
The data allowance in bytes included in this plan. A value of
-1
indicates unlimited data.Example:10000000000
required- Name
dataUnit
- Type
- string DEPRECATED
- Description
The unit of the data value is always
byte
.
required- Name
description
- Type
- nullable string
- 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.
required- Name
image
- Type
- nullable string
- Description
The plan's image, meant to be displayable to the users.
Example:https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
required- Name
limits
- Type
- object
- Description
- The limitations of the plan.
required- Name
name
- Type
- string
- Description
The plan's name, meant to be displayable to the users.
Example:Gigs Global
required- Name
price
- Type
- object
- Description
- The price of the plan.
required- Name
provider
- Type
- string
- Description
The ID of the network provider supported by this plan.
Example:p5
required- Name
requirements
- Type
- object
- Description
required- Name
simTypes
- Type
- array
- Description
List of SIM types supported by this plan. Can be
eSIM
,pSIM
, or both.Example:eSIM,pSIM
required- Name
sms
- Type
- integer DEPRECATED
- Description
The sms allowance included in this plan. A value of
-1
indicates unlimited sms.Example:100
required- Name
smsUnit
- Type
- string DEPRECATED
- Description
The unit of the sms value is always
message
.
required- Name
status
- Type
- string
- Description
- Allowed values:
available, archived, pending, draft
required- Name
validity
- Type
- object
- Description
- The validity of the plan.
required- Name
voice
- Type
- integer DEPRECATED
- Description
The voice allowance included in this plan. A value of
-1
indicates unlimited voice.Example:30000
required- Name
voiceUnit
- Type
- string DEPRECATED
- Description
The unit of the voice value is always
second
.
required- Name
createdAt
- Type
- string
- Description
Time when the plan was created.
Example:2021-01-21T19:38:34Z
required
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
- Name
object
- Type
- string
- Description
Type of object is always
porting
.
required- Name
id
- Type
- string
- Description
Unique identifier for the porting.
Example:prt_0SNlurA049MEWV39s2kSYqaat7ZS
required- Name
accountNumber
- Type
- nullable string
- Description
The account number on the donor service provider.
Example:123456789
required- Name
accountPinExists
- Type
- boolean
- Description
Whether the account PIN has been provided.
Example:true
required- Name
address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:2017-07-21
required- Name
declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0
>= 0
required- Name
declinedCode
- Type
- nullable string PREVIEW
- Description
The code reason for the declined porting.
Example:portingPhoneNumberPortProtected
required- Name
declinedMessage
- Type
- nullable string PREVIEW
- Description
The reason description for the declined porting.
Example:The phone number has port protection on the provider.
required- Name
donorProvider
- Type
- nullable object
- Description
- The service provider from whom the number is ported.
required- Name
donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
required- Name
firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:Jerry
required- Name
lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:Seinfeld
required- Name
phoneNumber
- Type
- string
- Description
The phone number to port in E.164 format.
Example:+19591234567
required- Name
provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:p9
required- Name
recipientProvider
- Type
- object
- Description
- The service provider to whom the number is ported.
required- Name
required
- Type
- array
- 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
required- Name
status
- Type
- string
- Description
The current status of the porting.
Allowed values:draft, pending, informationRequired, requested, declined, completed, canceled, expired
required- Name
subscription
- Type
- nullable string
- Description
Unique identifier for the porting subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
user
- Type
- string
- Description
Unique identifier for the user this porting is for.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:2021-01-21T19:39:53Z
required- Name
completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:2021-01-21T19:36:57Z
required- Name
createdAt
- Type
- string
- Description
Time when the porting was created.
Example:2021-01-21T19:12:28Z
required- Name
expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:2021-01-21T19:39:53Z
required- Name
lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:2021-01-21T19:31:13Z
required- Name
lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:2021-01-21T19:22:31Z
required
required- Name
sim
- Type
- nullable object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
sim
.
required- Name
id
- Type
- string
- Description
Unique identifier for the SIM.
Example:sim_0SNlurA049MEWV1BAAmWZULA4lf6
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
iccid
- Type
- string
- Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example:89883070000007537119
required- Name
provider
- Type
- string
- Description
The ID of the network provider of the SIM.
Example:p9
required- Name
status
- Type
- string
- Description
The status of the SIM. Can be
active
orinactive
.Allowed values:inactive, active, retired
required- Name
type
- Type
- string
- Description
The type of the SIM. Can be
eSIM
orpSIM
.Allowed values:eSIM, pSIM
required- Name
createdAt
- Type
- string
- Description
Time when the SIM was created.
Example:2021-01-21T19:38:34Z
required
required- Name
status
- Type
- string
- Description
The current status of the subscription. Note that the
initiated
status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.Allowed values:pending, initiated, active, ended
required- Name
user
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
user
.
required- Name
id
- Type
- string
- Description
Unique identifier for the user.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the user.
Example:2017-07-21
required- Name
email
- Type
- string
- Description
The primary email address of the user.
Example:jerry@example.com
required- Name
emailVerified
- Type
- boolean
- Description
Whether the user's primary email address is verified or not.
Example:true
required- Name
fullName
- Type
- nullable string
- Description
The user's full name. Required for some Plans.
Example:Jerry Seinfeld
required- Name
preferredLocale
- Type
- string
- Description
The user's locale preference represented as an IETF language tag.
Example:en-US
required- Name
createdAt
- Type
- string
- Description
Time when the user was created.
Example:2021-01-21T19:38:34Z
required
required- Name
activatedAt
- Type
- nullable string
- Description
Time when the subscription was activated.
Example:2021-01-21T19:38:34Z
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the subscription was canceled.
Example:2021-01-29T13:22:51Z
required- Name
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
required- 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
required- Name
endedAt
- Type
- nullable string
- Description
Time when the subscription was ended.
Example:2021-02-20T19:38:34Z
required- Name
firstUsageAt
- Type
- nullable string
- Description
Time when the subscription was first used.
Example:2021-01-21T19:38:34Z
required
Request
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"
}
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
- Description
Reason for the user to cancel the subscription.
Allowed values:connectivityIssues, customerService, noDetails, other, tooExpensive, unused
required
Path Parameters
- Name
project
- Type
- string
- Description
The unique identifier for the project.
Example:gigs
required- Name
id
- Type
- string
- Description
The unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required
Response Schemas
- Name
object
- Type
- string
- Description
Type of object is always
subscription
.
required- Name
id
- Type
- string
- Description
Unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- 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
required- Name
currentPeriod
- Type
- nullable object
- Description
- Current subscription period. Only present for active subscriptions.
- Name
number
- Type
- integer
- Description
Sequence number of the period.
Example:1
>= 1
required- Name
start
- Type
- string
- Description
Beginning of the period.
Example:2021-01-21T19:32:13Z
required- Name
end
- Type
- string
- Description
End of the period.
Example:2021-02-20T19:38:34Z
required
required- Name
phoneNumber
- Type
- nullable string
- Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example:+19591234567
required- Name
plan
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
plan
.
required- Name
id
- Type
- string
- Description
Unique identifier for the plan.
Example:pln_0SNlurA049MEWV3V0q7gjQbM4EVo
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
allowances
- Type
- object
- Description
- The allowances included in the plan.
required- Name
coverage
- Type
- object
- Description
- The geographic coverage of the plan.
required- Name
data
- Type
- integer DEPRECATED
- Description
The data allowance in bytes included in this plan. A value of
-1
indicates unlimited data.Example:10000000000
required- Name
dataUnit
- Type
- string DEPRECATED
- Description
The unit of the data value is always
byte
.
required- Name
description
- Type
- nullable string
- 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.
required- Name
image
- Type
- nullable string
- Description
The plan's image, meant to be displayable to the users.
Example:https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
required- Name
limits
- Type
- object
- Description
- The limitations of the plan.
required- Name
name
- Type
- string
- Description
The plan's name, meant to be displayable to the users.
Example:Gigs Global
required- Name
price
- Type
- object
- Description
- The price of the plan.
required- Name
provider
- Type
- string
- Description
The ID of the network provider supported by this plan.
Example:p5
required- Name
requirements
- Type
- object
- Description
required- Name
simTypes
- Type
- array
- Description
List of SIM types supported by this plan. Can be
eSIM
,pSIM
, or both.Example:eSIM,pSIM
required- Name
sms
- Type
- integer DEPRECATED
- Description
The sms allowance included in this plan. A value of
-1
indicates unlimited sms.Example:100
required- Name
smsUnit
- Type
- string DEPRECATED
- Description
The unit of the sms value is always
message
.
required- Name
status
- Type
- string
- Description
- Allowed values:
available, archived, pending, draft
required- Name
validity
- Type
- object
- Description
- The validity of the plan.
required- Name
voice
- Type
- integer DEPRECATED
- Description
The voice allowance included in this plan. A value of
-1
indicates unlimited voice.Example:30000
required- Name
voiceUnit
- Type
- string DEPRECATED
- Description
The unit of the voice value is always
second
.
required- Name
createdAt
- Type
- string
- Description
Time when the plan was created.
Example:2021-01-21T19:38:34Z
required
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
- Name
object
- Type
- string
- Description
Type of object is always
porting
.
required- Name
id
- Type
- string
- Description
Unique identifier for the porting.
Example:prt_0SNlurA049MEWV39s2kSYqaat7ZS
required- Name
accountNumber
- Type
- nullable string
- Description
The account number on the donor service provider.
Example:123456789
required- Name
accountPinExists
- Type
- boolean
- Description
Whether the account PIN has been provided.
Example:true
required- Name
address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:2017-07-21
required- Name
declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0
>= 0
required- Name
declinedCode
- Type
- nullable string PREVIEW
- Description
The code reason for the declined porting.
Example:portingPhoneNumberPortProtected
required- Name
declinedMessage
- Type
- nullable string PREVIEW
- Description
The reason description for the declined porting.
Example:The phone number has port protection on the provider.
required- Name
donorProvider
- Type
- nullable object
- Description
- The service provider from whom the number is ported.
required- Name
donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
required- Name
firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:Jerry
required- Name
lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:Seinfeld
required- Name
phoneNumber
- Type
- string
- Description
The phone number to port in E.164 format.
Example:+19591234567
required- Name
provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:p9
required- Name
recipientProvider
- Type
- object
- Description
- The service provider to whom the number is ported.
required- Name
required
- Type
- array
- 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
required- Name
status
- Type
- string
- Description
The current status of the porting.
Allowed values:draft, pending, informationRequired, requested, declined, completed, canceled, expired
required- Name
subscription
- Type
- nullable string
- Description
Unique identifier for the porting subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
user
- Type
- string
- Description
Unique identifier for the user this porting is for.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:2021-01-21T19:39:53Z
required- Name
completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:2021-01-21T19:36:57Z
required- Name
createdAt
- Type
- string
- Description
Time when the porting was created.
Example:2021-01-21T19:12:28Z
required- Name
expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:2021-01-21T19:39:53Z
required- Name
lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:2021-01-21T19:31:13Z
required- Name
lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:2021-01-21T19:22:31Z
required
required- Name
sim
- Type
- nullable object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
sim
.
required- Name
id
- Type
- string
- Description
Unique identifier for the SIM.
Example:sim_0SNlurA049MEWV1BAAmWZULA4lf6
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
iccid
- Type
- string
- Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example:89883070000007537119
required- Name
provider
- Type
- string
- Description
The ID of the network provider of the SIM.
Example:p9
required- Name
status
- Type
- string
- Description
The status of the SIM. Can be
active
orinactive
.Allowed values:inactive, active, retired
required- Name
type
- Type
- string
- Description
The type of the SIM. Can be
eSIM
orpSIM
.Allowed values:eSIM, pSIM
required- Name
createdAt
- Type
- string
- Description
Time when the SIM was created.
Example:2021-01-21T19:38:34Z
required
required- Name
status
- Type
- string
- Description
The current status of the subscription. Note that the
initiated
status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.Allowed values:pending, initiated, active, ended
required- Name
user
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
user
.
required- Name
id
- Type
- string
- Description
Unique identifier for the user.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the user.
Example:2017-07-21
required- Name
email
- Type
- string
- Description
The primary email address of the user.
Example:jerry@example.com
required- Name
emailVerified
- Type
- boolean
- Description
Whether the user's primary email address is verified or not.
Example:true
required- Name
fullName
- Type
- nullable string
- Description
The user's full name. Required for some Plans.
Example:Jerry Seinfeld
required- Name
preferredLocale
- Type
- string
- Description
The user's locale preference represented as an IETF language tag.
Example:en-US
required- Name
createdAt
- Type
- string
- Description
Time when the user was created.
Example:2021-01-21T19:38:34Z
required
required- Name
activatedAt
- Type
- nullable string
- Description
Time when the subscription was activated.
Example:2021-01-21T19:38:34Z
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the subscription was canceled.
Example:2021-01-29T13:22:51Z
required- Name
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
required- 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
required- Name
endedAt
- Type
- nullable string
- Description
Time when the subscription was ended.
Example:2021-02-20T19:38:34Z
required- Name
firstUsageAt
- Type
- nullable string
- Description
Time when the subscription was first used.
Example:2021-01-21T19:38:34Z
required
Request
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"
}
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
- Description
The unique identifier for the project.
Example:gigs
required- Name
id
- Type
- string
- Description
The unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required
Response Schemas
- Name
object
- Type
- string
- Description
Type of object is always
subscription
.
required- Name
id
- Type
- string
- Description
Unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- 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
required- Name
currentPeriod
- Type
- nullable object
- Description
- Current subscription period. Only present for active subscriptions.
- Name
number
- Type
- integer
- Description
Sequence number of the period.
Example:1
>= 1
required- Name
start
- Type
- string
- Description
Beginning of the period.
Example:2021-01-21T19:32:13Z
required- Name
end
- Type
- string
- Description
End of the period.
Example:2021-02-20T19:38:34Z
required
required- Name
phoneNumber
- Type
- nullable string
- Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example:+19591234567
required- Name
plan
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
plan
.
required- Name
id
- Type
- string
- Description
Unique identifier for the plan.
Example:pln_0SNlurA049MEWV3V0q7gjQbM4EVo
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
allowances
- Type
- object
- Description
- The allowances included in the plan.
required- Name
coverage
- Type
- object
- Description
- The geographic coverage of the plan.
required- Name
data
- Type
- integer DEPRECATED
- Description
The data allowance in bytes included in this plan. A value of
-1
indicates unlimited data.Example:10000000000
required- Name
dataUnit
- Type
- string DEPRECATED
- Description
The unit of the data value is always
byte
.
required- Name
description
- Type
- nullable string
- 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.
required- Name
image
- Type
- nullable string
- Description
The plan's image, meant to be displayable to the users.
Example:https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
required- Name
limits
- Type
- object
- Description
- The limitations of the plan.
required- Name
name
- Type
- string
- Description
The plan's name, meant to be displayable to the users.
Example:Gigs Global
required- Name
price
- Type
- object
- Description
- The price of the plan.
required- Name
provider
- Type
- string
- Description
The ID of the network provider supported by this plan.
Example:p5
required- Name
requirements
- Type
- object
- Description
required- Name
simTypes
- Type
- array
- Description
List of SIM types supported by this plan. Can be
eSIM
,pSIM
, or both.Example:eSIM,pSIM
required- Name
sms
- Type
- integer DEPRECATED
- Description
The sms allowance included in this plan. A value of
-1
indicates unlimited sms.Example:100
required- Name
smsUnit
- Type
- string DEPRECATED
- Description
The unit of the sms value is always
message
.
required- Name
status
- Type
- string
- Description
- Allowed values:
available, archived, pending, draft
required- Name
validity
- Type
- object
- Description
- The validity of the plan.
required- Name
voice
- Type
- integer DEPRECATED
- Description
The voice allowance included in this plan. A value of
-1
indicates unlimited voice.Example:30000
required- Name
voiceUnit
- Type
- string DEPRECATED
- Description
The unit of the voice value is always
second
.
required- Name
createdAt
- Type
- string
- Description
Time when the plan was created.
Example:2021-01-21T19:38:34Z
required
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
- Name
object
- Type
- string
- Description
Type of object is always
porting
.
required- Name
id
- Type
- string
- Description
Unique identifier for the porting.
Example:prt_0SNlurA049MEWV39s2kSYqaat7ZS
required- Name
accountNumber
- Type
- nullable string
- Description
The account number on the donor service provider.
Example:123456789
required- Name
accountPinExists
- Type
- boolean
- Description
Whether the account PIN has been provided.
Example:true
required- Name
address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:2017-07-21
required- Name
declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0
>= 0
required- Name
declinedCode
- Type
- nullable string PREVIEW
- Description
The code reason for the declined porting.
Example:portingPhoneNumberPortProtected
required- Name
declinedMessage
- Type
- nullable string PREVIEW
- Description
The reason description for the declined porting.
Example:The phone number has port protection on the provider.
required- Name
donorProvider
- Type
- nullable object
- Description
- The service provider from whom the number is ported.
required- Name
donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
required- Name
firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:Jerry
required- Name
lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:Seinfeld
required- Name
phoneNumber
- Type
- string
- Description
The phone number to port in E.164 format.
Example:+19591234567
required- Name
provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:p9
required- Name
recipientProvider
- Type
- object
- Description
- The service provider to whom the number is ported.
required- Name
required
- Type
- array
- 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
required- Name
status
- Type
- string
- Description
The current status of the porting.
Allowed values:draft, pending, informationRequired, requested, declined, completed, canceled, expired
required- Name
subscription
- Type
- nullable string
- Description
Unique identifier for the porting subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
user
- Type
- string
- Description
Unique identifier for the user this porting is for.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:2021-01-21T19:39:53Z
required- Name
completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:2021-01-21T19:36:57Z
required- Name
createdAt
- Type
- string
- Description
Time when the porting was created.
Example:2021-01-21T19:12:28Z
required- Name
expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:2021-01-21T19:39:53Z
required- Name
lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:2021-01-21T19:31:13Z
required- Name
lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:2021-01-21T19:22:31Z
required
required- Name
sim
- Type
- nullable object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
sim
.
required- Name
id
- Type
- string
- Description
Unique identifier for the SIM.
Example:sim_0SNlurA049MEWV1BAAmWZULA4lf6
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
iccid
- Type
- string
- Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example:89883070000007537119
required- Name
provider
- Type
- string
- Description
The ID of the network provider of the SIM.
Example:p9
required- Name
status
- Type
- string
- Description
The status of the SIM. Can be
active
orinactive
.Allowed values:inactive, active, retired
required- Name
type
- Type
- string
- Description
The type of the SIM. Can be
eSIM
orpSIM
.Allowed values:eSIM, pSIM
required- Name
createdAt
- Type
- string
- Description
Time when the SIM was created.
Example:2021-01-21T19:38:34Z
required
required- Name
status
- Type
- string
- Description
The current status of the subscription. Note that the
initiated
status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.Allowed values:pending, initiated, active, ended
required- Name
user
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
user
.
required- Name
id
- Type
- string
- Description
Unique identifier for the user.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the user.
Example:2017-07-21
required- Name
email
- Type
- string
- Description
The primary email address of the user.
Example:jerry@example.com
required- Name
emailVerified
- Type
- boolean
- Description
Whether the user's primary email address is verified or not.
Example:true
required- Name
fullName
- Type
- nullable string
- Description
The user's full name. Required for some Plans.
Example:Jerry Seinfeld
required- Name
preferredLocale
- Type
- string
- Description
The user's locale preference represented as an IETF language tag.
Example:en-US
required- Name
createdAt
- Type
- string
- Description
Time when the user was created.
Example:2021-01-21T19:38:34Z
required
required- Name
activatedAt
- Type
- nullable string
- Description
Time when the subscription was activated.
Example:2021-01-21T19:38:34Z
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the subscription was canceled.
Example:2021-01-29T13:22:51Z
required- Name
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
required- 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
required- Name
endedAt
- Type
- nullable string
- Description
Time when the subscription was ended.
Example:2021-02-20T19:38:34Z
required- Name
firstUsageAt
- Type
- nullable string
- Description
Time when the subscription was first used.
Example:2021-01-21T19:38:34Z
required
Request
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"
}
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
- Description
The unique identifier for the project.
Example:gigs
required- Name
id
- Type
- string
- Description
The unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required
Response Schemas
- Name
object
- Type
- string
- Description
Type of object is always
subscription
.
required- Name
id
- Type
- string
- Description
Unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- 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
required- Name
currentPeriod
- Type
- nullable object
- Description
- Current subscription period. Only present for active subscriptions.
- Name
number
- Type
- integer
- Description
Sequence number of the period.
Example:1
>= 1
required- Name
start
- Type
- string
- Description
Beginning of the period.
Example:2021-01-21T19:32:13Z
required- Name
end
- Type
- string
- Description
End of the period.
Example:2021-02-20T19:38:34Z
required
required- Name
phoneNumber
- Type
- nullable string
- Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example:+19591234567
required- Name
plan
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
plan
.
required- Name
id
- Type
- string
- Description
Unique identifier for the plan.
Example:pln_0SNlurA049MEWV3V0q7gjQbM4EVo
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
allowances
- Type
- object
- Description
- The allowances included in the plan.
required- Name
coverage
- Type
- object
- Description
- The geographic coverage of the plan.
required- Name
data
- Type
- integer DEPRECATED
- Description
The data allowance in bytes included in this plan. A value of
-1
indicates unlimited data.Example:10000000000
required- Name
dataUnit
- Type
- string DEPRECATED
- Description
The unit of the data value is always
byte
.
required- Name
description
- Type
- nullable string
- 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.
required- Name
image
- Type
- nullable string
- Description
The plan's image, meant to be displayable to the users.
Example:https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
required- Name
limits
- Type
- object
- Description
- The limitations of the plan.
required- Name
name
- Type
- string
- Description
The plan's name, meant to be displayable to the users.
Example:Gigs Global
required- Name
price
- Type
- object
- Description
- The price of the plan.
required- Name
provider
- Type
- string
- Description
The ID of the network provider supported by this plan.
Example:p5
required- Name
requirements
- Type
- object
- Description
required- Name
simTypes
- Type
- array
- Description
List of SIM types supported by this plan. Can be
eSIM
,pSIM
, or both.Example:eSIM,pSIM
required- Name
sms
- Type
- integer DEPRECATED
- Description
The sms allowance included in this plan. A value of
-1
indicates unlimited sms.Example:100
required- Name
smsUnit
- Type
- string DEPRECATED
- Description
The unit of the sms value is always
message
.
required- Name
status
- Type
- string
- Description
- Allowed values:
available, archived, pending, draft
required- Name
validity
- Type
- object
- Description
- The validity of the plan.
required- Name
voice
- Type
- integer DEPRECATED
- Description
The voice allowance included in this plan. A value of
-1
indicates unlimited voice.Example:30000
required- Name
voiceUnit
- Type
- string DEPRECATED
- Description
The unit of the voice value is always
second
.
required- Name
createdAt
- Type
- string
- Description
Time when the plan was created.
Example:2021-01-21T19:38:34Z
required
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
- Name
object
- Type
- string
- Description
Type of object is always
porting
.
required- Name
id
- Type
- string
- Description
Unique identifier for the porting.
Example:prt_0SNlurA049MEWV39s2kSYqaat7ZS
required- Name
accountNumber
- Type
- nullable string
- Description
The account number on the donor service provider.
Example:123456789
required- Name
accountPinExists
- Type
- boolean
- Description
Whether the account PIN has been provided.
Example:true
required- Name
address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:2017-07-21
required- Name
declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0
>= 0
required- Name
declinedCode
- Type
- nullable string PREVIEW
- Description
The code reason for the declined porting.
Example:portingPhoneNumberPortProtected
required- Name
declinedMessage
- Type
- nullable string PREVIEW
- Description
The reason description for the declined porting.
Example:The phone number has port protection on the provider.
required- Name
donorProvider
- Type
- nullable object
- Description
- The service provider from whom the number is ported.
required- Name
donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
required- Name
firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:Jerry
required- Name
lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:Seinfeld
required- Name
phoneNumber
- Type
- string
- Description
The phone number to port in E.164 format.
Example:+19591234567
required- Name
provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:p9
required- Name
recipientProvider
- Type
- object
- Description
- The service provider to whom the number is ported.
required- Name
required
- Type
- array
- 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
required- Name
status
- Type
- string
- Description
The current status of the porting.
Allowed values:draft, pending, informationRequired, requested, declined, completed, canceled, expired
required- Name
subscription
- Type
- nullable string
- Description
Unique identifier for the porting subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
user
- Type
- string
- Description
Unique identifier for the user this porting is for.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:2021-01-21T19:39:53Z
required- Name
completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:2021-01-21T19:36:57Z
required- Name
createdAt
- Type
- string
- Description
Time when the porting was created.
Example:2021-01-21T19:12:28Z
required- Name
expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:2021-01-21T19:39:53Z
required- Name
lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:2021-01-21T19:31:13Z
required- Name
lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:2021-01-21T19:22:31Z
required
required- Name
sim
- Type
- nullable object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
sim
.
required- Name
id
- Type
- string
- Description
Unique identifier for the SIM.
Example:sim_0SNlurA049MEWV1BAAmWZULA4lf6
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
iccid
- Type
- string
- Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example:89883070000007537119
required- Name
provider
- Type
- string
- Description
The ID of the network provider of the SIM.
Example:p9
required- Name
status
- Type
- string
- Description
The status of the SIM. Can be
active
orinactive
.Allowed values:inactive, active, retired
required- Name
type
- Type
- string
- Description
The type of the SIM. Can be
eSIM
orpSIM
.Allowed values:eSIM, pSIM
required- Name
createdAt
- Type
- string
- Description
Time when the SIM was created.
Example:2021-01-21T19:38:34Z
required
required- Name
status
- Type
- string
- Description
The current status of the subscription. Note that the
initiated
status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.Allowed values:pending, initiated, active, ended
required- Name
user
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
user
.
required- Name
id
- Type
- string
- Description
Unique identifier for the user.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the user.
Example:2017-07-21
required- Name
email
- Type
- string
- Description
The primary email address of the user.
Example:jerry@example.com
required- Name
emailVerified
- Type
- boolean
- Description
Whether the user's primary email address is verified or not.
Example:true
required- Name
fullName
- Type
- nullable string
- Description
The user's full name. Required for some Plans.
Example:Jerry Seinfeld
required- Name
preferredLocale
- Type
- string
- Description
The user's locale preference represented as an IETF language tag.
Example:en-US
required- Name
createdAt
- Type
- string
- Description
Time when the user was created.
Example:2021-01-21T19:38:34Z
required
required- Name
activatedAt
- Type
- nullable string
- Description
Time when the subscription was activated.
Example:2021-01-21T19:38:34Z
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the subscription was canceled.
Example:2021-01-29T13:22:51Z
required- Name
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
required- 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
required- Name
endedAt
- Type
- nullable string
- Description
Time when the subscription was ended.
Example:2021-02-20T19:38:34Z
required- Name
firstUsageAt
- Type
- nullable string
- Description
Time when the subscription was first used.
Example:2021-01-21T19:38:34Z
required
Request
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"
}
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
- Description
The unique identifier for the project.
Example:gigs
required- Name
id
- Type
- string
- Description
The unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required
Response Schemas
- Name
object
- Type
- string
- Description
Type of object is always
subscription
.
required- Name
id
- Type
- string
- Description
Unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- 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
required- Name
currentPeriod
- Type
- nullable object
- Description
- Current subscription period. Only present for active subscriptions.
- Name
number
- Type
- integer
- Description
Sequence number of the period.
Example:1
>= 1
required- Name
start
- Type
- string
- Description
Beginning of the period.
Example:2021-01-21T19:32:13Z
required- Name
end
- Type
- string
- Description
End of the period.
Example:2021-02-20T19:38:34Z
required
required- Name
phoneNumber
- Type
- nullable string
- Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example:+19591234567
required- Name
plan
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
plan
.
required- Name
id
- Type
- string
- Description
Unique identifier for the plan.
Example:pln_0SNlurA049MEWV3V0q7gjQbM4EVo
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
allowances
- Type
- object
- Description
- The allowances included in the plan.
required- Name
coverage
- Type
- object
- Description
- The geographic coverage of the plan.
required- Name
data
- Type
- integer DEPRECATED
- Description
The data allowance in bytes included in this plan. A value of
-1
indicates unlimited data.Example:10000000000
required- Name
dataUnit
- Type
- string DEPRECATED
- Description
The unit of the data value is always
byte
.
required- Name
description
- Type
- nullable string
- 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.
required- Name
image
- Type
- nullable string
- Description
The plan's image, meant to be displayable to the users.
Example:https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
required- Name
limits
- Type
- object
- Description
- The limitations of the plan.
required- Name
name
- Type
- string
- Description
The plan's name, meant to be displayable to the users.
Example:Gigs Global
required- Name
price
- Type
- object
- Description
- The price of the plan.
required- Name
provider
- Type
- string
- Description
The ID of the network provider supported by this plan.
Example:p5
required- Name
requirements
- Type
- object
- Description
required- Name
simTypes
- Type
- array
- Description
List of SIM types supported by this plan. Can be
eSIM
,pSIM
, or both.Example:eSIM,pSIM
required- Name
sms
- Type
- integer DEPRECATED
- Description
The sms allowance included in this plan. A value of
-1
indicates unlimited sms.Example:100
required- Name
smsUnit
- Type
- string DEPRECATED
- Description
The unit of the sms value is always
message
.
required- Name
status
- Type
- string
- Description
- Allowed values:
available, archived, pending, draft
required- Name
validity
- Type
- object
- Description
- The validity of the plan.
required- Name
voice
- Type
- integer DEPRECATED
- Description
The voice allowance included in this plan. A value of
-1
indicates unlimited voice.Example:30000
required- Name
voiceUnit
- Type
- string DEPRECATED
- Description
The unit of the voice value is always
second
.
required- Name
createdAt
- Type
- string
- Description
Time when the plan was created.
Example:2021-01-21T19:38:34Z
required
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
- Name
object
- Type
- string
- Description
Type of object is always
porting
.
required- Name
id
- Type
- string
- Description
Unique identifier for the porting.
Example:prt_0SNlurA049MEWV39s2kSYqaat7ZS
required- Name
accountNumber
- Type
- nullable string
- Description
The account number on the donor service provider.
Example:123456789
required- Name
accountPinExists
- Type
- boolean
- Description
Whether the account PIN has been provided.
Example:true
required- Name
address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:2017-07-21
required- Name
declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0
>= 0
required- Name
declinedCode
- Type
- nullable string PREVIEW
- Description
The code reason for the declined porting.
Example:portingPhoneNumberPortProtected
required- Name
declinedMessage
- Type
- nullable string PREVIEW
- Description
The reason description for the declined porting.
Example:The phone number has port protection on the provider.
required- Name
donorProvider
- Type
- nullable object
- Description
- The service provider from whom the number is ported.
required- Name
donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
required- Name
firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:Jerry
required- Name
lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:Seinfeld
required- Name
phoneNumber
- Type
- string
- Description
The phone number to port in E.164 format.
Example:+19591234567
required- Name
provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:p9
required- Name
recipientProvider
- Type
- object
- Description
- The service provider to whom the number is ported.
required- Name
required
- Type
- array
- 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
required- Name
status
- Type
- string
- Description
The current status of the porting.
Allowed values:draft, pending, informationRequired, requested, declined, completed, canceled, expired
required- Name
subscription
- Type
- nullable string
- Description
Unique identifier for the porting subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
user
- Type
- string
- Description
Unique identifier for the user this porting is for.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:2021-01-21T19:39:53Z
required- Name
completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:2021-01-21T19:36:57Z
required- Name
createdAt
- Type
- string
- Description
Time when the porting was created.
Example:2021-01-21T19:12:28Z
required- Name
expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:2021-01-21T19:39:53Z
required- Name
lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:2021-01-21T19:31:13Z
required- Name
lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:2021-01-21T19:22:31Z
required
required- Name
sim
- Type
- nullable object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
sim
.
required- Name
id
- Type
- string
- Description
Unique identifier for the SIM.
Example:sim_0SNlurA049MEWV1BAAmWZULA4lf6
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
iccid
- Type
- string
- Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example:89883070000007537119
required- Name
provider
- Type
- string
- Description
The ID of the network provider of the SIM.
Example:p9
required- Name
status
- Type
- string
- Description
The status of the SIM. Can be
active
orinactive
.Allowed values:inactive, active, retired
required- Name
type
- Type
- string
- Description
The type of the SIM. Can be
eSIM
orpSIM
.Allowed values:eSIM, pSIM
required- Name
createdAt
- Type
- string
- Description
Time when the SIM was created.
Example:2021-01-21T19:38:34Z
required
required- Name
status
- Type
- string
- Description
The current status of the subscription. Note that the
initiated
status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.Allowed values:pending, initiated, active, ended
required- Name
user
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
user
.
required- Name
id
- Type
- string
- Description
Unique identifier for the user.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the user.
Example:2017-07-21
required- Name
email
- Type
- string
- Description
The primary email address of the user.
Example:jerry@example.com
required- Name
emailVerified
- Type
- boolean
- Description
Whether the user's primary email address is verified or not.
Example:true
required- Name
fullName
- Type
- nullable string
- Description
The user's full name. Required for some Plans.
Example:Jerry Seinfeld
required- Name
preferredLocale
- Type
- string
- Description
The user's locale preference represented as an IETF language tag.
Example:en-US
required- Name
createdAt
- Type
- string
- Description
Time when the user was created.
Example:2021-01-21T19:38:34Z
required
required- Name
activatedAt
- Type
- nullable string
- Description
Time when the subscription was activated.
Example:2021-01-21T19:38:34Z
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the subscription was canceled.
Example:2021-01-29T13:22:51Z
required- Name
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
required- 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
required- Name
endedAt
- Type
- nullable string
- Description
Time when the subscription was ended.
Example:2021-02-20T19:38:34Z
required- Name
firstUsageAt
- Type
- nullable string
- Description
Time when the subscription was first used.
Example:2021-01-21T19:38:34Z
required
Request
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"
}
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
- Description
The unique identifier for the project.
Example:gigs
required- Name
id
- Type
- string
- Description
The unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required
Response Schemas
- Name
object
- Type
- string
- Description
Type of object is always
subscription
.
required- Name
id
- Type
- string
- Description
Unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- 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
required- Name
currentPeriod
- Type
- nullable object
- Description
- Current subscription period. Only present for active subscriptions.
- Name
number
- Type
- integer
- Description
Sequence number of the period.
Example:1
>= 1
required- Name
start
- Type
- string
- Description
Beginning of the period.
Example:2021-01-21T19:32:13Z
required- Name
end
- Type
- string
- Description
End of the period.
Example:2021-02-20T19:38:34Z
required
required- Name
phoneNumber
- Type
- nullable string
- Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example:+19591234567
required- Name
plan
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
plan
.
required- Name
id
- Type
- string
- Description
Unique identifier for the plan.
Example:pln_0SNlurA049MEWV3V0q7gjQbM4EVo
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
allowances
- Type
- object
- Description
- The allowances included in the plan.
required- Name
coverage
- Type
- object
- Description
- The geographic coverage of the plan.
required- Name
data
- Type
- integer DEPRECATED
- Description
The data allowance in bytes included in this plan. A value of
-1
indicates unlimited data.Example:10000000000
required- Name
dataUnit
- Type
- string DEPRECATED
- Description
The unit of the data value is always
byte
.
required- Name
description
- Type
- nullable string
- 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.
required- Name
image
- Type
- nullable string
- Description
The plan's image, meant to be displayable to the users.
Example:https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
required- Name
limits
- Type
- object
- Description
- The limitations of the plan.
required- Name
name
- Type
- string
- Description
The plan's name, meant to be displayable to the users.
Example:Gigs Global
required- Name
price
- Type
- object
- Description
- The price of the plan.
required- Name
provider
- Type
- string
- Description
The ID of the network provider supported by this plan.
Example:p5
required- Name
requirements
- Type
- object
- Description
required- Name
simTypes
- Type
- array
- Description
List of SIM types supported by this plan. Can be
eSIM
,pSIM
, or both.Example:eSIM,pSIM
required- Name
sms
- Type
- integer DEPRECATED
- Description
The sms allowance included in this plan. A value of
-1
indicates unlimited sms.Example:100
required- Name
smsUnit
- Type
- string DEPRECATED
- Description
The unit of the sms value is always
message
.
required- Name
status
- Type
- string
- Description
- Allowed values:
available, archived, pending, draft
required- Name
validity
- Type
- object
- Description
- The validity of the plan.
required- Name
voice
- Type
- integer DEPRECATED
- Description
The voice allowance included in this plan. A value of
-1
indicates unlimited voice.Example:30000
required- Name
voiceUnit
- Type
- string DEPRECATED
- Description
The unit of the voice value is always
second
.
required- Name
createdAt
- Type
- string
- Description
Time when the plan was created.
Example:2021-01-21T19:38:34Z
required
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
- Name
object
- Type
- string
- Description
Type of object is always
porting
.
required- Name
id
- Type
- string
- Description
Unique identifier for the porting.
Example:prt_0SNlurA049MEWV39s2kSYqaat7ZS
required- Name
accountNumber
- Type
- nullable string
- Description
The account number on the donor service provider.
Example:123456789
required- Name
accountPinExists
- Type
- boolean
- Description
Whether the account PIN has been provided.
Example:true
required- Name
address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:2017-07-21
required- Name
declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0
>= 0
required- Name
declinedCode
- Type
- nullable string PREVIEW
- Description
The code reason for the declined porting.
Example:portingPhoneNumberPortProtected
required- Name
declinedMessage
- Type
- nullable string PREVIEW
- Description
The reason description for the declined porting.
Example:The phone number has port protection on the provider.
required- Name
donorProvider
- Type
- nullable object
- Description
- The service provider from whom the number is ported.
required- Name
donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
required- Name
firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:Jerry
required- Name
lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:Seinfeld
required- Name
phoneNumber
- Type
- string
- Description
The phone number to port in E.164 format.
Example:+19591234567
required- Name
provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:p9
required- Name
recipientProvider
- Type
- object
- Description
- The service provider to whom the number is ported.
required- Name
required
- Type
- array
- 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
required- Name
status
- Type
- string
- Description
The current status of the porting.
Allowed values:draft, pending, informationRequired, requested, declined, completed, canceled, expired
required- Name
subscription
- Type
- nullable string
- Description
Unique identifier for the porting subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
user
- Type
- string
- Description
Unique identifier for the user this porting is for.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:2021-01-21T19:39:53Z
required- Name
completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:2021-01-21T19:36:57Z
required- Name
createdAt
- Type
- string
- Description
Time when the porting was created.
Example:2021-01-21T19:12:28Z
required- Name
expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:2021-01-21T19:39:53Z
required- Name
lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:2021-01-21T19:31:13Z
required- Name
lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:2021-01-21T19:22:31Z
required
required- Name
sim
- Type
- nullable object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
sim
.
required- Name
id
- Type
- string
- Description
Unique identifier for the SIM.
Example:sim_0SNlurA049MEWV1BAAmWZULA4lf6
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
iccid
- Type
- string
- Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example:89883070000007537119
required- Name
provider
- Type
- string
- Description
The ID of the network provider of the SIM.
Example:p9
required- Name
status
- Type
- string
- Description
The status of the SIM. Can be
active
orinactive
.Allowed values:inactive, active, retired
required- Name
type
- Type
- string
- Description
The type of the SIM. Can be
eSIM
orpSIM
.Allowed values:eSIM, pSIM
required- Name
createdAt
- Type
- string
- Description
Time when the SIM was created.
Example:2021-01-21T19:38:34Z
required
required- Name
status
- Type
- string
- Description
The current status of the subscription. Note that the
initiated
status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.Allowed values:pending, initiated, active, ended
required- Name
user
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
user
.
required- Name
id
- Type
- string
- Description
Unique identifier for the user.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the user.
Example:2017-07-21
required- Name
email
- Type
- string
- Description
The primary email address of the user.
Example:jerry@example.com
required- Name
emailVerified
- Type
- boolean
- Description
Whether the user's primary email address is verified or not.
Example:true
required- Name
fullName
- Type
- nullable string
- Description
The user's full name. Required for some Plans.
Example:Jerry Seinfeld
required- Name
preferredLocale
- Type
- string
- Description
The user's locale preference represented as an IETF language tag.
Example:en-US
required- Name
createdAt
- Type
- string
- Description
Time when the user was created.
Example:2021-01-21T19:38:34Z
required
required- Name
activatedAt
- Type
- nullable string
- Description
Time when the subscription was activated.
Example:2021-01-21T19:38:34Z
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the subscription was canceled.
Example:2021-01-29T13:22:51Z
required- Name
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
required- 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
required- Name
endedAt
- Type
- nullable string
- Description
Time when the subscription was ended.
Example:2021-02-20T19:38:34Z
required- Name
firstUsageAt
- Type
- nullable string
- Description
Time when the subscription was first used.
Example:2021-01-21T19:38:34Z
required
Request
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"
}
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
- Description
The E.164-formatted phone number associated with the subscription.
Example:+12065550123
required
Path Parameters
- Name
project
- Type
- string
- Description
The unique identifier for the project.
Example:gigs
required
Response Schemas
- Name
object
- Type
- string
- Description
Type of object is always
list
.
required- Name
items
- Type
- array
- Description
List of objects of type
subscription
.
required- Name
moreItemsAfter
- Type
- nullable string
- Description
A unique identifier to be used as
after
pagination parameter if more items are available sorted after the current batch of items.
required- Name
moreItemsBefore
- Type
- nullable string
- Description
A unique identifier to be used as
before
pagination parameter if more items are available sorted before the current batch of items.
required
Request
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
}
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
- Description
The unique identifier for the project.
Example:gigs
required
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,initiated,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
- Description
Type of object is always
list
.
required- Name
items
- Type
- array
- Description
List of objects of type
subscription
.
required- Name
moreItemsAfter
- Type
- nullable string
- Description
A unique identifier to be used as
after
pagination parameter if more items are available sorted after the current batch of items.
required- Name
moreItemsBefore
- Type
- nullable string
- Description
A unique identifier to be used as
before
pagination parameter if more items are available sorted before the current batch of items.
required
Request
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
}
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
- Description
The unique identifier for the existing plan to be used for the subscription.
Example:pln_0SNlurA049MEWV3V0q7gjQbM4EVo
required- 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
- Description
The unique identifier for the existing user to which the subscription will be assigned.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required
Path Parameters
- Name
project
- Type
- string
- Description
The unique identifier for the project.
Example:gigs
required
Response Schemas
- Name
object
- Type
- string
- Description
Type of object is always
subscription
.
required- Name
id
- Type
- string
- Description
Unique identifier for the subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- 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
required- Name
currentPeriod
- Type
- nullable object
- Description
- Current subscription period. Only present for active subscriptions.
- Name
number
- Type
- integer
- Description
Sequence number of the period.
Example:1
>= 1
required- Name
start
- Type
- string
- Description
Beginning of the period.
Example:2021-01-21T19:32:13Z
required- Name
end
- Type
- string
- Description
End of the period.
Example:2021-02-20T19:38:34Z
required
required- Name
phoneNumber
- Type
- nullable string
- Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example:+19591234567
required- Name
plan
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
plan
.
required- Name
id
- Type
- string
- Description
Unique identifier for the plan.
Example:pln_0SNlurA049MEWV3V0q7gjQbM4EVo
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
allowances
- Type
- object
- Description
- The allowances included in the plan.
required- Name
coverage
- Type
- object
- Description
- The geographic coverage of the plan.
required- Name
data
- Type
- integer DEPRECATED
- Description
The data allowance in bytes included in this plan. A value of
-1
indicates unlimited data.Example:10000000000
required- Name
dataUnit
- Type
- string DEPRECATED
- Description
The unit of the data value is always
byte
.
required- Name
description
- Type
- nullable string
- 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.
required- Name
image
- Type
- nullable string
- Description
The plan's image, meant to be displayable to the users.
Example:https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png
required- Name
limits
- Type
- object
- Description
- The limitations of the plan.
required- Name
name
- Type
- string
- Description
The plan's name, meant to be displayable to the users.
Example:Gigs Global
required- Name
price
- Type
- object
- Description
- The price of the plan.
required- Name
provider
- Type
- string
- Description
The ID of the network provider supported by this plan.
Example:p5
required- Name
requirements
- Type
- object
- Description
required- Name
simTypes
- Type
- array
- Description
List of SIM types supported by this plan. Can be
eSIM
,pSIM
, or both.Example:eSIM,pSIM
required- Name
sms
- Type
- integer DEPRECATED
- Description
The sms allowance included in this plan. A value of
-1
indicates unlimited sms.Example:100
required- Name
smsUnit
- Type
- string DEPRECATED
- Description
The unit of the sms value is always
message
.
required- Name
status
- Type
- string
- Description
- Allowed values:
available, archived, pending, draft
required- Name
validity
- Type
- object
- Description
- The validity of the plan.
required- Name
voice
- Type
- integer DEPRECATED
- Description
The voice allowance included in this plan. A value of
-1
indicates unlimited voice.Example:30000
required- Name
voiceUnit
- Type
- string DEPRECATED
- Description
The unit of the voice value is always
second
.
required- Name
createdAt
- Type
- string
- Description
Time when the plan was created.
Example:2021-01-21T19:38:34Z
required
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
- Name
object
- Type
- string
- Description
Type of object is always
porting
.
required- Name
id
- Type
- string
- Description
Unique identifier for the porting.
Example:prt_0SNlurA049MEWV39s2kSYqaat7ZS
required- Name
accountNumber
- Type
- nullable string
- Description
The account number on the donor service provider.
Example:123456789
required- Name
accountPinExists
- Type
- boolean
- Description
Whether the account PIN has been provided.
Example:true
required- Name
address
- Type
- nullable object
- Description
- The address of the account holder on the donor service provider.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the account holder on the donor service provider.
Example:2017-07-21
required- Name
declinedAttempts
- Type
- integer
- Description
The number of declined porting attempts so far.
Example:0
>= 0
required- Name
declinedCode
- Type
- nullable string PREVIEW
- Description
The code reason for the declined porting.
Example:portingPhoneNumberPortProtected
required- Name
declinedMessage
- Type
- nullable string PREVIEW
- Description
The reason description for the declined porting.
Example:The phone number has port protection on the provider.
required- Name
donorProvider
- Type
- nullable object
- Description
- The service provider from whom the number is ported.
required- Name
donorProviderApproval
- Type
- nullable boolean
- Description
Whether the donor provider has approved or not the porting.
Example:true
required- Name
firstName
- Type
- nullable string
- Description
The first name of the account holder on the donor service provider.
Example:Jerry
required- Name
lastName
- Type
- nullable string
- Description
The last name of the account holder on the donor service provider.
Example:Seinfeld
required- Name
phoneNumber
- Type
- string
- Description
The phone number to port in E.164 format.
Example:+19591234567
required- Name
provider
- Type
- string
- Description
The ID of the recipient network provider.
Example:p9
required- Name
recipientProvider
- Type
- object
- Description
- The service provider to whom the number is ported.
required- Name
required
- Type
- array
- 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
required- Name
status
- Type
- string
- Description
The current status of the porting.
Allowed values:draft, pending, informationRequired, requested, declined, completed, canceled, expired
required- Name
subscription
- Type
- nullable string
- Description
Unique identifier for the porting subscription.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
user
- Type
- string
- Description
Unique identifier for the user this porting is for.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the porting was canceled.
Example:2021-01-21T19:39:53Z
required- Name
completedAt
- Type
- nullable string
- Description
Time when the porting was completed.
Example:2021-01-21T19:36:57Z
required- Name
createdAt
- Type
- string
- Description
Time when the porting was created.
Example:2021-01-21T19:12:28Z
required- Name
expiredAt
- Type
- nullable string
- Description
Time when the porting was expired.
Example:2021-01-21T19:39:53Z
required- Name
lastDeclinedAt
- Type
- nullable string
- Description
Time when the porting was last declined.
Example:2021-01-21T19:31:13Z
required- Name
lastRequestedAt
- Type
- nullable string
- Description
Time when the porting was last requested.
Example:2021-01-21T19:22:31Z
required
required- Name
sim
- Type
- nullable object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
sim
.
required- Name
id
- Type
- string
- Description
Unique identifier for the SIM.
Example:sim_0SNlurA049MEWV1BAAmWZULA4lf6
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
iccid
- Type
- string
- Description
The ICCID (integrated circuit card identifier) associated with the SIM.
Example:89883070000007537119
required- Name
provider
- Type
- string
- Description
The ID of the network provider of the SIM.
Example:p9
required- Name
status
- Type
- string
- Description
The status of the SIM. Can be
active
orinactive
.Allowed values:inactive, active, retired
required- Name
type
- Type
- string
- Description
The type of the SIM. Can be
eSIM
orpSIM
.Allowed values:eSIM, pSIM
required- Name
createdAt
- Type
- string
- Description
Time when the SIM was created.
Example:2021-01-21T19:38:34Z
required
required- Name
status
- Type
- string
- Description
The current status of the subscription. Note that the
initiated
status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.Allowed values:pending, initiated, active, ended
required- Name
user
- Type
- object
- Description
- Name
object
- Type
- string
- Description
Type of object is always
user
.
required- Name
id
- Type
- string
- Description
Unique identifier for the user.
Example:usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
required- Name
metadata
- Type
- object PREVIEW
- Description
- A set of key-value pairs, to store metadata related to the resource.
required- Name
birthday
- Type
- nullable string
- Description
The birthday of the user.
Example:2017-07-21
required- Name
email
- Type
- string
- Description
The primary email address of the user.
Example:jerry@example.com
required- Name
emailVerified
- Type
- boolean
- Description
Whether the user's primary email address is verified or not.
Example:true
required- Name
fullName
- Type
- nullable string
- Description
The user's full name. Required for some Plans.
Example:Jerry Seinfeld
required- Name
preferredLocale
- Type
- string
- Description
The user's locale preference represented as an IETF language tag.
Example:en-US
required- Name
createdAt
- Type
- string
- Description
Time when the user was created.
Example:2021-01-21T19:38:34Z
required
required- Name
activatedAt
- Type
- nullable string
- Description
Time when the subscription was activated.
Example:2021-01-21T19:38:34Z
required- Name
canceledAt
- Type
- nullable string
- Description
Time when the subscription was canceled.
Example:2021-01-29T13:22:51Z
required- Name
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
required- 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
required- Name
endedAt
- Type
- nullable string
- Description
Time when the subscription was ended.
Example:2021-02-20T19:38:34Z
required- Name
firstUsageAt
- Type
- nullable string
- Description
Time when the subscription was first used.
Example:2021-01-21T19:38:34Z
required
Request
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"
}