UsageAdapterManager

The type is used to implement Charge Import API

Schema

The considered APS type (download) extends the Resource APS type(s) and looks as follows:

{
  "name": "UsageAdapterManager",
  "id": "http://com.odin.rating/usage-adapter-manager/1.0",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/resource/1.0"
  ],
  "operations": {
    "processUsageReports": {
      "path": "usageReports",
      "verb": "POST",
      "errorResponse": {
        "type": "object"
      }
    },
    "getUsageReports": {
      "path": "usageReportsList",
      "verb": "GET",
      "response": {
        "type": "object"
      },
      "errorResponse": {
        "type": "object"
      }
    },
    "getReportErrors": {
      "path": "errorList",
      "verb": "GET",
      "response": {
        "type": "object"
      },
      "errorResponse": {
        "type": "object"
      },
      "parameters": {
        "reportId": {
          "kind": "query",
          "type": "string"
        },
        "productId": {
          "kind": "query",
          "type": "string"
        }
      }
    },
    "getReportTemplate": {
      "path": "/usageReportTemplate",
      "verb": "GET",
      "response": {
        "type": "object"
      },
      "errorResponse": {
        "type": "object"
      }
    }
  }
}

Custom Operations

OPERATION	VERB	PATH	RETURNS	Description
processUsageReports	POST	/usageReports
getUsageReports	GET	/usageReportsList
getReportErrors	GET	/errorList
getReportTemplate	GET	/usageReportTemplate

processUsageReports

HTTP Request

POST /aps/2/resources/{aps-id}/usageReports

Description

Returns

getUsageReports

HTTP Request

GET /aps/2/resources/{aps-id}/usageReportsList

Description

Returns

getReportErrors

HTTP Request

GET /aps/2/resources/{aps-id}/errorList

Description

Parameters

PARAMETER	TYPE	DESCRIPTION
reportId	String
productId	String

Returns

getReportTemplate

HTTP Request

GET /aps/2/resources/{aps-id}/usageReportTemplate

Description

Returns

Limitations

Only the provider staff is authorized to call the Usage Adapter Manager operations.

This API is initially intended for CloudBlue Connect, a business-to-business (B2B) matching platform that connects various software vendors with various commerce platforms. Other integrated applications can use this API as well.

Monitoring Resource Usage

Account Layers

The platform supports a sales channel hierarchy with several levels. The following is a typical hierarchy that consists of four levels:

• The provider, also called as level 0 (L0), is the platform owner. The provider can interact with software vendors directly or through L1 resellers that can be operating units of the provider rather than partners.

• L1 resellers can be the provider’s partners (who have a commercial relationship with the provider) or the provider’s operating units. For example, in the latter case, they represent the provider in different countries.

• L2 resellers are the partners of the upper-level resellers.

• Customers are the consumers of products sold by their L2 resellers.

Layers and Tiers

On the software vendor side, the business hierarchy terminology can differ from the terminology described above. For example, the CloudBlue Connect platform breaks the account hierarchy vertically into tiers counting them from customers up to the provider. In this case, keep in mind the following mapping:

Account	Levels on the commerce platform	Tiers on a vendor’s side
Provider	L0	T3
Reseller as a partner or a provider’s operating unit	L1	T2
Reseller as a partner	L2	T1
Customer	Not applicable	T0

Product Usage Schemas

A product usage schema defines the way the vendor and the commerce platform charge the provider, resellers, and customers. Currently, the following schemas can be used in vendor-rated reports:

• TR (Tier-Rated):

  • The vendor specifies prices for all tiers.

  • The platform uses those prices to charge all involved accounts except for the provider. The provider pays to the vendor outside the BSS.

• CR (Cost Rated):

  • The vendor specifies the cost for the used resources, that is, the price that the provider must pay the vendor.

  • The platform calculates prices for the other levels using a margin. According to this method, the price for every lower-level account equals the upper-level price with an added margin assigned to that upper-level account.

• PR (Price Rated):

  • The vendor specifies the price for the end customer. Typically, this is the MSRP (Manufacture Suggested Retail Price).

  • The platform calculates prices for the other levels using a margin. According to this method, the price for each upper-level account equals the price of the lower-level account minus the margin assigned to that upper-level account.

File Format

External systems, including UI systems, can use the considered API to upload the resource usage reported by a software vendor system as a file in XLSX format. The file must contain at least two tabs:

• general defines general parameters of the report, including identification of the schema, marketplace, and hub.

• records defines charges for resources of a specific product sold through the specified hub.

General Tab

