Subscription Add-ons

Subscription add-ons are features or top-ups that extend the functionality offered to the end user through their subscription, as defined by the associated add-on.

Properties

Name
object
Type
string
Description
Type of object is always subscriptionAddon.
Allowed values: subscriptionAddon
Name
id
Type
string
Description
Unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
activatedAt
Type
nullable string
Description
Time when the subscription add-on was activated.
Example: "2021-01-15T12:36:57Z"
Name
addon
Type
Add-on
Description
The add-on associated to the subscription add-on.
Name
billing
Type
nullable object
Description
Billing details for the subscription add-on. Present when the add-on has billing settings.
Name
discount
Type
nullable object
Description
Discount currently applied to the subscription add-on.
Name
canceledAt
Type
nullable string
Description
Time when the subscription add-on was canceled.
Example: "2021-01-22T19:39:53Z"
Name
createdAt
Type
string
Description
Time when the subscription add-on was created.
Example: "2021-01-15T12:30:28Z"
Name
currentPeriod
Type
nullable Period
Description
Current subscription add-on period. Only present for active subscription add-ons.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
Example: "2021-02-20T19:38:34Z"
Name
endedAt
Type
nullable string
Description
Time when the subscription add-on was ended. The value is null if the subscription add-on is not ended.
Example: "2021-01-30T23:12:28Z"
Name
status
Type
string
Description
The current status of the subscription add-on.
Allowed values: pending initiated active ended
Name
subscription
Type
string
Description
Unique identifier of the subscription the add-on applies to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
Description
Unique identifier of the user the subscription add-on belongs to.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Example

{
  "object": "subscriptionAddon",
  "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
  "activatedAt": "2021-01-15T12:36:57Z",
  "addon": {
    "object": "addon",
    "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
    "metadata": {},
    "activationTrigger": "creation",
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": {
        "0": "DE",
        "1": "FR",
        "2": "US"
      },
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:12:28.0Z",
    "description": "Disable international roaming.",
    "name": "1GB Data Top-up",
    "plans": [
      "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
    ],
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "recurrenceType": "oneTime",
    "status": "draft",
    "type": "topUp",
    "validity": {
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "expiresAt": "2021-02-20T19:38:34Z"
    }
  },
  "canceledAt": "2021-01-22T19:39:53Z",
  "createdAt": "2021-01-15T12:30:28.0Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13.0Z",
    "end": "2021-02-20T19:38:34.0Z"
  },
  "endedAt": "2021-01-30T23:12:28Z",
  "status": "pending",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

GET/projects/{project}/subscriptionAddons

List all subscription add-ons

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

Path Parameters

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

Query Parameters

Name
addon
Type
string
Description
The unique identifier for the add-on to be filtered by.
Example: "add_0SNlurA049MEWV4VxLfwJc7PJtHc"
Name
status
Type
array
Description
A comma-separated list of statuses to filter the subscription add-ons by.
Default: pending,initiated,active
Name
subscription
Type
string
Description
The unique identifier for the subscription to be filtered by.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
Description
The unique identifier for the user to be filtered by.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
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.
Example: 20
Default: 10
>= 0
<= 200

Responses

Returns a dictionary with an items property that contains an array of subscription add-ons.

Name
object
Type
string
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
Description
List of objects of type subscriptionAddon.
Name
moreItemsAfter
Type
nullable string
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/projects/{project}/subscriptionAddons

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

Responses

