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
- Description
A set of key-value pairs, to store metadata related to the resource.
- 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
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, invoiceUnpaid, 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
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
- 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
earliestEndAt
- Type
- nullable string
- Description
Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."
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
- 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
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
- Name
sim
- Type
- nullable object
- Description
- 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
Response
{
"object": "subscription",
"id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"activatedAt": "2021-01-21T19:38:34Z",
"canceledAt": "2021-01-29T13:22:51Z",
"cancellationDetails": {
"cause": "cancellationRequested",
"userReason": "connectivityIssues"
},
"createdAt": "2021-01-21T19:32:13Z",
"currentPeriod": {
"number": 1,
"start": "2021-01-21T19:32:13Z",
"end": "2021-02-20T19:38:34Z"
},
"earliestEndAt": "2021-02-20T19:38:34Z",
"endedAt": "2021-02-20T19:38:34Z",
"firstUsageAt": "2021-01-21T19: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"
},
"createdAt": "2021-01-21T19:38:34Z",
"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"
],
"status": "available",
"validity": {
"minimumPeriods": 12,
"type": "recurring",
"unit": "day",
"value": 7
},
"data": 10000000000,
"dataUnit": "byte",
"sms": 100,
"smsUnit": "message",
"voice": 30000,
"voiceUnit": "second"
},
"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",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"declinedCode": "portingPhoneNumberPortProtected",
"declinedMessage": "The phone number has port protection on the provider.",
"donorProvider": {
"object": "serviceProvider",
"id": "svp_0SNlurA01K6GY5L0XJffY8",
"name": "AT&T"
},
"donorProviderApproval": true,
"expiredAt": "2021-01-21T19:39:53Z",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"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"
},
"sim": {
"object": "sim",
"id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
"createdAt": "2021-01-21T19:38:34Z",
"iccid": "89883070000007537119",
"provider": "p9",
"status": "inactive",
"type": "eSIM"
},
"status": "pending",
"user": {
"object": "user",
"id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"birthday": "2017-07-21",
"createdAt": "2021-01-21T19:38:34Z",
"email": "jerry@example.com",
"emailVerified": true,
"fullName": "Jerry Seinfeld",
"preferredLocale": "en-US"
}
}
Cancel an active subscription
Cancels a subscription. A canceled subscription still has connectivity, but is no longer renewed.
A canceled subscription is effectively ended at the end of its contract term (as defined by its plan) or, if it is already past the term, at the end of its current period.
A subscription can only be canceled up to one hour before its renewal. If it is canceled after this point, it is effectively only ended at the end of the following period.
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
subscription
- 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
- Description
A set of key-value pairs, to store metadata related to the resource.
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
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, invoiceUnpaid, 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
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
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
earliestEndAt
- Type
- nullable string
- Description
Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."
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- 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
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
required- Name
sim
- Type
- nullable object
- Description
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
required
Request
curl https://api.gigs.com/projects/{project}/subscriptions/{subscription}/cancel \
-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": {},
"activatedAt": "2021-01-21T19:38:34Z",
"canceledAt": "2021-01-29T13:22:51Z",
"cancellationDetails": {
"cause": "cancellationRequested",
"userReason": "connectivityIssues"
},
"createdAt": "2021-01-21T19:32:13Z",
"currentPeriod": {
"number": 1,
"start": "2021-01-21T19:32:13Z",
"end": "2021-02-20T19:38:34Z"
},
"earliestEndAt": "2021-02-20T19:38:34Z",
"endedAt": "2021-02-20T19:38:34Z",
"firstUsageAt": "2021-01-21T19: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"
},
"createdAt": "2021-01-21T19:38:34Z",
"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"
],
"status": "available",
"validity": {
"minimumPeriods": 12,
"type": "recurring",
"unit": "day",
"value": 7
},
"data": 10000000000,
"dataUnit": "byte",
"sms": 100,
"smsUnit": "message",
"voice": 30000,
"voiceUnit": "second"
},
"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",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"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,
"expiredAt": "2021-01-21T19:39:53Z",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"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"
},
"sim": {
"object": "sim",
"id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
"metadata": {},
"createdAt": "2021-01-21T19:38:34Z",
"iccid": "89883070000007537119",
"provider": "p9",
"status": "inactive",
"type": "eSIM"
},
"status": "pending",
"user": {
"object": "user",
"id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"metadata": {},
"birthday": "2017-07-21",
"createdAt": "2021-01-21T19:38:34Z",
"email": "jerry@example.com",
"emailVerified": true,
"fullName": "Jerry Seinfeld",
"preferredLocale": "en-US"
}
}
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
subscription
- 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
- Description
A set of key-value pairs, to store metadata related to the resource.
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
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, invoiceUnpaid, 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
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
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
earliestEndAt
- Type
- nullable string
- Description
Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."
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- 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
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
required- Name
sim
- Type
- nullable object
- Description
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
required
Request
curl https://api.gigs.com/projects/{project}/subscriptions/{subscription}/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": {},
"activatedAt": "2021-01-21T19:38:34Z",
"canceledAt": "2021-01-29T13:22:51Z",
"cancellationDetails": {
"cause": "cancellationRequested",
"userReason": "connectivityIssues"
},
"createdAt": "2021-01-21T19:32:13Z",
"currentPeriod": {
"number": 1,
"start": "2021-01-21T19:32:13Z",
"end": "2021-02-20T19:38:34Z"
},
"earliestEndAt": "2021-02-20T19:38:34Z",
"endedAt": "2021-02-20T19:38:34Z",
"firstUsageAt": "2021-01-21T19: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"
},
"createdAt": "2021-01-21T19:38:34Z",
"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"
],
"status": "available",
"validity": {
"minimumPeriods": 12,
"type": "recurring",
"unit": "day",
"value": 7
},
"data": 10000000000,
"dataUnit": "byte",
"sms": 100,
"smsUnit": "message",
"voice": 30000,
"voiceUnit": "second"
},
"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",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"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,
"expiredAt": "2021-01-21T19:39:53Z",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"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"
},
"sim": {
"object": "sim",
"id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
"metadata": {},
"createdAt": "2021-01-21T19:38:34Z",
"iccid": "89883070000007537119",
"provider": "p9",
"status": "inactive",
"type": "eSIM"
},
"status": "pending",
"user": {
"object": "user",
"id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"metadata": {},
"birthday": "2017-07-21",
"createdAt": "2021-01-21T19:38:34Z",
"email": "jerry@example.com",
"emailVerified": true,
"fullName": "Jerry Seinfeld",
"preferredLocale": "en-US"
}
}
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
subscription
- 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
- Description
A set of key-value pairs, to store metadata related to the resource.
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
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, invoiceUnpaid, 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
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
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
earliestEndAt
- Type
- nullable string
- Description
Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."
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- 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
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
required- Name
sim
- Type
- nullable object
- Description
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
required
Request
curl https://api.gigs.com/projects/{project}/subscriptions/{subscription} \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"
Responses
{
"object": "subscription",
"id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"metadata": {},
"activatedAt": "2021-01-21T19:38:34Z",
"canceledAt": "2021-01-29T13:22:51Z",
"cancellationDetails": {
"cause": "cancellationRequested",
"userReason": "connectivityIssues"
},
"createdAt": "2021-01-21T19:32:13Z",
"currentPeriod": {
"number": 1,
"start": "2021-01-21T19:32:13Z",
"end": "2021-02-20T19:38:34Z"
},
"earliestEndAt": "2021-02-20T19:38:34Z",
"endedAt": "2021-02-20T19:38:34Z",
"firstUsageAt": "2021-01-21T19: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"
},
"createdAt": "2021-01-21T19:38:34Z",
"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"
],
"status": "available",
"validity": {
"minimumPeriods": 12,
"type": "recurring",
"unit": "day",
"value": 7
},
"data": 10000000000,
"dataUnit": "byte",
"sms": 100,
"smsUnit": "message",
"voice": 30000,
"voiceUnit": "second"
},
"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",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"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,
"expiredAt": "2021-01-21T19:39:53Z",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"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"
},
"sim": {
"object": "sim",
"id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
"metadata": {},
"createdAt": "2021-01-21T19:38:34Z",
"iccid": "89883070000007537119",
"provider": "p9",
"status": "inactive",
"type": "eSIM"
},
"status": "pending",
"user": {
"object": "user",
"id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"metadata": {},
"birthday": "2017-07-21",
"createdAt": "2021-01-21T19:38:34Z",
"email": "jerry@example.com",
"emailVerified": true,
"fullName": "Jerry Seinfeld",
"preferredLocale": "en-US"
}
}
Update a subscription
Updates the specified subscription by setting the values of the parameters passed.
Body
- Name
metadata
- Type
- object
- 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
subscription
- 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
- Description
A set of key-value pairs, to store metadata related to the resource.
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
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, invoiceUnpaid, 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
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
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
earliestEndAt
- Type
- nullable string
- Description
Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."
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- 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
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
required- Name
sim
- Type
- nullable object
- Description
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
required
Request
curl https://api.gigs.com/projects/{project}/subscriptions/{subscription} \
-X PATCH \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"metadata\":{}}"
Responses
{
"object": "subscription",
"id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"metadata": {},
"activatedAt": "2021-01-21T19:38:34Z",
"canceledAt": "2021-01-29T13:22:51Z",
"cancellationDetails": {
"cause": "cancellationRequested",
"userReason": "connectivityIssues"
},
"createdAt": "2021-01-21T19:32:13Z",
"currentPeriod": {
"number": 1,
"start": "2021-01-21T19:32:13Z",
"end": "2021-02-20T19:38:34Z"
},
"earliestEndAt": "2021-02-20T19:38:34Z",
"endedAt": "2021-02-20T19:38:34Z",
"firstUsageAt": "2021-01-21T19: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"
},
"createdAt": "2021-01-21T19:38:34Z",
"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"
],
"status": "available",
"validity": {
"minimumPeriods": 12,
"type": "recurring",
"unit": "day",
"value": 7
},
"data": 10000000000,
"dataUnit": "byte",
"sms": 100,
"smsUnit": "message",
"voice": 30000,
"voiceUnit": "second"
},
"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",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"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,
"expiredAt": "2021-01-21T19:39:53Z",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"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"
},
"sim": {
"object": "sim",
"id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
"metadata": {},
"createdAt": "2021-01-21T19:38:34Z",
"iccid": "89883070000007537119",
"provider": "p9",
"status": "inactive",
"type": "eSIM"
},
"status": "pending",
"user": {
"object": "user",
"id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"metadata": {},
"birthday": "2017-07-21",
"createdAt": "2021-01-21T19:38:34Z",
"email": "jerry@example.com",
"emailVerified": true,
"fullName": "Jerry Seinfeld",
"preferredLocale": "en-US"
}
}
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
subscription
- 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
- Description
A set of key-value pairs, to store metadata related to the resource.
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
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, invoiceUnpaid, 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
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
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
earliestEndAt
- Type
- nullable string
- Description
Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."
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- 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
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
required- Name
sim
- Type
- nullable object
- Description
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
required
Request
curl https://api.gigs.com/projects/{project}/subscriptions/{subscription}/resume \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"
Responses
{
"object": "subscription",
"id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"metadata": {},
"activatedAt": "2021-01-21T19:38:34Z",
"canceledAt": "2021-01-29T13:22:51Z",
"cancellationDetails": {
"cause": "cancellationRequested",
"userReason": "connectivityIssues"
},
"createdAt": "2021-01-21T19:32:13Z",
"currentPeriod": {
"number": 1,
"start": "2021-01-21T19:32:13Z",
"end": "2021-02-20T19:38:34Z"
},
"earliestEndAt": "2021-02-20T19:38:34Z",
"endedAt": "2021-02-20T19:38:34Z",
"firstUsageAt": "2021-01-21T19: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"
},
"createdAt": "2021-01-21T19:38:34Z",
"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"
],
"status": "available",
"validity": {
"minimumPeriods": 12,
"type": "recurring",
"unit": "day",
"value": 7
},
"data": 10000000000,
"dataUnit": "byte",
"sms": 100,
"smsUnit": "message",
"voice": 30000,
"voiceUnit": "second"
},
"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",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"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,
"expiredAt": "2021-01-21T19:39:53Z",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"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"
},
"sim": {
"object": "sim",
"id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
"metadata": {},
"createdAt": "2021-01-21T19:38:34Z",
"iccid": "89883070000007537119",
"provider": "p9",
"status": "inactive",
"type": "eSIM"
},
"status": "pending",
"user": {
"object": "user",
"id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"metadata": {},
"birthday": "2017-07-21",
"createdAt": "2021-01-21T19:38:34Z",
"email": "jerry@example.com",
"emailVerified": true,
"fullName": "Jerry Seinfeld",
"preferredLocale": "en-US"
}
}
Search for subscriptions
Searches for existing subscriptions matching the given parameters.
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": {},
"activatedAt": "2021-01-21T19:38:34Z",
"canceledAt": "2021-01-29T13:22:51Z",
"cancellationDetails": {
"cause": "cancellationRequested",
"userReason": "connectivityIssues"
},
"createdAt": "2021-01-21T19:32:13Z",
"currentPeriod": {
"number": 1,
"start": "2021-01-21T19:32:13Z",
"end": "2021-02-20T19:38:34Z"
},
"earliestEndAt": "2021-02-20T19:38:34Z",
"endedAt": "2021-02-20T19:38:34Z",
"firstUsageAt": "2021-01-21T19: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"
},
"createdAt": "2021-01-21T19:38:34Z",
"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"
],
"status": "available",
"validity": {
"minimumPeriods": 12,
"type": "recurring",
"unit": "day",
"value": 7
},
"data": 10000000000,
"dataUnit": "byte",
"sms": 100,
"smsUnit": "message",
"voice": 30000,
"voiceUnit": "second"
},
"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",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"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,
"expiredAt": "2021-01-21T19:39:53Z",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"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"
},
"sim": {
"object": "sim",
"id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
"metadata": {},
"createdAt": "2021-01-21T19:38:34Z",
"iccid": "89883070000007537119",
"provider": "p9",
"status": "inactive",
"type": "eSIM"
},
"status": "pending",
"user": {
"object": "user",
"id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"metadata": {},
"birthday": "2017-07-21",
"createdAt": "2021-01-21T19:38:34Z",
"email": "jerry@example.com",
"emailVerified": true,
"fullName": "Jerry Seinfeld",
"preferredLocale": "en-US"
}
}
],
"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": {},
"activatedAt": "2021-01-21T19:38:34Z",
"canceledAt": "2021-01-29T13:22:51Z",
"cancellationDetails": {
"cause": "cancellationRequested",
"userReason": "connectivityIssues"
},
"createdAt": "2021-01-21T19:32:13Z",
"currentPeriod": {
"number": 1,
"start": "2021-01-21T19:32:13Z",
"end": "2021-02-20T19:38:34Z"
},
"earliestEndAt": "2021-02-20T19:38:34Z",
"endedAt": "2021-02-20T19:38:34Z",
"firstUsageAt": "2021-01-21T19: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"
},
"createdAt": "2021-01-21T19:38:34Z",
"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"
],
"status": "available",
"validity": {
"minimumPeriods": 12,
"type": "recurring",
"unit": "day",
"value": 7
},
"data": 10000000000,
"dataUnit": "byte",
"sms": 100,
"smsUnit": "message",
"voice": 30000,
"voiceUnit": "second"
},
"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",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"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,
"expiredAt": "2021-01-21T19:39:53Z",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"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"
},
"sim": {
"object": "sim",
"id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
"metadata": {},
"createdAt": "2021-01-21T19:38:34Z",
"iccid": "89883070000007537119",
"provider": "p9",
"status": "inactive",
"type": "eSIM"
},
"status": "pending",
"user": {
"object": "user",
"id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"metadata": {},
"birthday": "2017-07-21",
"createdAt": "2021-01-21T19:38:34Z",
"email": "jerry@example.com",
"emailVerified": true,
"fullName": "Jerry Seinfeld",
"preferredLocale": "en-US"
}
}
],
"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 (or
deviceModel
) for activation. If the exact IMEI of the device is known, then it is recommended to create a device and specify its ID here. SeedeviceModel
if the device IMEI is not known. At most one ofdevice
anddeviceModel
may be specified. Trying to link a pSIM to a second device will cause an error.Example:dev_0SNlurA049MEWV55CrA9qMvI2FVJ
- Name
deviceModel
- Type
- nullable string
- Description
The unique identifier for the device model to be linked with the passed SIM. Some network providers require this field (or
device
) for activation. If the device IMEI is not known, but the device model is known, this property can be used in place ofdevice
. At most one ofdevice
anddeviceModel
may be specified.Example:dmd_0SNlurA04OUskUGfGAn3Rh
- Name
metadata
- Type
- object
- 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
- 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
- Description
A set of key-value pairs, to store metadata related to the resource.
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
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, invoiceUnpaid, 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
createdAt
- Type
- string
- Description
Time when the subscription was created.
Example:2021-01-21T19:32:13Z
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
earliestEndAt
- Type
- nullable string
- Description
Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."
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- 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
required- Name
porting
- Type
- nullable object
- Description
- Current porting (if any) related with the subscription.
required- Name
sim
- Type
- nullable object
- Description
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
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\",\"deviceModel\":\"dmd_0SNlurA04OUskUGfGAn3Rh\",\"metadata\":{},\"plan\":\"pln_0SNlurA049MEWV3V0q7gjQbM4EVo\",\"porting\":\"prt_0SNlurA049MEWV39s2kSYqaat7ZS\",\"sim\":\"sim_0SNlurA049MEWV1BAAmWZULA4lf6\",\"userAddress\":\"adr_0SNlurA049MEWV5ELDmnaqVXgTFT\",\"user\":\"usr_0SNlurA049MEWV4OpCwsNyC9Kn2d\"}"
Responses
{
"object": "subscription",
"id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
"metadata": {},
"activatedAt": "2021-01-21T19:38:34Z",
"canceledAt": "2021-01-29T13:22:51Z",
"cancellationDetails": {
"cause": "cancellationRequested",
"userReason": "connectivityIssues"
},
"createdAt": "2021-01-21T19:32:13Z",
"currentPeriod": {
"number": 1,
"start": "2021-01-21T19:32:13Z",
"end": "2021-02-20T19:38:34Z"
},
"earliestEndAt": "2021-02-20T19:38:34Z",
"endedAt": "2021-02-20T19:38:34Z",
"firstUsageAt": "2021-01-21T19: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"
},
"createdAt": "2021-01-21T19:38:34Z",
"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"
],
"status": "available",
"validity": {
"minimumPeriods": 12,
"type": "recurring",
"unit": "day",
"value": 7
},
"data": 10000000000,
"dataUnit": "byte",
"sms": 100,
"smsUnit": "message",
"voice": 30000,
"voiceUnit": "second"
},
"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",
"canceledAt": "2021-01-21T19:39:53Z",
"completedAt": "2021-01-21T19:36:57Z",
"createdAt": "2021-01-21T19:12:28Z",
"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,
"expiredAt": "2021-01-21T19:39:53Z",
"firstName": "Jerry",
"lastDeclinedAt": "2021-01-21T19:31:13Z",
"lastName": "Seinfeld",
"lastRequestedAt": "2021-01-21T19:22:31Z",
"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"
},
"sim": {
"object": "sim",
"id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
"metadata": {},
"createdAt": "2021-01-21T19:38:34Z",
"iccid": "89883070000007537119",
"provider": "p9",
"status": "inactive",
"type": "eSIM"
},
"status": "pending",
"user": {
"object": "user",
"id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
"metadata": {},
"birthday": "2017-07-21",
"createdAt": "2021-01-21T19:38:34Z",
"email": "jerry@example.com",
"emailVerified": true,
"fullName": "Jerry Seinfeld",
"preferredLocale": "en-US"
}
}