# Declared Order Quantity Cap Review (`remarkable_whipscorpion/declared-order-quantity-cap-review`) Actor

Find the lowest declared merchandise subtotal within each supplied offer’s MOQ, total-unit multiple and excess cap, using explicit all-units tiers.

- **URL**: https://apify.com/remarkable_whipscorpion/declared-order-quantity-cap-review.md
- **Developed by:** [Kagerou AP](https://apify.com/remarkable_whipscorpion) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.25 / useful declared quantity review report saved

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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.

```json
{
  "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](https://docs.apify.com/actors/development/actor-definition/input-schema/specification/v1), [Dataset schema](https://docs.apify.com/storage/dataset-schema) and [Actor Output schema](https://docs.apify.com/actors/development/actor-definition/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.

# Actor input Schema

## `mode` (type: `string`):

demo uses only the original frozen fixture, with no custom report event. review processes your authorized offers and charges one event for a useful report. Customer data cannot be passed through demo.

## `offers` (type: `array`):

Maximum 100 rows. Exact profile: supplierId, sku, demand (0..1,000,000,000), MOQ, orderMultiple (1..1,000,000,000), multipleBasis=total_units, maxExcessUnits (0..1,000,000,000), unit, currency, tierUnitBasis=same_declared_unit, allUnitsTiers:\[{minimum,unitPrice}]. demand+maxExcessUnits must be <=1,000,000,000; minimum is 1..1,000,000,000. unitPrice is a nonnegative decimal string (at most 12 integer and 6 decimal digits); at most 100 tiers per row. Missing or ambiguous source terms remain unknown. Demo allows only this original fixture. Review requires an explicit offers array; no source offer default is inserted.

## `rightsConfirmed` (type: `boolean`):

For review mode, set true only if you own or are authorized to process the supplied demand, supplier constraints and current price schedules. Missing or false is rejected in review. The original demo has an owned-fixture exemption.

## Actor input object example

```json
{
  "mode": "demo",
  "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"
        }
      ]
    }
  ],
  "rightsConfirmed": false
}
```

# Actor output Schema

## `report` (type: `string`):

The complete funded offer report and exact selected-tier evidence. Paid reports are saved before charge, so pre-charge billing metadata does not confirm a fee. Check the billing receipt for final confirmation.

## `reviewCsv` (type: `string`):

The same funded offer facts, with RFC 4180 quoting and spreadsheet-formula guards. Diagnostics contain no useful quantities or counts when report budget is unavailable.

## `summary` (type: `string`):

One summary for the same report. Paid eventCount=null means charge confirmation was not known when this row was saved.

## `billingReceipt` (type: `string`):

CHECKPOINT is authoritative for final billingState (confirmed, no_custom_fee or charge_unknown) and eventCount. A pending or uncertain charge is not retried blindly.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "demo",
    "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"
                }
            ]
        }
    ],
    "rightsConfirmed": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("remarkable_whipscorpion/declared-order-quantity-cap-review").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "demo",
    "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",
                },
            ],
        }],
    "rightsConfirmed": False,
}

# Run the Actor and wait for it to finish
run = client.actor("remarkable_whipscorpion/declared-order-quantity-cap-review").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "demo",
  "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"
        }
      ]
    }
  ],
  "rightsConfirmed": false
}' |
apify call remarkable_whipscorpion/declared-order-quantity-cap-review --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,remarkable_whipscorpion/declared-order-quantity-cap-review"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/xkGQnQyg7O49HT4PV/builds/QV08jq17vHarKpkY2/openapi.json