Lunch
Lunch Partner API
Lunch Partner API

Advances

Quote and request advances.

Request an advance

POST
https://api.lunchpayments.com
/v1/advances

Creates an advance against a synced invoice after checking eligibility and the business’s concentration limit (the maximum outstanding with one business). Idempotent per invoice: repeat requests return the existing advance.

The response includes remittance, the business’s collection account. Share it with the payor as the payment destination for this invoice.

Request an advance › Request Body

payeeExternalId
​string · minLength: 1 · required

Your identifier for the business.

invoiceExternalId
​string · required

Your identifier for the invoice.

Request an advance › Responses

The advance.

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: alreadyRequested, financeableAmount, advanceAmount +3 more
type = object · requires: alreadyRequested, financeableAmount, advanceAmount +1 more
Properties for Variant 1:
alreadyRequested
​boolean · enum · required
Enum values:
financeableAmount
​integer · required

Portion of the face value eligible for an advance, in cents. Equals faceValue unless capped by Lunch's per-invoice maximum. The excess is paid to the business through forwardedAtPayment.

advanceAmount
​integer · required

Amount paid to the business when the advance is issued, in cents. Fees are not deducted.

feeTotal
​integer · required

Total fee, in cents. Deducted from the payor's payment. On a quote it is an estimate: the advance is repriced when requested.

forwardedAtPayment
​integer · required

Amount paid to the business after the advance and fee are recovered, in cents, assuming the payor pays in full. Minimum 0. Paid as collections arrive, so part may be paid before the invoice is settled.

​Remittance · required

The business's collection account. Payors pay into this account. The same for every advance.

Quote an advance

POST
https://api.lunchpayments.com
/v1/quotes

Prices an advance for a face value without creating one. The business must be synced. Unknown identifiers return 404 business_not_found.

fundable evaluates the business and amount only. POST /v1/advances also validates the invoice and can still return 404 or 409.

Quote an advance › Request Body

externalId
​string · minLength: 1 · required

Your identifier for the business.

invoiceFaceValue
​integer · max: 2147483647 · required

Face value in cents. Positive. Maximum 2147483647 ($21,474,836.47).

Quote an advance › Responses

The quote.

financeableAmount
​integer · required

Portion of the face value eligible for an advance, in cents. Equals faceValue unless capped by Lunch's per-invoice maximum. The excess is paid to the business through forwardedAtPayment.

advanceAmount
​integer · required

Amount paid to the business when the advance is issued, in cents. Fees are not deducted.

feeTotal
​integer · required

Total fee, in cents. Deducted from the payor's payment. On a quote it is an estimate: the advance is repriced when requested.

forwardedAtPayment
​integer · required

Amount paid to the business after the advance and fee are recovered, in cents, assuming the payor pays in full. Minimum 0. Paid as collections arrive, so part may be paid before the invoice is settled.

fundable
​boolean · required

Whether the business can receive an advance of this amount today: the amount is eligible, onboarding is complete, and the advance is within its limit. Does not evaluate a specific invoice.

notFundableReason
​string | null · required

Reason fundable is false. Names the requirement or condition. null when true. Does not include limit amounts.

​object · required
InvoicesWebhooks