Price

Evaluate price

This endpoint is used to evaluate the output of a price for a given customer and time range. It enables filtering and grouping the output using computed properties, supporting the following workflows:

Showing detailed usage and costs to the end customer.
Auditing subtotals on invoice line items.

For these workflows, the expressiveness of computed properties in both the filters and grouping is critical. For example, if you’d like to show your customer their usage grouped by hour and another property, you can do so with the following grouping_keys: ["hour_floor_timestamp_millis(timestamp_millis)", "my_property"]. If you’d like to examine a customer’s usage for a specific property value, you can do so with the following filter: my_property = 'foo' AND my_other_property = 'bar'.

By default, the start of the time range must be no more than 100 days ago and the length of the results must be no greater than 1000. Note that this is a POST endpoint rather than a GET endpoint because it employs a JSON body rather than query parameters.

POST

prices

{price_id}

evaluate

curl --request POST \
  --url https://api.withorb.com/v1/prices/{price_id}/evaluate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer_id": "<string>",
  "external_customer_id": "<string>",
  "timeframe_start": "2023-11-07T05:31:56Z",
  "timeframe_end": "2023-11-07T05:31:56Z",
  "filter": "my_numeric_property > 100 AND my_other_property = '\''bar'\''",
  "grouping_keys": [
    "case when my_event_type = '\''foo'\'' then true else false end"
  ]
}'

{
  "data": [
    {
      "grouping_values": [
        "<string>"
      ],
      "quantity": 123,
      "amount": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

API Keys can be issued in the Orb's web application.

Path Parameters

price_id

string

required

Body

application/json

timeframe_start

string

required

The inclusive lower bound for event timestamps

timeframe_end

string

required

The exclusive upper bound for event timestamps

customer_id

string | null

The ID of the customer to which this evaluation is scoped.

external_customer_id

string | null

The external customer ID of the customer to which this evaluation is scoped.

filter

string | null

A boolean computed property used to filter the underlying billable metric

grouping_keys

string[]

Properties (or computed properties) used to group the underlying billable metric

Response

200

application/json

data

object[]

required

Was this page helpful?

Update price List subscriptions

curl --request POST \
  --url https://api.withorb.com/v1/prices/{price_id}/evaluate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer_id": "<string>",
  "external_customer_id": "<string>",
  "timeframe_start": "2023-11-07T05:31:56Z",
  "timeframe_end": "2023-11-07T05:31:56Z",
  "filter": "my_numeric_property > 100 AND my_other_property = '\''bar'\''",
  "grouping_keys": [
    "case when my_event_type = '\''foo'\'' then true else false end"
  ]
}'

{
  "data": [
    {
      "grouping_values": [
        "<string>"
      ],
      "quantity": 123,
      "amount": "<string>"
    }
  ]
}

API Documentation

Alert

Coupon

Credit note

Customer

Credit

Dimensional Price Group

Event

Invoice

Item

Metric

Availability

Plan

Price

Subscription

Price interval

Evaluate price

Authorizations

Path Parameters

Body

Response