Copy page

Guides

Requesting an Advance

The full sequence from syncing a vendor to requesting an advance. The vendor is the payee. The city is the payor. Amounts are in cents.

1. Sync the Vendor

Code
curl -X PUT https://api.lunchpayments.com/v1/organizations/vendor-88 \
  -H "Authorization: Bearer lux_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Ridgeline Electrical LLC",
    "taxId": "12-3456789",
    "contact": { "email": "ap@ridgeline.example", "city": "Boise", "state": "ID" }
  }'

Field	Detail
legalName	Required.
taxId	Include when available. Required for compliance and used to match vendors across platforms. Omit if uncertain.
contact	Omitted fields keep their existing values.

2. Sync the Invoice

Code
curl -X PUT https://api.lunchpayments.com/v1/invoices/INV-001 \
  -H "Authorization: Bearer lux_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "payee": { "externalId": "vendor-88", "legalName": "Ridgeline Electrical LLC" },
    "payor": { "externalId": "city-of-boise", "legalName": "City of Boise" },
    "status": "ISSUED",
    "faceValue": 100000,
    "issueDate": "2026-09-01T00:00:00Z",
    "dueDate": "2026-11-30T00:00:00Z"
  }'

Creates or updates the payee and payor with the invoice, so step 1 is optional. Use step 1 to add a tax ID or contact details later.

Field	Detail
status	ISSUED, PARTIALLY_PAID, PAID or VOIDED. Advances require ISSUED.
faceValue	Full invoice amount in cents. 100000 is $1,000.00.
issueDate, dueDate	ISO date-times.

Invoice identifiers are unique per payee. See External IDs.

For backlogs, PUT /v1/invoices/imports/{externalId} accepts a CSV of up to 1000 rows, each processed like the call above. A rejected file writes nothing, so correct it and upload it again.

3. Quote the Advance

Code
curl -X POST https://api.lunchpayments.com/v1/quotes \
  -H "Authorization: Bearer lux_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "externalId": "vendor-88", "invoiceFaceValue": 100000 }'

Returns the terms of an advance on a face value for a vendor.

Field	Description
advanceAmount	Paid to the vendor in full when the advance is issued.
feeTotal	Cost of the advance. Deducted from the payor's payment.
forwardedAtPayment	Remainder after the advance and fees. Paid to the vendor as the city pays. Minimum 0.
fundable	Whether the vendor can receive an advance of this amount today.

For example, a $1,000.00 invoice could return $800.00 up front, $50.00 in fees, and $150.00 when the city pays.

• Floor: if the advance and fees exceed the face value, forwardedAtPayment is 0 and the three amounts do not sum to the face value.
• Estimates: quotes are non-binding and create nothing. Advances are repriced when requested. Quote again when the amount matters.
• No invoice required: quotes take an amount and a synced vendor. Unsynced vendors return 404 business_not_found.

4. Request the Advance

Code
curl -X POST https://api.lunchpayments.com/v1/advances \
  -H "Authorization: Bearer lux_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "payeeExternalId": "vendor-88", "invoiceExternalId": "INV-001" }'

Requires both identifiers because invoice identifiers are unique per payee. Reprices the advance, checks eligibility and the vendor's limit, then creates it. Idempotent per invoice.

The response includes remittance, the account the city should pay this invoice into. It is the vendor's collection account: the same for every advance, and it does not change. Share it with the payor through your normal invoicing.

Refusals return 409:

Code	Cause
invoice_not_financeable	Status is not ISSUED, face value is zero or negative, or the payee and payor are the same organization.
business_not_eligible	Onboarding is incomplete. Check GET /v1/organizations/{externalId}. See Vendor Onboarding.
concentration_exceeded	The vendor's outstanding advances would exceed its limit.

• Large invoices: not refused. The advance is calculated on a capped amount, returned as financeableAmount.
• Concentration limit: applies to the vendor's total outstanding advances across all payors.

5. Receive Payment Events

Funding, payment and settlement happen after your request returns. Subscribe to webhooks instead of polling.

Event	Description
partner.loan.issued	The vendor has been paid the advance.
partner.invoice.paid	The city has paid the invoice.

What's Next

• Webhooks