Finders

Use narrowed root endpoints to find typed resources before fetching exact detail, order context, or attached documents.

Choose the lookup for the job

Use the narrowest directory or lookup that matches the information already available:

Company and product finders require a supported narrowing filter. Supported finders can narrow by who entered a record or when it was entered. Order finders also accept exact identifiers, status, related records, product criteria, business-date windows, or last-updated windows. Opportunity finders support focused filtering or authorized browsing with signed continuation.

Use Entity Resolution for new single-record binding. Use Tags or Product Directory when the source information is an exact tag or product identifier. Use the reference directory when a local tool needs active customer/supplier hints for matching, and use a typed finder when the resource family and narrowing filters are already known. Existing connections can continue using search for broad discovery. Use detail and parent-scoped document endpoints only after selecting a visible record. Use reports for allowed aggregate rollups, not as substitutes for finders or detail reads.

Company and product finders

Product creation filters are available through GET /product-directory, where they can be combined with the directory's product and product-family identity filters. Orders, purchase orders, opportunities, lots, Cost Book entries, Price Book entries, and certification records support the same createdById, createdFrom, and createdTo pattern. See Created records for the complete route list and examples.

Optional limit caps response size. includeArchived is explicit; archived records are never write targets.

Supplier carriers

GET /suppliers?carrier=true finds suppliers with carrier profiles; carrier=false finds suppliers without them. Either value is a sufficient narrowing filter by itself, and omitting carrier leaves carrier status unrestricted. Results include carrierProfile so a workflow can review transportation details alongside supplier identity.

Continue with the returned meta.nextCursor alone. See Supplier carriers for exact profile reads and maintenance.

Customer ownership, setup, and shipped sales

The customer finder can narrow the current customer population with:

• salesPersonId for any active-location assignment.
• salesOwnership=all, mine, or unassigned. Unassigned means no owner on any active location.
• setupIssues=missing_account_owner, missing_payment_terms, no_primary, or ambiguous_primary. Multiple values use any-of matching.
• salesActivity=any or none together with both salesFrom and salesTo as inclusive organization-calendar dates.

Shipped-sales filtering also requires the acting person's current Sales Performance viewing access. Customer discovery without an activity filter remains available under its normal customer access.

curl "$SHELFCYCLE_API_BASE_URL/customers?salesOwnership=mine&setupIssues=missing_payment_terms&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

curl "$SHELFCYCLE_API_BASE_URL/customers?salesActivity=none&salesFrom=2026-01-01&salesTo=2026-09-08&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

Results include owners from every active location, primary account owner, payment terms, customer-service representative, commercialTermsState, location coverage, and the applied shipped-sales basis. Qualifying shipped sales use the dates and activity definition returned with the response.

If meta.hasMore is true, continue with meta.nextCursor alone. Customer pages are current-state reads, so deduplicate by customer ID and use the returned updatedAt values when reconciling later changes.

Company reference directories

Customer and supplier reference rows are active matching hints sorted by id_asc. They can include display names, source IDs, alternate names, website hosts, email domains, one phone, city, state, country, status, updatedAt, and URL.

Representative, payment-term, and ledger-account directories are sorted by name and ID. Representative identity always includes kind; payment terms return their exact financial definition; ledger accounts return account type and selection metadata without balances.

Directories accept their documented filters, limit, and cursor. Customer and supplier references require includeArchived=false; representative lookup can explicitly include archived records when needed.

curl "$SHELFCYCLE_API_BASE_URL/products?code=ACETONE-PAIL&limit=5" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

Product payloads use supported catalog fields. Product.name is deprecated and is not exposed by the public API.

Opportunity finder

Use the opportunity finder for customer- and supplier-side pipeline work. It returns visible opportunity summaries with relationship, owner, product, status, estimate, and update context.

curl "$SHELFCYCLE_API_BASE_URL/opportunities?status=LEAD,IN_PROGRESS&assignedToId=user-id&sortDirection=desc&limit=50" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Opportunity follow-up"

Narrow with matching text in query, one or more status or assignedToId values, an exact customerId, supplierId, productId, or createdById, or an ISO timestamp range using createdFrom and createdTo. Sort by updatedAt in ascending or descending order.

The response includes meta.total for the complete visible result and a signed meta.nextCursor when more rows are available. Continue with the cursor by itself. Fetch GET /opportunities/{id} after selecting a row to review metadata and the latest timeline activity.

Commercial document finders

For exact identifier matching, sales-order orderNo, customerOrderNo, and externalId accept one value or as many as 25 comma-separated values. Purchase-order orderNo and externalId support the same batching. For example:

GET /orders?customerOrderNo=A,B,C&limit=5

Order finders return up to 25 rows and a signed nextCursor when more results are available. Continue with the cursor alone so the original filters, ordering, and snapshot stay together.

Use paired changedFrom and changedTo for a half-open last-updated range of up to 30 days. Finder metadata reports the ordering, snapshot time, returned row count, and continuation cursor.

Continue through multiple pages

Start each finder with its documented filters and limit. When meta.nextCursor is available, follow the continuation rule for that finder:

Stop when meta.nextCursor is null. Use the limit documented for the selected endpoint; for example, Sales Orders, Purchase Orders, and Suppliers accept 1 through 25, while Purchase Execution and Certification Types accept 1 through 100.

If a request returns doNotRetrySameRequest: true, do not repeat it unchanged. Correct the filter, limit, or cursor from the returned error details. When a continuation cursor is no longer usable, restart from the original first-page request rather than trying to repair the cursor.

Detail reads

After selecting an id, hydrate the exact record:

GET /customers/{id}
GET /suppliers/{id}
GET /products/{id}
GET /orders/{id}
GET /purchase-orders/{id}
GET /opportunities/{id}
GET /contacts/{id}
GET /notes/{id}
GET /customers/{id}/documents
GET /suppliers/{id}/documents
GET /products/{id}/documents

Detail and attached document responses provide the fields documented for the selected record. Sales- and purchase-order detail returns 100 lines by default, accepts lineLimit up to 500, and supports consistent continuation through lineCursor. Continue with lineCursor alone.