Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stigg.io/llms.txt

Use this file to discover all available pages before exploring further.

When multiple credit grants are available for a customer, Stigg applies a consistent prioritization strategy to determine which credits should be consumed first. This ensures predictable behavior, simplifies debugging, and avoids edge cases as new grant types are introduced.

​
Prioritization of multiple credit grants

If more than one grant can apply to an invoice or usage event, Stigg selects grants in the following order:
  1. Priority
    Grants with a higher priority apply first.
    Lower numeric value = higher priority.
  2. Expiration date (expires_at)
    Grants that expire sooner are consumed before later-expiring or non-expiring grants.
  3. Category
    Among grants with the same expiration date, promotional credits are consumed before paid credits.
  4. Effective date (effective_at)
    Grants that became effective earlier apply first.
  5. Created date (created_at)
    If all other attributes match, older grants are consumed before newer ones.

​
Deductions that span multiple grants

If a single usage event requires more credits than are available in one grant:
  • Stigg deducts from the highest-ranked grant until its balance is zero,
  • Then continues with the next eligible grant according to the same prioritization order,
  • Creating a separate ledger entry for each consumed grant.

​
Example

A customer has these credit grants:
GrantPriorityExpiresCategoryBalance
A1Sep 1paid50
B1Sep 1promotional20
C2Aug 15promotional100
A usage event requires 60 credits. Stigg applies the prioritization rules:
  1. Priority → only A and B (priority 1).
  2. Expiration → both expire Sep 1.
  3. Category → promotional before paid → B then A.

​
Deduction result

  • 20 credits deducted from B
  • 40 credits deducted from A
  • Grant C is not used
Two ledger entries are created, one for each grant consumed.

​
When credits are depleted

When a usage event requires more credits than are available across all active grants, Stigg handles the deficit using an overdraft grant rather than rejecting the event. Example: A customer has one active grant with 10 credits remaining. A usage event costs 25 credits.
  1. The system deducts 10 credits from the existing grant (fully consumed).
  2. The remaining 15 credits are tracked in a new overdraft grant.
  3. The customer’s effective balance is now -15 credits.
The overdraft grant appears in the credit grants table and ledger, providing full visibility into the negative balance.

​
Automatic overdraft settlement

When new credits are granted to a customer who has an active overdraft, Stigg automatically settles the deficit:
  1. The new grant is created.
  2. The system checks for an active overdraft in the same currency.
  3. Credits are transferred from the overdraft to the new grant (up to the new grant’s available capacity).
  4. If fully settled, the overdraft grant is voided.
Example: A customer has an overdraft of 15 credits. They purchase a 50-credit grant.
  1. The 50-credit grant is created.
  2. 15 credits of consumption are transferred from the overdraft to the new grant.
  3. The overdraft is fully settled and voided.
  4. The new grant now shows: 50 total, 15 consumed, 35 remaining.