# Report Failed Usage

Find usage the marketplace rejected, understand why, and get it billed.

---

## What Report Failed means

Fours validates usage when it arrives, then sends it to the marketplace in an hourly report (see
[Reporting late usage](/metering/usage-metering/#reporting-late-usage)). **Report Failed** means Fours
accepted the usage, but the marketplace rejected the hourly report that carried it. The usage is not billed.

Most of these rejections come from the buyer's account on the marketplace, not from your integration: the
buyer's subscription, license, or billing is not in a state the marketplace can charge. Your request to
Fours succeeded, so the API response gives no sign of the failure.

A Report Failed record stays failed. Fours does not send it again until you [retry it](#retry-a-failed-report).

## Find failed reports

### In the console

1. Open **Usage Metering** in the left menu. It opens on **Received Usages**.
2. Set **Status** to **Report Failed**, and widen the date range in the same row if you need to (the
   last 7 days by default).
3. Hover a row's red **Report Failed** status. For the errors listed under
   [Common errors](#common-errors), the tooltip names the cause and the next step.

To fetch the same records from your backend, call
[List Usage Record Groups](/api/list-usage-record-groups/) with `status` set to `REPORT_FAILED`.

### With a webhook

Each time a marketplace rejects a report, Fours sends a `METER` event for the entitlement to your
[webhook](/settings/webhook/). Its `message` names the marketplace and the error:

```json
{
  "organizationID": "your-suger-org-id",
  "partner": "AWS",
  "action": "METER",
  "entityType": "ENTITLEMENT",
  "entityID": "your-suger-entitlement-id",
  "message": "AWS marketplace usage metering failed: CustomerNotSubscribed"
}
```

The payload above is trimmed; the event also carries the entitlement under `info`. It repeats on every hourly
report that fails, so expect more than one per entitlement until the cause
is fixed.

### With a daily email

Switch on the **Abnormal Alert Usage Record Group** scope (`ABNORMAL_ALERT.USAGE_RECORD_GROUP`) in
[Email Notification](/settings/email-notification/). Once a day, Fours emails the recipients you set a
count of the usage records, received between 7 days and 2 hours earlier, that are still Created, Report
Pending, or Report Failed on active entitlements, with the entitlements they belong to.

## Common errors

The error is the marketplace's own code. Each section below links to the marketplace's documentation for it.

### AWS: CustomerNotSubscribed

**What it means:** AWS will not accept usage for this customer on this product. AWS gives three causes:
the customer identifier is invalid, the customer has no active agreement or subscription for the product, or
the customer's AWS account is suspended. Further usage for the customer fails until it subscribes again.

**What to do:** Confirm the subscription with the buyer. If they unsubscribed, stop reporting usage for the
entitlement. If the agreement is still active in AWS Marketplace, open a case with AWS Marketplace Seller
Operations.

**Reference:** [AWS `UsageRecordResult` status](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_UsageRecordResult.html)

### AWS: InvalidLicenseException

**What it means:** AWS rejected the license behind the entitlement.

**What to do:** AWS returns this error unless three things hold: the license (`LicenseArn`) is valid, it
matches the customer the usage is reported for, and the usage falls within the license's activation period.
Check that the usage belongs to this buyer and that its timestamp is inside the period the buyer is entitled
for. The license itself is the buyer's — it appears under **Granted licenses** in their AWS License Manager —
so ask the buyer to confirm it is active. If it is not active while the agreement is, open a case with AWS
asking why.

**Reference:** [AWS `BatchMeterUsage` errors](https://docs.aws.amazon.com/marketplace/latest/APIReference/API_marketplace-metering_BatchMeterUsage.html#API_marketplace-metering_BatchMeterUsage_Errors)

### Azure: ResourceNotActive

**What it means:** The buyer's SaaS subscription is not in a billable state, for example still pending
activation, suspended, or unsubscribed. Fours records this error as **Resource not active**.

**What to do:** Check the subscription in Partner Center. Usage cannot be billed until the buyer completes or
resumes it. If it shows as active there, open an Azure support case to confirm whether the buyer is in a
billable state.

**Reference:** [Microsoft marketplace metering service APIs](https://learn.microsoft.com/en-us/partner-center/marketplace-offers/marketplace-metering-service-apis) ·
[SaaS subscription lifecycle](https://learn.microsoft.com/en-us/partner-center/marketplace-offers/pc-saas-fulfillment-life-cycle)

### GCP: BILLING_DISABLED

**What it means:** Billing is disabled on the buyer's Google Cloud account, so Google refuses usage for it.

**What to do:** Ask the buyer to re-enable billing on the account behind the entitlement. Usage reported
while billing is disabled cannot be billed.

**Reference:** [Google Service Control `services.check`](https://docs.cloud.google.com/service-infrastructure/docs/service-control/reference/rest/v1/services/check)

:::info
A Report Failed record with an error not listed here shows no tooltip. Contact support@suger.io with the
record ID and Fours will look up the marketplace's response.
:::

## Retry a failed report

Once the cause is fixed, send the usage again:

- **From the console:** click the green **Retry** arrow in the row's **Action** column.
- **From the API:** call [Retry Usage Record Group](/api/retry-usage-record-group/) with the record's ID.

Retrying sets the record back to **Created**, and the next hourly report includes it. If the marketplace
rejects it again, it returns to Report Failed.

:::warning
The hourly report only picks up records that reached Fours in the last 14 days, and a retry keeps the
record's original arrival time. Retry within that window; a record older than 14 days is not sent again.
:::

## Related

- [Usage Metering](/metering/usage-metering/) — reporting usage from the console or the API, and the
  validation Fours runs before a report.
- [Webhook](/settings/webhook/) — creating a webhook and verifying its signature.
- [Email Notification](/settings/email-notification/) — turning on scopes and choosing recipients.