Usage-from-swagger

1. Invoices

"Invoices" presents billed usage

1.1 Get specific Invoice

Request
GET /billing/usage/v1/{ownerNo}/invoices/{invoiceNo} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Check if usage is billed and the invoice number is avalible in Usage

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "invoiceNo": "123456",
 "subscriptions": "/billing/usage/v1/xxx/invoices/123456/subscriptions"
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
invoiceNo string  Invoice number
subscriptions dynamic   Subscription/Phone -number

2. Subscriptions

"Subscriptions" presents a list of subscription number with billed usage included on selected invoice

2.1 Get list of Subscriptions

Request
GET /billing/usage/v1/{ownerNo}/invoices/{invoiceNo}/subscriptions HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a list of "Subscriptions" included on selected invoice

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "items": [
    {
     "subscriptionNo": "12345680",
     "usageDetails": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345680/usage-details",
     "usageSummaries": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345680/usage-summaries",
     "@id": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345680"
    },
    {
     "subscriptionNo": "12345690",
     "usageDetails": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345690/usage-details",
     "usageSummaries": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345690/usage-summaries",
     "@id": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345690"
    }
  ],
 "navigation": {
   "@id": "/billing/usage/v1/xxx/invoices/123456/subscriptions"
  }
}

"Subscription" -details for each subscription number included on selected invoice

2.2 Get specific Subscription

Request
GET /billing/usage/v1/{ownerNo}/invoices/{invoiceNo}/subscriptions/{subscriptionNo} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to present details for each "Subscriptions" included on selected invoice

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "subscriptionNo": "12345680",
 "usageDetails": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345680/usage-details",
 "usageSummaries": "/billing/usage/v1/xxx/invoices/123456/subscriptions/12345680/usage-summaries"
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
subscriptionNo string  Subscription/Phone -number
usageDetails dynamic   Detailed list of all usage
usageSummaries dynamic   Aggregated usage per usage type

3. Usage-details

"Usage-details" presents a detailed list of usage for each subscription number related to selected invoice

3.1 Get list of Usage-details

Request
GET /billing/usage/v1/{ownerNo}/invoices/{invoiceNo}/subscriptions/{subscriptionNo}/usage-details HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to present a detailed list of usage for selected "subscriptionNo" included on related invoice nr

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "items": [
    {
     "type": 250,
     "typeName": "Surf i hogkostnadszon",
     "startDateTime": "2023-09-01T01:08:25",
     "destination": "ROAM, SERVICES.COMPANY.COM",
     "destinationName": "APN Resterande",
     "subscriptionNo": "4671000000223344",
     "totalAmount": 2.50,
     "volume": 4257793,
     "volumeUnit": "B",
     "chargeDetails": {
       "vatRate": 25.00,
       "price": 107.61,
       "priceUnit": "MB",
       "interval": 50000,
       "intervalUnit": "B",
       "startPrice": 0.00
      },
     "roamingDetails": {
       "countryCode": "NO",
       "operator": "Vodafone"
      }
    },
    {
     "type": 255,
     "typeName": "Styckpris, Betalformedling, Mobil",
     "startDateTime": "2023-09-01T01:08:25",
     "destination": "Bingolotto fargfemman",
     "destinationName": "Innehallstjanst, samtal",
     "subscriptionNo": "4671000000223344",
     "totalAmount": 13,
     "volume": 1,
     "volumeUnit": "E",
     "chargeDetails": {
       "vatRate": 0.00,
       "price": 107.61,
       "priceUnit": "E",
       "interval": 1,
       "intervalUnit": "E",
       "startPrice": 0.00
      },
     "providerDetails": {
       "name": "Folkspel",
       "service": "Bingolotto fargfemman",
       "serviceName": "Bingolotto",
       "contact": "020-3334455, googleplay-support@google.com, play.google.com"
      }
    }
  ]
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
type number Type: int32 Usage type Id in PayEx Billing system
typeName string  Usage type name in PayEx Billing system
startDateTime string  Start time for CDR
destination string  "B-Nr" in CDR or if "Context" then "text"
destinationName string  Subscription Nr/Phone Nr
subscriptionNo string  Subscription Nr/Phone Nr
totalAmount number Type: double Total cost for CDR
volume number Type: int64 Volume/count of Usage
volumeUnit string  Unit for volume (S, MIN, E, B, KB, MB, GB)
chargeDetails object    
   vatRate number Type: double Vat rate for CDR
   price number Type: double Price per unit (Price per Event/MB/S/…)
   priceUnit string  Priced unit (S, MIN, E, B, KB, MB, GB)
   interval number Type: int32 Charge interval
   intervalUnit string  Start price for CDR
   startPrice number Type: double Start price for CDR
providerDetails object    
   name string  Content provider name
   service string  Content provider service
   serviceName string  Content provider service name
   contact string  Content provider contact details (phone, mail, web page)
