Subscriptions

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.
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 phoneNumberPortedOut portingExpired simUnusable 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 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"

Example

{
  "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",
    "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"
        }
      ]
    },
    "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",
    "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",
    "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"
        }
      ]
    },
    "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"
  }
}

GET/projects/{project}/subscriptions

Create a subscription

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

Body

Name
billing
Type
nullable object
Description
Configuration for this specific subscription billing. Only available when the Billing API is enabled.
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. See deviceModel if the device IMEI is not known. At most one of device and deviceModel 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 of device. At most one of device and deviceModel may be specified.
Example: "dmd_0SNlurA04OUskUGfGAn3Rh"
Name
metadata
Type
Metadata
Description
A set of key-value pairs, to store metadata related to the resource.
Name
fromSubscription
Type
nullable string
Description
The unique identifier for an existing ended subscription to base the new subscription on. The referenced subscription must have status ended and its SIM must still be usable (not retired, not ported out, and for eSIMs, the profile must not be deleted). When provided, the user, plan, SIM, billing settings, and applicable discounts are copied from the referenced subscription. Cannot be combined with user, plan, sim, porting, device, deviceModel, userAddress, or billing.
Name
plan
Type
nullable string
Description
The unique identifier for the existing plan to be used for the subscription. Required if fromSubscription is not provided.
Example: "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
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, or preferLastUsed to reuse the user's most recently used SIM from an ended subscription. preferLastUsed falls back to auto if no eligible SIM is found, which only works for eSIM-capable plans; for plans requiring a physical SIM, subscription creation will fail if no eligible SIM is found.
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
nullable string
Description
The unique identifier for the existing user to which the subscription will be assigned. Required if fromSubscription is not provided.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Path Parameters

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

Responses

Returns the newly created subscription and supporting objects.

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 phoneNumberPortedOut portingExpired simUnusable 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 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"

Request

POST

/projects/{project}/subscriptions

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
    },
    "invoiceGracePeriodDays": 3,
    "invoiceOverduePeriodDays": 1,
    "invoiceOverdueAction": "end"
  },
  "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",
  "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",
    "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",
  "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "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:34Z",
    "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: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",
    "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "scheduledOn": "2021-01-21",
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  }
}

GET/projects/{project}/subscriptions/{subscription}

Retrieve a subscription

Retrieves the details of an existing subscription. You need only supply the unique subscription identifier that was returned upon purchasing a plan.

Path Parameters

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

Responses

Returns the subscription if it exists.

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 phoneNumberPortedOut portingExpired simUnusable 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 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"

Request

GET

/projects/{project}/subscriptions/{subscription}

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/{subscription} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Responses

{
  "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",
    "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",
  "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "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:34Z",
    "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: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",
    "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "scheduledOn": "2021-01-21",
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  }
}

PATCH/projects/{project}/subscriptions/{subscription}

Update a subscription

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

Body

Name
metadata
Type
Metadata
Description
A set of key-value pairs, to store metadata related to the resource.
Name
billing
Type
object
Description
Configuration for this specific subscription billing. Only available when the Billing API is enabled.
Name
userAddress
Type
string
Status
PREVIEW
Description
The unique identifier for an existing user address to be used for the subscription.

Once a subscription has a user address it cannot be removed, only updated to a different user address. Only available for active subscriptions.
Example: "adr_0SNlurA049MEWV5ELDmnaqVXgTFT"

Path Parameters

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

Responses

Returns the updated subscription.

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 phoneNumberPortedOut portingExpired simUnusable 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 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"

Request

PATCH

/projects/{project}/subscriptions/{subscription}

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/{subscription} \
-X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
  "metadata": {},
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
    },
    "invoiceGracePeriodDays": 3,
    "invoiceOverduePeriodDays": 1,
    "invoiceOverdueAction": "end"
  },
  "userAddress": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
}'

Responses

{
  "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",
    "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",
  "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "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:34Z",
    "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: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",
    "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "scheduledOn": "2021-01-21",
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  }
}

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

Cancel an active subscription

Cancels a subscription. A canceled subscription still has connectivity, but is no longer renewed.

A canceled subscription is 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.

Note that the status of a subscription that has been canceled will remain active until the endedAt date is reached, at which point it will be updated to ended.

A subscription can only be canceled up to one hour before its renewal. If it is canceled after this point, it will be ended after the following period.

