Subscriptions

The Subscription resource

Subscriptions are tied to a user and are created once a user has a plan and SIM. This allows connectivity for their device and SIM.

Properties

Name
object
Type
string
Description
Type of object is always subscription.
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
canceledAt
Type
nullable string
Description
Time when the subscription was canceled.
Example: "2021-01-29T13:22:51Z"
Name
cancellationDetails
Type
nullable object
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, invoiceUnpaid, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
createdAt
Type
string
Description
Time when the subscription was created.
Example: "2021-01-21T19:32:13Z"
Name
currentPeriod
Type
nullable object
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
required
Description
End of the period.
Example: "2021-02-20T19:38:34Z"
Name
earliestEndAt
Type
nullable string
Description
Earliest time at which the subscription can currently be ended. This depends on the minimum period of the plan. This value is present after the first period has already started, and before the subscription has ended."
Example: "2021-02-20T19:38:34Z"
Name
endedAt
Type
nullable string
Description
Time when the subscription was ended.
Example: "2021-02-20T19:38:34Z"
Name
firstUsageAt
Type
nullable string
Description
Time when the subscription was first used.
Example: "2021-01-21T19:38:34Z"
Name
phoneNumber
Type
nullable string
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: "+19591234567"
Name
plan
Type
Plan
Description
Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users.
Name
porting
Type
nullable object
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
Description
A SIM is a unique card that identifies itself to a specific mobile network and provides voice, text, and data connectivity to a user’s device. There are two types of available SIMs: eSIM and pSIM. eSIMs can be activated and installed instantly on any eSIM compatible device, pSIMs (physical SIMs) must be provided to the user or installed into the device beforehand.
Name
status
Type
string
Description
The current status of the subscription. Note that the initiated status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.
Allowed values: pending, initiated, active, ended
Name
user
Type
User
Description
Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions.

Response

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "createdAt": "2021-01-21T19:32:13Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z",
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:38:34Z",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T"
    },
    "donorProviderApproval": true,
    "expiredAt": "2021-01-21T19:39:53Z",
    "firstName": "Jerry",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastName": "Seinfeld",
    "lastRequestedAt": "2021-01-21T19:22:31Z",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T"
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "createdAt": "2021-01-21T19:38:34Z",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "birthday": "2017-07-21",
    "createdAt": "2021-01-21T19:38:34Z",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US"
  }
}

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 effectively ended at the end of its contract term (as defined by its plan) or, if it is already past the term, at the end of its current period.

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

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

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
required
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"

Response Schemas

Returns the subscription after a successful cancellation.

Name
object
Type
string
required
Description
Type of object is always subscription.
Allowed values: subscription
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: "2021-01-21T19:38:34Z"
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: "2021-01-29T13:22:51Z"
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, invoiceUnpaid, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: "2021-01-21T19:32:13Z"
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
required
Description
End of the period.
Example: "2021-02-20T19:38:34Z"
Name
earliestEndAt
Type
nullable string
required
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
required
Description
Time when the subscription was ended.
Example: "2021-02-20T19:38:34Z"
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: "2021-01-21T19:38:34Z"
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: "+19591234567"
Name
plan
Type
Plan
required
Description
Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users.
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
A SIM is a unique card that identifies itself to a specific mobile network and provides voice, text, and data connectivity to a user’s device. There are two types of available SIMs: eSIM and pSIM. eSIMs can be activated and installed instantly on any eSIM compatible device, pSIMs (physical SIMs) must be provided to the user or installed into the device beforehand.
Name
status
Type
string
required
Description
The current status of the subscription. Note that the initiated status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.
Allowed values: pending, initiated, active, ended
Name
user
Type
User
required
Description
Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions.

Request

POST

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

curl https://api.gigs.com/projects/{project}/subscriptions/{subscription}/cancel \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"cancellationDetails\":{\"userReason\":\"connectivityIssues\"}}"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "createdAt": "2021-01-21T19:32:13Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z",
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:38:34Z",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "expiredAt": "2021-01-21T19:39:53Z",
    "firstName": "Jerry",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastName": "Seinfeld",
    "lastRequestedAt": "2021-01-21T19:22:31Z",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "createdAt": "2021-01-21T19:38:34Z",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "createdAt": "2021-01-21T19:38:34Z",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US"
  }
}

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

