# Invoices, bills, and payments

Find and open receivables, payables, customer payments, and supplier payments.

Canonical HTML: https://developer.shelfcycle.com/guides/financial-records

Find stored receivables and payables by identity, counterparty, date, currency, or amount, then open one exact document or payment with its connected financial context.

## Resource families

| Resource | Finder | Detail | Scope |
| --- | --- | --- | --- |
| Invoices and customer credits | `GET /invoices` | `GET /invoices/{id}` | `invoices:read` |
| Bills and supplier credits | `GET /bills` | `GET /bills/{id}` | `bills:read` |
| Customer payments | `GET /customer-payments` | `GET /customer-payments/{id}` | `customer-payments:read` |
| Supplier payments | `GET /supplier-payments` | `GET /supplier-payments/{id}` | `supplier-payments:read` |

Each family also checks the acting person's current ShelfCycle access. Receivables follow the acting person's current customer and salesperson visibility.

## Find documents

Invoice and bill finders accept an exact `id` or `number`, a `counterpartyId`, `transactionCurrencyCode`, and organization-calendar `from` and `to` dates. Amount filters use integer cents:

- `amountCents` for one exact amount;
- `amountMinCents` and `amountMaxCents` for a range;
- `amountBasis=total` or `amountBasis=open` to choose which document amount is compared;
- `openOnly=true` for documents with a current open balance; and
- `kind` to choose invoices or customer credits, or bills or supplier credits.

```bash
curl "$SHELFCYCLE_API_BASE_URL/invoices?counterpartyId=customer-id&openOnly=true&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Collections workspace"
```

Document results include status, counterparty, transaction currency, total, paid, and open amounts, the open amount in the organization's base currency, document and due dates, and whether the amount was carried over when the organization began using ShelfCycle.

## Find payments

Customer- and supplier-payment finders accept the same identity, counterparty, currency, date, and amount filters. Add `groupId` to select one customer deposit or supplier payment batch.

```bash
curl "$SHELFCYCLE_API_BASE_URL/customer-payments?amountCents=1594703&from=2026-06-01&to=2026-06-30&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Deposit matching"
```

Payment results include the exact paid amount, counterparty, paid date, payment identity, deposit or batch context, and `matchedOn` so the caller can see whether the match came from the payment itself or its group. Applied documents, credits, discounts, write-offs, and amounts kept on account are included when the key has the matching family access.

## Open one exact result

After selecting an ID, call the matching detail endpoint. Document detail can include connected payments, while payment detail can include the documents it settled. Each connected family keeps its own scope and current user access.

For example, an `invoices:read` key can read an invoice without receiving connected customer-payment details. Add `customer-payments:read` when the workflow needs those payment relationships too.

Use the returned relationships when explaining what a payment settled. Do not infer an allocation by adding amounts that happen to match.

## Continue a finder

The default page size is 25 and `limit` accepts 1 through 100. When `meta.nextCursor` is present, make the next request with that cursor by itself:

```bash
curl "$SHELFCYCLE_API_BASE_URL/invoices?cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

The cursor keeps the original resource, key, organization, filters, and page size together. Restart from the original filters when the workflow needs a fresh current view.

## Choose a report for totals

Use the finder and detail routes for exact financial documents and their relationships. Use [Reports](/guides/reports) for Accounts Receivable aging, Accounts Payable aging, payments received, payments made, and other complete-population summaries.