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.
Name
id
Type
string
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
Description
Details about the cancellation of the subscription.
Name
currentPeriod
Type
nullable object
Description
Current subscription period. Only present for active subscriptions.
Name
phoneNumber
Type
nullable string
Description
The phone number attached to the SIM in E.164 format. Only available for voice plans.
Example: +19591234567
Name
plan
Type
object
Description
Name
porting
Type
nullable object
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
Description
Name
status
Type
string
Description
The current status of the subscription. Note that the initiated status is currently only available when using the Billing API, where it implies that the subscription's first invoice has not yet been paid.
Allowed values: pending, initiated, active, ended
Name
user
Type
object
Description
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
createdAt
Type
string
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
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

Response

{
  "object": "subscription",
  "id": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19: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"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "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"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "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",
    "declinedCode": "portingPhoneNumberPortProtected",
    "declinedMessage": "The phone number has port protection on the provider.",
    "donorProvider": {
      "object": "serviceProvider",
      "id": "svp_0SNlurA01K6GY5L0XJffY8",
      "name": "AT&T"
    },
    "donorProviderApproval": true,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "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",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

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.

Body

Name
cancellationDetails
Type
nullable object
Description
Details about the cancellation of the subscription.

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

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
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
object
required
Description
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
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
object
required
Description
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
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
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

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": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19: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"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "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"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "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",
    "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,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "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",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

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.

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

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
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
object
required
Description
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
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
object
required
Description
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
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
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

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": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19: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"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "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"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "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",
    "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,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "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",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

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

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
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
object
required
Description
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
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
object
required
Description
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
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
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

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": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19: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"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "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"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "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",
    "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,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "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",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

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

Update a subscription

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

Body

Name
metadata
Type
object
Description
A set of key-value pairs, to store metadata related to the resource.

Path Parameters

Name
project
Type
string
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

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
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
object
required
Description
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
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
object
required
Description
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
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
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

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": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19: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"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "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"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "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",
    "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,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "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",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

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

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
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
object
required
Description
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
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
object
required
Description
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
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
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

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": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19: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"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "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"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "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",
    "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,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "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",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}

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

Name
object
Type
string
required
Description
Type of object is always 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": {},
      "cancellationDetails": {
        "cause": "cancellationRequested",
        "userReason": "connectivityIssues"
      },
      "currentPeriod": {
        "number": 1,
        "start": "2021-01-21T19:32:13Z",
        "end": "2021-02-20T19: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"
        },
        "data": 10000000000,
        "dataUnit": "byte",
        "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"
        ],
        "sms": 100,
        "smsUnit": "message",
        "status": "available",
        "validity": {
          "minimumPeriods": 12,
          "type": "recurring",
          "unit": "day",
          "value": 7
        },
        "voice": 30000,
        "voiceUnit": "second",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "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",
        "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,
        "firstName": "Jerry",
        "lastName": "Seinfeld",
        "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",
        "canceledAt": "2021-01-21T19:39:53Z",
        "completedAt": "2021-01-21T19:36:57Z",
        "createdAt": "2021-01-21T19:12:28Z",
        "expiredAt": "2021-01-21T19:39:53Z",
        "lastDeclinedAt": "2021-01-21T19:31:13Z",
        "lastRequestedAt": "2021-01-21T19:22:31Z"
      },
      "sim": {
        "object": "sim",
        "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
        "metadata": {},
        "iccid": "89883070000007537119",
        "provider": "p9",
        "status": "inactive",
        "type": "eSIM",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "status": "pending",
      "user": {
        "object": "user",
        "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
        "metadata": {},
        "birthday": "2017-07-21",
        "email": "jerry@example.com",
        "emailVerified": true,
        "fullName": "Jerry Seinfeld",
        "preferredLocale": "en-US",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "activatedAt": "2021-01-21T19:38:34Z",
      "canceledAt": "2021-01-29T13:22:51Z",
      "createdAt": "2021-01-21T19:32:13Z",
      "earliestEndAt": "2021-02-20T19:38:34Z",
      "endedAt": "2021-02-20T19:38:34Z",
      "firstUsageAt": "2021-01-21T19:38:34Z"
    }
  ],
  "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