{
  "object": "list",
  "items": [
    {
      "object": "subscriptionAddon",
      "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
      "activatedAt": "2021-01-15T12:36:57Z",
      "addon": {
        "object": "addon",
        "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
        "metadata": {},
        "activationTrigger": "creation",
        "allowances": {
          "dataBytes": 10000000000,
          "voiceSeconds": 30000,
          "smsMessages": 100
        },
        "coverage": {
          "object": "coverage",
          "id": "de",
          "countries": [
            "DE",
            "FR",
            "US"
          ],
          "name": "Europe"
        },
        "createdAt": "2021-01-21T19:12:28Z",
        "description": "Disable international roaming.",
        "name": "1GB Data Top-up",
        "plans": [
          "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
        ],
        "price": {
          "amount": 999,
          "currency": "USD"
        },
        "provider": "p5",
        "recurrenceType": "oneTime",
        "status": "draft",
        "type": "topUp",
        "validity": {
          "unit": "day",
          "value": 7
        },
        "data": 10000000000,
        "dataUnit": "byte",
        "sms": 100,
        "smsUnit": "message",
        "voice": 30000,
        "voiceUnit": "second"
      },
      "billing": {
        "discount": {
          "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
          "expiresAt": "2021-02-20T19:38:34Z"
        }
      },
      "canceledAt": "2021-01-22T19:39:53Z",
      "createdAt": "2021-01-15T12:30:28Z",
      "currentPeriod": {
        "number": 1,
        "start": "2021-01-21T19:32:13Z",
        "end": "2021-02-20T19:38:34Z"
      },
      "endedAt": "2021-01-30T23:12:28Z",
      "status": "pending",
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

POST/projects/{project}/subscriptionAddons

Create a subscription add-on

Creates a new subscription add-on for an existing subscription in the specified project.

Body

Name
addon
Type
string
required
Description
Unique identifier of the add-on.
Example: "add_0SNlurA049MEWV4VxLfwJc7PJtHc"
Name
billing
Type
nullable object
Description
Configuration for this specific subscription add-on billing. Only available when the Billing API is enabled.
Name
discount
Type
nullable object
Description
Discount to apply to the subscription add-on.
Name
subscription
Type
string
required
Description
Unique identifier of the subscription the add-on applies to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"

Path Parameters

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

Responses

Returns the newly created subscription add-on.

Name
object
Type
string
Description
Type of object is always subscriptionAddon.
Allowed values: subscriptionAddon
Name
id
Type
string
Description
Unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
activatedAt
Type
nullable string
Description
Time when the subscription add-on was activated.
Example: "2021-01-15T12:36:57Z"
Name
addon
Type
Add-on
Description
The add-on associated to the subscription add-on.
Name
billing
Type
nullable object
Description
Billing details for the subscription add-on. Present when the add-on has billing settings.
Name
discount
Type
nullable object
Description
Discount currently applied to the subscription add-on.
Name
canceledAt
Type
nullable string
Description
Time when the subscription add-on was canceled.
Example: "2021-01-22T19:39:53Z"
Name
createdAt
Type
string
Description
Time when the subscription add-on was created.
Example: "2021-01-15T12:30:28Z"
Name
currentPeriod
Type
nullable Period
Description
Current subscription add-on period. Only present for active subscription add-ons.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
Example: "2021-02-20T19:38:34Z"
Name
endedAt
Type
nullable string
Description
Time when the subscription add-on was ended. The value is null if the subscription add-on is not ended.
Example: "2021-01-30T23:12:28Z"
Name
status
Type
string
Description
The current status of the subscription add-on.
Allowed values: pending initiated active ended
Name
subscription
Type
string
Description
Unique identifier of the subscription the add-on applies to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
Description
Unique identifier of the user the subscription add-on belongs to.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Request

POST

/projects/{project}/subscriptionAddons

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionAddons \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
  "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
    }
  },
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
}'

Responses

