Subscription

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.

Name
object
Type
string
Description
Type of object is always subscription.
Allowed values: subscription
Name
id
Type
string
Description
Unique identifier for the subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
metadata
Type
Metadata
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
billing
Type
nullable object
Description
Billing details for the subscription. Present when Billing is enabled on your project.
Name
discount
Type
nullable object
Description
Discount currently applied to the subscription.
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.
Optional: This property may not always be included.
Allowed values: cancellationRequested deviceBlocked 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.
Optional: This property may not always be included.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Optional: This property may not always be included.
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
Name
start
Type
string
Description
Beginning of the period.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Example: "2021-02-20T19:38:34Z"
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
Plan
Description
Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users.
Name
porting
Type
nullable object
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
Description
A SIM is a unique card that identifies itself to a specific mobile network and provides voice, text, and data connectivity to a user’s device. There are two types of available SIMs: eSIM and pSIM. eSIMs can be activated and installed instantly on any eSIM compatible device, pSIMs (physical SIMs) must be provided to the user or installed into the device beforehand.
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
User
Description
Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions.

Example

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "activatedAt": "2021-01-21T19:38:34Z",
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "expiresAt": "2021-02-20T19:38:34Z"
    }
  },
  "canceledAt": "2021-01-29T13:22:51Z",
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userComment": "",
    "userReason": "connectivityIssues"
  },
  "createdAt": "2021-01-21T19:32:13.0Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13.0Z",
    "end": "2021-02-20T19:38:34.0Z"
  },
  "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:34.0Z",
    "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": -100000000,
      "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 5",
      "postalCode": "10024",
      "state": "NY"
    },
    "behavior": "portIn",
    "birthday": "2017-07-21",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28.0Z",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "country": "US",
      "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",
      "country": "US",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "scheduledOn": "2021-01-21",
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "createdAt": "2021-01-21T19:38:34.0Z",
    "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:34.0Z",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US"
  }
}