Costs API

Costs API lets you explore product usage data and experiment with pricing plans using existing datasets without impacting customers.

  1. See customer product adoption over a period of time
  2. Create a new plan and see how it stacks up against the current account plan
  3. Experiment with pricing by trying new plans on the account

How to use costs API?

If you use invoices API with RevOps today, you will be at home using costs API. It uses similar structure to invoices API, and gives you more flexibility to query your usage.

Cost Endpoints

Each endpoint assumes a default base url: https://vault.revops.io/v1/

Costs List Resource

https://vault.revops.io/v1/accounts/:acct_id/costs

Supported Methods:

  • GET - Calculates costs for a given time period on the existing plan (if no plan id provided) or the provided plan id for the given account.
URL Parameters
Name Description Required Schema
acct_id Unique identifier for the Account generated by the RevOps API. Yes string

API Key Accessibility

Invoice resources can only be accessed with your secret key.

HTTP Method Public Key Secret Key
GET N/A

Calculate usage and cost

GET /v1/accounts/:acct_id/costs

Summary:

Returns a paginated list of Usage and costs associated with an Account.

Query Parameters

Name Description
page Return results for the specified page number
pageSize The number of results to include with each page. The default is 50 and the maximum is 100.
startDate The start date for records to be included. This must be formatted YYYY-MM-DD.
endDate The end date for records to be included. This must be formatted YYYY-MM-DD.
planId Plan for which costs needs to be calculated, defaults to existing plan on the account.

Note: The startdate and enddate are inclusive or exclusive depending on the format you supply. See Determining Start and End Date for more information.

HTTP Response Codes
Code Description Schema
200 Costs Costs
400 Invalid request. API Error

Example

$> curl  https://vault.revops.io/v1/accounts/:acct_id/costs \
        -X GET \
        -H 'Authorization: Bearer <secret_key>' \
        -H 'Content-type: application/json'

The following is an example response:

{
  "first_page_uri": "/v1/accounts/acct_e0aadc65822548e0b3163bcc68a747de/costs?page=0&pageSize=50",
  "next_page_uri": null,
  "page": 0,
  "page_size": 50,
  "previous_page_uri": null,
  "results": [
    {
      "aggregate_amount": "340.04",
      "aggregate_quantity": "9001.0",
      "currency": "USD",
      "date_created": null,
      "date_updated": null,
      "description": "Persistent Records",
      "end_date": "2020-02-01T00:00:00+00:00",
      "invoice_id": "",
      "is_lifetime": true,
      "pricing_schedule": "",
      "provider_id": "",
      "rate_table": [
        {
          "amount": "0.0",
          "id": "84baf95b-fa17-487f-bcfb-bc75acb1db37",
          "monthly_rate": "0.00",
          "quantity": "500",
          "quantity_max": "500",
          "quantity_min": "0",
          "rate": "0.00000000000000000000"
        },
        {
          "amount": "340.04",
          "id": "17598498-23b4-435d-884a-422cbb9a82d5",
          "monthly_rate": "0.00",
          "quantity": "8501.0",
          "quantity_max": "Infinity",
          "quantity_min": "501",
          "rate": "0.04000000000000000000"
        }
      ],
      "sku_type": "",
      "start_date": "2020-01-01T00:00:00+00:00",
      "status": "active",
      "usage_rows": [
        {
          "amount": "0.0",
          "cumulative_sum": "11437.0",
          "quantity": "6001",
          "resource": "Persistent Records",
          "timestamp": "2020-01-30T00:00:00.000Z",
          "unit_rate": "0.02"
        },
        {
          "amount": "0.0",
          "cumulative_sum": "11737.0",
          "quantity": "3000",
          "resource": "Persistent Records",
          "timestamp": "2020-01-31T00:00:00.000Z",
          "unit_rate": "0.02"
        }
      ]
    },
    {
      "aggregate_amount": "0.0",
      "aggregate_quantity": "0",
      "currency": "USD",
      "date_created": null,
      "date_updated": null,
      "description": "Archived Records",
      "end_date": "2020-02-01T00:00:00+00:00",
      "invoice_id": "",
      "is_lifetime": true,
      "pricing_schedule": "",
      "provider_id": "",
      "rate_table": [
        {
          "amount": "0.0",
          "id": "1ec7b54a-4cf5-4f04-9447-7c798853e7b2",
          "monthly_rate": "0.00",
          "quantity": "0",
          "quantity_max": "500",
          "quantity_min": "0",
          "rate": "0.00000000000000000000"
        },
        {
          "amount": "-0.0",
          "id": "3f909f96-6f10-4bff-965a-1778d1b35e82",
          "monthly_rate": "0.00",
          "quantity": "0",
          "quantity_max": "Infinity",
          "quantity_min": "501",
          "rate": "-0.04000000000000000000"
        }
      ],
      "sku_type": "",
      "start_date": "2020-01-01T00:00:00+00:00",
      "status": "active",
      "usage_rows": []
    }
  ]
}

Response Model

Costs Response
Name Description
firstpageuri URI to access first page
nextpageuri URI to next page if there are more results
page Current page number
page_size Size of the page requested, defaults to 50
previouspageuri URI to previous page if exists (i.e. if page > 1)
results List of Costs, refer to costs model below
Cost Object
Name Description
aggregate_amount Total amount for the item in the given time period
aggregate_quantity Total quantity for the item in the given time period
currency Currency in which costs are calculated
description Description of the item
end_date End date(exclusive) for the time period which costs are calculated
is_lifetime Is this calculated as life time usage
rate_table Rate table used to calculate costs, refer to object below
start_date Start date (inclusive) for the time period which costs are calculated
usage_rows Breakdown of usage by date. Refer to usage object below
Usage Object
Name Description
amount Cost attributed to this item on given day
cumulative_sum Total running sum. This will be zero if it is not calculated as lifetime usage
quantity Quantity attributed to this item on given day
resource Resource on which usage has occured
timestamp Time for which usage occurred
unit_rate Per unit rate
RateTable Object

RateTables capture the tiers used to compute volume and progressive based pricing:

Name Description
amount Cost this individual rate tier contributes to the aggregate amount
id Unique identifer for the rate tier
monthly_rate Fixed monthly cost to include in the aggregate amount
quantity Quantity used to calculate the amount for this rate tier. For volume based pricing, this value can be up to quantitymax. For progressive based pricing, this value will be up to (quantitymax - quantity_min).
quantity_max Maximum quantity for this tier, for last tier it is infinity
quantity_min Minimum quantity for this tier to kick in
rate Cost at this tier