Name
object
Type
string
required
Description
Type of object is always 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": {},
      "cancellationDetails": {
        "cause": "cancellationRequested",
        "userReason": "connectivityIssues"
      },
      "currentPeriod": {
        "number": 1,
        "start": "2021-01-21T19:32:13Z",
        "end": "2021-02-20T19: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"
        },
        "data": 10000000000,
        "dataUnit": "byte",
        "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"
        ],
        "sms": 100,
        "smsUnit": "message",
        "status": "available",
        "validity": {
          "minimumPeriods": 12,
          "type": "recurring",
          "unit": "day",
          "value": 7
        },
        "voice": 30000,
        "voiceUnit": "second",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "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",
        "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,
        "firstName": "Jerry",
        "lastName": "Seinfeld",
        "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",
        "canceledAt": "2021-01-21T19:39:53Z",
        "completedAt": "2021-01-21T19:36:57Z",
        "createdAt": "2021-01-21T19:12:28Z",
        "expiredAt": "2021-01-21T19:39:53Z",
        "lastDeclinedAt": "2021-01-21T19:31:13Z",
        "lastRequestedAt": "2021-01-21T19:22:31Z"
      },
      "sim": {
        "object": "sim",
        "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
        "metadata": {},
        "iccid": "89883070000007537119",
        "provider": "p9",
        "status": "inactive",
        "type": "eSIM",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "status": "pending",
      "user": {
        "object": "user",
        "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
        "metadata": {},
        "birthday": "2017-07-21",
        "email": "jerry@example.com",
        "emailVerified": true,
        "fullName": "Jerry Seinfeld",
        "preferredLocale": "en-US",
        "createdAt": "2021-01-21T19:38:34Z"
      },
      "activatedAt": "2021-01-21T19:38:34Z",
      "canceledAt": "2021-01-29T13:22:51Z",
      "createdAt": "2021-01-21T19:32:13Z",
      "earliestEndAt": "2021-02-20T19:38:34Z",
      "endedAt": "2021-02-20T19:38:34Z",
      "firstUsageAt": "2021-01-21T19:38:34Z"
    }
  ],
  "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
object
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

Name
object
Type
string
required
Description
Type of object is always subscription.
Name
id
Type
string
required
Description
Unique identifier for the subscription.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
metadata
Type
object
required
Description
A set of key-value pairs, to store metadata related to the resource.
Name
cancellationDetails
Type
nullable object
required
Description
Details about the cancellation of the subscription.
Name
currentPeriod
Type
nullable object
required
Description
Current subscription period. Only present for active subscriptions.
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
object
required
Description
Name
porting
Type
nullable object
required
Description
Current porting (if any) related with the subscription.
Name
sim
Type
nullable object
required
Description
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
object
required
Description
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
createdAt
Type
string
required
Description
Time when the subscription was created.
Example: 2021-01-21T19:32:13Z
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

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": {},
  "cancellationDetails": {
    "cause": "cancellationRequested",
    "userReason": "connectivityIssues"
  },
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19: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"
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "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"
    ],
    "sms": 100,
    "smsUnit": "message",
    "status": "available",
    "validity": {
      "minimumPeriods": 12,
      "type": "recurring",
      "unit": "day",
      "value": 7
    },
    "voice": 30000,
    "voiceUnit": "second",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "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",
    "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,
    "firstName": "Jerry",
    "lastName": "Seinfeld",
    "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",
    "canceledAt": "2021-01-21T19:39:53Z",
    "completedAt": "2021-01-21T19:36:57Z",
    "createdAt": "2021-01-21T19:12:28Z",
    "expiredAt": "2021-01-21T19:39:53Z",
    "lastDeclinedAt": "2021-01-21T19:31:13Z",
    "lastRequestedAt": "2021-01-21T19:22:31Z"
  },
  "sim": {
    "object": "sim",
    "id": "sim_0SNlurA049MEWV1BAAmWZULA4lf6",
    "metadata": {},
    "iccid": "89883070000007537119",
    "provider": "p9",
    "status": "inactive",
    "type": "eSIM",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "status": "pending",
  "user": {
    "object": "user",
    "id": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d",
    "metadata": {},
    "birthday": "2017-07-21",
    "email": "jerry@example.com",
    "emailVerified": true,
    "fullName": "Jerry Seinfeld",
    "preferredLocale": "en-US",
    "createdAt": "2021-01-21T19:38:34Z"
  },
  "activatedAt": "2021-01-21T19:38:34Z",
  "canceledAt": "2021-01-29T13:22:51Z",
  "createdAt": "2021-01-21T19:32:13Z",
  "earliestEndAt": "2021-02-20T19:38:34Z",
  "endedAt": "2021-02-20T19:38:34Z",
  "firstUsageAt": "2021-01-21T19:38:34Z"
}