Add credits to a tenant (admin only)

Issue credits to a tenant and record the sale.

This is the currency boundary of the whole system: everything downstream of it is credits, which have no currency.

Validate, don't derive. The caller sends the credit count the customer was shown at checkout, and this endpoint confirms it against the active price list. It does not compute a second count of its own — that is how a customer ends up shown one number and granted another when a price publish lands mid-checkout, or when a cached pricing scalar goes stale.

Idempotent on provider_txn_id: a webhook retry returns the original grant rather than crediting the tenant twice. That is not a nicety — the Django webhook deletes its own idempotency row when a call to this endpoint times out, so a grant that committed but whose response was lost gets retried, and only this side can tell the difference.

post/v1/billing/credits

Request

  • Base URL: https://api.clichefactory.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.clichefactory.com/v1/billing/credits
  • Auth: none declared

Headers

X-API-KEYstring nullable

Request body

tenant_idstring required
creditsinteger nullable

Credits to issue. Derived from the amount when omitted.

currencystring

ISO-4217 code. EUR or USD.

gross_amount_minorinteger nullable

What the customer paid, incl. tax, in minor units.

tax_amount_minorinteger
net_amount_minorinteger nullable

Ex-tax, ex-provider-fee. Defaults to gross - tax.

providerstring

'paddle' | 'invoice' | 'admin' | 'migration'

provider_txn_idstring nullable

Payment-provider transaction id; the idempotency key. Required for provider='invoice', where it is the invoice number.

provider_net_minorinteger nullable

The provider's own reported earnings, if known.

provider_settle_ccystring nullable
credit_price_list_idinteger nullable
reasonstring
amount_usdnumber nullable

Response

Successful Response

tenant_idstring required
credits_addedinteger
currencystring
gross_amount_minorinteger
new_balance_creditsinteger
grant_idinteger nullable
creditedboolean
amount_usdnumber
new_balance_usdnumber

Changes

No recorded changes to this operation across all 1 revision of this API.