Ledger and Factoring

Usage-from-swagger

1. Invoices

Get invoice.

1.1 Get specific Invoice

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

This resource is used to get an invoice.

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  
subscriptions dynamic   

2. Subscriptions

Get subscriptions for 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

This resource is used to get subscription for 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"
  }
}

Get single subscription for 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

This resource is used to get single subcription for 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  
usageDetails dynamic   
usageSummaries dynamic   

3. Usage-details

Get usage details for subscription related to 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

Get usage details for subscription related to invoice

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

{
 "items": [
    {
     "type": 250,
     "typeName": "Surf i h\u00F6gkostnadszon",
     "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, Betalf\u00F6rmedling, Mobil",
     "startDateTime": "2023-09-01T01:08:25",
     "destination": "Bingolotto f\u00E4rgfemman",
     "destinationName": "Inneh\u00E5llstj\u00E4nst, 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 f\u00E4rgfemman",
       "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 
typeName string  
startDateTime string  
destination string  
destinationName string  
subscriptionNo string  
totalAmount number Type: double 
volume number Type: int64 
volumeUnit string  
chargeDetails object    
   vatRate number Type: double 
   price number Type: double 
   priceUnit string  
   interval number Type: int32 
   intervalUnit string  
   startPrice number Type: double 
providerDetails object    
   name string  
   service string  
   serviceName string  
   contact string  
roamingDetails object    
   countryCode string  
   operator string  

4. Usage-summaries

Get usage summaries for subscription related to 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

Get usage summaries for subscription related to invoice

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 
typeName string  
usageCount number Type: int32 
firstUsageDate string  
lastUsageDate string  
totalAmount number Type: double 
volume number Type: int64 
volumeUnit string  
vatRate number Type: double 

5. Customers

Get customer

5.1 Get specific Customer

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

This resource is used to get a customer.

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  
subscriptions dynamic   

6. Subscriptions

Get subscriptions  for 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

This resource is used to get subscriptions for 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"
  }
}

Get single subscription  for customer

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

This resource is used to get single subcription for 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  
unbilledUsageDetails dynamic   
unbilledUsageSummaries dynamic   

7. Unbilled-usage-details

Get unbilled usage details for subscription related to 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

Get unbilled usage details for subscription related to customer

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

{
 "items": [
    {
     "type": 250,
     "typeName": "Surf i h\u00F6gkostnadszon",
     "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, Betalf\u00F6rmedling, Mobil",
     "startDateTime": "2023-09-01T01:08:25",
     "destination": "Bingolotto f\u00E4rgfemman",
     "destinationName": "Inneh\u00E5llstj\u00E4nst, 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 f\u00E4rgfemman",
       "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 
typeName string  
startDateTime string  
destination string  
destinationName string  
subscriptionNo string  
totalAmount number Type: double 
volume number Type: int64 
volumeUnit string  
chargeDetails object    
   vatRate number Type: double 
   price number Type: double 
   priceUnit string  
   interval number Type: int32 
   intervalUnit string  
   startPrice number Type: double 
providerDetails object    
   name string  
   service string  
   serviceName string  
   contact string  
roamingDetails object    
   countryCode string  
   operator string  

8. Unbilled-usage-summaries

Get unbilled usage summaries for subscription related to 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

Get unbilled usage summaries for subscription related to 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 
typeName string  
usageCount number Type: int32 
firstUsageDate string  
lastUsageDate string  
totalAmount number Type: double 
volume number Type: int64 
volumeUnit string  
vatRate number Type: double 

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