Invoices

Sync invoices individually or by CSV.

Retrieve an invoice

GET

https://api.lunchpayments.com

/v1/organizations/{payeeExternalId}/invoices/{externalId}

Returns an invoice and any advance against it. Invoice identifiers are unique per payee, so the path includes both.

advance is null until an advance is requested. Funding source and terms are not returned.

Retrieve an invoice › path Parameters

payeeExternalId

string · minLength: 1 · required

Your identifier for the business.

externalId

string · minLength: 1 · required

Your identifier for the invoice. Unique per payee.

Retrieve an invoice › Responses

The invoice.

externalId

string · required

status

string · enum · required

Status as last synced by you. Lunch does not change it. Collection status is reported separately in collected and collectionState. Values may be added. Existing values will not be removed or changed. Handle unknown values.

Enum values:

ISSUED

PARTIALLY_PAID

PAID

VOIDED

faceValue

integer · max: 2147483647 · required

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

collected

integer · required

Amount collected from the payor, in cents. Never exceeds faceValue.

collectionState

string · enum · required

Derived from collected and faceValue. Values may be added. Existing values will not be removed or changed. Handle unknown values.

Enum values:

UNCOLLECTED

PARTIALLY_COLLECTED

COLLECTED

issueDate

string · date-time · required

dueDate

string · date-time · required

advance

object | null · required

fundable

boolean · required

Whether an advance can be requested now. Uses the same checks as POST /v1/advances: the invoice is eligible, has no existing advance, the business has completed onboarding, and the advance is within its limit.

notFundableReason

string | null · required

Reason fundable is false. null when true. Does not include limit amounts.

Create or update an invoice

PUT

https://api.lunchpayments.com

/v1/invoices/{externalId}

Creates or updates an invoice under your identifier. Creates the payee and payor if they have not been synced. Invoice identifiers are unique per payee.

Once an advance is requested, only status can be updated. Changes to the amount or dates are ignored, and outcome returns statusOnly.

Create or update an invoice › path Parameters

externalId

string · minLength: 1 · required

Your identifier for the invoice. Unique per payee.

Create or update an invoice › Request Body

object · required

The business owed the money.

object · required

The party that owes the money.

status

string · enum · required

Advances can only be requested on ISSUED invoices.

Enum values:

ISSUED

PARTIALLY_PAID

PAID

VOIDED

faceValue

integer · max: 2147483647 · required

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

issueDate

string · date-time · required

dueDate

string · date-time · required

Create or update an invoice › Responses

The invoice.

externalId

string · required

outcome

string · enum · required

statusOnly: an advance exists, so only status was updated. Values may be added. Existing values will not be removed or changed. Handle unknown values.

Enum values:

created

updated

statusOnly

reason

string | null · required

PUT/v1/invoices/{externalId}

curl https://api.lunchpayments.com/v1/invoices/:externalId \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "payee": {
    "externalId": "vendor-88",
    "legalName": "legalName",
    "taxId": "12-3456789",
    "contact": {
      "email": "test@example.com",
      "phone": "phone",
      "address": "address",
      "city": "city",
      "state": "state",
      "postalCode": "postalCode"
    }
  },
  "payor": {
    "externalId": "vendor-88",
    "legalName": "legalName",
    "taxId": "12-3456789",
    "contact": {
      "email": "test@example.com",
      "phone": "phone",
      "address": "address",
      "city": "city",
      "state": "state",
      "postalCode": "postalCode"
    }
  },
  "status": "ISSUED",
  "faceValue": 100000,
  "issueDate": "2024-08-25T15:00:00Z",
  "dueDate": "2024-08-25T15:00:00Z"
}'

Example Request Body

{
  "payee": {
    "externalId": "vendor-88",
    "legalName": "legalName",
    "taxId": "12-3456789",
    "contact": {
      "email": "test@example.com",
      "phone": "phone",
      "address": "address",
      "city": "city",
      "state": "state",
      "postalCode": "postalCode"
    }
  },
  "payor": {
    "externalId": "vendor-88",
    "legalName": "legalName",
    "taxId": "12-3456789",
    "contact": {
      "email": "test@example.com",
      "phone": "phone",
      "address": "address",
      "city": "city",
      "state": "state",
      "postalCode": "postalCode"
    }
  },
  "status": "ISSUED",
  "faceValue": 100000,
  "issueDate": "2024-08-25T15:00:00Z",
  "dueDate": "2024-08-25T15:00:00Z"
}

json

Example Responses

{
  "externalId": "externalId",
  "outcome": "created",
  "reason": "reason"
}

json

application/json

Retrieve an import

GET

https://api.lunchpayments.com

/v1/invoices/imports/{externalId}

Returns the report for an import. Use it to check results after an interrupted upload.

Retrieve an import › path Parameters

externalId

string · minLength: 1 · required

Your identifier for the import.

Retrieve an import › Responses

The import and its rows.

externalId

string · required

rowCount

integer · required

finished

boolean · required

object · required

object[] · required

Import invoices

PUT

https://api.lunchpayments.com

/v1/invoices/imports/{externalId}

Imports up to 1000 invoices from a CSV. Each row is processed like PUT /invoices/{externalId}. Invalid rows are reported without failing the import.

Required columns: externalId, payeeLegalName, payorLegalName, status, faceValue, issueDate, dueDate. Matched by name, in any order.
Optional columns: payeeExternalId, payorExternalId, and the tax ID and contact fields from the single-invoice endpoint, prefixed with payee or payor.
Business identifiers: provide your own where possible. If blank, Lunch derives one from the legal name. Identical names resolve to the same business.
Retries: re-upload the same file with the same identifier to resume an interrupted import. Rows already processed are skipped.

Import invoices › path Parameters

externalId

string · minLength: 1 · required

Your identifier for the import.

Import invoices › Request Body

string

Import invoices › Responses

Import processed. Each row includes an outcome.

externalId

string · required

rowCount

integer · required

finished

boolean · required

object · required

object[] · required

PUT/v1/invoices/imports/{externalId}

curl https://api.lunchpayments.com/v1/invoices/imports/:externalId \
  --request PUT \
  --header 'Content-Type: text/csv' \
  --header 'Authorization: Bearer <token>' \
  --data 'string'

Example Request Body

string

csv

Example Responses

{
  "externalId": "externalId",
  "rowCount": 0,
  "finished": true,
  "summary": {
    "pending": 0,
    "created": 0,
    "updated": 0,
    "statusOnly": 0,
    "refused": 0,
    "malformed": 0
  },
  "rows": [
    {
      "row": 0,
      "externalId": "externalId",
      "payeeExternalId": "lunch-derived-4f2c8a1b9e7d3506",
      "payorExternalId": "payorExternalId",
      "outcome": "pending",
      "reason": "reason"
    }
  ]
}

json

application/json

Onboarding Advances