# Usage Credit

Add a USD-denominated allowance to an entitlement's usage-based metering.

---

## Overview

Usage credit lets you add a USD-denominated allowance to an entitlement's usage-based metering — useful for goodwill credit, promotional allowances, or SLA make-goods. It only takes effect if the entitlement has a usage-based metric defined.

Before you add credit, check two things:

- **No usage-based metering, no effect.** If the entitlement is a flat commit with no usage component, adding credit does nothing.
- **Don't stack with your metering service's own credits.** If your metering service (Orb, Metronome, etc.) already issues credits, adding Suger Credit on top can double-credit the buyer.

:::warning
Credit amounts can't be decreased or reverted — via Console or API — once added. If you add the wrong amount, contact Suger support to correct it.
:::

## How billing priority works

When a usage record comes in, Suger offsets it in this order:

| Order | Offset type | Notes |
| --- | --- | --- |
| 1 | Suger Credit | Consumed first |
| 2 | Commit | AWS/GCP commit amount, or Azure Flat Rate |
| 3 | Included Quantity | Not applicable for AWS; Azure Included/Infinite Included; GCP tiered free quantity |

## Add credit in the Suger Console

1. Go to the specific **Entitlement** record.
2. Scroll down past the top summary fields (**Auto Renew**, **Product**, **Start/End Date**, **Term Length**) to the **Entitlement term** section.
   - This is easy to miss — the action lives below the fold, not in the top summary.
3. Next to **Entitlement term**, click **Add Credit**.
4. In the **Add Credit to Entitlement** panel, optionally select an **Entitlement Term** from the dropdown.
   - If left blank, credit applies to the default entitlement term.
5. Enter the **Credit Amount** in USD.
6. Submit.

Once submitted, the credit shows up in two places:

- **Credit** and **Used Credit** fields in the entitlement's Detail panel.
- Per-term breakdown in the Entitlement term table.

![Add Credit to Entitlement panel](images/add-usage-credit-to-an-entitlement-1.jpeg)

## Add credit via API

Use the `addEntitlementCredit` REST API.

Request payload:

- `organizationID`
- `entitlementID`
- `entitlementTermID` (optional)
- `creditAmountIncrement`

The response confirms the new total credit amount on the entitlement. Credit amounts must be positive — the API has no decrease or revert path either.

## Troubleshooting

| Issue | Possible cause | Resolution |
| --- | --- | --- |
| Added credit isn't reducing the buyer's bill | Entitlement has no usage-based metric | Usage credit only applies to usage-based metering — verify the entitlement type before adding credit |
| Buyer appears to be credited twice | Metering service (Orb, Metronome, etc.) also has its own credit for this usage | Use only one credit source at a time — don't stack Suger Credit with a metering-service credit |
| Added the wrong credit amount | Credit amounts can't be decreased or reverted after submission | Contact Suger support to correct the entitlement |

## Frequently asked questions

**Does credit work if my entitlement has no usage-based metric?**
No — it has no effect at all.

**What gets consumed first, my credit or the buyer's included quantity?**
Credit first, then commit, then included quantity.

**Can I reduce a credit amount I added by mistake?**
No. Contact Suger support — there's no self-service way to decrease or revert credit.

**Will this double-credit my buyer if my metering service already gives credits?**
Possibly. Don't run both at the same time.