xMatix
Sign in Request demo
xMatix
PRODUCTS
SalesField Sales & SFACRMRewardsClaimsInventoryProcurementWarehouse ManagementField ServiceServiceSupportTelephony & MessagingFinance & AccountingPayrollExpense ManagementCommercePortalsAnalytics & ReportingData StudioMobile AppSee all products →
PLATFORM
Platform overviewApp BuilderAutomationIntegrationsSecurity & GovernanceChange ManagementDevelopers
SENSE AI
Sense AI overviewSense AssistSense ControlSense VisionAI StudioTrust & governanceIn Claude & ChatGPTUse cases
SOLUTIONS
Auto DMSConsumer Goods DMSSales Force Automation (SFA) FMCG & DistributionManufacturing & Dealer NetworksAutomotive & DealershipsPharma & HealthcareConsumer DurablesAgri-InputsBuilding MaterialsService NetworksWarehousing & 3PLFinancial AccountingERP SoftwareIndia GST ComplianceUAE VAT & e-InvoicingSaudi ZATCA & VATAll solutions →
RESOURCES
Knowledge CenterDeveloper & CLIBlogGuidesWhat is xMatix?Company facts
COMPANY
AboutCareersPartnersEventsContactAuthorsLegal
Sign in Request demo
Home/Docs/Entity Reference/Scheme — entity reference
REFERENCE · Last reviewed

Scheme — entity reference

A scheme is a trade or promotional offer, such as buy 10 get 1 free or 5% off orders over a threshold. It is defined once and applied to documents by the scheme engine. The scheme record is the header: it sets which document the offer evaluates (Scheme Type), how it is triggered (Application), when it is valid, who it is for and its budget behaviour. The qualification rules sit on its Scheme Slabs. Each slab pairs Scheme Conditions (what the document must contain) with Scheme Benefits (what is granted). Only schemes whose Status is Approved are evaluated. The engine runs on sale orders, carts, invoices, credit notes, purchase orders, bills and service orders. It picks a scheme when the scheme type covers the document, the document date falls inside Val From and Val To (both inclusive, empty means open), and the account, partner and account-group scope match. Every application is recorded in the Scheme Ledger. Val Count limits and budgets are enforced against that ledger. Scheme Account Budget rows cap spend for the whole scheme and per partner. The Scheme entity is listed in the Rewards app.

Fields

