Declared Order Quantity Cap Review

For sourcing agencies already holding demand quantities, supplier MOQ/carton constraints and current all-units price offers. This Actor finds the feasible quantity with the lowest declared merchandise subtotal for each exact supplier/SKU offer independently, within the buyer’s excess-unit limit. It processes a bounded JSON input and returns explicit evidence for human review.

Try the original demo

The default mode is demo. Run { "mode": "demo" }, or use samples/demo.json and the prefilled original offer. The fixture is fictional, authored for this project and dedicated under CC0-1.0. It uses demand 180, MOQ 1, total-unit multiple 10 and an excess cap of 20, with all-units tiers of $5.00 from quantity 1 and $4.00 from quantity 200. Quantity 200 costs exactly $800.00; quantity 180 would cost $900.00.

The original demo has $0 custom report events. The separate platform-managed $0.00005 Actor start fee applies when configured, including demo runs. Demo accepts only the frozen original fixture. Passing changed or customer offers in demo is rejected.

Review your own offers

Set mode to review, confirm permission with rightsConfirmed: true, and supply an explicit offers array of at most 100 rows. Missing or false permission is rejected. Missing offers are never replaced with the demo fixture. samples/review.json uses the same fictional offer in custom review mode: its useful report is eligible for the $0.25 custom event.

{
  "mode": "review",
  "rightsConfirmed": true,
  "offers": [
    {
      "supplierId": "project-supplier",
      "sku": "PROJECT-001",
      "demand": 180,
      "MOQ": 1,
      "orderMultiple": 10,
      "multipleBasis": "total_units",
      "maxExcessUnits": 20,
      "unit": "piece",
      "currency": "USD",
      "tierUnitBasis": "same_declared_unit",
      "allUnitsTiers": [
        { "minimum": 1, "unitPrice": "5.00" },
        { "minimum": 200, "unitPrice": "4.00" }
      ]
    }
  ]
}

The profile is exact and case-sensitive. Keep supplier and SKU identifiers as strings, including leading zeros. Supplier/SKU identifiers must be nonblank strings up to 200 characters, and unit a nonblank string up to 80 characters, without control characters. currency must have exactly three uppercase letters. Every tier applies to that same declared unit and currency; optional tier-level unit/currency/supplierId/sku declarations must match the offer. Supply current all-units prices separately from your demand/MOQ/multiple records; historical purchase cost is not assumed to be a current tier schedule. maxExcessUnits is your chosen policy for that offer. There is no CSV input, file/URL fetch, ERP adapter or automatic field translation.

Rules and interpretation

A feasible quantity q must be an integer total-unit multiple: q = k * orderMultiple, q >= max(demand, MOQ) and q <= demand + maxExcessUnits. MOQ + n * orderMultiple conventions are unsupported and remain unknown.

Supply tiers in strictly increasing unique minimum-quantity order; the Actor does not sort or merge them automatically. A tier price applies to every ordered unit in its interval [minimum, next minimum). For each interval, the Actor checks its smallest feasible multiple. With nonnegative unit prices, a larger quantity within that interval cannot have a smaller subtotal. It compares the exact q * unitPrice values across these bounded candidates and chooses the lowest quantity when subtotals tie. No exhaustive quantity sweep is used.

feasible means a selected quantity satisfies the supplied constraints. infeasible means validated constraints have no quantity within the cap; that is a useful completed review. unknown means source terms are missing, invalid, ambiguous or unsupported. Missing first applicable price coverage, duplicate tier minimums, mixed tier units/basis, ambiguous SKU terms and malformed prices are never guessed. Zero prices are allowed. Monetary arithmetic uses scaled BigInt, without binary floating-point rounding.

The result is per offer. It does not rank suppliers or infer graduated pricing, combined-SKU MOQ, landed cost, tax, shipping, FX, stock availability, supplier acceptance or purchase advice.

Outputs and billing receipt

The default Dataset has one summary row (including the frozen profile and content reportHash): schemaVersion, mode, status, offersReviewed, feasibleCount, infeasibleCount, unknownCount, billable, eventCount, billingState, reportKey and csvKey. The default Key-value store has:

• REPORT.json: the complete funded report, with source-row identity, supplier/SKU, status/reason, selected quantity or null, selected-tier evidence, exact unit price/subtotal, currency/unit and declared constraints.
• REVIEW.csv: the same funded offer facts. Cells are quoted and potential spreadsheet formulas receive an apostrophe guard; raw JSON strings remain available in the report.
• CHECKPOINT: the resume checkpoint and authoritative final billing receipt.

Actor Output links all three files and the Dataset. Useful custom output is persisted before charging. Therefore a paid report and its Dataset summary retain pre-charge metadata: billingState is pending and eventCount is null. These fields do not claim a settled fee. Read CHECKPOINT.billingState: confirmed confirms the report event, no_custom_fee confirms no custom event, and charge_unknown means the charge outcome is uncertain. The report and summary are not rewritten to claim final billing confirmation.

Budget exhaustion and invalid input return diagnostic output with no useful quantities or counts; the summary’s counts are null. All-unknown output likewise has no offer results or counts; its diagnostics contain only source-row references and reasons. A diagnostic link alone does not establish that a useful review completed.

Price, budget and resumption

The proposed Pay-per-event price is $0.25 per quantity_cap_review_completed event: one useful bounded report covering at most 100 offers. One or more feasible or valid infeasible rows makes a custom report useful; an all-unknown report, invalid input or the original demo has $0 custom report events. There is no default Dataset-item charge and no manual custom start event. The platform-managed $0.00005 start fee is separate and applies when configured, including demo and diagnostic runs. This local price specification is awaiting native setup.

The Actor determines whole-report funding capacity, with startup allocation separate, before writing useful content to any Dataset, KVS record or checkpoint. A partial event budget cannot fund a report. A report with insufficient custom-event capacity is not partially released. Additional budget does not create extra report events.

After complete useful output is accessible, the Actor requests the single event. A confirmed checkpoint for the same input returns the saved result without repeating output or billing. Interrupted or uncertain charge states stop automatic replay rather than blindly charging again. Local SDK tests do not establish native billing behavior.

Bounds and processing

Bound	Maximum
UTF-8 JSON input bytes	1 MiB
Offers	100
All-units tiers per offer	100
Demand and excess units	1,000,000,000 each
MOQ, order multiple and tier minimum	1 through 1,000,000,000
demand + maxExcessUnits	1,000,000,000
Unit price integer / fractional digits	12 / 6

Demand and excess units can be zero. Quantity fields are whole JSON numbers. Prices are nonnegative decimal strings; exponents, signs, thousands separators and floating JSON prices are unsupported. The whole input is capped at 1 MiB of UTF-8 JSON. Excess limits, quantity bounds and unsupported source terms are checked explicitly. Unsupported fields in an offer are not interpreted as alternate profile aliases.

Custom data requires permission for all supplied records. Processing uses the Actor input and the customer’s Apify storage; no supplier API, upstream Actor, LLM, database, webhook, email or external business-system write is used. The runtime pins Apify SDK 3.7.2 and uses native JavaScript for this job. LICENSE-DEMO.txt covers the original fixture only. Third-party dependency licenses remain their own.

Input, Dataset and Actor Output definitions follow the official input schema, Dataset schema and Actor Output schema formats. Native build recognition, run behavior and billing require the separate release checks. This implementation does not itself create, build, run or publish an Apify Actor.

For local development, run npm test, npm run validate, npm run sdk-test and npm run main-test. The Windows SDK launchers give each process a new SKU-only storage directory before importing the SDK. Local files are REPORT.json and REVIEW.csv; the SDK uses canonical local keys REPORT and REVIEW, accessed through actorIO.read. This avoids the pinned local SDK's extension restoration and record-metadata serialization defects. Native KVS keys and Output links remain REPORT.json and REVIEW.csv. A new-process read is checked by the main-entrypoint test.