Usage API

Overview

All of the data elements and actions related to the usage management module are available through the API that could be used interchangeably with the manual usage reporting through the User interface.

This procedure will require interaction with following APIs:

#	API Method Name
1	Get Listings – GET /listings
2	Get Listing Details – GET /listings/{id}
3	Get Usage Files – GET /usage/files
4	Create Usage File – POST /usage/files
5	Get usage File – GET /usage/files/{id}
6	Upload usage file records – POST /usage/files/{id}/upload
7	Change usage file status – POST /usage/files/{id}/{status}

Note that all of the API calls described in this article follow common Data Format Conventions.

Scheduler recommendation

Vendor is free to upload usage files as often as it is required, any way is recommended to:

• Upload usage once a day for products that has reservation items
• For Pay Per use:
  • Daily: in case that vendor has real usage consumed on the day or after usage is final, this provides best accuracy and allows Distributors to ensure most of the usage is billed according to their business rules relative to the subscription
  • Once a month: Typically vendors uploads the usage once a month, either 1-2 days in advance the natural end of month, either matching the date that vendor bills Distributor

1. Get Listings – GET /listings

Resource	/listings/{id}
Method	GET
Header	Authorization:  ApiKey <key_id>:<key_secret>
Filter(s)	–
Default Filter(s)	–
Ordering	–
Default Ordering	–
Limit	–
Default limit	–

Response BodyHTML

Content-Type: application/json<span class="fr-marker" data-id="0" data-type="false" style="display: none; line-height: 0;"></span><span class="fr-marker" data-id="0" data-type="true" style="display: none; line-height: 0;"></span>
[ listing_obj1,
listing_obj1,
listing_obj1
]

---

2. Get Listing Details – GET /listings/{id}

Resource	/listings
Method	GET
Header	Authorization:  ApiKey <key_id>:<key_secret>
Filter(s)	status, contract, product, created_date
Default Filter(s)	–
Ordering	–
Default Ordering	–
Limit	–
Default limit	1000

Response Body

Content-Type: application/json
{
"id": "LST-066-644-910",
"status": "listed",
"contract": {
"id": "CRD-99082-45842-69180",
"type": "distribution",
"name": "Contract of IMC Demos Spain Distribution Agreement",
"marketplace": {
"id": "MP-91673",
"name": "IMC demos Marketplace",
"icon": "/media/PA-425-033/marketplaces/MP-91673/icon.jpg"
}
},
"product": {
"id": "CN-276-025-466",
"name": "release14Test"
},
"created": "2018-12-26T09:58:09+00:00",
"vendor": {
"id": "VA-004-290",
"name": "Marc's Staging Vendor"
},
"distributor": {
"id": "PA-425-033",
"name": "IMCDemos Testing Account"
}
}

NOTE: Is only possible to report usage for products in status listed

3. Get Usage Files – GET /usage/files

Resource	/usage/files
Method	GET
Header	Authorization:  ApiKey <key_id>:<key_secret>
Filter(s)	product_id, distribution_contract_id, status, created_at
Default Filter(s)	–
Ordering	Descending
Default Ordering	created_at
Limit	1000
Default limit	–

Response Body

Content-Type: application/json
[
usage_file_object1,
usage_file_object2,
usage_file_object3
]

4. Create Usage File – POST /usage/files

Resource	/usage/files
Method	POST
Header	Authorization:  ApiKey <key_id>:<key_secret>
Filter(s)	–
Default Filter(s)	–
Ordering	–
Default Ordering	–
Limit	–
Default limit	–

Request Body example

{
"name": "January 2019 usage",
"note": "",
"product": {
"id": "PRD-670-247-426"
},
"contract": {
"id": "CRD-00000-00000-00000"
}
}

Response body:

Content-Type: application/json
{
"id": "UF-2019-06-2923-9341",
"name": "January 2019 usage",
"note": "",
"status": "draft",
"created_by": "SU-164-531-341",
"created_at": "2019-06-05T14:09:19Z",
"records": {
"valid": 0,
"invalid": 0,
"closed": 0
},
"vendor": {
"id": "VA-004-290",
"name": "Acme Vendor"
},
"distributor": {
"id": "PA-323-693",
"name": "ACME Distributor"
},
"environment": "test",
"product": {
"id": "PRD-670-247-426",
"name": "Usage Product"
},
"contract": {
"id": "CRD-00000-00000-00000",
"name": "ACME Distribution Contract"
},
"marketplace": {
"id": "MP-00000",
"name": "ACME Marketplace"
}
}

5. Get usage File – GET /usage/files/{id}