{
  "object": "subscriptionAddon",
  "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
  "activatedAt": "2021-01-15T12:36:57Z",
  "addon": {
    "object": "addon",
    "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
    "metadata": {},
    "activationTrigger": "creation",
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:12:28Z",
    "description": "Disable international roaming.",
    "name": "1GB Data Top-up",
    "plans": [
      "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
    ],
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "recurrenceType": "oneTime",
    "status": "draft",
    "type": "topUp",
    "validity": {
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "expiresAt": "2021-02-20T19:38:34Z"
    }
  },
  "canceledAt": "2021-01-22T19:39:53Z",
  "createdAt": "2021-01-15T12:30:28Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "endedAt": "2021-01-30T23:12:28Z",
  "status": "pending",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

GET/projects/{project}/subscriptionAddons/{subscriptionAddon}

Retrieve a subscription add-on

Retrieve the details of an existing subscription add-on which the authenticated user is authorized to view.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
subscriptionAddon
Type
string
required
Description
The unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"

Responses

Returns the subscription add-on if it exists.

Name
object
Type
string
Description
Type of object is always subscriptionAddon.
Allowed values: subscriptionAddon
Name
id
Type
string
Description
Unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
activatedAt
Type
nullable string
Description
Time when the subscription add-on was activated.
Example: "2021-01-15T12:36:57Z"
Name
addon
Type
Add-on
Description
The add-on associated to the subscription add-on.
Name
billing
Type
nullable object
Description
Billing details for the subscription add-on. Present when the add-on has billing settings.
Name
discount
Type
nullable object
Description
Discount currently applied to the subscription add-on.
Name
canceledAt
Type
nullable string
Description
Time when the subscription add-on was canceled.
Example: "2021-01-22T19:39:53Z"
Name
createdAt
Type
string
Description
Time when the subscription add-on was created.
Example: "2021-01-15T12:30:28Z"
Name
currentPeriod
Type
nullable Period
Description
Current subscription add-on period. Only present for active subscription add-ons.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
Example: "2021-02-20T19:38:34Z"
Name
endedAt
Type
nullable string
Description
Time when the subscription add-on was ended. The value is null if the subscription add-on is not ended.
Example: "2021-01-30T23:12:28Z"
Name
status
Type
string
Description
The current status of the subscription add-on.
Allowed values: pending initiated active ended
Name
subscription
Type
string
Description
Unique identifier of the subscription the add-on applies to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
Description
Unique identifier of the user the subscription add-on belongs to.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Request

GET

/projects/{project}/subscriptionAddons/{subscriptionAddon}

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

Responses

{
  "object": "subscriptionAddon",
  "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
  "activatedAt": "2021-01-15T12:36:57Z",
  "addon": {
    "object": "addon",
    "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
    "metadata": {},
    "activationTrigger": "creation",
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:12:28Z",
    "description": "Disable international roaming.",
    "name": "1GB Data Top-up",
    "plans": [
      "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
    ],
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "recurrenceType": "oneTime",
    "status": "draft",
    "type": "topUp",
    "validity": {
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "expiresAt": "2021-02-20T19:38:34Z"
    }
  },
  "canceledAt": "2021-01-22T19:39:53Z",
  "createdAt": "2021-01-15T12:30:28Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "endedAt": "2021-01-30T23:12:28Z",
  "status": "pending",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

DELETE/projects/{project}/subscriptionAddons/{subscriptionAddon}

End a subscription add-on

Ends a subscription add-on immediately. Subscription add-ons that are already ended cannot be ended again.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
subscriptionAddon
Type
string
required
Description
The unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"

Responses

Returns the ended subscription add-on.

Name
object
Type
string
Description
Type of object is always subscriptionAddon.
Allowed values: subscriptionAddon
Name
id
Type
string
Description
Unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
activatedAt
Type
nullable string
Description
Time when the subscription add-on was activated.
Example: "2021-01-15T12:36:57Z"
Name
addon
Type
Add-on
Description
The add-on associated to the subscription add-on.
Name
billing
Type
nullable object
Description
Billing details for the subscription add-on. Present when the add-on has billing settings.
Name
discount
Type
nullable object
Description
Discount currently applied to the subscription add-on.
Name
canceledAt
Type
nullable string
Description
Time when the subscription add-on was canceled.
Example: "2021-01-22T19:39:53Z"
Name
createdAt
Type
string
Description
Time when the subscription add-on was created.
Example: "2021-01-15T12:30:28Z"
Name
currentPeriod
Type
nullable Period
Description
Current subscription add-on period. Only present for active subscription add-ons.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
Example: "2021-02-20T19:38:34Z"
Name
endedAt
Type
nullable string
Description
Time when the subscription add-on was ended. The value is null if the subscription add-on is not ended.
Example: "2021-01-30T23:12:28Z"
Name
status
Type
string
Description
The current status of the subscription add-on.
Allowed values: pending initiated active ended
Name
subscription
Type
string
Description
Unique identifier of the subscription the add-on applies to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
Description
Unique identifier of the user the subscription add-on belongs to.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Request

DELETE

/projects/{project}/subscriptionAddons/{subscriptionAddon}

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

Responses

{
  "object": "subscriptionAddon",
  "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
  "activatedAt": "2021-01-15T12:36:57Z",
  "addon": {
    "object": "addon",
    "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
    "metadata": {},
    "activationTrigger": "creation",
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:12:28Z",
    "description": "Disable international roaming.",
    "name": "1GB Data Top-up",
    "plans": [
      "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
    ],
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "recurrenceType": "oneTime",
    "status": "draft",
    "type": "topUp",
    "validity": {
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "expiresAt": "2021-02-20T19:38:34Z"
    }
  },
  "canceledAt": "2021-01-22T19:39:53Z",
  "createdAt": "2021-01-15T12:30:28Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "endedAt": "2021-01-30T23:12:28Z",
  "status": "pending",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

Subscription Add-ons

Subscription add-ons are features or top-ups that extend the functionality offered to the end user through their subscription, as defined by the associated add-on.

Properties

Name
object
Type
string
Description
Type of object is always subscriptionAddon.
Allowed values: subscriptionAddon
Name
id
Type
string
Description
Unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
activatedAt
Type
nullable string
Description
Time when the subscription add-on was activated.
Example: "2021-01-15T12:36:57Z"
Name
addon
Type
Add-on
Description
The add-on associated to the subscription add-on.
Name
billing
Type
nullable object
Description
Billing details for the subscription add-on. Present when the add-on has billing settings.
Name
discount
Type
nullable object
Description
Discount currently applied to the subscription add-on.
Name
canceledAt
Type
nullable string
Description
Time when the subscription add-on was canceled.
Example: "2021-01-22T19:39:53Z"
Name
createdAt
Type
string
Description
Time when the subscription add-on was created.
Example: "2021-01-15T12:30:28Z"
Name
currentPeriod
Type
nullable Period
Description
Current subscription add-on period. Only present for active subscription add-ons.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
Example: "2021-02-20T19:38:34Z"
Name
endedAt
Type
nullable string
Description
Time when the subscription add-on was ended. The value is null if the subscription add-on is not ended.
Example: "2021-01-30T23:12:28Z"
Name
status
Type
string
Description
The current status of the subscription add-on.
Allowed values: pending initiated active ended
Name
subscription
Type
string
Description
Unique identifier of the subscription the add-on applies to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
Description
Unique identifier of the user the subscription add-on belongs to.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Example

{
  "object": "subscriptionAddon",
  "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
  "activatedAt": "2021-01-15T12:36:57Z",
  "addon": {
    "object": "addon",
    "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
    "metadata": {},
    "activationTrigger": "creation",
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": {
        "0": "DE",
        "1": "FR",
        "2": "US"
      },
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:12:28.0Z",
    "description": "Disable international roaming.",
    "name": "1GB Data Top-up",
    "plans": [
      "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
    ],
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "recurrenceType": "oneTime",
    "status": "draft",
    "type": "topUp",
    "validity": {
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "expiresAt": "2021-02-20T19:38:34Z"
    }
  },
  "canceledAt": "2021-01-22T19:39:53Z",
  "createdAt": "2021-01-15T12:30:28.0Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13.0Z",
    "end": "2021-02-20T19:38:34.0Z"
  },
  "endedAt": "2021-01-30T23:12:28Z",
  "status": "pending",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

GET/projects/{project}/subscriptionAddons

List all subscription add-ons

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

Path Parameters

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

Query Parameters

Name
addon
Type
string
Description
The unique identifier for the add-on to be filtered by.
Example: "add_0SNlurA049MEWV4VxLfwJc7PJtHc"
Name
status
Type
array
Description
A comma-separated list of statuses to filter the subscription add-ons by.
Default: pending,initiated,active
Name
subscription
Type
string
Description
The unique identifier for the subscription to be filtered by.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
Description
The unique identifier for the user to be filtered by.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
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.
Example: 20
Default: 10
>= 0
<= 200

Responses

Returns a dictionary with an items property that contains an array of subscription add-ons.

Name
object
Type
string
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
Description
List of objects of type subscriptionAddon.
Name
moreItemsAfter
Type
nullable string
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/projects/{project}/subscriptionAddons

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

Responses

{
  "object": "list",
  "items": [
    {
      "object": "subscriptionAddon",
      "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
      "activatedAt": "2021-01-15T12:36:57Z",
      "addon": {
        "object": "addon",
        "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
        "metadata": {},
        "activationTrigger": "creation",
        "allowances": {
          "dataBytes": 10000000000,
          "voiceSeconds": 30000,
          "smsMessages": 100
        },
        "coverage": {
          "object": "coverage",
          "id": "de",
          "countries": [
            "DE",
            "FR",
            "US"
          ],
          "name": "Europe"
        },
        "createdAt": "2021-01-21T19:12:28Z",
        "description": "Disable international roaming.",
        "name": "1GB Data Top-up",
        "plans": [
          "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
        ],
        "price": {
          "amount": 999,
          "currency": "USD"
        },
        "provider": "p5",
        "recurrenceType": "oneTime",
        "status": "draft",
        "type": "topUp",
        "validity": {
          "unit": "day",
          "value": 7
        },
        "data": 10000000000,
        "dataUnit": "byte",
        "sms": 100,
        "smsUnit": "message",
        "voice": 30000,
        "voiceUnit": "second"
      },
      "billing": {
        "discount": {
          "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
          "expiresAt": "2021-02-20T19:38:34Z"
        }
      },
      "canceledAt": "2021-01-22T19:39:53Z",
      "createdAt": "2021-01-15T12:30:28Z",
      "currentPeriod": {
        "number": 1,
        "start": "2021-01-21T19:32:13Z",
        "end": "2021-02-20T19:38:34Z"
      },
      "endedAt": "2021-01-30T23:12:28Z",
      "status": "pending",
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

POST/projects/{project}/subscriptionAddons

Create a subscription add-on

Creates a new subscription add-on for an existing subscription in the specified project.

Body

Name
addon
Type
string
required
Description
Unique identifier of the add-on.
Example: "add_0SNlurA049MEWV4VxLfwJc7PJtHc"
Name
billing
Type
nullable object
Description
Configuration for this specific subscription add-on billing. Only available when the Billing API is enabled.
Name
discount
Type
nullable object
Description
Discount to apply to the subscription add-on.
Name
subscription
Type
string
required
Description
Unique identifier of the subscription the add-on applies to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"

Path Parameters

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

Responses

Returns the newly created subscription add-on.

Name
object
Type
string
Description
Type of object is always subscriptionAddon.
Allowed values: subscriptionAddon
Name
id
Type
string
Description
Unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
activatedAt
Type
nullable string
Description
Time when the subscription add-on was activated.
Example: "2021-01-15T12:36:57Z"
Name
addon
Type
Add-on
Description
The add-on associated to the subscription add-on.
Name
billing
Type
nullable object
Description
Billing details for the subscription add-on. Present when the add-on has billing settings.
Name
discount
Type
nullable object
Description
Discount currently applied to the subscription add-on.
Name
canceledAt
Type
nullable string
Description
Time when the subscription add-on was canceled.
Example: "2021-01-22T19:39:53Z"
Name
createdAt
Type
string
Description
Time when the subscription add-on was created.
Example: "2021-01-15T12:30:28Z"
Name
currentPeriod
Type
nullable Period
Description
Current subscription add-on period. Only present for active subscription add-ons.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
Example: "2021-02-20T19:38:34Z"
Name
endedAt
Type
nullable string
Description
Time when the subscription add-on was ended. The value is null if the subscription add-on is not ended.
Example: "2021-01-30T23:12:28Z"
Name
status
Type
string
Description
The current status of the subscription add-on.
Allowed values: pending initiated active ended
Name
subscription
Type
string
Description
Unique identifier of the subscription the add-on applies to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
Description
Unique identifier of the user the subscription add-on belongs to.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Request

POST

/projects/{project}/subscriptionAddons

curl https://api.gigs.com/projects/${GIGS_PROJECT}/subscriptionAddons \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
  "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
    }
  },
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
}'

Responses

{
  "object": "subscriptionAddon",
  "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
  "activatedAt": "2021-01-15T12:36:57Z",
  "addon": {
    "object": "addon",
    "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
    "metadata": {},
    "activationTrigger": "creation",
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:12:28Z",
    "description": "Disable international roaming.",
    "name": "1GB Data Top-up",
    "plans": [
      "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
    ],
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "recurrenceType": "oneTime",
    "status": "draft",
    "type": "topUp",
    "validity": {
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "expiresAt": "2021-02-20T19:38:34Z"
    }
  },
  "canceledAt": "2021-01-22T19:39:53Z",
  "createdAt": "2021-01-15T12:30:28Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "endedAt": "2021-01-30T23:12:28Z",
  "status": "pending",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

GET/projects/{project}/subscriptionAddons/{subscriptionAddon}

Retrieve a subscription add-on

Retrieve the details of an existing subscription add-on which the authenticated user is authorized to view.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
subscriptionAddon
Type
string
required
Description
The unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"

Responses

Returns the subscription add-on if it exists.

Name
object
Type
string
Description
Type of object is always subscriptionAddon.
Allowed values: subscriptionAddon
Name
id
Type
string
Description
Unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
activatedAt
Type
nullable string
Description
Time when the subscription add-on was activated.
Example: "2021-01-15T12:36:57Z"
Name
addon
Type
Add-on
Description
The add-on associated to the subscription add-on.
Name
billing
Type
nullable object
Description
Billing details for the subscription add-on. Present when the add-on has billing settings.
Name
discount
Type
nullable object
Description
Discount currently applied to the subscription add-on.
Name
canceledAt
Type
nullable string
Description
Time when the subscription add-on was canceled.
Example: "2021-01-22T19:39:53Z"
Name
createdAt
Type
string
Description
Time when the subscription add-on was created.
Example: "2021-01-15T12:30:28Z"
Name
currentPeriod
Type
nullable Period
Description
Current subscription add-on period. Only present for active subscription add-ons.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
Example: "2021-02-20T19:38:34Z"
Name
endedAt
Type
nullable string
Description
Time when the subscription add-on was ended. The value is null if the subscription add-on is not ended.
Example: "2021-01-30T23:12:28Z"
Name
status
Type
string
Description
The current status of the subscription add-on.
Allowed values: pending initiated active ended
Name
subscription
Type
string
Description
Unique identifier of the subscription the add-on applies to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
Description
Unique identifier of the user the subscription add-on belongs to.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Request

GET

/projects/{project}/subscriptionAddons/{subscriptionAddon}

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

Responses

{
  "object": "subscriptionAddon",
  "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
  "activatedAt": "2021-01-15T12:36:57Z",
  "addon": {
    "object": "addon",
    "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
    "metadata": {},
    "activationTrigger": "creation",
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:12:28Z",
    "description": "Disable international roaming.",
    "name": "1GB Data Top-up",
    "plans": [
      "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
    ],
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "recurrenceType": "oneTime",
    "status": "draft",
    "type": "topUp",
    "validity": {
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "expiresAt": "2021-02-20T19:38:34Z"
    }
  },
  "canceledAt": "2021-01-22T19:39:53Z",
  "createdAt": "2021-01-15T12:30:28Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "endedAt": "2021-01-30T23:12:28Z",
  "status": "pending",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}

DELETE/projects/{project}/subscriptionAddons/{subscriptionAddon}

End a subscription add-on

Ends a subscription add-on immediately. Subscription add-ons that are already ended cannot be ended again.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
subscriptionAddon
Type
string
required
Description
The unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"

Responses

Returns the ended subscription add-on.

Name
object
Type
string
Description
Type of object is always subscriptionAddon.
Allowed values: subscriptionAddon
Name
id
Type
string
Description
Unique identifier for the subscription add-on.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
activatedAt
Type
nullable string
Description
Time when the subscription add-on was activated.
Example: "2021-01-15T12:36:57Z"
Name
addon
Type
Add-on
Description
The add-on associated to the subscription add-on.
Name
billing
Type
nullable object
Description
Billing details for the subscription add-on. Present when the add-on has billing settings.
Name
discount
Type
nullable object
Description
Discount currently applied to the subscription add-on.
Name
canceledAt
Type
nullable string
Description
Time when the subscription add-on was canceled.
Example: "2021-01-22T19:39:53Z"
Name
createdAt
Type
string
Description
Time when the subscription add-on was created.
Example: "2021-01-15T12:30:28Z"
Name
currentPeriod
Type
nullable Period
Description
Current subscription add-on period. Only present for active subscription add-ons.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
Example: "2021-02-20T19:38:34Z"
Name
endedAt
Type
nullable string
Description
Time when the subscription add-on was ended. The value is null if the subscription add-on is not ended.
Example: "2021-01-30T23:12:28Z"
Name
status
Type
string
Description
The current status of the subscription add-on.
Allowed values: pending initiated active ended
Name
subscription
Type
string
Description
Unique identifier of the subscription the add-on applies to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
user
Type
string
Description
Unique identifier of the user the subscription add-on belongs to.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"

Request

DELETE

/projects/{project}/subscriptionAddons/{subscriptionAddon}

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

Responses

{
  "object": "subscriptionAddon",
  "id": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
  "activatedAt": "2021-01-15T12:36:57Z",
  "addon": {
    "object": "addon",
    "id": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
    "metadata": {},
    "activationTrigger": "creation",
    "allowances": {
      "dataBytes": 10000000000,
      "voiceSeconds": 30000,
      "smsMessages": 100
    },
    "coverage": {
      "object": "coverage",
      "id": "de",
      "countries": [
        "DE",
        "FR",
        "US"
      ],
      "name": "Europe"
    },
    "createdAt": "2021-01-21T19:12:28Z",
    "description": "Disable international roaming.",
    "name": "1GB Data Top-up",
    "plans": [
      "pln_0SNlurA049MEWV3V0q7gjQbM4EVo"
    ],
    "price": {
      "amount": 999,
      "currency": "USD"
    },
    "provider": "p5",
    "recurrenceType": "oneTime",
    "status": "draft",
    "type": "topUp",
    "validity": {
      "unit": "day",
      "value": 7
    },
    "data": 10000000000,
    "dataUnit": "byte",
    "sms": 100,
    "smsUnit": "message",
    "voice": 30000,
    "voiceUnit": "second"
  },
  "billing": {
    "discount": {
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN",
      "expiresAt": "2021-02-20T19:38:34Z"
    }
  },
  "canceledAt": "2021-01-22T19:39:53Z",
  "createdAt": "2021-01-15T12:30:28Z",
  "currentPeriod": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "endedAt": "2021-01-30T23:12:28Z",
  "status": "pending",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
}