> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quivly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Push product usage events to Quivly directly over HTTP

<Info>
  **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.
</Info>

***

## 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:

<CardGroup cols={2}>
  <Card title="Data Warehouse" icon="database" href="/integrations/warehouses/overview">
    Quivly queries your BigQuery or Snowflake on a schedule. Best when usage data already lives in a warehouse.
  </Card>

  <Card title="Push API" icon="code">
    Your backend posts events to Quivly. Best when you want to push directly, without a warehouse. **(this section)**
  </Card>
</CardGroup>

You can use either method, or both.

***

## How to set it up

<Steps>
  <Step title="Open the configuration">
    Go to **Settings → Objects → Product Usage → Configuration**. Create a configuration and choose **Push API** as the source.
  </Step>

  <Step title="Generate an API key">
    Generate an API key in the panel. There is **one key per organization**, and it authenticates every request.
  </Step>

  <Step title="Copy the endpoint and example request">
    The panel shows your endpoint and a ready-to-run `curl` example with your key filled in.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Publish">
    Once a test event has verified, click **Publish**. From then on, events you send are stored as product usage.
  </Step>
</Steps>

<Warning>
  **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.
</Warning>

***

## 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.

<Tip>
  You can review which customers have sent usage, and the IDs Quivly recognizes for each, on the **Customer Mapping** tab of the configuration.
</Tip>

### 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.

***

<Card title="API Reference" icon="code" href="/integrations/product-usage/api-reference">
  Endpoint, request format, idempotency, rate limits, and response details.
</Card>