End an active subscription

Ends an active plan subscription immediately. You only need to supply the unique subscription identifier which was generated on subscription creation.

Additionally, you can pass in optional cancellation details in the request body. These will be used to provide more context on why the subscription was ended.

Body

Name
cancellationDetails
Type
nullable object
Description
Details about the cancellation of the subscription.
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
string
required
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"

Response Schemas

Returns the ended subscription after a successful termination.

Name
object
Type
string
required
Description
Type of object is always subscription.
Allowed values: subscription
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: "2021-01-21T19:38:34Z"
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: "2021-01-29T13:22:51Z"
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, invoiceUnpaid, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: "2021-01-21T19:32:13Z"
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
required
Description
End of the period.
Example: "2021-02-20T19:38:34Z"
Name
earliestEndAt
Type
nullable string
required
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
required
Description
Time when the subscription was ended.
Example: "2021-02-20T19:38:34Z"
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: "2021-01-21T19:38:34Z"
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: "+19591234567"
Name
plan
Type
Plan
required
Description
Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users.
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
A SIM is a unique card that identifies itself to a specific mobile network and provides voice, text, and data connectivity to a user’s device. There are two types of available SIMs: eSIM and pSIM. eSIMs can be activated and installed instantly on any eSIM compatible device, pSIMs (physical SIMs) must be provided to the user or installed into the device beforehand.
Name
status
Type
string
required
Description
The current status of the subscription. Note that the initiated status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.
Allowed values: pending, initiated, active, ended
Name
user
Type
User
required
Description
Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions.

Request

POST

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

curl https://api.gigs.com/projects/{project}/subscriptions/{subscription}/end \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"cancellationDetails\":{\"userReason\":\"connectivityIssues\"}}"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "createdAt": "2021-01-21T19:32:13Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z",
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:38:34Z",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "expiredAt": "2021-01-21T19:39:53Z",
    "firstName": "Jerry",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastName": "Seinfeld",
    "lastRequestedAt": "2021-01-21T19:22:31Z",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "createdAt": "2021-01-21T19:38:34Z",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "createdAt": "2021-01-21T19:38:34Z",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US"
  }
}

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"

Response Schemas

Returns the subscription if it exists.

Name
object
Type
string
required
Description
Type of object is always subscription.
Allowed values: subscription
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: "2021-01-21T19:38:34Z"
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: "2021-01-29T13:22:51Z"
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, invoiceUnpaid, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: "2021-01-21T19:32:13Z"
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
required
Description
End of the period.
Example: "2021-02-20T19:38:34Z"
Name
earliestEndAt
Type
nullable string
required
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
required
Description
Time when the subscription was ended.
Example: "2021-02-20T19:38:34Z"
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: "2021-01-21T19:38:34Z"
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: "+19591234567"
Name
plan
Type
Plan
required
Description
Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users.
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
A SIM is a unique card that identifies itself to a specific mobile network and provides voice, text, and data connectivity to a user’s device. There are two types of available SIMs: eSIM and pSIM. eSIMs can be activated and installed instantly on any eSIM compatible device, pSIMs (physical SIMs) must be provided to the user or installed into the device beforehand.
Name
status
Type
string
required
Description
The current status of the subscription. Note that the initiated status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.
Allowed values: pending, initiated, active, ended
Name
user
Type
User
required
Description
Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions.

Request

GET

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

curl https://api.gigs.com/projects/{project}/subscriptions/{subscription} \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "createdAt": "2021-01-21T19:32:13Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z",
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:38:34Z",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "expiredAt": "2021-01-21T19:39:53Z",
    "firstName": "Jerry",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastName": "Seinfeld",
    "lastRequestedAt": "2021-01-21T19:22:31Z",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "createdAt": "2021-01-21T19:38:34Z",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "createdAt": "2021-01-21T19:38:34Z",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US"
  }
}

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.

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"

