Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
post
faq
Filter by Categories
Tools / SDKs
Public API
Recurring Services (pre-defined plans)
Integration Framework
Implementation Guide
Flow Diagram Library
Service Management
Payment Gateways
Use Cases
Developer Resources
Tools
Uncategorized

Pay Per Use Subscription Management

The service manager supports pay per use (PPU) subscriptions, since many distributors and service providers use the PPU billing model.

Please note that the following two terms are sometimes used interchangeably in the BSS and in this section:

  • Resource: a reserve supply that can be drawn upon when needed
  • Usage: is the act of using a resource

The endpoints in this section provide an overview of the consumption of a PPU subscription.

Usages Endpoint

Swagger Documentation: POST /api/Ppu/usages

This endpoint is used to obtain the data on the usages of an active PPU subscription.

Request

  • ID – The external ID of the subscription
  • RelatedSubscriptionID – The ID of the subscription on the interworks.cloud platform
  • ServiceType – The external ID of the product type
  • RelatedProductID – The product ID on the interworks.cloud platform
  • Account
    • ID – The external ID of the account
    • RelatedAccountID – The ID of the account on the interworks.cloud platform
  • BillingCycle – The period for which usage data is requested.
    • StartDate – The start date of the usage
    • EndDate – The end date of the usage
  • Currency – The currency in which the price(s) are requested
  • IsTest – A boolean value which determines whether or not the endpoint is called for testing purposes

Response

The response contains an array of records

  • Usages – This is an array of usage records, which contains the following fields for each resource:
    • Description – The description of the totals returned by the Get Usages endpoint.
    • Id – A unique identifier of the usage record
    • Name – The name of the resource in the usage record
    • Type – The type of resource(s) in the usage record
    • Location – Used to group usage data based on the location
    • Group – Specifies a resource group for the usage data
    • Customer – Used to group usage data based on the customer
    • AttributeId – A product type characteristic, as it was returned by the GetServicesDefinition endpoint.
    • Quantity – Specifies how much of the resource has been used
    • Unit – Determines the unit of measurement for the quantity used
    • CostPrice –The cost price for one unit of the resource
    • SellPrice – The recommended sale price for one unit of the resource
    • StartDate – The starting date of the usage
    • EndDate – The end date of the usage
  • Totals – The
    • Items – The total amount of resources included in the current usage record
    • CostPrice – The total cost price for all resources
    • SellPrice – The total recommended sale price for all resources
  • Currency – The currency is returned either to confirm that the requested currency has been returned, or to provide a base for conversion.
  • LastUpdateAt – Specifies when the usage data was last updated
  • Code – A negative value in this field means that there has been an error.
  • Message – The error message, if any

To override the CostPrice and SellPrice of specific records,

When this Endpoint is Called

The usages endpoint is called when selecting to view the usage records of a pay per use product.

Storefront Subscription Usage Records
BSS Subscription Usage Records

Implementation Checklist

To test this endpoint, select a PPU subscription, and view its usage records.

Billing Items Endpoint

Swagger Documentation: POST /api/Ppu/billingItems

The Billing Items endpoint is used to get the final charges that will be included in an invoice for a specific billing cycle of a Pay per Use subscription.

Request & Response

The request of this endpoint contains the same fields as the Usages endpoint.

The usage records obtained from GetUsages may be grouped to show fewer entries in the invoice.

The response is also similar, the main difference being the BillingCycleStatus field. This field indicates the status of the billing process, for the requested billing period in the third party system.

Whether or not to proceed with the billing process and invoice generation is decided by the value of BillingCycleStatus:

  • Open – When the collection of usages is incomplete for the specified billing period
  • Closed – When the collection of usages is complete for the specified billing period

BillingCycleStatus must be equal to Closed only when there are no more charges to include for the billing cycle. Any subsequent collection of usage data will not affect the charges provided for the billing cycle.

When this Endpoint is Called

The endpoint is called when the billing services run at the end of every day.