# Usage Credit Give usage credits to your clients in cloud marketplaces --- ## Overview ISV sellers can offer usage credits (in amount, default currency USD) to their clients (buyers) in the active Entitlements of all marketplaces. It provides flexibility for your sales or revenue operation team to customize deal & incentives. :::danger - The Suger Usage Credit is applicable `ONLY` for usage-based metering. If the Entitlement has no usage-based metrics defined, the Usage Credit has no effect at all. ::: :::warning - If your current metering service supports the credit, don't use it together with Suger Usage Credit, otherwise it may result in double credits. ::: ## Billing Priority Credit is just one of multiple available incentives. For example, In Azure Marketplace, each metering metric can have included quantity or even infinite included quantity. In GCP Marketplace, the metric may have free tiered quantity. In addition, some Entitlements are type of commit + usage-based combined, which has commit amount to consume. To eliminate confusion, they are ordered by their billing priorities in the table below. The `Suger Credit` is consumed first, then `Commit`, and the `Included Quantity` is the last. | Priority | Incentive | Description | | --------- | --------- | ----------- | | 1st | Suger Credit | Applied first to incoming usage records, in the order they are received by the Suger metering API, until the credit amount is used up. | | 2nd | Commit | Applicable if the `Entitlement` has commit amount (for AWS & GCP) or Flat_Rate (for Azure) | | 3rd | Included Quantity | | ### Worked example Assume a usage-based metric priced at $1/unit, on an entitlement with $30 Suger Credit, a $20 commit, and 10 units of Included Quantity. A usage record of 100 units ($100) is offset in priority order: 1. **Suger Credit (1st):** $30 of the $100 is covered by credit. Remaining: $70. 2. **Commit (2nd):** $20 of the remaining $70 is drawn from the commit amount. Remaining: $50. 3. **Included Quantity (3rd):** 10 units (= $10) are covered by included quantity. Remaining: $40. The buyer is billed the remaining **$40**. (Figures are illustrative.) ## Add Credit There are two approaches to add credit to the Entitlement: Suger Console or Suger API. :::warning - The Suger Usage Credit amount must be `positive`. ::: :::warning - You are only allowed to add the Usage Credit amount via the Suger Console or API. There is no way to revert or decrease the amount. If you would like to decrease the Usage Credit amount for any reason, please contact us at support@suger.io for support. ::: 1. **Suger Console** Go to the page of Entitlement where you want to add the credit, and scroll down to the section of `Entitlement Terms`. Click the button `Add credit`, select the target Entitlement Term (optional), input the credit amount in the dialog and submit. > Add credit button in the Entitlement Terms section > Add credit amount input dialog 2. **Suger API** Use the [addEntitlementCredit REST API](https://doc.suger.io/api/add-entitlement-credit/) to add the credit amount. The request payload would be like: ```json [Payload of addEntitlementCredit request] { "organizationID": "your-suger-organization-id", "entitlementID": "suger-entitlement-id", "entitlementTermID": "suger-entitlement-term-id", // Optional "creditAmountIncrement": 100.0, } ``` The success response would be: ```json [Payload of addEntitlementCredit response] { "organizationID": "your-suger-organization-id", "entitlementID": "suger-entitlement-id", "entitlementTermID": "suger-entitlement-term-id", "creditAmountIncrement": 100.0, "newCreditAmount": 150.0, // new total credit amount, assume there was $50.0 before addEntitlementCredit. } ``` ## Credit added by the Chargebee usage sync If Suger reports your Chargebee usage to the marketplaces, the sync can add credit to an entitlement term on its own. Marketplaces don't accept negative usage, so an amount Suger has already reported can't be pulled back — the sync credits it instead, in two cases: - **A discount lowers the invoice.** When a Chargebee billing window closes and the metered line on its invoice, net of Chargebee discounts, comes to less than Suger already reported for that window, Suger adds the difference as credit. - **The invoice is voided.** When a Chargebee invoice is voided after Suger reported its window, Suger credits the reported amount back to the entitlement that was billed. ```d2 direction: right invoiced: "Closed window's invoice\n(net of discounts)" voided: "Invoice voided" lower: "Lower than what Suger\nalready reported?" { shape: diamond } usage: "Any remaining usage\nis reported" credit: "Credit added to the\nentitlement term" spent: "Spent first on the\nbuyer's later usage" invoiced -> lower lower -> usage: "no" lower -> credit: "yes: the difference" voided -> credit: "the amount\nalready reported" credit -> spent ``` This is the same credit you add yourself: it shows in the entitlement term's **Credit** and **Used Credit** fields, it comes first in the [billing priority](#billing-priority), and it can't be decreased. So credit on an entitlement term that nobody on your team added can come from this sync. Don't also add credit by hand for the same Chargebee discount or voided invoice, or the buyer is credited twice. For how Suger settles each billing window, see [How Suger settles each billing window](/integrations/chargebee/#how-suger-settles-each-billing-window).