Variant Price Surcharge: Shop API and Headless

Variant Price Surcharge in the Sylius Shop API: no endpoints of its own, but calculated prices in a variant's price and originalPrice and in cart items, plus the limits around lowestPriceBeforeDiscount.

Deutsche Version

Back to overview

Variant Price Surcharge: Shop API and Headless

The plugin is dual-mode: storefront and Shop API return the same price because both go through the Sylius price calculators that the plugin decorates (from Sylius 2.3 also the catalog price calculator, see Storefront and Cart). You do not need to configure anything for headless use.

The plugin registers no API endpoints, no API resources and no serializers of its own.

graph LR
    A["Storefront (Twig)"] --> C["Price calculator (decorator)"]
    B["Shop API"] --> C
    C --> D["Base variant price"]
    D --> E["Price with surcharge"]

Which fields change

Field	Behaviour
`price` of a product variant	Price with surcharge in the smallest currency unit
`originalPrice` of a product variant	Calculated with the same formula from the base variant's original price
`lowestPriceBeforeDiscount` of a product variant	Unchanged, the variant's own value
`appliedPromotions` of a product variant	Lists the catalog promotions of the variant itself, not those of the base variant
Cart item prices	Include the surcharge, because Sylius sets them from the calculator on every cart recalculation

The price fields only appear when the channel is known. If the variant or the base variant has no price in the channel, Sylius omits price, originalPrice and lowestPriceBeforeDiscount from the response.

Which surcharge applies depends on the channel of the request: if the channel has its own setting, the API uses it, otherwise the global values.

Example

Base variant with price 2000, variant with a percentage of 150 and a fixed surcharge of 0:

{
  "code": "TSHIRT_XL",
  "price": 3000,
  "originalPrice": 3000
}

The response shows only the affected fields, the rest of the variant document follows the Sylius default.

Notes for frontends

Use the variant's price and originalPrice. Recalculating in the frontend is not needed and error-prone.
The plugin exposes no configuration through the API. You maintain surcharges only in the admin.
When the global switch is off, the API returns the stored channel prices again.