Claim settlement setups

A claim settlement setup tells xMatix what to create when a claim of one claim type is approved: a credit note or an invoice on the supplier, nothing at all, or a consolidated document for a whole batch of claims. Claims are raised, reviewed and approved as described in Trade claims. The settlement setup is the last link in that chain. Without an active setup for a claim's type, an approved claim stays approved and nothing is settled.

Overview

Each setup covers exactly one Claim Type. When an approval process approves a claim, xMatix queues the Settle claim background job. The job looks up the active setup whose Claim Type equals the claim's type and follows it:

• Settlement Document decides what is created.
• Header Mapping and Line Mapping adjust the created document's fields.
• Auto GL Posting, Apply To Open Invoices and Raise Event Name decide what happens around the document.
• Settlement Grouping decides whether each claim settles on its own or waits to be settled with others in a claim batch.
• Active and Simulate Mode decide whether the setup is used at all, and whether it writes anything.

Setups are listed in the Claims app under Claim Settlement Setups. They are configuration, not transactions: you create them once per claim type and change them rarely.

When to use it

Create a settlement setup for every claim type your organization settles:

• warranty and service claims that the manufacturer pays by credit note;
• claims you recover by billing the supplier, which settle by invoice;
• scheme or expense claims that are paid outside xMatix, where you only want an event raised (Settlement Document None);
• claim types that the manufacturer settles monthly in one document, which settle per batch.

You do not need a setup to raise, review or approve claims, only to settle them.

How xMatix handles it

• Matching. The job looks for an active setup whose Claim Type equals the claim's Claim Type exactly. There is no fallback to another type. Keep one active setup per type: if two are active, which one is used is not defined.
• Amounts. Only claim lines with an Approve Quantity above zero are settled. Each becomes one document line priced at Unit Price × Approve Quantity. The document's header amount is the claim's Total Approved Amount when that is filled, otherwise the sum of the lines. A partly approved claim therefore settles partly.
• Party. A credit note or invoice is raised on the claim's Supplier Account, the manufacturer or principal who pays the claim. A claim with no Supplier Account is refused rather than booked to your own company.
• Status. When the document is created, the claim's Status becomes Settled. In batch settlement, the batch becomes Settled too.
• Simulate mode. With Simulate Mode on, the job only reports in its run summary what it would have created, and writes nothing. The claim stays unsettled.
• Repeats. Running the job again for a settled claim creates nothing; it reports the document that already exists.

Prerequisites

• The Claims licence, assigned to your organization and to you.
• Create and edit access to Claim Settlement Setup (see Permissions).
• An approval process for the Claim entity. None is shipped; see Trade claims.
• A Supplier Account on the claims you intend to settle by credit note or invoice.
• Access to Setup → Platform → Monitoring → Jobs, where you read settlement results.

Procedure

Step 1 — Open the settlement setups

Open the Claims app from the App Launcher and select Claim Settlement Setups. The All Claim Settlement Setups list shows Name, Claim Type, Settlement Document, Auto GL Posting, Apply To Open Invoices, Active and Simulate Mode for each setup. Check whether a setup already exists for the claim type before you create another.

Step 2 — Create the setup

Select New. The form asks for five things:

1. Document Number — a name for the setup, for example Warranty — credit note. Nothing numbers setups automatically, so type one.
2. Claim Type — the type this setup settles. Choose the same value your claims carry.
3. Settlement Document — choose CreditNote, Invoice or None. Do not choose Adjustment (Part to Part); see Business rules.
4. Active — leave it off for now.
5. Simulate Mode — make sure it is on before you save.

Save. The setup opens on its record page. Its header shows the Claim Type, Settlement Document and Simulate Mode, with Delete as the only header button.

A setup created this way settles per claim. Auto GL Posting and Apply To Open Invoices start off, and there are no mappings.

Step 3 — Complete the details

The record page's Details tab has three sections. Change a value with the pencil next to it, then save.

• Settlement: Settlement Document, Auto GL Posting, Apply To Open Invoices, Raise Event Name, Settlement Grouping, Batch Filter and Batch Grouping Fields.
• Mappings: Header Mapping and Line Mapping.
• Status: Active and Simulate Mode.

These fields are only on the record page. Edit on a list row opens the short create form, which has only the five fields from Step 2.

Step 4 — Write mappings, if you need them

Leave both mappings empty unless the created document needs a value that xMatix does not fill on its own. A mapping is a JSON object. Each key is a field name on the created document (header) or document line. Each value is one of the following:

• a field path on the claim (Header Mapping) or the claim line (Line Mapping), for example "Remarks": "Name";
• @approvedAmount — the claim's Total Approved Amount, or on a line, Unit Price × Approve Quantity;
• @approvedQuantity — the claim's Total Approved Quantity, or on a line, its Approve Quantity;
• @const:<value> — a fixed value, for example "TransactionType": "@const:Warranty Settlement".

Mappings are applied after xMatix has filled the document, so they replace its values: the amount, dates, status, party or transaction type. For a batch, the header mapping reads the first claim in the batch. Nothing checks a mapping when you save: a mistake shows up only as a failed Settle claim run.

