User Tools

Site Tools


api:customer:customer-subscriptions

API : CustomerSubscriptions List

Introduction

This request will return all the subscriptions for either a given a customer, or a reseller. The reseller subscriptions is a summary of all of their customers' subscriptions.

For customers, all subscriptions are grouped per product, so the overview will show Product X, its price and wholesale, and the subscriptions/accounts that use this product.

For resellers, the grouping works similarly, but it goes a level beyond that, and groups all products on their reseller product, then showing per-customer usage under each product.

Both views are sorted by kind - the entry's accountType when it has one, else the product's type - and then by name, in Danish alphabetical order.

Request

URL https://api.telecomx.dk/customer/subscriptions
Method GET
Access level VIEWER, MANAGER or OWNER if user belongs to the customer.
RESELLER if customer belongs to the reseller or a sub reseller.
RESELLER_ADMIN.
ADMIN.
The reseller view: RESELLER if the reseller is the user's own or a sub reseller, RESELLER_ADMIN or ADMIN.
Query customer [optional] Id of the customer (24 hex-char string). RESELLER and up only - other users always get their own customer.
reseller [optional] Id of the reseller (24 hex-char string). If given, it will show a reseller view instead of customer view (thus overruling the customer query parameter). RESELLER and up - other users get the view of their own customer.
format [optional] Either csv or json (lowercase). Defaults to json. Only used in the reseller view - the customer view always returns JSON.

Query example

https://api.telecomx.dk/customer/subscriptions?customer=1234567890ABCDEF12345678
https://api.telecomx.dk/customer/subscriptions?customer=1234567890ABCDEF12345678&format=csv
https://api.telecomx.dk/customer/subscriptions?reseller=8211399890BBBDEF12345178
https://api.telecomx.dk/customer/subscriptions?reseller=8211399890BBBDEF12345178&format=csv

Response

The customer view and the reseller view return different objects, described below. A sum is null when a price or wholesale it adds up is missing, so below RESELLER every sumWholesale in the customer view is null.

Note that properties holding no value may be omitted from the object.

Customer view

Array of the following JSON objects
matchingProduct Object Product object, containing normal product properties (see API : Product Get). cost is left out below RESELLER_ADMIN, and wholesale below RESELLER. If the product no longer exists, the object only holds stats and the entry has no name
matchingProduct.stats Object Only when numbers use the product: singles (numbers outside whole blocks of 100 - on a number rent product not counting the first one), hundreds (whole blocks of 100 numbers) and usedRanges (the number ranges counted)
matchingProduct.units Number (integer) Number rent only: the numbers counted, a block of 100 counting as one
matchingProduct.sumPrice Number (decimal) Number rent only: the price of the numbers - the first single number at the product's price, the other single numbers at its extra price and each block of 100 at its price per 100
matchingProduct.sumWholesale Number (decimal) Number rent only: the wholesale of the numbers, counted like sumPrice
name String Name of the grouped product
accountType String AI, SMARTWATCH or DATA_SHARING_SIM on those entries. Absent on other entries
subscriptions Array The subscriptions/accounts that use the product - see below
sumPrice Number (decimal) Sum price of all subscriptions. For number rent the same as matchingProduct.sumPrice
sumWholesale Number (decimal) Sum wholesale of all subscriptions. null below RESELLER
units Number (integer) Amount of subscriptions/units, counting the units of add-ons, invoice lines and the AI subscription. For number rent the same as matchingProduct.units
subscriptions[] in the customer view
type String The kind of subscription: EMPLOYEE (PBX user), PBX_EXTENSION, PBX_SIP_PHONE, MVNO (mobile account), SIP (SIP account or PBX trunk), NUMBER or DNS. Absent on add-ons, invoice lines and the subscriptions with an accountType
accountType String AI, SMARTWATCH or DATA_SHARING_SIM
_id ObjectId Id of the subscription. A number's is the number (String, e.g. +4588888888), a domain's is the domain name (String), and the AI subscription's is the customer id. Absent on smartwatches and data-sharing SIMs
name String Name of the subscription
customer ObjectId Customer ID. Absent on add-ons, smartwatches and data-sharing SIMs
product ObjectId The product the subscription is on
startDate Date When the subscription started, where known
units Number (integer) Units, on add-ons, invoice lines and the AI subscription. Any other subscription counts as one
price Number (decimal) The price of the subscription: its own, else the product's price, or the unit price times units on an AD_HOC product. 0 when included. Absent on numbers on a number rent product, which are priced on the entry
wholesale Number (decimal) The wholesale of the subscription, counted like price. Absent or null below RESELLER unless the subscription has its own
isIncluded Boolean Only on a subscription that a PBX user's product or a mobile account's rate plan includes for free. Its price is then 0
normalPrice Number (decimal) Only with isIncluded: the price the subscription would have had

