# Supplier Returns & Credit Note Reconciliation (`prixodik/supplier-credit-reconciliation`) Actor

Find missing, partial and unapplied supplier credits from structured exports. Exact amounts, document evidence, cut-off dates and completeness checks.

- **URL**: https://apify.com/prixodik/supplier-credit-reconciliation.md
- **Developed by:** [Milchenko Oleksii](https://apify.com/prixodik) (community)
- **Categories:** Business, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$750.00 / 1,000 complete reconciliation reports

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

## Supplier Returns & Credit Note Reconciliation

Reconcile approved monetary supplier returns, issued credit notes and their applications from three authorized structured exports. Separate missing or partial issuance from an unapplied credit balance. Every finding retains exact document IDs and amounts; it is a review candidate, not proof of money owed.

### Quick start

Run the prefilled synthetic example. A EUR 1,000 approved return, EUR 800 credit and EUR 500 application produce a EUR 200 issuance difference and EUR 300 application balance. These are distinct stages, not a confirmed recovery total. Download the complete dataset report or `FULL_RECORDS` for individual return and credit review records.

Use the Input editor or Apify API with `example-input.json`. The Actor does not fetch URLs, read PDFs, connect to an ERP, send supplier emails, make payments or use an external AI model.

### Input contract

`scope` is an exact pseudonymous accounting-book identifier. `cutoffDate` is an inclusive ISO date (`YYYY-MM-DD`). Explicit `completeness` flags for `returns`, `credits` and `applications` must be true only after the caller has verified the entire relevant scope. False flags prevent definitive missing-credit or unapplied-credit classifications.

Every row includes an exact `supplierId` and supported uppercase `currency`. IDs are nonempty strings up to 80 characters, unpadded and case-sensitive; leading zeros matter. IDs must be unique within each table and accounting scope; qualify document numbers yourself when different suppliers reuse a number. Amounts are positive decimal strings with at most two decimal places, at most 10^14 minor units. No floats, exponent notation, thousands separators, zero or negative amounts.

| Table | Required fields |
|---|---|
| `returns` | `returnId`, `supplierId`, `currency`, `approvedAmount`, `approvedAt`, `creditDueDate` |
| `credits` | `creditId`, `supplierId`, `currency`, `amount`, `issuedAt`, `applicationDueDate`, `allocations` |
| `applications` | `applicationId`, `supplierId`, `currency`, `creditId`, `amount`, `appliedAt` |

A credit's `allocations` contains explicit `{returnId, amount}` objects. Allocations must add up exactly to the credit amount; a shared credit is never counted in full under each return. Applications link to a credit, not to a guessed return. Supplier and currency must agree along every link. Missing, duplicate or conflicting links fail explicitly. Unknown fields are rejected.

USD, EUR, GBP, CAD, AUD, PLN and CZK use two decimal places. There is no currency conversion. Choose one consistent amount basis (such as net), resolve cancellations and corrections upstream, and supply contractually agreed due dates. Dates are not inferred from law or payment terms. Pre-approval credits and pre-issue applications are rejected. Future documents are excluded from the selected cut-off; a due date becomes overdue only on the following day. Overcredits and overapplications retain their negative signed differences for review.

Limits: 10,000 combined table rows, 20,000 allocations, 4 MB input and 8 MB per output artifact. Split oversized input into independent complete scopes, preserving all related documents. This Actor cannot authenticate approvals, deadlines, completeness, balances or the supplied identities.

### Results and repeat checks

One dataset item is a complete report containing `returns`, `credits`, completeness, source counts and evidence. Monetary results are integer minor units; EUR 200 is `20000`. `humanReviewRequired` is always true and `confirmedRecovery` always false. `FULL_RECORDS` and `RECORDS` are machine-readable review arrays; `CHANGES` explains differences from the previous complete supplied export; `SUMMARY` contains report metadata.

`snapshot` returns a full check. `changes` also performs and delivers a complete check but identifies differences from a previous successful run. Supply a persistent `stateStoreId` and the same scope. A first run establishes a baseline. Removed input rows mean absence from the new export, not supplier cancellation. Older cut-offs require a separate store. Serialize runs using one store and scope; conflicting state is rejected. Only verified complete deliveries advance the baseline. Resuming the same delivered run validates the saved report and avoids a second dataset delivery; changed or uncertain storage stops explicitly.

### Pricing

**$0.75 per completed report**, platform usage included. One report covers the bounded input, not one fee per financial row. A new run is a new paid complete check, including unchanged data, no exceptions or incomplete-source findings. Invalid input and insufficient report budget do not deliver a paid report. Do not rerun unchanged exports unnecessarily. Long-term storage and subsequent external reads are subject to Apify platform rules. No third-party API subscription or AI bill is required.

### Privacy and limitations

Submit only records you are authorized to process. Use pseudonymous book, supplier and document IDs; amounts and dates remain sensitive. No raw financial rows are logged or forwarded to third-party services, but Apify stores Actor inputs, datasets and key-value artifacts under your account's access and retention settings. This is not local-only or zero-retention processing. Review resource sharing and retention before uploading actual records. Do not put confidential data in public tasks or support issues.

The report is deterministic evidence review, not accounting, tax, legal advice, payment approval or an audit certification. Real discrepancies require review against underlying documents. For support, provide a synthetic reproduction and run ID without confidential data.

# Actor input Schema

## `scope` (type: `string`):

Stable pseudonymous book or company scope. Do not mix different accounting books.

## `cutoffDate` (type: `string`):

Inclusive ISO date YYYY-MM-DD. Due dates are overdue only after the specified date.

## `completeness` (type: `object`):

Explicit boolean flags for returns, credits and applications. Unknown or partial exports must use false.

## `returns` (type: `array`):

Approved monetary returns with exact returnId, supplierId, currency, approvedAmount, approvedAt and creditDueDate.

## `credits` (type: `array`):

Positive credit amounts and explicit allocations. Sum of allocations must equal the credit amount.

## `applications` (type: `array`):

Positive applied amounts with exact applicationId, creditId, supplierId, currency and appliedAt.

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

Return a complete report, optionally with a separate list of differences from the previous supplied export.

## `stateStoreId` (type: `string`):

Required for changes mode. Serialize runs sharing a store and scope. Inputs and results remain subject to Apify storage settings.

## Actor input object example

```json
{
  "scope": "synthetic-book-01",
  "cutoffDate": "2026-10-11",
  "completeness": {
    "returns": true,
    "credits": true,
    "applications": true
  },
  "returns": [
    {
      "returnId": "R-DEMO-001",
      "supplierId": "S-DEMO-001",
      "currency": "EUR",
      "approvedAmount": "1000.00",
      "approvedAt": "2026-09-01",
      "creditDueDate": "2026-09-20"
    }
  ],
  "credits": [
    {
      "creditId": "CN-DEMO-001",
      "supplierId": "S-DEMO-001",
      "currency": "EUR",
      "amount": "800.00",
      "issuedAt": "2026-09-10",
      "applicationDueDate": "2026-09-30",
      "allocations": [
        {
          "returnId": "R-DEMO-001",
          "amount": "800.00"
        }
      ]
    }
  ],
  "applications": [
    {
      "applicationId": "AP-DEMO-001",
      "supplierId": "S-DEMO-001",
      "currency": "EUR",
      "creditId": "CN-DEMO-001",
      "amount": "500.00",
      "appliedAt": "2026-09-12"
    }
  ],
  "mode": "snapshot",
  "stateStoreId": ""
}
```

# Actor output Schema

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

No description

## `records` (type: `string`):

No description

## `changes` (type: `string`):

No description

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

No description

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("prixodik/supplier-credit-reconciliation").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("prixodik/supplier-credit-reconciliation").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 '{}' |
apify call prixodik/supplier-credit-reconciliation --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,prixodik/supplier-credit-reconciliation"
        }
    }
}
```

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/QmMsXdBuANnf5Q7zI/builds/ymdgZrJbvQcTPBpTc/openapi.json