A canceled subscription that hasn't yet ended can be resumed.

Note: Cancellation is rejected when the subscription might never activate on its own, e.g. the porting has not been submitted to the provider yet. Use the end endpoint instead to immediately terminate the subscription.

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

Path Parameters

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

Responses

Returns the subscription after a successful cancellation.

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 phoneNumberPortedOut portingExpired simUnusable 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 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"

Request

POST

/projects/{project}/subscriptions/{subscription}/cancel

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/{subscription}/cancel \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
  "cancellationDetails": {
    "userReason": "connectivityIssues"
  }
}'

Responses

{
  "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",
    "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",
  "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "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:34Z",
    "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: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",
    "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "scheduledOn": "2021-01-21",
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  }
}

POST/projects/{project}/subscriptions/{subscription}/portIn

Port a phone number into a subscription

Port a phone number into an active subscription.

The subscription remains activated and connected to the old phone number until the porting is completed. After the porting is completed, the phone number of this subscription is updated.

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
porting
Type
string
required
Description
The unique identifier for the existing draft porting to be requested for this subscription.
Example: "prt_0SNlurA049MEWV39s2kSYqaat7ZS"

Path Parameters

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

Responses

Returns the subscription after successfully requesting the port in.

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 phoneNumberPortedOut portingExpired simUnusable 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 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"

Request

POST

/projects/{project}/subscriptions/{subscription}/portIn

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/{subscription}/portIn \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
  "porting": "prt_0SNlurA049MEWV39s2kSYqaat7ZS"
}'

Responses

{
  "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",
    "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",
  "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "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:34Z",
    "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: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",
    "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "scheduledOn": "2021-01-21",
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  }
}

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

End a subscription immediately

Ends a subscriptions immediately given its identifier.

Additionally, you can pass in optional cancellation details in the request body, which 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

Path Parameters

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

Responses

Returns the ended subscription after a successful termination.

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 phoneNumberPortedOut portingExpired simUnusable 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 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"

Request

POST

/projects/{project}/subscriptions/{subscription}/end

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/{subscription}/end \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
  "cancellationDetails": {
    "userReason": "connectivityIssues"
  }
}'

Responses

{
  "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",
    "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",
  "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "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:34Z",
    "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: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",
    "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "scheduledOn": "2021-01-21",
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  }
}

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

Resume a canceled subscription

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

Path Parameters

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

Responses

Returns the resumed subscription.

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 phoneNumberPortedOut portingExpired simUnusable 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 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"

Request

POST

/projects/{project}/subscriptions/{subscription}/resume

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/{subscription}/resume \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Responses

{
  "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",
    "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",
  "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "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:34Z",
    "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: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",
    "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:28Z",
    "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",
    "failedAt": "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",
      "accountType",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "scheduledOn": "2021-01-21",
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  }
}

POST/projects/{project}/subscriptions/search

Search for subscriptions

Searches for existing subscriptions matching the given parameters.

Body

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

Path Parameters

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

Responses

Returns a list schema response with all found subscriptions.

Name
object
Type
string
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
Description
List of objects of type subscription.
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.
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.

Request

POST

/projects/{project}/subscriptions/search

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptions/search \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
  "phoneNumber": "+12065550123"
}'

Responses

{
  "object": "list",
  "items": [
    {
      "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",
        "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",
      "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:28Z",
        "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",
        "failedAt": "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",
          "accountType",
          "address",
          "birthday",
          "donorProvider",
          "donorProviderApproval",
          "firstName",
          "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:34Z",
        "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: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",
        "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:28Z",
        "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",
        "failedAt": "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",
          "accountType",
          "address",
          "birthday",
          "donorProvider",
          "donorProviderApproval",
          "firstName",
          "lastName"
        ],
        "scheduledOn": "2021-01-21",
        "status": "draft",
        "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
        "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
      }
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

Subscriptions

Properties

Example

Path Parameters

Query Parameters

Responses

Request

Responses

Body

Path Parameters

Responses

Request

Responses

Path Parameters

Responses

Request

Responses

Body

Path Parameters

Responses

Request

Responses

Body

Path Parameters

Responses

Request

Responses

Preview

Body

Path Parameters

Responses

Request

Responses

Body

Path Parameters

Responses

Request

Responses

Path Parameters

Responses

Request

Responses

Body

Path Parameters

Responses

Request

Responses