Step 5 — Choose per-claim or batch settlement

Leave Settlement Grouping as it is to settle each approved claim on its own document.

To settle many claims as one document, set Settlement Grouping to PerBatch. The list also offers Per Batch (consolidated), but the batching job does not recognise that value, so a setup that uses it settles per claim. With PerBatch:

• An approval no longer settles the claim. The Batch claims for settlement job collects the claims into claim batches, and Settle Batch on a batch settles them together. See Batches.
• Batch Filter narrows which claims the batching job picks up. Empty means Status == "Approved". The filter is an expression over claim fields; saving the setup test-runs it and refuses one that does not work.
• Batch Grouping Fields is a comma-separated list of claim fields. Empty means PartnerAccountId,BranchId,SupplierAccountId.
• Batch Period (None or Month) is not on the shipped forms. Add it to the record page in the layout designer if you want monthly batches.

Only CreditNote and Invoice can be settled per batch.

Step 6 — Prove the setup in simulate mode

Turn Active on and keep Simulate Mode on. Approve one or two real claims of the type, then open Setup → Platform → Monitoring → Jobs and find the Settle claim runs. A simulated run reports, for example, "SIMULATE: would create CreditNote for ₹8400 (Warranty, claim CN-…)".

The amount in that message is the claim's Total Approved Amount, not the line total. On a claim typed by hand that field is usually empty, so the message shows ₹0 even though the real document would carry the approved lines. Check the lines yourself: the real document has one line per approved line at Unit Price × Approve Quantity. Compare the total with what the supplier should pay.

For a PerBatch setup, start the batching job instead (Step 8). Its simulated summary reports how many claims would go into how many batches.

Step 7 — Go live

Switch Simulate Mode off and save. Claims approved from now on settle for real.

Claims that were approved while the setup was simulating are not picked up again automatically. Settle each of them by hand (Step 8).

Step 8 — Start a settlement or batching run by hand

The jobs can also be started from Setup → Platform → Monitoring → Jobs. You need permission to manage jobs.

1. On the Schedules tab, add a schedule. As Job type, choose Settle claim or Batch claims for settlement.
2. In Payload JSON, enter what to run:
   • one claim: {"claimId": "<the claim's record id>"};
   • one claim batch: {"claimBatchId": "<the batch's record id>"};
   • batching for one claim type only: {"claimType": "Warranty"}.

Add "simulate": true or "simulate": false to override the setup's Simulate Mode for that run only.

1. Select Run now on the schedule's row, then read the run on the runs list.
2. Delete the schedule when you no longer need it, or keep a batching schedule as your nightly run.

The record id is the last part of the record page's address.

Fields

Business rules

• One active setup per type. The job takes an active setup with the exact Claim Type. A missing setup is not an error: the run reports "No settlement setup for claim type '…' — nothing to do."
• Settlement Document None creates nothing and raises the event only. The run reports "Settlement document 'None' — events only."
• Adjustment (Part to Part) does not run as shipped. The settlement job recognises the stored value Adjustment, but the list stores Adjustment (Part to Part). A claim on such a setup fails with "Settlement document 'Adjustment (Part to Part)' is not supported yet."
• PerBatch with Adjustment is refused when you save: "Adjustment settlement is per-claim; it cannot be combined with Per Batch grouping." A batch whose setup has any document other than CreditNote or Invoice fails with "Batch settlement supports Invoice and CreditNote; '…' is per-claim only."
• Batch filter check. Saving a setup with a Batch Filter runs it once against your claims. If it fails, the save is refused with "batch filter does not compile —" followed by the reason.
• Supplier required. A credit note or invoice settlement for a claim, or a batch, with no Supplier Account fails with "… has no supplier / OEM (SupplierAccountId), so its settlement … would be booked to the company itself. Set the supplier and settle again."
• Nothing approved. A claim with no approved amount and no lines reports "Nothing approved on the claim — no settlement document created."
• Created documents. The credit note or invoice is created as Draft, dated the day of the run. It has transaction type Claim Settlement, one line per approved claim line, and a link back to the claim (or batch). The claim's Status becomes Settled.
• Batch top-up. The batching job adds claims to an existing Draft batch for the same partner account, branch and supplier account, whatever the grouping fields say. Extra grouping fields therefore only make a difference with a monthly Batch Period, where every run creates new batches.
• Retries. A failed Settle claim run is retried up to three times, and runs for one organization never overlap.

Example

Your service team raises warranty claims on a two-wheeler manufacturer, Sarvam Motors, which pays them by credit note against your open purchase invoices.

1. In Claims → Claim Settlement Setups, you select New. You enter Warranty — credit note, Claim Type Warranty, Settlement Document CreditNote, Active off, Simulate Mode on, and save.
2. On the Details tab, you switch on Apply To Open Invoices. You leave Settlement Grouping and the mappings as they are.
3. You turn Active on. Approvers approve claim CN-12-10-2026-000231 with two lines: 2 × 1,800 and 1 × 4,800. The claim came from a generation setup that fills Total Approved Amount, here 8,400.
4. The Settle claim run reports "SIMULATE: would create CreditNote for ₹8400 (Warranty, claim CN-12-10-2026-000231)". The lines add up to the same 8,400, which matches the supplier's acknowledgement.
5. You switch Simulate Mode off and settle that claim by hand with a Settle claim schedule whose payload names the claim.
6. The run reports the credit note, 8,400, how much was applied, and the open amount. The claim shows Settled, and the credit note appears on its Related tab, in Draft. Your accountant posts it with Post General Ledger.

