Skip to content
StartupBuilder
by startups.studio
by Startups.Studio
Code
Changelog
APIFinanceCredit Grant

Credit Grant routes: apply, issue, void

The Credit Grant Verbs apply, issue, void as api.sb routes, with inputs, result, refusals and an example.

Reference for Credit Grant, one group of Credit Grant routes.

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.

Text
POST /{namespace}/credit-grants/apply

Body, as JSON: the inputs. Emits CreditGrant.applied.

Inputs

InputTypeRequiredDescription
invoiceInvoicerequiredThe Invoice being finalized.

Returns

OutputTypeRequiredDescription
appliedmoneyrequiredThe total the grants paid toward the Invoice.
creditGrantslist of Credit GrantrequiredEach grant drawn, with its new remaining balance.

Refuses when

CheckErrorFixThen call
The key is valid, but its scopes do not allow this operation.forbiddenUse a key whose scopes cover the operation, or ask an owner of the namespace to grant them.None.

Example

Terminal
curl -X POST https://api.sb/leaseline.app/credit-grants/apply \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"invoice":"inv_9sfvgeRT7L"}'
JSON
{
  "api": "https://api.sb/leaseline.app",
  "applied": {
    "amount": 29,
    "currency": "USD"
  },
  "creditGrants": [
    {
      "$id": "https://api.sb/leaseline.app/credit-grants/credgr_PduV9IB1HF",
      "$type": "CreditGrant",
      "amount": {
        "amount": 29,
        "currency": "USD"
      },
      "category": "paid"
    }
  ],
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "CreditGrant.apply",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}

CreditGrant.issue

Issue gives a Customer a paid or promotional Credit Grant that its metered calls draw down before anything is invoiced. Verb page.

Text
POST /{namespace}/credit-grants/issue

Body, as JSON: the inputs. Emits CreditGrant.issued.

Inputs

InputTypeRequiredDescription
customerCustomerrequiredThe Customer who receives it.
amountmoneyrequiredThe balance granted.
categorystringrequiredpaid for a balance the Customer bought; promotional for one given, which is never cash.
appliesToOfferThe metered Offer it pays for; every metered Offer of the Startup when absent.
expiresAtdatetimeWhen any remaining balance lapses; never, when absent.
priorityintegerOrder of use among grants; a lower number spends first.

Returns

OutputTypeRequiredDescription
creditGrantCredit GrantrequiredThe new Credit Grant, its remaining balance equal to its amount.

Refuses when

CheckErrorFixThen call
The key is valid, but its scopes do not allow this operation.forbiddenUse a key whose scopes cover the operation, or ask an owner of the namespace to grant them.None.

Example

Terminal
curl -X POST https://api.sb/leaseline.app/credit-grants/issue \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer":"cus_K1BROJhqzZ","amount":{"amount":29,"currency":"USD"},"category":"paid"}'
JSON
{
  "api": "https://api.sb/leaseline.app",
  "creditGrant": {
    "$id": "https://api.sb/leaseline.app/credit-grants/credgr_PduV9IB1HF",
    "$type": "CreditGrant",
    "amount": {
      "amount": 29,
      "currency": "USD"
    },
    "category": "paid"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "CreditGrant.issue",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}

CreditGrant.void

Void ends a promotional Credit Grant early and forfeits its remaining balance, keeping the record. Verb page.

Text
POST /{namespace}/credit-grants/{creditGrant}/void

Path: creditGrant. Body, as JSON: the other inputs. Emits CreditGrant.voided.

Inputs

InputTypeRequiredDescription
creditGrantCredit GrantrequiredThe grant to end.
reasontextrequiredWhy it ends, shown to the Customer.

Returns

OutputTypeRequiredDescription
creditGrantCredit GrantrequiredThe voided grant, its remaining balance zero.

Refuses when

CheckErrorFixThen call
The key is valid, but its scopes do not allow this operation.forbiddenUse a key whose scopes cover the operation, or ask an owner of the namespace to grant them.None.

Example

Terminal
curl -X POST https://api.sb/leaseline.app/credit-grants/credgr_PduV9IB1HF/void \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Example reason"}'
JSON
{
  "api": "https://api.sb/leaseline.app",
  "creditGrant": {
    "$id": "https://api.sb/leaseline.app/credit-grants/credgr_PduV9IB1HF",
    "$type": "CreditGrant",
    "amount": {
      "amount": 29,
      "currency": "USD"
    },
    "category": "paid"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "CreditGrant.void",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}

create, get, list

Previous

Entitlement

Next