# 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

```bash
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

```bash
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](/external-ids).

For backlogs,
[`PUT /v1/invoices/imports/{externalId}`](/reference/invoices#import-invoices)
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

```bash
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.

<Callout type="caution" title="Do not hard-code this split">
Rates vary by vendor. Always quote.
</Callout>

- **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

```bash
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}`](/reference/businesses#retrieve-a-business). See [Vendor Onboarding](/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](/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](/webhooks)