Skip to main content
Who is this guide for? Engineers who want to send product usage data to Quivly straight from their backend, instead of (or alongside) a data warehouse connection.

​
What is the Push API?

The Push API lets your application send product usage events to Quivly over HTTP. Instead of Quivly querying your warehouse on a schedule, your backend pushes events — one at a time or in batches. There are two ways to get product usage into Quivly:

Data Warehouse

Quivly queries your BigQuery or Snowflake on a schedule. Best when usage data already lives in a warehouse.

Push API

Your backend posts events to Quivly. Best when you want to push directly, without a warehouse. (this section)
You can use either method, or both.

​
How to set it up

1

Open the configuration

Go to Settings → Objects → Product Usage → Configuration. Create a configuration and choose Push API as the source.
2

Generate an API key

Generate an API key in the panel. There is one key per organization, and it authenticates every request.
3

Copy the endpoint and example request

The panel shows your endpoint and a ready-to-run curl example with your key filled in.
4

Send a test event to verify

Send your first call to the endpoint. Include all the customer IDs you plan to send, so the whole mapping is checked at once. Quivly verifies the event the moment it arrives — nothing is stored yet.
5

Publish

Once a test event has verified, click Publish. From then on, events you send are stored as product usage.
Nothing is stored until you publish. Before you publish, every call is verify-only: Quivly resolves the events against your customers and tells you what matched, but writes nothing.

​
Key things to know

​
Customer IDs must already be recognized

external_customer_id must be an ID Quivly already knows for that customer — typically the ID from a connected CRM or source (for example, a Salesforce or HubSpot ID). IDs Quivly doesn’t recognize are dropped and returned in the response’s errors. There is no separate mapping step for the API: send IDs your customers are already known by.
You can review which customers have sent usage, and the IDs Quivly recognizes for each, on the Customer Mapping tab of the configuration.

​
Metrics are discovered automatically

You don’t pre-declare metrics. Any metric_key you send is accepted. New metric keys appear in the configuration’s metric list and roll up as Sum across periods by default — you can change a metric’s rollup there.

​
Re-sending replaces, it doesn’t add

A value is stored per customer + metric + period + granularity. Sending the same combination again replaces the previous value — it is not added on top. Pre-aggregate to one value per customer / metric / period before sending.

API Reference

Endpoint, request format, idempotency, rate limits, and response details.