Sale offers

A Sale offer is the selling price of a Variant for buyers in a given Country, over a validity period, optionally scoped to specific Channels. It carries the tax-excluded price and a Tax reference, from which the tax-included price is computed.

Sale offers are what the API reads to produce a variant’s resolvedPrice: when you pass resolveContext[channel], resolveContext[country] and resolveContext[at] on a variant read, the matching sale offer (right country, channel and date) determines the price a buyer would see.

The Sale offer object

Property	Type	Required	Description
id	string	-	The unique identifier of the sale offer.
status	string	-	The status of the offer.
taxExcludedPrice	EmbeddedMoneyResource	required	The price set for the offer, excluding tax.
Show taxExcludedPrice fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR).
taxExcludedPricePerUnit	EmbeddedPricePerUnitResource | null	-	The tax-excluded price expressed per measurement reference unit.
Show taxExcludedPricePerUnit fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR). unit "ml" | "cl" | "l" | "mg" | "g" | "kg" | "mm" | "cm" | "m" | "m2" | "unit" required The reference unit the amount is expressed per. value integer required The number of reference units the amount applies to.
price	EmbeddedMoneyResource	-	The tax-included price, computed from taxExcludedPrice and the referenced Tax rate.
Show price fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR).
pricePerUnit	EmbeddedPricePerUnitResource | null	-	The tax-included price expressed per measurement reference unit.
Show pricePerUnit fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR). unit "ml" | "cl" | "l" | "mg" | "g" | "kg" | "mm" | "cm" | "m" | "m2" | "unit" required The reference unit the amount is expressed per. value integer required The number of reference units the amount applies to.
discountPrice	EmbeddedMoneyResource | null	-	The discounted tax-included price, when a discount applies.
Show discountPrice fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR).
discountPricePerUnit	EmbeddedPricePerUnitResource | null	-	The discounted tax-included price per measurement reference unit, when a discount applies.
Show discountPricePerUnit fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR). unit "ml" | "cl" | "l" | "mg" | "g" | "kg" | "mm" | "cm" | "m" | "m2" | "unit" required The reference unit the amount is expressed per. value integer required The number of reference units the amount applies to.
discountTaxExcludedPrice	EmbeddedMoneyResource | null	-	The discounted tax-excluded price, when a discount applies.
Show discountTaxExcludedPrice fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR).
discountTaxExcludedPricePerUnit	EmbeddedPricePerUnitResource | null	-	The discounted tax-excluded price per measurement reference unit, when a discount applies.
Show discountTaxExcludedPricePerUnit fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR). unit "ml" | "cl" | "l" | "mg" | "g" | "kg" | "mm" | "cm" | "m" | "m2" | "unit" required The reference unit the amount is expressed per. value integer required The number of reference units the amount applies to.
startsAt	string	-	Start date of the offer. Defaults to the current date/time if not provided.
endsAt	string | null	-	End date of the offer.
country	string	required	The country resource it belongs to.
tax	string	required	The tax resource it belongs to.
variant	string	required	The variant resource it belongs to.
channels	string[]	-	A list of Channel IRIs the sale offer is distributed through.
createdAt	string	-	The date and time when the resource was created (ISO 8601 format).
updatedAt	string	-	The date and time when the resource was last modified (ISO 8601 format).

How pricing resolves

• A variant can have several sale offers - one per country, channel set, or time window.
• startsAt / endsAt bound when an offer applies. Leave endsAt open for an ongoing price.
• discountTaxExcludedPrice (optional) sets a promotional price for the period.
• On read, resolveContext selects the applicable offer and exposes the computed price, discountPrice and per-unit values.

Common workflows

• Set a price. Create a sale offer for a variant with a country, tax, taxExcludedPrice and startsAt.
• Run a promotion. Add an offer with a discountTaxExcludedPrice and an endsAt, then let it expire.
• Price per channel. Attach channels to an offer so it only applies on those sales surfaces.

Conventions

All requests require an OAuth 2.0 bearer token and the organization scope header:

Authorization: Bearer <token>
X-Flowkiwi-Organization-Id: <organization-id>

PATCH uses JSON Merge Patch with Content-Type: application/merge-patch+json.