Each kind of subscription also holds its own properties:

  • EMPLOYEE (PBX user): accessLevel, invoicedUntil, addonProducts (the user's add-ons, the same objects listed as add-on subscriptions) and subscriptions (always an empty array).
  • Add-on of a PBX user (no type): employee (the PBX user), description, unitPrice, start, earliestStart, terminate, invoicedUntil, employeeId and employeeName. The name is the add-on's name and the user's name separated by : '', or the user's name alone. * ''PBX_EXTENSION: employee and invoicedUntil. Only extensions with a product of their own are listed.
  • PBX_SIP_PHONE: sipPhoneModel, matchingSipPhoneModel (the model's _id, brand and model, or only the model id when the model no longer exists), extension, employee (the user of the extension) and invoicedUntil. A phone without a name is named <brand>: <model>.
  • MVNO and SIP: ratePlan (the same as product), numbers and invoicedUntil. A mobile account also has employee (the user of its extension or number), sipAccount, extension, smartWatch (its smartwatch and the SIM's details, as stored) and dataSharingSims (its data-sharing SIMs and their details, as stored). Only active or blocked accounts with a rate plan are listed.
  • NUMBER: range, employee, live and state. The name is the number without +45, followed by the user's name in brackets when the number belongs to a user. Only numbers in use are listed, and a number without a product of its own is on the customer's number rent product.
  • DNS: no other properties - the domain is its _id and name.
  • Invoice line (no type): the recurring invoice line as stored, e.g. description, unitPrice, unitWholesale, start, earliestStart, terminate, invoicedUntil, locked, recurrence and billingCustomer. A line without a name is named after its description.
  • AI: units, always 1.
  • SMARTWATCH: the smartwatch as stored (eid, model, state, number, createdAt, orderState, invoicedUntil and smartWatchSim, the SIM's details) and voiceAccount (the mobile account). Only active smartwatches are listed.
  • DATA_SHARING_SIM: voiceAccount (the mobile account). The name is the account's name or number and the SIM's name or SIM number, separated by '' - ''.

Reseller view

The reseller view covers the reseller's active customers (its own customers, not those of its sub resellers). It counts every number that is not on a mobile account, whatever its state, and leaves out what a PBX user's product includes for free.

Array of the following JSON objects
matchingProduct Object The reseller product that the customers' products inherit from, or the customer's product itself when it inherits from none - e.g. an AD_HOC product put directly on customers (see API : Product Get). cost, costExtra and cost100 are left out below ADMIN, and always on the smartwatch and data-sharing SIM products
matchingProduct.stats Object Only on a customer's number rent product that inherits from none: the counts per customer id, each with singles, hundreds, usedRanges, units, sumPrice and sumWholesale
matchingProduct.units Number (integer) Only on a customer's product that inherits from none: for number rent the numbers counted, otherwise the product's own units or 0
matchingProduct.sumPrice Number (decimal) Only on a customer's number rent product that inherits from none: the price over the customers
matchingProduct.sumWholesale Number (decimal) Only on a customer's number rent product that inherits from none: the wholesale over the customers
name String Name of the grouped product
accountType String SMARTWATCH or DATA_SHARING_SIM on those entries. Absent on other entries
stats Object Only on a customer's number rent product that inherits from none: always an empty object
subscriptions Array One total per customer
subscriptions[].customer ObjectId Customer ID
subscriptions[].name String Customer name
subscriptions[].sumPrice Number (decimal) The customer's price of these subscriptions
subscriptions[].sumWholesale Number (decimal) The customer's wholesale of these subscriptions
subscriptions[].units Number (integer) The customer's amount of these subscriptions
subscriptions[].startDate Date The start date of the customer's first subscription on the product, where known
sumPrice Number (decimal) Sum price of all subscriptions
sumWholesale Number (decimal) Sum wholesale of all subscriptions
units Number (integer) Amount of subscriptions/units

With format=csv (reseller view only) the response is a text/csv attachment (subscriptions.csv), one line per entry in the same order, with the columns: Productkode;Produktnavn;Antal;Forhandlerpris;Pris. Antal is units, Forhandlerpris sumWholesale and Pris sumPrice, written with two decimals and a decimal comma.

Example

The customer view as a RESELLER sees it, with matchingProduct shortened:

[
  {
    "matchingProduct": {
      "stats": {
        "singles": 1,
        "hundreds": 0,
        "usedRanges": []
      },
      "_id": "650000000000000000000401",
      "type": "NUMBER_RENT",
      "name": "Number rent",
      "productCode": "NR-1",
      "price": 10,
      "wholesale": 8,
      "priceExtra": 5,
      "wholesaleExtra": 4,
      "price100": 300,
      "wholesale100": 250,
      "units": 2,
      "sumPrice": 15,
      "sumWholesale": 12
    },
    "subscriptions": [
      {
        "_id": "+4588888801",
        "customer": "650000000000000000000101",
        "name": "88888801 (Example User)",
        "range": null,
        "employee": "650000000000000000000201",
        "product": "650000000000000000000401",
        "live": "2026-01-05T00:00:00.000Z",
        "state": "IN_USE",
        "startDate": "2026-01-05T00:00:00.000Z",
        "type": "NUMBER"
      },
      {
        "_id": "+4588888802",
        "customer": "650000000000000000000101",
        "name": "88888802",
        "range": null,
        "employee": null,
        "product": "650000000000000000000401",
        "live": "2026-02-01T00:00:00.000Z",
        "state": "IN_USE",
        "startDate": "2026-02-01T00:00:00.000Z",
        "type": "NUMBER"
      }
    ],
    "name": "Number rent",
    "sumPrice": 15,
    "sumWholesale": 12,
    "units": 2
  },
  {
    "matchingProduct": {
      "_id": "650000000000000000000402",
      "type": "PBX_USER",
      "name": "PBX user",
      "productCode": "PBX-1",
      "price": 99,
      "wholesale": 60
    },
    "subscriptions": [
      {
        "_id": "650000000000000000000201",
        "customer": "650000000000000000000101",
        "name": "Example User",
        "accessLevel": "MANAGER",
        "product": "650000000000000000000402",
        "addonProducts": [],
        "invoicedUntil": "2026-10-31T00:00:00.000Z",
        "startDate": "2025-03-01T00:00:00.000Z",
        "type": "EMPLOYEE",
        "subscriptions": [],
        "price": 99,
        "wholesale": 60
      }
    ],
    "name": "PBX user",
    "sumPrice": 99,
    "sumWholesale": 60,
    "units": 1
  }
]

The reseller view, with matchingProduct shortened:

[
  {
    "matchingProduct": {
      "_id": "650000000000000000000501",
      "type": "PBX_USER",
      "name": "PBX user",
      "productCode": "PBX-1",
      "price": 99,
      "wholesale": 60
    },
    "sumPrice": 297,
    "sumWholesale": 180,
    "subscriptions": [
      {
        "sumPrice": 198,
        "sumWholesale": 120,
        "units": 2,
        "name": "Example Company East",
        "customer": "650000000000000000000101",
        "startDate": "2025-03-01T00:00:00.000Z"
      },
      {
        "sumPrice": 99,
        "sumWholesale": 60,
        "units": 1,
        "name": "Example Company North",
        "customer": "650000000000000000000102",
        "startDate": "2025-06-01T00:00:00.000Z"
      }
    ],
    "name": "PBX user",
    "units": 3
  }
]

Errors

Error code Message Description
422 <property> Invalid input for the named property - the request body, query or URL parameter failed validation
404 reseller Reseller not found
403 access_denied Insufficient access level
500 internal_error <Unspecified>
api/customer/customer-subscriptions.txt · Last modified: by Mikkel Meerwaldt Jørgensen

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki