Invoices, bills, and payments

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

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.

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.

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:

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 for Accounts Receivable aging, Accounts Payable aging, payments received, payments made, and other complete-population summaries.