Add-on

Add-ons define features or top-ups that can be used to extend the functionality offered to the end user through their subscription's plan.

  • Name
    object
    Type
    string
    Description

    Type of object is always addon.

    Allowed values: addon 
  • Name
    id
    Type
    string
    Description

    Unique identifier for the add-on.

    Example: "add_0SNlurA049MEWV4VxLfwJc7PJtHc"
  • Name
    metadata
    Type
    Metadata
    Description

    A set of key-value pairs, to store metadata related to the resource.

  • Name
    activationTrigger
    Type
    string
    Description

    Indicates when a subscription add-on will take effect.

    • creation: As soon as it is created. The user does not need to take any further action.
    • networkLatch: When the user's data session ends, which can be forced by power cycling the device.
    • usageStarted: When the user starts using add-on allowance on their device.
    Example: "creation"
    Allowed values: creation networkLatch usageStarted 
  • Name
    allowances
    Type
    Allowances
    Description
    The allowances included in the add-on.
    • Name
      dataBytes
      Type
      nullable integer
      Description

      The data allowance in bytes. A value of null indicates unlimited data.

      Example: 10000000000
    • Name
      voiceSeconds
      Type
      nullable integer
      Description

      The voice call allowance in seconds. A value of null indicates unlimited calls.

      Example: 30000
    • Name
      smsMessages
      Type
      nullable integer
      Description

      The SMS allowance in messages. A value of null indicates unlimited SMS.

      Example: 100
  • Name
    coverage
    Type
    nullable Coverage
    Description
    The geographic coverage of the add-on. A value of null indicates that coverage is not applicable for this add-on.
  • Name
    createdAt
    Type
    string
    Description

    Time when the add-on was created .

    Example: "2021-01-21T19:12:28Z"
  • Name
    description
    Type
    nullable string
    Description

    The description of the add-on.

    Example: "Disable international roaming."
  • Name
    limits
    Type
    nullable object
    Description
    Usage limits for a recurring add-on: how much data it gets each period, and when it's throttled. The value is null if the add-on has none.
    • Name
      dataBytes
      Type
      integer
      Description

      The maximum amount of data in bytes each period, including the throttled part.

      Example: 13000000000
    • Name
      throttling
      Type
      object
      Description
      The throttling configuration for the add-on.
  • Name
    name
    Type
    string
    Description

    Name for the add-on.

    Example: "1GB Data Top-up"
  • Name
    plans
    Type
    array
    Description

    The plans this add-on is compatible with.

  • Name
    price
    Type
    Price
    Description
    The price of the add-on.
    • Name
      amount
      Type
      integer
      Description

      The price amount in the currency's minor unit, e.g. "cents" for many currencies.

      Most currencies have two decimals, so USD 9.99 is 999. These currencies have a different number of decimals, e.g. JPY 28,500 is 28500:

      • 0 decimals: CLP, ISK, JPY, KRW
      Example: 999
      >= 0
    • Name
      currency
      Type
      string
      Description

      Three-letter ISO 4217 currency code. Must be a supported currency.

      Example: "USD"
  • Name
    provider
    Type
    string
    Description

    The ID of the network provider supported by this add-on.

    Example: "p5"
  • Name
    recurrenceType
    Type
    string
    Description

    The recurrence type the add-on.

    Example: "oneTime"
    Allowed values: oneTime recurring 
  • Name
    status
    Type
    string
    Description

    The current status of the add-on.

    Allowed values: draft available archived 
  • Name
    type
    Type
    string
    Description

    The type of the add-on.

    Example: "topUp"
    Allowed values: topUp other 
  • Name
    validity
    Type
    nullable object
    Description
    The validity period of the add-on. When the add-on is activated, it will expire after this duration. Not all add-ons have a validity period.
    • Name
      unit
      Type
      string
      Description

      The time unit of the add-on, either day or month.

      Allowed values: day month 
    • Name
      value
      Type
      integer
      Description

      The amount of units (specified in the unit property).

      Example: 7
      >= 1
    • Name
      totalPeriods
      Type
      integer
      Description

      How many times the validity period repeats. It is 2 or more for recurring add-ons and 1 for one-time add-ons. The total lifetime (value times unit times totalPeriods) must not exceed 10 years.

      Optional: This property may not always be included.
      Example: 1
      Default: 1
      >= 1
      <= 3652

Add-on object

{
  "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.",
  "limits": {
    "dataBytes": 13000000000,
    "throttling": {
      "thresholdBytes": 3000000000,
      "bandwidthBitsPerSecond": 256000
    }
  },
  "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,
    "totalPeriods": 1
  },
  "data": 10000000000,
  "dataUnit": "byte",
  "sms": 100,
  "smsUnit": "message",
  "voice": 30000,
  "voiceUnit": "second"
}