Resource	/usage/files({id}
Method	GET
Header	Authorization:  ApiKey <key_id>:<key_secret>
Filter(s)	–
Default Filter(s)	–
Ordering	–
Default Ordering	–
Limit	–
Default limit	–

Response body:

Content-Type: application/json
{
"id": "UF-2019-06-2923-9341",
"name": "January 2019 usage",
"note": "",
"status": "draft",
"created_by": "SU-164-531-341",
"created_at": "2019-06-05T14:09:19Z",
"records": {
"valid": 0,
"invalid": 0,
"closed": 0
},
"vendor": {
"id": "VA-004-290",
"name": "Acme Vendor"
},
"distributor": {
"id": "PA-323-693",
"name": "ACME Distributor"
},
"environment": "test",
"product": {
"id": "PRD-670-247-426",
"name": "Usage Product"
},
"contract": {
"id": "CRD-00000-00000-00000",
"name": "ACME Distribution Contract"
},
"marketplace": {
"id": "MP-00000",
"name": "ACME Marketplace"
}
}

6. Upload usage file records – POST /usage/files/{id}/upload

Usage file must be prepared according to the template in XLSX format. Please check the usage reporting article to get more information about the file structure.

Resource	/usage/files({id}/upload
Method	POST
Header	Authorization:  ApiKey <key_id>:<key_secret>
Request Content Type	multipart/form-data

Response will return code 201 if success

7. Change usage file status – POST /usage/files/{id}/{status}

Resource	/usage/files/{id}/{status}
Method	POST
Header	Authorization:  ApiKey <key_id>:<key_secret>
Filter(s)	–
Default Filter(s)	–
Ordering	–
Default Ordering	–
Limit	–
Default limit	–

4a. Status → submit

Resource	/usage/files/{id}/submit
Method	POST
Header	Authorization: ApiKey  <key_id>:<key_secret>
Actor	Vendor

Request Body

Content-Type: application-json
{}

Response Body

Content-type: application/json
{
id: 'UF-2018-11-9878764342',
name: 'Usage for Feb 2019',
description: 'This file contains usage for the product belonging to month Feb 2019',
note: 'My personal note',
status:'pending',
created_by: 'admin@vendor.com',
created_at: '2018-11-21T11:10:29+00:00',
product: {
id: 'CN-783-317-575',
name: 'Google Apps'
},
contract: {
id: 'CRD-00000-00000-00000',
name: 'ACME Distribution Contract'
},
marketplace: {
id: 'MP-198987',
name: 'France',
icon: '/media/PA-123-123/marketplaces/MP-12345/image.png'
},
upload_file_uri: '<File Location for uploaded file>',
processed_file_uri: '<File Location for generated file>',
records: {
valid: 56,
invalid: 0
},
uploaded_by: 'admin@vendor.com',
uploaded_at: '2019-01-21T11:10:29+00:00',
submitted_by: 'admin@vendor.com',
submitted_at: '2018-01-21T11:10:29+00:00'
}

4b. Status → accept

Resource	/usage/files/{id}/accept
Method	POST
Header	Authorization: ApiKey  <key_id>:<key_secret>
Actor	Distributor

Request Body

Content-Type: application-json
{
acceptance_note: 'All usage data is correct'
}

Response Body

{
id: 'UF-2018-11-9878764342',
name: 'Usage for Feb 2019',
description: 'This file contains usage for the product belonging to month Feb 2019',
status:'accepted',
product: {
id: 'CN-783-317-575',
name: 'Google Apps'
},
contract: {
id: 'CRD-00000-00000-00000',
name: 'ACME Distribution Contract'
},
marketplace: {
id: 'MP-198987',
name: 'France',
icon: '/media/PA-123-123/marketplaces/MP-12345/image.png'
},
processed_file_uri: '<File Location for generated file>',
acceptance_note: 'All usage data is correct',
records: {
valid: 56,
invalid: 0
},
accepted_by: 'admin@distributor.com',
accepted_at: '2018-11-21T11:10:29+00:00'
}

4c. Status → reject

Resource	/usage/files/{id}/reject
Method	POST
Header	Authorization: ApiKey  <key_id>:<key_secret>
Actor	Distributor

Request Body

Content-Type: application-json
{
"rejection_note": "Rejected due to wrong usage for item 56"
}

Response Body

{
id: 'UF-2018-11-9878764342',
name: 'Usage for Feb 2019',
description: 'This file contains usage for the product belonging to month Feb 2019',
status:'rejected',
product: {
id: 'CN-783-317-575',
name: 'Google Apps'
},
contract: {
id: 'CRD-00000-00000-00000',
name: 'ACME Distribution Contract'
},
marketplace: {
id: 'MP-198987',
name: 'France',
icon: '/media/PA-123-123/marketplaces/MP-12345/image.png'
},
processed_file_uri: '<File Location for generated file>',
rejection_note: 'Rejected due to wrong usage for item 56',
records: {
valid: 56,
invalid: 0
},
rejected_by: 'admin@distributor.com',
rejected_at: '2018-11-21T11:10:29+00:00'
}

4d. Status → close

Resource	/usage/files/{id}/close
Method	POST
Header	Authorization: ApiKey  <key_id>:<key_secret>
Actor	Distributor

Request Body

Content-Type: application-json
{}

Response Body

{
id: 'UF-2018-11-9878764342',
name: 'Usage for Feb 2019',
description: 'This file contains usage for the product belonging to month Feb 2019',
status:'closed',
product: {
id: 'CN-783-317-575',
name: 'Google Apps'
},
contract: {
id: 'CRD-00000-00000-00000',
name: 'ACME Distribution Contract'
},
marketplace: {
id: 'MP-198987',
name: 'France',
icon: '/media/PA-123-123/marketplaces/MP-12345/image.png'
},
processed_file_uri: '<File Location for generated file>',
acceptance_note: 'All usage data is correct',
records: {
valid: 56,
invalid: 0
},
accepted_by: 'admin@distributor.com',
accepted_at: '2018-11-21T11:10:29+00:00',
closed_by: 'admin@distributor.com',
closed_at: '2018-11-21T11:10:29+00:00'
}

Usage File Status Transitions

Supported (valid) transitions:

1. draft → uploading (automatic transition by system)
2. uploading → uploaded (automatic transition by system)
3. uploaded → processing (automatic transition by system)
4. processing → ready (automatic transition by system)
5. processing → invalid (automatic transition by system)
6. ready → pending
7. pending → failed
8. pending → accepted
9. accepted → closed