How should an API distinguish a calculated value from a manual override?

Use separate fields for intent and result. The safest contract is: store the user’s manual override explicitly, expose the system-calculated value separately, and return a distinct effective value that the application actually uses. Add an explicit way to clear the override and return to automatic mode. Do not let clients write the same field that the server recalculates, or a normal update can accidentally freeze a derived value.

What contract should the API expose?

For HTTP APIs, treat the calculated value as server-owned output and the override as client-owned input. That matches the guidance in Google AIP-203 field behavior documentation, which says OUTPUT_ONLY is appropriate for “Derived or structured information based on original user input” and that documented field behavior helps clients understand what they can send. It also fits the purpose of the OpenAPI Specification: a description should let consumers “discover and understand the capabilities of a service” without guesswork.

A practical resource shape looks like this:

• calculated_price: output only, recomputed by the server
• price_override: optional nullable input, set only when a human wants to pin a value
• effective_price: output only, equal to price_override when present, otherwise calculated_price
• price_source: output only enum such as CALCULATED or MANUAL_OVERRIDE

That makes ownership obvious. Clients never wonder whether writing price will be preserved, recalculated, or silently converted into a manual override.

How does reset-to-automatic mode work?

Make reset explicit. The cleanest rule is: price_override = null means “remove the manual override and resume calculation.” If you use PATCH semantics, the boundary is the single resource write processed by the service: evaluate the stored override state after applying the patch, then recompute effective_price for that resource before returning it. That is the ordering guarantee you want. Avoid advice that depends on a separate read, client-side comparison, and later write.

Worked example:

1. Product base inputs change, and the server computes calculated_price = 1200.
2. A merchandiser sets price_override = 999.
3. The API returns effective_price = 999 and price_source = MANUAL_OVERRIDE.
4. Later, cost inputs change again. The server may recompute calculated_price = 1100, but effective_price stays 999.
5. The merchandiser clears price_override.
6. The API returns effective_price = 1100 and price_source = CALCULATED.

This prevents the classic failure mode where a user edits some unrelated field and accidentally persists yesterday’s derived number as if it were authoritative.

When does this pattern apply, and when does it not?

Use this contract when the derived value belongs to server-side business rules, but a human may temporarily supersede it. Pricing, fulfillment dates, risk scores, shipping promises, and inventory buffers fit well.

Do not use it when the value is purely client-local presentation data, or when the “override” is really a different upstream input to the formula. In that case, model the underlying input instead of adding an override layer.

Also avoid a single writable mode field unless the mode has independent business meaning. In many APIs, the presence or absence of price_override already encodes the state with less room for contradiction.

What should the API documentation make unambiguous?

Document three things directly in the schema:

• which fields are writable versus output only
• what clearing the override means
• when recalculation happens relative to the resource write

In OpenAPI, reflect the split clearly in request and response schemas so SDK and docs do not imply that derived fields are normal inputs.

Follow-up: Should I expose both effective_price and calculated_price?

Yes, if operators need to see what the system would choose automatically. Keep both when auditability or UI explainability matters.

Follow-up: Should a manual override expire automatically?

Only if expiry is a business rule users can understand. If you add it, model it explicitly with fields such as an override timestamp or expiration time, not hidden recalculation behavior.

Next step: pick one resource with an overridable derived field and rewrite its schema so override intent, calculated output, and reset behavior are separate and testable.

Reviewed: 2026-09-05.