Training

Practice exercise

In a sandbox with the Claims licence and a claim approval process:

1. Create a settlement setup for Transport, Settlement Document CreditNote, Active on, Simulate Mode on.
2. Create a Transport claim with a Supplier Account and one line, approve the line, and get the claim approved.
3. Open the Jobs screen and read the Settle claim run.

Expected result: the run says "SIMULATE: would create CreditNote for ₹0 …" (a hand-made claim has no Total Approved Amount), and the claim is still Approved, not Settled. Then switch Simulate Mode off and settle the claim by hand (Step 8). The claim becomes Settled, and a Draft credit note for Unit Price × Approve Quantity appears on its Related tab.

Quick reference

• One active setup per claim type; the type must match exactly.
• Choose CreditNote, Invoice or None, never Adjustment (Part to Part).
• Check that Simulate Mode is on when you create a setup.
• A simulated run shows the claim's Total Approved Amount, not the line total.
• For batch settlement choose PerBatch, not Per Batch (consolidated).
• Mappings, batching and event fields are edited on the record page, not in the create form.
• Settlement pays Unit Price × Approve Quantity per approved line.
• The claim needs a Supplier Account for a credit note or invoice.
• Credit notes are created as Draft; post them yourself.
• Claims approved during simulation need a manual run.
• Results are on Setup → Platform → Monitoring → Jobs.

Permissions

A user without access to Claim Settlement Setup does not see the list. Settlement itself runs as a background job and does not depend on the approver's permissions.

Configuration

• Settlement setups. Claims → Claim Settlement Setups, one per claim type, as above.
• Claim types. A setup's Claim Type list and the claim's Claim Type list are separate picklists. If you add a claim type to claims, add the same value to the setup's Claim Type picklist (Design Studio → Entities → Claim Settlement Setup → picklist values), then create the setup.
• Batch Period. To batch per month, add the Batch Period field to the setup's record page in the layout designer, then set it to Month.
• Batching schedule. Schedule Batch claims for settlement on the Jobs screen's Schedules tab, for example nightly. See Batches.
• Events. A Raise Event Name can be picked up by business rules on the Claim entity; see Business rules.
• Credit-note posting and application. How a Draft credit note is posted and applied is described in Credit notes.

Common problems

The claim is approved but stays Approved

Check that an active setup exists for exactly that Claim Type, and that Simulate Mode is off and the document is not None. Then read the Settle claim run on the Jobs screen. If the setup was simulating when the claim was approved, settle the claim by hand (Step 8).

The run failed with "Settlement document 'Adjustment (Part to Part)' is not supported yet."

Cause: the setup uses the Adjustment (Part to Part) value, which the job does not recognise.

Fix: change Settlement Document to CreditNote, Invoice or None, then settle the claim by hand.

Claims of a batch type settle one by one and no batches appear

Cause: Settlement Grouping is Per Batch (consolidated) or Per Claim. Only PerBatch turns on batching.

Fix: set it to PerBatch. Claims already settled stay settled.

The run failed with "has no supplier / OEM"

Cause: the claim, or the batch, has no Supplier Account.

Fix: fill in the Supplier Account on the claim (or batch), then select Retry on the failed run.

Saving the setup fails with "batch filter does not compile"

Cause: the Batch Filter names a field that claims don't have, or isn't a valid expression.

Fix: use claim field names and quoted text values, for example Status == "Approved". Clear the filter to use the default.

The settle run fails after I added a mapping

Cause: the mapping is not valid JSON, or names a field the document or claim does not have. Mappings are not checked on save.

Fix: correct the mapping, then select Retry on the failed run, or settle by hand.

Common questions

Do I need a setup for every claim type?

Only for the types you want xMatix to settle. A claim whose type has no active setup can still be raised, reviewed and approved. On approval, the Settle claim run reports that there is no setup and creates nothing, and the claim stays Approved. If you later add a setup, settle those claims by hand from the Jobs screen. If you settle a type outside xMatix but want downstream automation, create a setup with Settlement Document None and a Raise Event Name.

What happens if I change a setup after claims were approved?

Settlement reads the setup at the moment the Settle claim job runs, not when the claim was raised. Claims that are already settled are not changed. Claims settled from then on use the new values. A claim that a simulated run only reported is not re-run when you switch Simulate Mode off; start a run for it yourself.

Can a setup settle by debit note or stock adjustment?

No. As shipped, a setup settles by credit note, by invoice, or not at all (None). The stock adjustment value in the list does not run.

Related topics

• Trade claims — raising, approving and batching claims
• Authoring a claim generation setup
• Credit notes
• Approvals
• Claim Settlement Setup reference
• Claim — entity reference