Create ledger entry
This endpoint allows you to create a new ledger entry for a specified customer’s balance. This can be used to increment balance, deduct credits, and change the expiry date of existing credits.
Effects of adding a ledger entry
- After calling this endpoint, Fetch Credit Balance will return a credit block that represents the changes (i.e. balance changes or transfers).
- A ledger entry will be added to the credits ledger for this customer, and therefore returned in the View Credits Ledger response as well as serialized in the response to this request. In the case of deductions without a specified block, multiple ledger entries may be created if the deduction spans credit blocks.
- If
invoice_settingsis specified, an invoice will be created that reflects the cost of the credits (based onamountandper_unit_cost_basis).
Currency
currency sets which currency or custom pricing unit ledger the entry applies to. It is optional: if it is
omitted, Orb uses the customer’s default ledger pricing unit, which may not be the one you intend. We recommend
passing currency explicitly on every ledger entry.
For entries that act on an existing block (void, amendment, and expiration_change), currency must match
the block’s pricing unit. Otherwise the request fails with a currency mismatch error.
Adding credits
Adding credits is done by creating an entry of type increment. This requires the caller to specify a number of
credits as well as an optional expiry date in YYYY-MM-DD format. Orb also recommends specifying a description
to assist with auditing. When adding credits, the caller can also specify a cost basis per-credit, to indicate
how much in USD a customer paid for a single credit in a block. This can later be used for revenue recognition.
The following snippet illustrates a sample request body to increment credits which will expire in January of 2022.
Note that an increment entry always creates a new credit block (defined by the optional effective_date and
expiry_date); it never modifies an existing block.
Invoicing for credits
By default, Orb manipulates the credit ledger but does not charge for credits. However, if you pass
invoice_settings in the body of this request, Orb will also generate a one-off invoice for the customer for the
credits pre-purchase. Note that you must provide the per_unit_cost_basis, since the total charges on the
invoice are calculated by multiplying the cost basis with the number of credit units added. If you invoice or handle payment
of credits outside of Orb (i.e. marketplace customers), set mark_as_paid in the invoice_settings to true to prevent
duplicate invoicing effects.
- if
per_unit_cost_basisis greater than zero, an invoice will be generated andinvoice_settingsmust be included - if
invoice_settingsis passed, one of eithercustom_due_dateornet_termsis required to determine the due date
Deducting Credits
Orb allows you to deduct credits from a customer by creating an entry of type decrement. A decrement entry
records credits as usage and immediately recognizes revenue at the block’s per_unit_cost_basis.
For most credit removals, use void (no revenue impact) or expiration_change (revenue recognized on expiration)
instead. Only use decrement when credits were genuinely consumed outside of normal event ingestion.
Orb matches the algorithm for automatic deductions for determining which credit blocks to decrement from. In the case that the deduction leads to multiple ledger entries, the response from this endpoint will be the final deduction. Orb also optionally allows specifying a description to assist with auditing.
The following snippet illustrates a sample request body to decrement credits.
Changing credits expiry
If you’d like to change when existing credits expire, you should create a ledger entry of type expiration_change.
For this entry, the required parameter expiry_date identifies the originating block, and the required parameter
target_expiry_date identifies when the transferred credits should now expire. A new credit block will be created
with expiry date target_expiry_date, with the same cost basis data as the original credit block, if present.
Note that the balance of the block with the given expiry_date must be at least equal to the desired transfer
amount determined by the amount parameter.
The following snippet illustrates a sample request body to extend the expiration date of credits by one year:
Voiding credits
If you’d like to void a credit block, create a ledger entry of type void. For this entry, block_id is required
to identify the block, and amount indicates how many credits to void, up to the block’s initial balance. Pass
in a void_reason of refund if the void is due to a refund.
Pass currency set to the block’s currency or custom pricing unit. If it is omitted and the block is not in the
customer’s default ledger pricing unit, the request fails with a currency mismatch error.
The following snippet illustrates a sample request body to void 50 credits from a block that uses a
custom pricing unit named tokens:
Amendment
If you’d like to undo a decrement on a credit block, create a ledger entry of type amendment. For this entry, block_id
is required to identify the block that was originally decremented from, and amount indicates how many credits to return
to the customer, up to the block’s initial balance.
Body
- AddIncrementCreditLedgerEntryRequestParams
- AddDecrementCreditLedgerEntryRequestParams
- AddExpirationChangeCreditLedgerEntryRequestParams
- AddVoidCreditLedgerEntryRequestParams
- AddAmendmentCreditLedgerEntryRequestParams
Response
Created
- IncrementLedgerEntry
- DecrementLedgerEntry
- ExpirationChangeLedgerEntry
- CreditBlockExpiryLedgerEntry
- VoidLedgerEntry
- VoidInitiatedLedgerEntry
- AmendmentLedgerEntry
The Credit Ledger Entry resource models prepaid credits within Orb.