FieldLabelTypeRequiredWhat it does
AccountGroupIdAccount GroupLookup → AccountGroupLimits the scheme to accounts that are active members of this account group. The engine only counts groups whose Account Group Type is Scheme. Pick a group of any other type and no account ever matches, so the scheme never applies. Empty means no group restriction.
AccountIdAccountLookup → AccountLimits the scheme to one customer account: when set, only documents for exactly this account qualify. Empty means any account.
ApplicableTransactionTypeApplicable Transaction TypePickListWhen set, the document's transaction type must equal this value or the scheme is skipped; empty means any transaction type.
ApplicationApplicationPickListHow the scheme is triggered: Auto Apply schemes run automatically inside the document save; Apply On Selection schemes only surface in recommendation and qualification lists and take effect when a user explicitly applies them (the ApplyScheme server action on the document). Values: Auto Apply, Apply On Selection.
BranchIdBranchLookup → BranchA branch recorded on the scheme; the lookup offers only branches of the selected Partner Account. The scheme engine does not filter on it, so it does not restrict which documents the scheme applies to.
BusinessHoursIdBusiness HourLookup → BusinessHoursA business-hours calendar reference. It is not on the shipped forms and the scheme engine does not use it.
ClaimablePercentageClaimable PercentagePercentShare of a claimable scheme's unclaimed ledger value that counts as claimable rebate in partner performance figures. 0 or empty counts the full value.
ClaimGenerationFrequencyClaim Generation FrequencyPickListDaily, Weekly or Monthly, recorded on the scheme. Claim runs are scheduled on the Claim Generation Setup, not by this field, which no process reads. Values: Daily, Weekly, Monthly.
CreatedByIdCreated ByLookup → UserAccountYes
CreatedDateTimeCreated DateDateAndTimeYes
IdIdGuidYes
IgnoreBudgetIgnore BudgetBooleanYesSkips all budget gating for this scheme: it applies on both Sale Order and Sale Invoice regardless of budget configuration or remaining budget. Without it, a scheme lacking both a global and a partner-scoped SchemeAccountBudget is suppressed on the Sale Invoice.
IncludeChildAccountTransactionsInclude Child Account TransactionsBooleanYesFor Per Period schemes: also count PerformanceKPI accrual rows of the document account's child accounts toward the period totals, not just the account itself.
IncludeRelatedAccountTransactionsInclude Related Account TransactionsBooleanYesFor Per Period schemes: also count PerformanceKPI accrual rows of sibling accounts under the same parent account toward the period totals.
IsClaimableIs ClaimableBooleanYesMarks the scheme's payouts as claimable. Partner rebate figures count unclaimed ledger value only from claimable schemes, and a Claim Generation Setup can filter on it. Ticking it does not create claims on its own; claims come from an active Claim Generation Setup.
ModifiedByIdModified ByLookup → UserAccountYes
MultipleFulfilmentTreatmentMultiple Fulfilment TreatmentPickListWhat happens when several slabs of this scheme qualify on the same document: Apply All Fulfilled applies every qualifying slab, Apply First Fulfilled keeps only the first qualifying slab in sequence, Apply Last Fulfilled keeps only the last. Values: Apply All Fulfilled, Apply First Fulfilled, Apply Last Fulfilled.
NameScheme NameTextYesThe scheme's name, shown in scheme lists, recommendations and applied-scheme details on documents. Required. Clone names the copy after the original with (Copy) appended.
OriginalSchemeIdOriginal SchemeTextFree-text reference to an original scheme, for imports and your own tracking. No process reads or sets it.
OwnerIdOwnerLookup → UserAccountYes
PartnerAccountGroupIdPartner Account GroupLookup → AccountGroupLimits the scheme to partners that are active members of this account group. As with Account Group, only groups whose Account Group Type is Scheme are recognised. Empty means no restriction.
PartnerAccountIdPartner AccountLookup → AccountLimits the scheme to documents raised by this partner (the selling or buying company on the document). Empty means any partner.
PerformCloneSchemePerform Clone SchemeBooleanYesA flag kept for imports. No process reads it; use the Clone action to copy a scheme.
PeriodEndDatePeriod End DateDateA period end date shown in the Type section. The scheme engine does not use it for qualification. Partner scheme-progress views show it as the scheme's end date only when Val To is empty.
PeriodStartDatePeriod Start DateDateA period start date shown in the Type section. The scheme engine does not use it; the validity window is Val From and Val To.
PeriodTypePeriod TypePickListYesSeeded values: Validity Period and Per Order. Neither generates scheme period rows, and that is fine for every per-document scheme type. For Per Period scheme types the engine looks for a period row covering the document date. With no period rows, the scheme's accumulated performance across its whole life counts. To accumulate per month or quarter, add Scheme Period rows on the scheme's Period tab. The period generator also understands Yearly, Quarterly, Monthly, Weekly, Bi-Weekly and Daily, but only when the scheme is first saved, and those values are not in the shipped picklist. Values: Validity Period, Per Order.
RecordTypeIdRecord TypeGuid, hidden
ReferenceSchemeIdReference SchemeLookup → SchemeOptional link to another scheme, for your own cross-reference. No process reads it, and Clone does not set it.
RoundOffTypeRound Off TypePickListCeil or Floor rounding the engine applies to computed scheme values (for example derived free-item quantities); empty means no rounding. Values: Floor, Ceil.
SchemeBudgetScheme BudgetDecimalLegacy header-level global budget; a value greater than zero counts as the scheme having a global budget. The live model expresses the scheme-wide budget as a partner-less SchemeAccountBudget row instead, and this header field is normally empty on migrated data.
SchemeCodeScheme CodeTextAn optional code for the scheme, for your own reference and imports. It is not generated automatically and is not on the shipped forms.
SchemeQuotaScheme QuotaPercentA percentage kept on the scheme for reference. It is not on the shipped forms and the scheme engine does not read it.
SchemeTypeScheme TypePickListYesWhich documents the scheme evaluates. Per Sale Order covers sale orders and carts. Per Sale Invoice covers invoices and credit notes. Per Purchase Order, Per Bill and Per Repair Order (service orders) each cover their own document. Per Sale Order And Invoice applies on both sale orders and invoices, and Per Purchase Order And Bill on both purchase orders and bills. Per Repair Order And Invoice applies on service orders and on invoices. The Per Period variants (Per Period Sale Order, Sale Invoice, Purchase Order, Bill, Repair Order) qualify on performance accumulated over the scheme's periods instead of the single document. The value Sales Order Per Period is in the picklist but the engine does not recognise it, so a scheme of that type never applies. Required. Values: Per Sale Order, Per Sale Invoice, Per Sale Order And Invoice, Per Purchase Order, Per Bill, Per Purchase Order And Bill, Per Repair Order, Per Repair Order And Invoice, Per Period Sale Order, Per Period Sale Invoice, Per Period Purchase Order, Per Period Bill, Per Period Repair Order, Sales Order Per Period.
SequenceNumberSequence NumberNumberOrder in which schemes are loaded and evaluated by the engine; lower numbers are considered first.
StatusStatusPickListLifecycle of the scheme: Draft, Pending Approval, Approved or Deactivated. Only Approved schemes are evaluated by the scheme engine; every other value keeps the scheme out of documents. Nothing sets Status automatically and no approval workflow is seeded. It changes when a user edits the field or clicks the next step on the record's status bar, which saves straight away, refuses to skip ahead more than one step and allows moving back. A new scheme has no status until one is chosen. Values: Draft, Pending Approval, Approved, Deactivated.
SupplierAccountIdSupplier AccountLookup → AccountA supplier account recorded on the scheme. It is not on the shipped forms and the scheme engine does not compare it with the document's supplier, so it does not restrict purchase-side schemes.
UIPropsUI PropsTextDisplay settings used by the user interface. Not meant to be edited by hand.
UpdatedDateTimeModified DateDateAndTimeYes
UtilizedAmountUtilized AmountDecimalDenormalized consumption figure refreshed from live SchemeLedger rows (sum of netSchemeDiscount2) so admins can watch the budget deplete. Display-oriented: budget enforcement compares against the larger of this stored value and the live ledger sum, so a stale figure cannot wrongly admit a scheme.
ValidCountVal CountNumberCap on how many distinct documents per customer account the scheme may apply to. Enforced live against SchemeLedger: the engine counts distinct applied documents of the current type for the account (excluding the document being saved) and stops applying once the count reaches this value. Zero or empty means unlimited.
ValidFromVal FromDateFirst date the scheme can apply, compared with the document date (inclusive). Empty means no start limit. Must not be later than Val To.
ValidToVal ToDateLast date the scheme can apply, compared with the document date (inclusive). Empty means no end limit. Saving with Val To earlier than Val From fails with Valid to should be greater than the valid from; the same date for both is accepted.