roamingDetails object    
   countryCode string  Country code, (SE, NO,…)
   operator string  Name of operator for CDR/Usage

4. Usage-summaries

"Usage-summaries" presents a list of summarized usage per usage types for each subscription number related to selected invoice

4.1 Get list of Usage-summaries

Request
GET /billing/usage/v1/{ownerNo}/invoices/{invoiceNo}/subscriptions/{subscriptionNo}/usage-summaries HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to present a summarized list of usage per usage types for selected "subscriptionNo" included on related invoice nr

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "items": [
    {
     "type": 310,
     "typeName": "Description for 250",
     "usageCount": 3,
     "firstUsageDate": "2023-10-08T10:40:52",
     "lastUsageDate": "2023-10-19T12:20:52",
     "totalAmount": 299.50,
     "volume": 634,
     "volumeUnit": "S",
     "vatRate": 0.000
    },
    {
     "type": 330,
     "typeName": "Description for 330",
     "usageCount": 56,
     "firstUsageDate": "2023-10-02T12:19:52",
     "lastUsageDate": "2023-10-12T12:20:52",
     "totalAmount": 299.50,
     "volume": 634,
     "volumeUnit": "S",
     "vatRate": 0.000
    }
  ]
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
type number Type: int32 Usage type Id in PayEx Billing system
typeName string  Usage type name in PayEx Billing system
usageCount number Type: int32 CDR -count
firstUsageDate string  "First" day for Usage type
lastUsageDate string  "Last" day for Usage type
totalAmount number Type: double Total cost for aggregated CDRs
volume number Type: int64 Summarized volume for aggregated CDRs
volumeUnit string  Unit for volume (S, MIN, E, B, KB, MB, GB)
vatRate number Type: double Vat rate

5. Customers

"Customers" presents unbilled usage

5.1 Get specific Customer

Request
GET /billing/usage/v1/{ownerNo}/customers/{customerNo} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

Check if customer has any unbilled usage

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "customerNo": "224455",
 "subscriptions": "/billing/usage/v1/xxx/customers/224455/subscriptions"
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
customerNo string  Customer number
subscriptions dynamic   Subscription/Phone -number

6. Subscriptions

"Subscriptions" presents a list of subscription numbers with unbilled usage for selected customer

6.1 Get list of Subscriptions

Request
GET /billing/usage/v1/{ownerNo}/customers/{customerNo}/subscriptions HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a list of "Subscriptions" with unbilled usage for selected customer

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "items": [
    {
     "subscriptionNo": "12345680",
     "unbilledUsageDetails": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345680/unbilled-usage-details",
     "unbilledUsageSummaries": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345680/unbilled-usage-summaries",
     "@id": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345680"
    },
    {
     "subscriptionNo": "12345690",
     "unbilledUsageDetails": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345690/unbilled-usage-details",
     "unbilledUsageSummaries": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345690/unbilled-usage-summaries",
     "@id": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345690"
    }
  ],
 "navigation": {
   "@id": "/billing/usage/v1/xxx/customers/224455/subscriptions"
  }
}

"Subscription" -details for each subscription number with unbilled usage on selected customer nr

6.2 Get specific Subscription

Request
GET /billing/usage/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionNo} HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to get a list of "Subscriptions" with unbilled usage for selected customerThe resource is used to present details for each "Subscriptions" with unbilled usage on selected customer

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "subscriptionNo": "12345680",
 "unbilledUsageDetails": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345680/unbilled-usage-details",
 "unbilledUsageSummaries": "/billing/usage/v1/xxx/customers/224455/subscriptions/12345680/unbilled-usage-summaries"
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
subscriptionNo string  Subscription/Phone -number
unbilledUsageDetails dynamic   Detailed list of all unbilled usage
unbilledUsageSummaries dynamic   Aggregated unbilled usage per usage type

7. Unbilled-usage-details

"Unbilled-usage-details" presents a detailed list of unbilled usage for each subscription number related to selected customer

7.1 Get list of Unbilled-usage-details

