{"id":"price-change-attribution","title":"Attribute a total's change to quantity, price, FX, added and removed lines (sums exactly)","description":"Explains why a total moved between two versions of a quote, order or invoice (up to 300 lines each), for an agent that must say how much of the change came from quantity, unit price, exchange rate, new lines and dropped lines. Lines are matched by key. Matched lines are decomposed by sequential substitution in the declared factor order (default quantity, then price, then fx), so the effects sum to the change exactly; added and removed lines are their own effects. Rounded minor-unit effects are reconciled so they sum to the rounded total change. The order matters (price-first and quantity-first attribute the cross term differently) and is echoed back. If stated totals are supplied they are checked against the recomputed totals and the drift is reported. Not a variance explanation of why a supplier changed a price.","roi":"A total up $412.07 is three different stories depending on how the cross term is booked. Exact, ordered, and summing to the cent.","audience":"business","package":"money-math-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/price-change-attribution","path":"/api/v1/price-change-attribution","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["before","after"],"properties":{"before":{"type":"array","minItems":0,"maxItems":300,"items":{"type":"object","required":["key","quantity","unitPrice"],"properties":{"key":{"type":"string","minLength":1,"maxLength":80},"quantity":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."},"unitPrice":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."}},"additionalProperties":false}},"after":{"type":"array","minItems":0,"maxItems":300,"items":{"type":"object","required":["key","quantity","unitPrice"],"properties":{"key":{"type":"string","minLength":1,"maxLength":80},"quantity":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."},"unitPrice":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."}},"additionalProperties":false}},"fx":{"type":"object","required":["before","after"],"properties":{"before":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."},"after":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."}},"description":"Multiplier from line currency to reporting currency, before and after. Default 1 and 1.","additionalProperties":false},"order":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string","enum":["quantity","price","fx"]},"description":"Substitution order of the factors; each at most once. Default [quantity, price, fx]."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 alphabetic code, upper case."},"exponent":{"type":"integer","minimum":0,"maximum":8},"rounding":{"type":"string","enum":["half-up","half-down","half-even","up","down","ceiling","floor"],"description":"Default half-even. half-up: ties away from zero. half-down: ties toward zero. half-even: ties to the even neighbour. up: away from zero. down: toward zero. ceiling: toward +infinity. floor: toward -infinity."},"statedBeforeTotal":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Optional stated total of `before` (reporting currency) to verify."},"statedAfterTotal":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Optional stated total of `after` to verify."}}},"resultSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"order":{"type":"array","items":{"type":"string"}},"beforeMinor":{"type":"integer"},"afterMinor":{"type":"integer"},"deltaMinor":{"type":"integer","description":"The exact change (after minus before) rounded once; equals the sum of byFactor and of byLine. It can differ by one unit from afterMinor minus beforeMinor, which round each total separately."},"byFactor":{"type":"object","properties":{"quantity":{"type":"integer"},"price":{"type":"integer"},"fx":{"type":"integer"},"added":{"type":"integer"},"removed":{"type":"integer"}},"description":"Signed minor-unit effects; they sum to deltaMinor."},"byLine":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["changed","added","removed","unchanged"]},"deltaMinor":{"type":"integer"}}}},"exponent":{"type":"integer"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"outputSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"order":{"type":"array","items":{"type":"string"}},"beforeMinor":{"type":"integer"},"afterMinor":{"type":"integer"},"deltaMinor":{"type":"integer","description":"The exact change (after minus before) rounded once; equals the sum of byFactor and of byLine. It can differ by one unit from afterMinor minus beforeMinor, which round each total separately."},"byFactor":{"type":"object","properties":{"quantity":{"type":"integer"},"price":{"type":"integer"},"fx":{"type":"integer"},"added":{"type":"integer"},"removed":{"type":"integer"}},"description":"Signed minor-unit effects; they sum to deltaMinor."},"byLine":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["changed","added","removed","unchanged"]},"deltaMinor":{"type":"integer"}}}},"exponent":{"type":"integer"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]},"example":{"currency":"USD","before":[{"key":"widget","quantity":"100","unitPrice":"2.00"},{"key":"gadget","quantity":"10","unitPrice":"9.99"}],"after":[{"key":"widget","quantity":"120","unitPrice":"2.10"},{"key":"gizmo","quantity":"5","unitPrice":"4.00"}],"statedBeforeTotal":"299.90","statedAfterTotal":"272.00"},"openapiOperation":{"operationId":"price_change_attribution","summary":"Attribute a total's change to quantity, price, FX, added and removed lines (sums exactly)","description":"Explains why a total moved between two versions of a quote, order or invoice (up to 300 lines each), for an agent that must say how much of the change came from quantity, unit price, exchange rate, new lines and dropped lines. Lines are matched by key. Matched lines are decomposed by sequential substitution in the declared factor order (default quantity, then price, then fx), so the effects sum to the change exactly; added and removed lines are their own effects. Rounded minor-unit effects are reconciled so they sum to the rounded total change. The order matters (price-first and quantity-first attribute the cross term differently) and is echoed back. If stated totals are supplied they are checked against the recomputed totals and the drift is reported. Not a variance explanation of why a supplier changed a price.\n\nPrice: 0.005 USDC on Base (x402).","x-x402-price-usdc":"0.005","x-x402-amount":"5000","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"x-audience":"business","x-sample-url":"https://agents.writerslogic.com/api/v1/samples/price-change-attribution","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["before","after"],"properties":{"before":{"type":"array","minItems":0,"maxItems":300,"items":{"type":"object","required":["key","quantity","unitPrice"],"properties":{"key":{"type":"string","minLength":1,"maxLength":80},"quantity":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."},"unitPrice":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."}},"additionalProperties":false}},"after":{"type":"array","minItems":0,"maxItems":300,"items":{"type":"object","required":["key","quantity","unitPrice"],"properties":{"key":{"type":"string","minLength":1,"maxLength":80},"quantity":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."},"unitPrice":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."}},"additionalProperties":false}},"fx":{"type":"object","required":["before","after"],"properties":{"before":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."},"after":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Decimal string such as \"-12.50\" (up to 15 integer and 12 fraction digits). JSON numbers are not accepted: they are binary floats."}},"description":"Multiplier from line currency to reporting currency, before and after. Default 1 and 1.","additionalProperties":false},"order":{"type":"array","minItems":1,"maxItems":3,"items":{"type":"string","enum":["quantity","price","fx"]},"description":"Substitution order of the factors; each at most once. Default [quantity, price, fx]."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217 alphabetic code, upper case."},"exponent":{"type":"integer","minimum":0,"maximum":8},"rounding":{"type":"string","enum":["half-up","half-down","half-even","up","down","ceiling","floor"],"description":"Default half-even. half-up: ties away from zero. half-down: ties toward zero. half-even: ties to the even neighbour. up: away from zero. down: toward zero. ceiling: toward +infinity. floor: toward -infinity."},"statedBeforeTotal":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Optional stated total of `before` (reporting currency) to verify."},"statedAfterTotal":{"type":"string","pattern":"^-?\\d{1,15}(\\.\\d{1,12})?$","maxLength":30,"description":"Optional stated total of `after` to verify."}}},"example":{"currency":"USD","before":[{"key":"widget","quantity":"100","unitPrice":"2.00"},{"key":"gadget","quantity":"10","unitPrice":"9.99"}],"after":[{"key":"widget","quantity":"120","unitPrice":"2.10"},{"key":"gizmo","quantity":"5","unitPrice":"4.00"}],"statedBeforeTotal":"299.90","statedAfterTotal":"272.00"}}}},"responses":{"200":{"description":"Paid result with provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"order":{"type":"array","items":{"type":"string"}},"beforeMinor":{"type":"integer"},"afterMinor":{"type":"integer"},"deltaMinor":{"type":"integer","description":"The exact change (after minus before) rounded once; equals the sum of byFactor and of byLine. It can differ by one unit from afterMinor minus beforeMinor, which round each total separately."},"byFactor":{"type":"object","properties":{"quantity":{"type":"integer"},"price":{"type":"integer"},"fx":{"type":"integer"},"added":{"type":"integer"},"removed":{"type":"integer"}},"description":"Signed minor-unit effects; they sum to deltaMinor."},"byLine":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"kind":{"type":"string","enum":["changed","added","removed","unchanged"]},"deltaMinor":{"type":"integer"}}}},"exponent":{"type":"integer"},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]}}}},"400":{"description":"Invalid request (no payment consumed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Invalid X-API-KEY","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Payment required or invalid","content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"code":{"type":"string"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}},"extensions":{"type":"object"}}}}}},"502":{"description":"Upstream failure; the payment is released or not settled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}},"links":{"docs":"https://agents.writerslogic.com/docs/price-change-attribution/","docsJson":"https://agents.writerslogic.com/docs/price-change-attribution.json","sample":"https://agents.writerslogic.com/api/v1/samples/price-change-attribution","openapi":"https://agents.writerslogic.com/openapi.json","catalog":"https://agents.writerslogic.com/api/v1/catalog","verifyProvenance":"https://agents.writerslogic.com/api/v1/verify-provenance","index":"https://agents.writerslogic.com/docs/index.json"}}