Skip to main content

Money, pricing, and tax

Money is business data, not presentation data. ARC owns the authoritative price, tax, totals, currency, and exchange-rate decisions for a tenant's documents.

Never calculate the commercial result locally​

A client may select a product, variant, UOM, partner, and quantity. It must not become the pricing authority by copying a catalog price and adding its own discount/tax formula.

The canonical pricing path can consider:

  1. the variant price ladder and quantity tier;
  2. the selected UOM and conversion factor;
  3. partner/customer context;
  4. discount schemes and promotions;
  5. the tenant's currency and available price currency;
  6. tax configuration and the document's tax method.

Use the pricing operation or the server-side document/cart operation, then persist the API's returned values. The catalog and pricing guide shows the query entry points.

Currency rules​

Every document has a currency context. Treat these as different values:

  • the document amount in its document currency;
  • the organization's base currency amount/shadow;
  • the exchange rate and its provenance;
  • the display format chosen by the organization.

Do not attach a hardcoded $, ₹, £, or other symbol to a dynamic amount. Render the currency code and amount using the user's/organization's currency policy.

A foreign-currency document must have a price available in that currency when the pricing contract requires it. Do not silently convert a base-currency price in the client and submit it as if it were a native price.

Tax is explicit​

New quotes, sales orders and invoices are tax-exclusive only: tax is calculated on top of line prices. Send taxCalculationMethod: EXCLUSIVE or omit it, which defaults to EXCLUSIVE. INCLUSIVE is refused when you create one of these documents and when you switch an existing one to it, whatever the organization's tax settings say. Only legacy documents created before this rule keep INCLUSIVE; they can be resaved without changing their method. Preserve the value returned by ARC.

When converting a taxed quote, the quote must carry a valid tax method: EXCLUSIVE, or INCLUSIVE on a legacy quote. ARC refuses an ambiguous conversion rather than risk changing the customer's tax meaning.

Document totals​

For quotes and sales orders, the input schema includes fields such as subtotal, discountAmount, taxAmount, shippingCost/shippingAmount, and totalAmount because the same DTO serves multiple clients. Those fields do not make the client the authority. The service recalculates the persisted money from the accepted line and header inputs, applies the organization's currency rules, and returns the stored totals.

Use this invariant in your integration:

persisted total = the total returned by ARC
not             = a total recalculated by the connector

Store the API's document number, currency, totals, tax breakdown, and exchange-rate metadata with your external record for reconciliation.

Price drift at quote conversion​

A quote freezes the commercial commitment. When it is converted to a sales order, ARC may re-resolve the current price to detect drift, but the accepted quote price is honored on the resulting order. Your integration should surface a drift warning or audit signal rather than silently repricing the customer.

Practical rules​

  • Use decimal-safe arithmetic in your own reporting; never use binary floating-point as the source of truth.
  • Do not infer payment due dates from a string when ARC returns a due date/document status.
  • Do not treat 0 as “unlimited credit” or “no credit” without checking the feature/configuration flags described by the operation.
  • Keep currency codes with every amount in your own database.
  • Re-read an invoice or payment after allocation rather than deriving outstanding balances locally.

Next: Catalog and pricing or quote to cash.