Request
GET /billing/usage/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionNo}/unbilled-usage-details HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to present a detailed list of unbilled usage for selected "subscriptionNo" included on related customer

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "items": [
    {
     "type": 250,
     "typeName": "Surf i hogkostnadszon",
     "startDateTime": "2023-09-01T01:08:25",
     "destination": "ROAM, SERVICES.COMPANY.COM",
     "destinationName": "APN Resterande",
     "subscriptionNo": "4671000000223344",
     "totalAmount": 2.50,
     "volume": 4257793,
     "volumeUnit": "B",
     "chargeDetails": {
       "vatRate": 25.00,
       "price": 107.61,
       "priceUnit": "MB",
       "interval": 50000,
       "intervalUnit": "B",
       "startPrice": 0.00
      },
     "roamingDetails": {
       "countryCode": "NO",
       "operator": "Vodafone"
      }
    },
    {
     "type": 255,
     "typeName": "Styckpris, Betalformedling, Mobil",
     "startDateTime": "2023-09-01T01:08:25",
     "destination": "Bingolotto fargfemman",
     "destinationName": "Innehallstjanst, samtal",
     "subscriptionNo": "4671000000223344",
     "totalAmount": 13,
     "volume": 1,
     "volumeUnit": "E",
     "chargeDetails": {
       "vatRate": 0.00,
       "price": 107.61,
       "priceUnit": "E",
       "interval": 1,
       "intervalUnit": "E",
       "startPrice": 0.00
      },
     "providerDetails": {
       "name": "Folkspel",
       "service": "Bingolotto fargfemman",
       "serviceName": "Bingolotto",
       "contact": "020-3334455, googleplay-support@google.com, play.google.com"
      }
    }
  ]
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
type number Type: int32 Usage type Id in PayEx Billing system
typeName string  Usage type name in PayEx Billing system
startDateTime string  Start time for CDR
destination string  Called number ("B-Nr") in CDR or if "Context" then "text"
destinationName string  Subscription Nr/Phone Nr
subscriptionNo string  Subscription Nr/Phone Nr
totalAmount number Type: double Total cost for CDR
volume number Type: int64 Volume/count of Usage
volumeUnit string  Unit for volume (S, MIN, E, B, KB, MB, GB)
chargeDetails object    
   vatRate number Type: double Vat rate for CDR
   price number Type: double Price per unit (Price per Event/MB/S/…)
   priceUnit string  Priced unit (S, MIN, E, B, KB, MB, GB)
   interval number Type: int32 Charge interval
   intervalUnit string  Start price for CDR
   startPrice number Type: double Start price for CDR
providerDetails object    
   name string  Content provider name
   service string  Content provider service
   serviceName string  Content provider service name
   contact string  Content provider contact details (phone, mail, web page)
roamingDetails object    
   countryCode string  Country code, (SE, NO,…)
   operator string  Name of operator for CDR/Usage

8. Unbilled-usage-summaries

"Unbilled-usage-summaries" presents a list of summarized unbilled usage per usage types for each subscription number related to selected customer

8.1 Get list of Unbilled-usage-summaries

Request
GET /billing/usage/v1/{ownerNo}/customers/{customerNo}/subscriptions/{subscriptionNo}/unbilled-usage-summaries HTTP/1.1
Host: -
Authorization: Bearer<Token>
Content-Type: application/json

The resource is used to present a summarized list of unbilled usage per usage types for selected "subscriptionNo" related to selected customer

Response
HTTP/1.1 200 OK
Content-Type: application/json

{
 "items": [
    {
     "type": 310,
     "typeName": "Description for 250",
     "usageCount": 3,
     "firstUsageDate": "2023-10-08T10:40:52",
     "lastUsageDate": "2023-10-19T12:20:52",
     "totalAmount": 299.50,
     "volume": 634,
     "volumeUnit": "S",
     "vatRate": 0.000
    },
    {
     "type": 330,
     "typeName": "Description for 330",
     "usageCount": 56,
     "firstUsageDate": "2023-10-02T12:19:52",
     "lastUsageDate": "2023-10-12T12:20:52",
     "totalAmount": 299.50,
     "volume": 634,
     "volumeUnit": "S",
     "vatRate": 0.000
    }
  ]
}

Response object specification

Property Data typeFormatDescription
@id string  Uri identifier of the current resource
type number Type: int32 Usage type Id in PayEx Billing system
typeName string  Usage type name in PayEx Billing system
usageCount number Type: int32 CDR -count
firstUsageDate string  Date of "first" day for Usage type
lastUsageDate string  Date of "last" day for Usage type
totalAmount number Type: double Total cost for aggregated CDRs
volume number Type: int64 Summarized volume for aggregated CDRs
volumeUnit string  Unit for volume (S, MIN, E, B, KB, MB, GB)
vatRate number Type: double Vat rate

Problems

All errors from the api are returned in the form of "problems" (response body), except for the http status code itself.
The problem object contain more detailed info on what the error is. The "type" property can be used to programmatically interpret the error as it contains a code definition of the problem.
Other properties can be useful for logging and subsequent troubleshooting. Some problems are extended with additional parameters so it may be a good idea to log response body as raw data to include these.

Problems of type validation does contain an additional list ("Problems") that describes exactly which parameter that failed the validation

Example

Response
HTTP/1.1 400 Error
Content-Type: application/problem+json

{
  "Type" : "ledger/{domain}/v1/problems/validation",
  "Title" : "A validation error occurred",
  "Status" : 400,
  "Instance" : "215d4206-ca35-4f43-85ad-169c8f6d4ec1",
  "Detail" : "A validation error occurred. Please fix the problems mentioned in the 'problems' property below.",
  "Problems" :
      {
        "amount" : [
           "Expected value between [0,01]-[79228162514264337593543950335] actual [0]"
         ]
      }
}
Created by Anders Göthberg on 2024/04/17 13:31