Response Schemas

Returns the updated subscription.

Name
object
Type
string
required
Description
Type of object is always subscription.
Allowed values: subscription
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: "2021-01-21T19:38:34Z"
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: "2021-01-29T13:22:51Z"
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, invoiceUnpaid, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: "2021-01-21T19:32:13Z"
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
required
Description
End of the period.
Example: "2021-02-20T19:38:34Z"
Name
earliestEndAt
Type
nullable string
required
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
required
Description
Time when the subscription was ended.
Example: "2021-02-20T19:38:34Z"
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: "2021-01-21T19:38:34Z"
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: "+19591234567"
Name
plan
Type
Plan
required
Description
Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users.
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
A SIM is a unique card that identifies itself to a specific mobile network and provides voice, text, and data connectivity to a user’s device. There are two types of available SIMs: eSIM and pSIM. eSIMs can be activated and installed instantly on any eSIM compatible device, pSIMs (physical SIMs) must be provided to the user or installed into the device beforehand.
Name
status
Type
string
required
Description
The current status of the subscription. Note that the initiated status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.
Allowed values: pending, initiated, active, ended
Name
user
Type
User
required
Description
Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions.

Request

PATCH

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

curl https://api.gigs.com/projects/{project}/subscriptions/{subscription} \
-X PATCH \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"metadata\":{}}"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "createdAt": "2021-01-21T19:32:13Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z",
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:38:34Z",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "expiredAt": "2021-01-21T19:39:53Z",
    "firstName": "Jerry",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastName": "Seinfeld",
    "lastRequestedAt": "2021-01-21T19:22:31Z",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "createdAt": "2021-01-21T19:38:34Z",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "createdAt": "2021-01-21T19:38:34Z",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US"
  }
}

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"

Response Schemas

Returns the resumed subscription.

Name
object
Type
string
required
Description
Type of object is always subscription.
Allowed values: subscription
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: "2021-01-21T19:38:34Z"
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: "2021-01-29T13:22:51Z"
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, invoiceUnpaid, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: "2021-01-21T19:32:13Z"
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
required
Description
End of the period.
Example: "2021-02-20T19:38:34Z"
Name
earliestEndAt
Type
nullable string
required
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
required
Description
Time when the subscription was ended.
Example: "2021-02-20T19:38:34Z"
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: "2021-01-21T19:38:34Z"
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: "+19591234567"
Name
plan
Type
Plan
required
Description
Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users.
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
A SIM is a unique card that identifies itself to a specific mobile network and provides voice, text, and data connectivity to a user’s device. There are two types of available SIMs: eSIM and pSIM. eSIMs can be activated and installed instantly on any eSIM compatible device, pSIMs (physical SIMs) must be provided to the user or installed into the device beforehand.
Name
status
Type
string
required
Description
The current status of the subscription. Note that the initiated status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.
Allowed values: pending, initiated, active, ended
Name
user
Type
User
required
Description
Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions.

Request

POST

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

curl https://api.gigs.com/projects/{project}/subscriptions/{subscription}/resume \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "createdAt": "2021-01-21T19:32:13Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z",
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:38:34Z",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "expiredAt": "2021-01-21T19:39:53Z",
    "firstName": "Jerry",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastName": "Seinfeld",
    "lastRequestedAt": "2021-01-21T19:22:31Z",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "createdAt": "2021-01-21T19:38:34Z",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "createdAt": "2021-01-21T19:38:34Z",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US"
  }
}

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"

Response Schemas

Returns a list schema response with all found subscriptions.

Name
object
Type
string
required
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
required
Description
List of objects of type `subscription`.
Name
moreItemsAfter
Type
nullable string
required
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
required
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/{project}/subscriptions/search \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"phoneNumber\":\"+12065550123\"}"

Responses

