> ## Documentation Index > Fetch the complete documentation index at: https://docs.withorb.com/llms.txt > Use this file to discover all available pages before exploring further. # Evaluate price > [NOTE] It is recommended to use the `/v1/prices/evaluate` which offers further functionality, such as multiple prices, inline price definitions, and querying over preview events. 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](/extensibility/advanced-metrics#computed-properties), supporting the following workflows: 1. Showing detailed usage and costs to the end customer. 2. 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. ## OpenAPI ````yaml /api-reference/orb-openapi.json post /prices/{price_id}/evaluate openapi: 3.1.0 info: title: API Reference description: >- Orb's API is built with the following principles in mind: 1. **Predictable developer experience**: Where applicable, the Orb API uses industry-standard patterns such as cursor-based pagination and standardized error output. To help with debugging in critical API actions, the API always strives to provide detailed and actionable error messages. Aliases such as external customer IDs aid in fast integration times. 2. **Reliably real time**: Orb's event-based APIs, such as event ingestion are designed to handle extremely high throughput and scale with concurrent load. Orb also provides a real-time event-level credits ledger and a highly performant webhooks architecture. 3. **Flexibility at the forefront**: Features like timezone localization and the ability to amend historical usage show the flexible nature of the platform. You can download the latest OpenAPI spec [here](https://api.withorb.com/spec.json) - pass `?version=3.0` for an OpenAPI 3.0-compatible spec. contact: name: Orb, Inc. url: https://www.withorb.com/ email: team@withorb.com version: '1.0' servers: - url: https://api.withorb.com/v1 description: Production server security: - APIKeyAuth: [] tags: - name: Alert description: >- [Alerts within Orb](/product-catalog/configuring-alerts) monitor spending, usage, or credit balance and trigger webhooks when a threshold is exceeded. Alerts created through the API can be scoped to either customers or subscriptions. - name: Availability - name: Coupon description: >- A coupon represents a reusable discount configuration that can be applied either as a fixed or percentage amount to an invoice or subscription. Coupons are activated using a redemption code, which applies the discount to a subscription or invoice. The duration of a coupon determines how long it remains available for use by end users. - name: Credit description: >- The [Credit Ledger Entry resource](/product-catalog/prepurchase) models prepaid credits within Orb. - name: Credit note description: >- The [Credit Note](/invoicing/credit-notes) resource represents a credit that has been applied to a particular invoice. - name: Customer description: >- A customer is a buyer of your products, and the other party to the billing relationship. In Orb, customers are assigned system generated identifiers automatically, but it's often desirable to have these match existing identifiers in your system. To avoid having to denormalize Orb ID information, you can pass in an `external_customer_id` with your own identifier. See [Customer ID Aliases](/events-and-metrics/customer-aliases) for further information about how these aliases work in Orb. In addition to having an identifier in your system, a customer may exist in a payment provider solution like Stripe. Use the `payment_provider_id` and the `payment_provider` enum field to express this mapping. A customer also has a timezone (from the standard [IANA timezone database](https://www.iana.org/time-zones)), which defaults to your account's timezone. See [Timezone localization](/essentials/timezones) for information on what this timezone parameter influences within Orb. - name: Dimensional Price Group - name: Event description: >- The [Event](/core-concepts#event) resource represents a usage event that has been created for a customer. Events are the core of Orb's usage-based billing model, and are used to calculate the usage charges for a given billing period. - name: Invoice description: >- An [`Invoice`](/core-concepts#invoice) is a fundamental billing entity, representing the request for payment for a single subscription. This includes a set of line items, which correspond to prices in the subscription's plan and can represent fixed recurring fees or usage-based fees. They are generated at the end of a billing period, or as the result of an action, such as a cancellation. - name: Item description: >- The Item resource represents a sellable product or good. Items are associated with all line items, billable metrics, and prices and are used for defining external sync behavior for invoices and tax calculation purposes. - name: License - name: LicenseType description: >- The LicenseType resource represents a type of license that can be assigned to users. License types are used during billing by grouping metrics on the configured grouping key. - name: Metric description: >- The Metric resource represents a calculation of a quantity based on events. Metrics are defined by the query that transforms raw usage events into meaningful values for your customers. - name: Plan description: >- The [Plan](/core-concepts#plan-and-price) resource represents a plan that can be subscribed to by a customer. Plans define the billing behavior of the subscription. You can see more about how to configure prices in the [Price resource](/reference/price). - name: Price description: >- The Price resource represents a price that can be billed on a subscription, resulting in a charge on an invoice in the form of an invoice line item. Prices take a quantity and determine an amount to bill. Orb supports a few different pricing models out of the box. Each of these models is serialized differently in a given Price object. The model_type field determines the key for the configuration object that is present. For more on the types of prices, see [the core concepts documentation](/core-concepts#plan-and-price) - name: Price interval description: >- The Price Interval resource represents a period of time for which a price will bill on a subscription. A subscription’s price intervals define its billing behavior. - name: Subscription description: >- A [subscription](/core-concepts#subscription) represents the purchase of a plan by a customer. By default, subscriptions begin on the day that they're created and renew automatically for each billing cycle at the cadence that's configured in the plan definition. Subscriptions also default to **beginning of month alignment**, which means the first invoice issued for the subscription will have pro-rated charges between the `start_date` and the first of the following month. Subsequent billing periods will always start and end on a month boundary (e.g. subsequent month starts for monthly billing). Depending on the plan configuration, any _flat_ recurring fees will be billed either at the beginning (in-advance) or end (in-arrears) of each billing cycle. Plans default to **in-advance billing**. Usage-based fees are billed in arrears as usage is accumulated. In the normal course of events, you can expect an invoice to contain usage-based charges for the previous period, and a recurring fee for the following period. - name: Subscription Change paths: /prices/{price_id}/evaluate: post: tags: - Price summary: Evaluate price description: >- [NOTE] It is recommended to use the `/v1/prices/evaluate` which offers further functionality, such as multiple prices, inline price definitions, and querying over preview events. 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](/extensibility/advanced-metrics#computed-properties), supporting the following workflows: 1. Showing detailed usage and costs to the end customer. 2. 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. operationId: evaluate-price parameters: - required: true style: simple schema: type: string name: price_id in: path requestBody: content: application/json: schema: $ref: '#/components/schemas/EvaluatePriceBody' required: true responses: '200': description: OK headers: {} content: application/json: schema: $ref: '#/components/schemas/EvaluatePriceResource' '400': description: Bad Request headers: {} content: application/json: schema: $ref: '#/components/schemas/400Error' '401': description: Unauthorized headers: {} content: application/json: schema: $ref: '#/components/schemas/401Error' '404': description: Not Found headers: {} content: application/json: schema: $ref: '#/components/schemas/404Error' '409': description: Conflict headers: {} content: application/json: schema: $ref: '#/components/schemas/409Error' '413': description: Content Too Large headers: {} content: application/json: schema: $ref: '#/components/schemas/413Error' '429': description: Too Many Requests headers: {} content: application/json: schema: $ref: '#/components/schemas/429Error' '500': description: Internal Server Error headers: {} content: application/json: schema: $ref: '#/components/schemas/500Error' components: schemas: EvaluatePriceBody: properties: customer_id: oneOf: - type: string - type: 'null' title: Customer Id description: The ID of the customer to which this evaluation is scoped. external_customer_id: oneOf: - type: string - type: 'null' title: External Customer Id description: >- The external customer ID of the customer to which this evaluation is scoped. timeframe_start: type: string format: date-time title: Timeframe Start description: The inclusive lower bound for event timestamps timeframe_end: type: string format: date-time title: Timeframe End description: The exclusive upper bound for event timestamps filter: oneOf: - type: string - type: 'null' title: Filter description: >- A boolean [computed property](/extensibility/advanced-metrics#computed-properties) used to filter the underlying billable metric examples: - my_numeric_property > 100 AND my_other_property = 'bar' - my_property = 'foo' grouping_keys: items: type: string type: array title: Grouping Keys description: >- Properties (or [computed properties](/extensibility/advanced-metrics#computed-properties)) used to group the underlying billable metric default: [] examples: - - case when my_event_type = 'foo' then true else false end - - hour_floor_timestamp_millis(timestamp_millis) - my_property metric_parameter_overrides: oneOf: - additionalProperties: true type: object - type: 'null' title: Metric Parameter Overrides description: >- Optional overrides for parameterized billable metric parameters. If the metric has parameter definitions and no overrides are provided, defaults will be used. additionalProperties: false type: object required: - timeframe_start - timeframe_end title: EvaluatePriceBody EvaluatePriceResource: properties: data: items: $ref: '#/components/schemas/EvaluatePriceGroup' type: array title: Data type: object required: - data title: EvaluatePriceResource 400Error: oneOf: - $ref: '#/components/schemas/ConstraintViolationError' - $ref: '#/components/schemas/DuplicateResourceCreationError' - $ref: '#/components/schemas/RequestValidationError' 401Error: $ref: '#/components/schemas/AuthorizationError' title: 401Error 404Error: oneOf: - $ref: '#/components/schemas/FeatureNotAvailableError' - $ref: '#/components/schemas/ResourceNotFoundError' - $ref: '#/components/schemas/URLNotFound' 409Error: $ref: '#/components/schemas/IdempotencyRequestMismatch' title: 409Error 413Error: oneOf: - $ref: '#/components/schemas/RequestTooLargeError' - $ref: '#/components/schemas/ResourceTooLargeError' - $ref: '#/components/schemas/TooManyResultsError' 429Error: $ref: '#/components/schemas/TooManyRequests' title: 429Error 500Error: $ref: '#/components/schemas/ServerError' title: 500Error EvaluatePriceGroup: properties: grouping_values: items: oneOf: - type: string - type: number - type: boolean type: array title: Grouping Values description: The values for the group in the order specified by `grouping_keys` quantity: type: number title: Quantity description: The price's usage quantity for the group amount: type: string title: Amount description: The price's output for the group type: object required: - grouping_values - quantity - amount title: EvaluatePriceGroup ConstraintViolationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-constraint-violation title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ConstraintViolationError DuplicateResourceCreationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-duplicate-resource-creation title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: DuplicateResourceCreationError RequestValidationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#400-request-validation-errors title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title validation_errors: items: {} type: array title: Validation Errors type: object required: - type - status - validation_errors title: RequestValidationError AuthorizationError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#401-authentication-error title: Type status: type: integer enum: - 401 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: AuthorizationError FeatureNotAvailableError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-feature-not-available title: Type status: type: integer enum: - 400 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: FeatureNotAvailableError ResourceNotFoundError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-resource-not-found title: Type status: type: integer enum: - 404 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: type: string title: Title type: object required: - type - status - title title: ResourceNotFoundError URLNotFound: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#404-url-not-found title: Type status: type: integer enum: - 404 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: URLNotFound IdempotencyRequestMismatch: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#409-resource-conflict title: Type status: type: integer enum: - 409 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: IdempotencyRequestMismatch RequestTooLargeError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-request-too-large title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: RequestTooLargeError ResourceTooLargeError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-resource-too-large title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ResourceTooLargeError TooManyResultsError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#413-too-many-results title: Type status: type: integer enum: - 413 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: TooManyResultsError TooManyRequests: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#429-too-many-requests title: Type status: type: integer enum: - 429 title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: TooManyRequests ServerError: properties: type: type: string enum: - >- https://docs.withorb.com/reference/error-responses#500-internal-server-error title: Type status: type: integer title: Status detail: oneOf: - type: string - type: 'null' title: Detail title: oneOf: - type: string - type: 'null' title: Title type: object required: - type - status title: ServerError securitySchemes: APIKeyAuth: type: http description: API Keys can be issued in the Orb's web application. scheme: bearer ````