Close
Community
PDF
Usage Community Modules Usage

Usage API

Updated: May 21, 2020
Contents

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
1Get Listings – GET /listings
2Get Listing Details – GET /listings/{id}
3Get Usage Files – GET /usage/files
4Create Usage File – POST /usage/files
5Get usage File – GET /usage/files/{id}
6Upload usage file records – POST /usage/files/{id}/upload
7Change 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 providers 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 provider

1. Get Listings – GET /listings

Resource/listings/{id}
MethodGET
HeaderAuthorization:  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
MethodGET
HeaderAuthorization:  ApiKey <key_id>:<key_secret>
Filter(s)status, contract, product, created_date
Default Filter(s)–
Ordering–
Default Ordering–
Limit–
Default limit1000

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"
  },
  "provider": {
    "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
MethodGET
HeaderAuthorization:  ApiKey <key_id>:<key_secret>
Filter(s)product_id, distribution_contract_id, status, created_at
Default Filter(s)–
OrderingDescending
Default Orderingcreated_at
Limit1000
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
MethodPOST
HeaderAuthorization:  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"
  },
  "provider": {
    "id": "PA-323-693",
    "name": "ACME Provider"
  },
  "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}
MethodGET
HeaderAuthorization:  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"
  },
  "provider": {
    "id": "PA-323-693",
    "name": "ACME Provider"
  },
  "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
MethodPOST
HeaderAuthorization:  ApiKey <key_id>:<key_secret>
Request Content Typemultipart/form-data

Response will return code 201 if success

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

Resource/usage/files/{id}/{status}
MethodPOST
HeaderAuthorization:  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>
ActorVendor

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>
ActorProvider

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@provider.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>
ActorProvider

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@provider.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>
ActorProvider

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@provider.com',
    accepted_at: '2018-11-21T11:10:29+00:00',
    closed_by: 'admin@provider.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
Is this page helpful?
Translate with Google
en English
ar Arabiczh-CN Chinese (Simplified)nl Dutchen Englishfr Frenchde Germanit Italianpt Portugueseru Russianes Spanish
Contents
Translate with Google
en English
ar Arabiczh-CN Chinese (Simplified)nl Dutchen Englishfr Frenchde Germanit Italianpt Portugueseru Russianes Spanish
Is this page helpful?
Copied to clipboard