{
  "object": "list",
  "items": [
    {
      "object": "subscription",
      "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "metadata": {},
      "activatedAt": "2021-01-21T19:38:34Z",
      "canceledAt": "2021-01-29T13:22:51Z",
      "cancellationDetails": {
        "cause": "cancellationRequested",
        "userReason": "connectivityIssues"
      },
      "createdAt": "2021-01-21T19:32:13Z",
      "currentPeriod": {
        "number": 1,
        "start": "2021-01-21T19:32:13Z",
        "end": "2021-02-20T19:38:34Z"
      },
      "earliestEndAt": "2021-02-20T19:38:34Z",
      "endedAt": "2021-02-20T19:38:34Z",
      "firstUsageAt": "2021-01-21T19:38:34Z",
      "phoneNumber": "+19591234567",
      "plan": {
        "object": "plan",
        "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
        "metadata": {},
        "allowances": {
          "dataBytes": 10000000000,
          "voiceSeconds": 30000,
          "smsMessages": 100
        },
        "coverage": {
          "object": "coverage",
          "id": "de",
          "countries": [
            "DE",
            "FR",
            "US"
          ],
          "name": "Europe"
        },
        "createdAt": "2021-01-21T19:38:34Z",
        "description": "A data plan you will love! Operates in most countries of the world.",
        "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
        "limits": {
          "dataBytes": 100000000000,
          "bandwidthBitsPerSecond": null,
          "throttling": {
            "thresholdBytes": 10000000000,
            "bandwidthBitsPerSecond": 512000
          }
        },
        "name": "Gigs Global",
        "price": {
          "amount": 999,
          "currency": "USD"
        },
        "provider": "p5",
        "requirements": {
          "address": "present",
          "device": "none",
          "user.birthday": "none",
          "user.fullName": "present"
        },
        "simTypes": [
          "eSIM",
          "pSIM"
        ],
        "status": "available",
        "validity": {
          "minimumPeriods": 12,
          "type": "recurring",
          "unit": "day",
          "value": 7
        },
        "data": 10000000000,
        "dataUnit": "byte",
        "sms": 100,
        "smsUnit": "message",
        "voice": 30000,
        "voiceUnit": "second"
      },
      "porting": {
        "object": "porting",
        "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
        "accountNumber": "123456789",
        "accountPinExists": true,
        "address": {
          "city": "New York City",
          "country": "US",
          "line1": "129 West 81st Street",
          "line2": "Apartment 5A",
          "postalCode": "10024",
          "state": "NY"
        },
        "birthday": "2017-07-21",
        "canceledAt": "2021-01-21T19:39:53Z",
        "completedAt": "2021-01-21T19:36:57Z",
        "createdAt": "2021-01-21T19:12:28Z",
        "declinedAttempts": 0,
        "declinedCode": "portingPhoneNumberPortProtected",
        "declinedMessage": "The phone number has port protection on the provider.",
        "donorProvider": {
          "object": "serviceProvider",
          "id": "svp_0SNlurA01K6GY5L0XJffY8",
          "name": "AT&T",
          "recipientProviders": [
            "p3"
          ]
        },
        "donorProviderApproval": true,
        "expiredAt": "2021-01-21T19:39:53Z",
        "firstName": "Jerry",
        "lastDeclinedAt": "2021-01-21T19:31:13Z",
        "lastName": "Seinfeld",
        "lastRequestedAt": "2021-01-21T19:22:31Z",
        "phoneNumber": "+19591234567",
        "provider": "p9",
        "recipientProvider": {
          "object": "serviceProvider",
          "id": "svp_0SNlurA01K6GY5L0XJffY8",
          "name": "AT&T",
          "recipientProviders": [
            "p3"
          ]
        },
        "required": [
          "accountNumber",
          "accountPin",
          "address",
          "birthday",
          "donorProvider",
          "donorProviderApproval",
          "firstName",
          "lastName"
        ],
        "status": "draft",
        "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
        "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
      },
      "sim": {
        "object": "sim",
        "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
        "metadata": {},
        "createdAt": "2021-01-21T19:38:34Z",
        "iccid": "89883070000007537119",
        "provider": "p9",
        "status": "inactive",
        "type": "eSIM"
      },
      "status": "pending",
      "user": {
        "object": "user",
        "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
        "metadata": {},
        "birthday": "2017-07-21",
        "createdAt": "2021-01-21T19:38:34Z",
        "email": "jerry@example.com",
        "emailVerified": true,
        "fullName": "Jerry Seinfeld",
        "preferredLocale": "en-US"
      }
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

GET/projects/{project}/subscriptions

List all subscriptions

Returns a list of subscriptions. The subscriptions returned are sorted by creation date, with the most recently created subscriptions appearing first.

Path Parameters

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

Query Parameters

Name
user
Type
string
Description
The unique identifier for the user to be filtered by.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
Name
plan
Type
string
Description
The unique identifier for the plan to be filtered by.
Example: "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
Name
sim
Type
string
Description
The unique identifier for the sim to be filtered by.
Example: "sim_0SNlurA049MEWV1BAAmWZULA4lf6"
Name
status
Type
array
Description
A comma-separated list of statuses to filter the subscriptions by. Only pending and active subscriptions are returned by default.
Default: pending,initiated,active
Name
after
Type
string
Description
A cursor for use in pagination. The after parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned.
Name
before
Type
string
Description
A cursor for use in pagination. The before parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned.
Name
limit
Type
integer
Description
The limit of items to be returned in the list, between 0 and 200.
Default: 10
>= 0
<= 200

Response Schemas

Returns a list of subscription objects.

Name
object
Type
string
required
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
required
Description
List of objects of type `subscription`.
Name
moreItemsAfter
Type
nullable string
required
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
required
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/projects/{project}/subscriptions

curl https://api.gigs.com/projects/{project}/subscriptions \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Responses

{
  "object": "list",
  "items": [
    {
      "object": "subscription",
      "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "metadata": {},
      "activatedAt": "2021-01-21T19:38:34Z",
      "canceledAt": "2021-01-29T13:22:51Z",
      "cancellationDetails": {
        "cause": "cancellationRequested",
        "userReason": "connectivityIssues"
      },
      "createdAt": "2021-01-21T19:32:13Z",
      "currentPeriod": {
        "number": 1,
        "start": "2021-01-21T19:32:13Z",
        "end": "2021-02-20T19:38:34Z"
      },
      "earliestEndAt": "2021-02-20T19:38:34Z",
      "endedAt": "2021-02-20T19:38:34Z",
      "firstUsageAt": "2021-01-21T19:38:34Z",
      "phoneNumber": "+19591234567",
      "plan": {
        "object": "plan",
        "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
        "metadata": {},
        "allowances": {
          "dataBytes": 10000000000,
          "voiceSeconds": 30000,
          "smsMessages": 100
        },
        "coverage": {
          "object": "coverage",
          "id": "de",
          "countries": [
            "DE",
            "FR",
            "US"
          ],
          "name": "Europe"
        },
        "createdAt": "2021-01-21T19:38:34Z",
        "description": "A data plan you will love! Operates in most countries of the world.",
        "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
        "limits": {
          "dataBytes": 100000000000,
          "bandwidthBitsPerSecond": null,
          "throttling": {
            "thresholdBytes": 10000000000,
            "bandwidthBitsPerSecond": 512000
          }
        },
        "name": "Gigs Global",
        "price": {
          "amount": 999,
          "currency": "USD"
        },
        "provider": "p5",
        "requirements": {
          "address": "present",
          "device": "none",
          "user.birthday": "none",
          "user.fullName": "present"
        },
        "simTypes": [
          "eSIM",
          "pSIM"
        ],
        "status": "available",
        "validity": {
          "minimumPeriods": 12,
          "type": "recurring",
          "unit": "day",
          "value": 7
        },
        "data": 10000000000,
        "dataUnit": "byte",
        "sms": 100,
        "smsUnit": "message",
        "voice": 30000,
        "voiceUnit": "second"
      },
      "porting": {
        "object": "porting",
        "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
        "accountNumber": "123456789",
        "accountPinExists": true,
        "address": {
          "city": "New York City",
          "country": "US",
          "line1": "129 West 81st Street",
          "line2": "Apartment 5A",
          "postalCode": "10024",
          "state": "NY"
        },
        "birthday": "2017-07-21",
        "canceledAt": "2021-01-21T19:39:53Z",
        "completedAt": "2021-01-21T19:36:57Z",
        "createdAt": "2021-01-21T19:12:28Z",
        "declinedAttempts": 0,
        "declinedCode": "portingPhoneNumberPortProtected",
        "declinedMessage": "The phone number has port protection on the provider.",
        "donorProvider": {
          "object": "serviceProvider",
          "id": "svp_0SNlurA01K6GY5L0XJffY8",
          "name": "AT&T",
          "recipientProviders": [
            "p3"
          ]
        },
        "donorProviderApproval": true,
        "expiredAt": "2021-01-21T19:39:53Z",
        "firstName": "Jerry",
        "lastDeclinedAt": "2021-01-21T19:31:13Z",
        "lastName": "Seinfeld",
        "lastRequestedAt": "2021-01-21T19:22:31Z",
        "phoneNumber": "+19591234567",
        "provider": "p9",
        "recipientProvider": {
          "object": "serviceProvider",
          "id": "svp_0SNlurA01K6GY5L0XJffY8",
          "name": "AT&T",
          "recipientProviders": [
            "p3"
          ]
        },
        "required": [
          "accountNumber",
          "accountPin",
          "address",
          "birthday",
          "donorProvider",
          "donorProviderApproval",
          "firstName",
          "lastName"
        ],
        "status": "draft",
        "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
        "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
      },
      "sim": {
        "object": "sim",
        "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
        "metadata": {},
        "createdAt": "2021-01-21T19:38:34Z",
        "iccid": "89883070000007537119",
        "provider": "p9",
        "status": "inactive",
        "type": "eSIM"
      },
      "status": "pending",
      "user": {
        "object": "user",
        "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
        "metadata": {},
        "birthday": "2017-07-21",
        "createdAt": "2021-01-21T19:38:34Z",
        "email": "jerry@example.com",
        "emailVerified": true,
        "fullName": "Jerry Seinfeld",
        "preferredLocale": "en-US"
      }
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

POST/projects/{project}/subscriptions

Create a subscription

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

Body

Name
device
Type
nullable string
Description
The unique identifier for the existing device to be linked with the passed SIM. Some network providers require this field (or deviceModel) for activation. If the exact IMEI of the device is known, then it is recommended to create a device and specify its ID here. 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
plan
Type
string
required
Description
The unique identifier for the existing plan to be used for the subscription.
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.
Example: "sim_0SNlurA049MEWV1BAAmWZULA4lf6"
Default: auto
Name
userAddress
Type
nullable string
Description
The unique identifier for the existing user address to be used for the subscription. Only needed if the plan requires an address.
Example: "adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
Name
user
Type
string
required
Description
The unique identifier for the existing user to which the subscription will be assigned.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Path Parameters

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

Response Schemas

Returns the newly created subscription and supporting objects.

Name
object
Type
string
required
Description
Type of object is always subscription.
Allowed values: subscription
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
metadata
Type
Metadata
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
activatedAt
Type
nullable string
required
Description
Time when the subscription was activated.
Example: "2021-01-21T19:38:34Z"
Name
canceledAt
Type
nullable string
required
Description
Time when the subscription was canceled.
Example: "2021-01-29T13:22:51Z"
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
cause
Type
nullable string
Description
Cause of subscription cancellation.
Allowed values: cancellationRequested, invoiceUnpaid, paymentDisputed, paymentFailed, phoneNumberPortedOut, portingExpired, subscriptionEnded, userDeleted
Name
userComment
Type
nullable string
Description
Comment from the user explaining the cancellation reason. It is only present when the userReason is other.
Name
userReason
Type
nullable string
Description
Reason for the user to cancel the subscription. It is only present when the cause is cancellationRequested
Allowed values: connectivityIssues, customerService, noDetails, other, tooExpensive, unused
Name
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: "2021-01-21T19:32:13Z"
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
Name
number
Type
integer
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
required
Description
End of the period.
Example: "2021-02-20T19:38:34Z"
Name
earliestEndAt
Type
nullable string
required
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
required
Description
Time when the subscription was ended.
Example: "2021-02-20T19:38:34Z"
Name
firstUsageAt
Type
nullable string
required
Description
Time when the subscription was first used.
Example: "2021-01-21T19:38:34Z"
Name
phoneNumber
Type
nullable string
required
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: "+19591234567"
Name
plan
Type
Plan
required
Description
Plans define the network options and parameters offered to the end user, e.g. 'Unlimited data, voice & text'. Plan allowances (data, sms, voice) and limits are configurable, and Gigs will work with you to find the best balance for your users.
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
A SIM is a unique card that identifies itself to a specific mobile network and provides voice, text, and data connectivity to a user’s device. There are two types of available SIMs: eSIM and pSIM. eSIMs can be activated and installed instantly on any eSIM compatible device, pSIMs (physical SIMs) must be provided to the user or installed into the device beforehand.
Name
status
Type
string
required
Description
The current status of the subscription. Note that the initiated status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.
Allowed values: pending, initiated, active, ended
Name
user
Type
User
required
Description
Users are end consumers of subscriptions. Users can have multiple devices, SIMs, and subscriptions.

Request

POST

/projects/{project}/subscriptions

curl https://api.gigs.com/projects/{project}/subscriptions \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json" \
-d "{\"device\":\"dev_0SNlurA049MEWV55CrA9qMvI2FVJ\",\"deviceModel\":\"dmd_0SNlurA04OUskUGfGAn3Rh\",\"metadata\":{},\"plan\":\"pln_0SNlurA049MEWV3V0q7gjQbM4EVo\",\"porting\":\"prt_0SNlurA049MEWV39s2kSYqaat7ZS\",\"sim\":\"sim_0SNlurA049MEWV1BAAmWZULA4lf6\",\"userAddress\":\"adr_0SNlurA049MEWV5ELDmnaqVXgTFT\",\"user\":\"usr_0SNlurA049MEWV4OpCwsNyC9Kn2d\"}"

Responses

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "metadata": {},
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "createdAt": "2021-01-21T19:32:13Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z",
  "phoneNumber": "+19591234567",
  "plan": {
    "object": "plan",
    "id": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
    "metadata": {},
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:38:34Z",
    "description": "A data plan you will love! Operates in most countries of the world.",
    "image": "https://i.gigscdn.com/pr/nTZpgaEj5dTQ2Jo/original.png",
    "limits": {
      "dataBytes": 100000000000,
      "bandwidthBitsPerSecond": null,
      "throttling": {
        "thresholdBytes": 10000000000,
        "bandwidthBitsPerSecond": 512000
      }
    },
    "name": "Gigs Global",
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "requirements": {
      "address": "present",
      "device": "none",
      "user.birthday": "none",
      "user.fullName": "present"
    },
    "simTypes": [
      "eSIM",
      "pSIM"
    ],
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "porting": {
    "object": "porting",
    "id": "prt_0SNlurA049MEWV39s2kSYqaat7ZS",
    "accountNumber": "123456789",
    "accountPinExists": true,
    "address": {
      "city": "New York City",
      "country": "US",
      "line1": "129 West 81st Street",
      "line2": "Apartment 5A",
      "postalCode": "10024",
      "state": "NY"
    },
    "birthday": "2017-07-21",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "declinedAttempts": 0,
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "donorProviderApproval": true,
    "expiredAt": "2021-01-21T19:39:53Z",
    "firstName": "Jerry",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastName": "Seinfeld",
    "lastRequestedAt": "2021-01-21T19:22:31Z",
    "phoneNumber": "+19591234567",
    "provider": "p9",
    "recipientProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T",
      "recipientProviders": [
        "p3"
      ]
    },
    "required": [
      "accountNumber",
      "accountPin",
      "address",
      "birthday",
      "donorProvider",
      "donorProviderApproval",
      "firstName",
      "lastName"
    ],
    "status": "draft",
    "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
    "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "createdAt": "2021-01-21T19:38:34Z",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "createdAt": "2021-01-21T19:38:34Z",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US"
  }
}