Purchase offers

A Purchase offer records the cost price of a Variant from a Supplier, for a given Country and validity period. Like a Sale offer it carries a taxExcludedPrice and a Tax reference, but it is the buying side: where a sale offer is what a customer pays, a purchase offer is what you pay your supplier.

Purchase offers feed cost and margin reporting, and let you track price changes from a supplier over time through their startsAt / endsAt windows.

The Purchase offer object

Property	Type	Required	Description
country	string | Country | null	required	The country resource it belongs to. Requires the instance_params:read scope. Returned null when the scope is missing.
createdAt	string	-	The date and time when the resource was created (ISO 8601 format).
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.
endsAt	string | null	-	End date of the offer.
id	string	-	The unique identifier of the purchase offer.
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.
startsAt	string	-	Start date of the offer. Defaults to the current date/time if not provided.
status	"/api/statuses/DRAFT" | "/api/statuses/ACTIVE" | "/api/statuses/ARCHIVED"	-	The status of the offer.
supplier	string | Supplier | null	required	The supplier resource it belongs to. Requires the suppliers:read scope. Returned null when the scope is missing.
tax	string | Tax | null	required	The tax resource it belongs to. Requires the instance_params:read scope. Returned null when the scope is missing.
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.
updatedAt	string	-	The date and time when the resource was last modified (ISO 8601 format).
variant	string | Product.Variant | null	required	The variant resource it belongs to. Requires the products:read scope. Returned null when the scope is missing.

Common workflows

• Record a supplier cost. Create a purchase offer for a variant with a supplier, country, tax, taxExcludedPrice and status.
• Track a cost change. Close the current offer with an endsAt and create a new one with the updated price.
• Compare suppliers. Keep concurrent offers from different suppliers for the same variant.

Conventions

All requests require an OAuth 2.0 bearer token:

Authorization: Bearer <token>

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