# Usage Metering Upload

Report consumer usage to Snowflake Marketplace in bulk by uploading a CSV file.

---

## Overview

For metered (usage-based) listings, you report each consumer's usage to Snowflake so it can be billed. Suger lets you submit usage for many entitlements at once by uploading a CSV — no need to call the API per consumer.

:::info
Usage charges can only be reported for **Connected App** listings. Standard data-share listings do not support usage metering. See the [FAQ](#faq) for details.
:::

## Upload CSV

1. Open the **Usage Records** (metering) page.
2. Click **Batch Report** to open the **Batch Report Usage Records** dialog.
3. Click **Choose File** and select your usage CSV.
4. Suger parses the file and previews the result in two tables:
   - **Valid Usage Records** — records matched to an entitlement and dimension, with the calculated amount.
   - **Invalid Usage Records** — records that could not be matched, each annotated with an error message (e.g. `buyer is not found`, `usage dimension is not found`). You can download these to fix and re-upload.
5. (Optional) Turn on **Auto Fix** to automatically map a record to the entitlement's first available dimension when the supplied dimension does not match.
6. Review the valid records, then click **Batch Report** to submit them.

## CSV format

Each row is one usage record. The header row must include a column that identifies the consumer, plus `dimension` and `quantity`.

**Identify the consumer with one of:**

| Column | Description |
|--------|-------------|
| `sugerBuyerId` | Suger buyer ID |
| `sugerExternalBuyerId` | Your external buyer ID |
| `customerId` | Your customer ID stored on the buyer |
| `sugerEntitlementId` | Suger entitlement ID |
| `sugerExternalEntitlementId` | Your external entitlement ID |

**Required usage columns:**

| Column | Description |
|--------|-------------|
| `dimension` | The billable dimension / event key to charge against |
| `quantity` | The number of units consumed (thousands separators like `12,238` are accepted) |

Records that share the same entitlement (and the same `erpInvoiceID`, if supplied) are grouped together and the quantities for each dimension are summed before reporting. Rows with the same entitlement but different `erpInvoiceID` values are reported as separate groups.

:::info
The upload dialog also accepts `timestamp` and `erpInvoiceID` columns, but they do **not** affect Snowflake charges. Snowflake stamps each charge with Suger's report-generation time (grounded to the hour, for idempotent retries), so a supplied `timestamp` is ignored; `erpInvoiceID` is not sent to Snowflake.
:::

:::caution
A row is rejected if its consumer or entitlement cannot be found, the entitlement is not in an `ACTIVE`, `SUSPENDED`, or `PENDING_CANCEL` status, the `dimension` does not exist on the entitlement, or the `quantity` is missing or not a number.
:::

## FAQ

Frequently asked questions about selling and billing on Snowflake Marketplace with Suger.

### Can I report usage charges for standard data-share listings?

No. Usage charges can only be reported for **Connected App** listings. Standard data-share listings do not support usage metering.

### When will the invoice be generated?

Invoicing is handled on the **Snowflake side**. Suger reports usage charges to Snowflake as they are submitted (deduplicated per hour), and Snowflake generates the invoice at the end of the billing period, aggregating all charges reported during that period.

### How do I undo or modify a charge that was already sent?

Charges are **append-only** — once a charge is reported it cannot be edited or removed. If you need to correct a charge, contact **Snowflake Marketplace Ops**.