Attribute ID	Example	Description	Required
report_name	Consumption report for April 2020	The name that the vendor assigns to this report.	Yes
report_note	Please process before May 15th.	Anything that the vendor wants to note.	Yes
report_id	RID-12345-12345	The report ID on the vendor side.	Yes
report_start_time_utc	01/04/20 00:00	The usage period start date and time.	Yes
report_end_time_utc	01/05/20 00:00	The usage period end date and time.	Yes
usage_schema	CR	Defines one of the billing modes (TR, CR, PR, or QT).	Yes
marketplace_account_id	10000012	Applicable only to the CR schema. It defines the marketplace owner (typically, the provider or L1 reseller) ID assigned in the platform.	Yes
currency	USD	Applicable to AR, CR, and PR schemas.	Yes
product_id	PRD-12345-67890	The product ID on the vendor side.	Yes
product_name	Cloud Puzzles	The product name.	Yes
marketplace_id	MKT-1234-1234	The marketplace ID on the vendor side. A marketplace is a logical unit containing several hubs.	No
marketplace_name	United States	The marketplace name on the vendor side.	No
hub_id	HB-1234-1234	The hub ID on the vendor side. A hub is a specific installation of the commerce platform belonging to the provider.	No
hub_name	European Production	The name of the hub on the vendor side.	No
vendor_account_id	VA-1234-1234	The vendor ID that is typically assigned by an intermediate B2B matching platform.	No
vendor_account_name	Puzzles and Games for Business	The vendor name.	No
provider_account_id	PA-1234-1234	The provider ID that is typically assigned by an intermediate B2B matching platform.	No
provider_account_name	Fun for Business Provider	The provider name on the vendor side.	No
distribution_contract_id	CRD-12345-12345	The ID of the distribution contract signed by the provider and vendor. This is typically assigned by an intermediate B2B matching platform.	No

Records Tab

An imported XLS file must contain the records tab with a table that consists of charges with the following attributes (columns):

Attribute ID	Example	Description	Required
record_id	f2b0b523-38ae-4653-b870-48b3cddcd38d	A globally unique record ID that comes from the vendor side.	Yes
report_note	Please process before May 15th.	An optional note that is associated with the charge record.	No
start_time_utc	01/04/20 00:00	The timestamp in UTC 0 that represents the beginning of the time period for the usage file.	Yes
end_time_utc	01/05/20 00:00	timestamp in UTC 0 that represents the end of the time period for the usage file.	Yes
item_name	Migration Tool	A descriptive name of a resource (product item) defined by the vendor.	Yes
item_id	PRD-111-222-333-444	A globally unique product item ID assigned on the vendor side.	Yes
item_mpn	Migration-001-001	The product item MPN assigned on the vendor side. It is unique within a given product and can be changed by the vendor during the product lifetime.	Yes
item_unit	item	A unit of measure for the product item.	Yes
asset_external_id	1000044	The asset ID that is the respective subscription ID assigned in the commerce platform.	Yes
asset_external_uid	df0d6f14-22a9-11ea-9fdf-2b0b8bc501b3	The asset unique ID that is the APS ID assigned to the respective resource in the commerce platform.	Yes
asset_recon_id	ABC123	A primary reconciliation ID assigned on the vendor side.	No
quantity	4	A quantity of the resource usage.	Yes
amount	15.8	Total monetary amount in the currency specified in the general tab. It can be different from the value calculated as the quantity multiplied by the unit_price.	Yes for TR, CR, and PR
tier	0	A tier that the charge is generated for.	Yes for TR

Parameters Differentiated by Schemas

The tier and amount parameters can be ignored depending on the product usage schema:

Schema	Tier	Amount
TR	A separate row for every tier; see the example for the TR schema below	A different value for every tier
CR	Ignored	The provider’s cost
PR	Ignored	The price that the customer pays for the resource (the customer’s cost)
QT	Ignored	Ignored

Examples

Uploading Resource Usage

To upload resource usage data from the resource-usage.xlsx file to the platform, run the following command:

curl -F ‘data=@path/to/local/file’  https://{brand-endpoint}/aps/2/{aps-id}/usageReports

TR Schema

If a product supports the TR schema, the resource usage table contains several rows for every resource differentiated by tiers. For simplicity, the following example has only a few columns:

asset_external_id	asset_external_uid	quantity	asset_recon_id	amount	tier
10000012	df0d6f14-22a9-11ea-9fdf-2b0b8bc501b3	15,75	ABC123	70	0
10000012	df0d6f14-22a9-11ea-9fdf-2b0b8bc501b3	15,75	ABC123	60	1
10000012	df0d6f14-22a9-11ea-9fdf-2b0b8bc501b3	15,75	ABC123	50	2

← MarginManager

Configuration Management →