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
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 deviceNotSupported invoiceUnpaid paymentDisputed paymentFailed phoneNumberExpired phoneNumberPortedOut portingExpired projectDeleted simSuspensionExpired simUnusable subscriptionEnded suspectedPortOut 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 Period
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
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 will end or has ended. This field is populated in different scenarios:

When a subscription is canceled, this represents the future date when it will be terminated

When a subscription has already ended, this represents the past date when it was terminated

For active subscriptions, this field is null
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
lastPorting
Type
nullable Porting
Description
Last porting (if any) related with the subscription.
Name
phoneNumber
Type
nullable string
Description
The phone number attached to the SIM in E.164 string_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
restoreRequestedAt
Type
nullable string
Description
Time when a restore was requested for the subscription. It is set when a restore is accepted and cleared once the restore completes.
Example: "2021-02-21T19:38:34Z"
Name
restrictedAt
Type
nullable string
Description
Time when the subscription was restricted.
Example: "2021-02-21T19:38:34Z"
Name
restrictionDetails
Type
nullable object
Description
Details about the restriction applied to the subscription. Present when the subscription is restricted.
Name
restrictBehavior
Type
string
Description
Determines how the subscription is restricted. It can have one of the following values:

incomingOnly: The subscription line can receive calls & SMS, but cannot make calls, send SMS, or use data.

noData: The subscription line can make and receive calls & SMS, but cannot use data.

throttledData: The subscription line can still make and receive calls & SMS, and use up to 1GB of data at a reduced speed.

Example: "incomingOnly"
Allowed values: incomingOnly noData throttledData
Name
restoreBehavior
Type
string
Description
Determines how the subscription is restored. It can have one of the following values:

resetPeriodAnchor: The subscription cycle is reset to the date of restoration. This means the user has a whole new period to use their plan allowance that was just restored.

keepPeriodAnchor: The subscription cycle remains unchanged. The next renewal date stays the same as before the restriction.

Example: "resetPeriodAnchor"
Allowed values: keepPeriodAnchor resetPeriodAnchor
Name
cause
Type
string
Description
Determines the cause that triggered the subscription restriction. It can have one of the following values:

invoiceOverdue: The subscription was automatically restricted due to an unpaid invoice that has become overdue.

restrictionRequested: The subscription was manually restricted due to an explicit request.

Example: "invoiceOverdue"
Allowed values: invoiceOverdue restrictionRequested
Name
sim
Type
nullable Sim
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 restricted ended
Name
user
Type
User
Description
Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions.
Name
userAddress
Type
nullable string
Description
Current user address identifier (if any) related with the subscription.
Example: "adr_0SNlurA049MEWV5ELDmnaqVXgTFT"

Subscription object

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "activatedAt": "2021-01-21T19:38:34Z",
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "expiresAt": "2021-02-20T19:38:34Z"
    },
    "invoiceGracePeriodDays": 3,
    "invoiceOverduePeriodDays": 1,
    "invoiceOverdueAction": null,
    "restrictBehavior": null,
    "restoreBehavior": null
  },
  "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",
  "lastPorting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "accountType": "prepaidUnregistered",
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5",
      "postalCode": "10024",
      "state": "NY"
    },
    "behavior": "portIn",
    "billingPinExists": true,
    "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": [
        {
          "0": "p",
          "1": "3"
        }
      ]
    },
    "donorProviderApproval": true,
    "expiredAt": "2021-01-21T19:39:53Z",
    "failedAt": "2021-01-21T19:39:53Z",
    "failureReason": "consentNotGiven",
    "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": [
        {
          "0": "p",
          "1": "3"
        }
      ]
    },
    "requestBehavior": "automatic",
    "required": {
      "0": "accountNumber",
      "1": "accountPin",
      "2": "accountType",
      "3": "address",
      "4": "birthday",
      "5": "donorProvider",
      "6": "donorProviderApproval",
      "7": "firstName",
      "8": "lastName"
    },
    "scheduledOn": "2021-01-21",
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  },
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "activationTrigger": "creation",
    "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.",
    "firstPeriodTrigger": "creation",
    "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"
  },
  "restoreRequestedAt": "2021-02-21T19:38:34Z",
  "restrictedAt": "2021-02-21T19:38:34Z",
  "restrictionDetails": {
    "restrictBehavior": "incomingOnly",
    "restoreBehavior": "resetPeriodAnchor",
    "cause": "invoiceOverdue"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "createdAt": "2021-01-21T19:38:34.0Z",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "suspension": null,
    "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",
    "status": "active"
  },
  "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "accountType": "prepaidUnregistered",
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5",
      "postalCode": "10024",
      "state": "NY"
    },
    "behavior": "portIn",
    "billingPinExists": true,
    "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": [
        {
          "0": "p",
          "1": "3"
        }
      ]
    },
    "donorProviderApproval": true,
    "expiredAt": "2021-01-21T19:39:53Z",
    "failedAt": "2021-01-21T19:39:53Z",
    "failureReason": "consentNotGiven",
    "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": [
        {
          "0": "p",
          "1": "3"
        }
      ]
    },
    "requestBehavior": "automatic",
    "required": {
      "0": "accountNumber",
      "1": "accountPin",
      "2": "accountType",
      "3": "address",
      "4": "birthday",
      "5": "donorProvider",
      "6": "donorProviderApproval",
      "7": "firstName",
      "8": "lastName"
    },
    "scheduledOn": "2021-01-21",
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  }
}