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

Invoice routes: bill, collect, refund, void

The Invoice Verbs bill, collect, refund, void as api.sb routes, with inputs, result, refusals and an example.

Reference for Invoice, one group of Invoice routes.

Invoice.bill

Bill finalizes an Invoice and presents it to the Customer for payment. Verb page.

Text
POST /{namespace}/invoices/{invoice}/bill

Path: invoice. Emits Invoice.billed.

Inputs

InputTypeRequiredDescription
invoiceInvoicerequiredThe draft Invoice.

Returns

OutputTypeRequiredDescription
invoiceInvoicerequiredThe open Invoice.

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.
The record is not in a state that allows this Verb, so the call is refused.refusedRead the record, run the Verb that moves it to an allowed state, then retry.None.

Example

Terminal
curl -X POST https://api.sb/leaseline.app/invoices/inv_KjgRxmhMzZ/bill \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
JSON
{
  "api": "https://api.sb/leaseline.app",
  "invoice": {
    "$id": "https://api.sb/leaseline.app/invoices/inv_KjgRxmhMzZ",
    "$type": "Invoice",
    "total": {
      "amount": 99,
      "currency": "USD"
    },
    "due": "2026-11-01"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Invoice.bill",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}

Invoice.collect

Collect charges a Customer’s saved payment method for an open Invoice and retries on failure. Verb page.

Text
POST /{namespace}/invoices/{invoice}/collect

Path: invoice. Emits Invoice.collected.

Inputs

InputTypeRequiredDescription
invoiceInvoicerequiredThe open Invoice.

Returns

OutputTypeRequiredDescription
invoiceInvoicerequiredThe paid Invoice.

Refuses when

CheckErrorFixThen call
The operation is part of an Offer the caller has not accepted or paid for.payment-requiredAccept the Offer named in the response, then retry the call.Offer.accept
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.
The record is not in a state that allows this Verb, so the call is refused.refusedRead the record, run the Verb that moves it to an allowed state, then retry.None.

Example

Terminal
curl -X POST https://api.sb/leaseline.app/invoices/inv_FXANyzQojc/collect \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
JSON
{
  "api": "https://api.sb/leaseline.app",
  "invoice": {
    "$id": "https://api.sb/leaseline.app/invoices/inv_FXANyzQojc",
    "$type": "Invoice",
    "total": {
      "amount": 29,
      "currency": "USD"
    },
    "due": "2026-10-13"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Invoice.collect",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}

Invoice.refund

Refund returns all or part of a paid Invoice to the Customer’s original payment method and posts the reversing Entries. Verb page.

Text
POST /{namespace}/invoices/{invoice}/refund

Path: invoice. Body, as JSON: the other inputs. Emits Invoice.refunded.

Inputs

InputTypeRequiredDescription
invoiceInvoicerequiredThe paid Invoice.
amountmoneyThe amount. Defaults to the full payment; pro rata takes the unused part of the Period.
reasontextrequiredWhy the money goes back, kept on the Invoice.

Returns

OutputTypeRequiredDescription
invoiceInvoicerequiredThe Invoice, with its refunded 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.
A Dispute on the Invoice is openrefusedClear what the check names, then call it again.None.

Example

Terminal
curl -X POST https://api.sb/leaseline.app/invoices/inv_9sfvgeRT7L/refund \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Example reason"}'
JSON
{
  "api": "https://api.sb/leaseline.app",
  "invoice": {
    "$id": "https://api.sb/leaseline.app/invoices/inv_9sfvgeRT7L",
    "$type": "Invoice",
    "total": {
      "amount": 99,
      "currency": "USD"
    },
    "due": "2026-10-01"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Invoice.refund",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}

Invoice.void

Void cancels an unpaid Invoice, keeps it on record, and posts the reversing Entries. Verb page.

Text
POST /{namespace}/invoices/{invoice}/void

Path: invoice. Body, as JSON: the other inputs. Emits Invoice.voided.

Inputs

InputTypeRequiredDescription
invoiceInvoicerequiredThe unpaid Invoice.
reasontextrequiredWhy the amount is no longer due.

Returns

OutputTypeRequiredDescription
invoiceInvoicerequiredThe voided Invoice, kept forever.

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.
The record changed since it was read, so the write would overwrite a newer version.conflictRead the record again, then retry the write against its current state.None.
The record is not in a state that allows this Verb, so the call is refused.refusedRead the record, run the Verb that moves it to an allowed state, then retry.None.

Example

Terminal
curl -X POST https://api.sb/leaseline.app/invoices/inv_KjgRxmhMzZ/void \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Example reason"}'
JSON
{
  "api": "https://api.sb/leaseline.app",
  "invoice": {
    "$id": "https://api.sb/leaseline.app/invoices/inv_KjgRxmhMzZ",
    "$type": "Invoice",
    "total": {
      "amount": 99,
      "currency": "USD"
    },
    "due": "2026-11-01"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Invoice.void",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}

update

Previous

Meter

Next