Credit Grant methods: apply, issue, void
The Credit Grant Verbs apply, issue, void as typed SDK methods, with inputs, result, refusals and an example.
Reference for Credit Grant, one group of Credit Grant methods.
CreditGrant.apply
Apply spends Credit Grants against a finalizing Invoice, promotional first, then by priority and earliest expiry, and settles them through Stripe credit grants. Verb page.
interface CreditGrantVerbs {
apply(input: CreditGrantApplyInput, options?: SB.CallOptions): SB.Call<CreditGrantApplyOutput>
}Emits CreditGrant.applied.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
invoice | Invoice | required | The Invoice being finalized. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
applied | money | required | The total the grants paid toward the Invoice. |
creditGrants | list of Credit Grant | required | Each grant drawn, with its new remaining balance. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
Example
import { $ } from 'startup-builder'
const { applied, creditGrants } = await $.CreditGrant.apply({ invoice: 'inv_9sfvgeRT7L' })CreditGrant.issue
Issue gives a Customer a paid or promotional Credit Grant that its metered calls draw down before anything is invoiced. Verb page.
interface CreditGrantVerbs {
issue(input: CreditGrantIssueInput, options?: SB.CallOptions): SB.Call<CreditGrant>
}Emits CreditGrant.issued.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
customer | Customer | required | The Customer who receives it. |
amount | money | required | The balance granted. |
category | string | required | paid for a balance the Customer bought; promotional for one given, which is never cash. |
appliesTo | Offer | The metered Offer it pays for; every metered Offer of the Startup when absent. | |
expiresAt | datetime | When any remaining balance lapses; never, when absent. | |
priority | integer | Order of use among grants; a lower number spends first. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
creditGrant | Credit Grant | required | The new Credit Grant, its remaining balance equal to its amount. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
Example
import { $ } from 'startup-builder'
const creditGrant = await $.CreditGrant.issue({ customer: 'cus_K1BROJhqzZ', amount: { amount: 29, currency: 'USD' }, category: 'paid' })CreditGrant.void
Void ends a promotional Credit Grant early and forfeits its remaining balance, keeping the record. Verb page.
interface CreditGrantVerbs {
void(input: CreditGrantVoidInput, options?: SB.CallOptions): SB.Call<CreditGrant>
}Emits CreditGrant.voided.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
creditGrant | Credit Grant | required | The grant to end. |
reason | text | required | Why it ends, shown to the Customer. |
Returns
| Output | Type | Required | Description |
|---|---|---|---|
creditGrant | Credit Grant | required | The voided grant, its remaining balance zero. |
Refuses when
| Check | Error | Fix | Then call |
|---|---|---|---|
| The key is valid, but its scopes do not allow this operation. | forbidden | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |
Example
import { $ } from 'startup-builder'
const creditGrant = await $.CreditGrant.void({ creditGrant: 'credgr_PduV9IB1HF', reason: 'Example reason' })