Actions

ActionLabelTypeWhat it does
CloneCloneServerAction (Clone)Create a copy of this record
CreateSchemeBenefitCreate Scheme BenefitServerAction (CreateSchemeBenefit)Seeded as a server action but no server handler implements it - executing it performs no server work; the rewards designer creates SchemeBenefit rows directly through the data API.
CreateSchemeConditionCreate Scheme ConditionServerAction (CreateSchemeCondition)Seeded as a server action but no server handler implements it - executing it performs no server work; the rewards designer creates SchemeCondition rows directly through the data API.
CreateSchemeSlabCreate Scheme SlabsServerAction (CreateSchemeSlab)Seeded as a server action but no server handler implements it - executing it saves the record and performs no other work (the rewards designer creates SchemeLine slab rows directly through the data API instead).
DeleteDeleteDeleteDelete In View Page
DeleteEntityDetailDeleteDeleteDeleteEntityDetail
DeleteInLineDeleteDeleteDeleteInLine
EditEditEditEdit in View Pages
EditInLineEditEditInlineEdit
EditInListEditEditEdit
EditListHeaderEditEditInlineEditListHeader
ImportImportUIActionImport
NewNewNewNew
SaveSaveServerActionA plain record save; no server action handler adds behavior beyond persisting the scheme (period generation runs on insert via the lifecycle handler regardless of which save path is used).
SubmitforApprovalSubmit for ApprovalServerActionNo server handler implements this action, so it performs no approval workflow - it is a plain save. A scheme becomes live by setting Status to Approved (only Approved schemes are evaluated by the engine).

Validations

ValidationApplies toError messageNotes
Valid To RuleValidTo, ErrorValid to should be greater than the valid fromEnsures Valid To date is not earlier than Valid From date

Lookup filters

FilterLookup fieldNotes
Branch For Partner AccountBranchId