Small Business: Shop API
Shop API of the Sylius plugin Small Business §19 UStG: the kleinunternehmerNoticeApplies field on cart, order, product and variant for headless frontends, with rules and examples.
Small Business: Shop API
Live Demo: Try this and other plugins live — no installation, no risk: demo.markus-michalski.net
What the field is for
The storefront notice comes from Twig hooks, which a headless frontend never sees. That is why the plugin adds a boolean field kleinunternehmerNoticeApplies to the Shop API (/api/v2/shop). Your frontend uses it to decide where and in which language to show the notice, exactly where the Twig storefront would show it.
The Shop API delivers only the flag, never the notice text. You write the wording in your frontend.
graph LR
A["Storefront Twig hook"] --> C["NoticeApplicabilityChecker"]
B["Shop API request"] --> D["ShopNoticeNormalizer"]
D --> C
C --> E{"Regulation active and object without tax?"}
E --> F["Twig render: notice"]
E --> G["JSON: kleinunternehmerNoticeApplies"]
Where the field appears
The rule is the same as in the storefront. The field is true if the regulation is active and the object is actually charged without tax:
| Resource | true if |
|---|---|
| Cart and order | both tax totals of the cart or order are 0 |
| Product variant | the variant is on the tax category kleinunternehmer_zero |
| Product | it has enabled variants and all enabled variants are on kleinunternehmer_zero |
If the regulation is off or the object is not yet migrated, the field is false.
The plugin attaches the field to these Shop API serialization groups:
| Resource | Groups |
|---|---|
| Cart / order | sylius:shop:cart:show, sylius:shop:order:account:show, sylius:shop:order:index |
| Product | sylius:shop:product:index, sylius:shop:product:show |
| Product variant | sylius:shop:product_variant:index, sylius:shop:product_variant:show |
The Admin API is not affected, the field only appears in Shop API responses. The plugin brings no endpoints of its own.
Example
curl -s https://shop.example.com/api/v2/shop/products/PRODUCT-CODE \
-H "Accept: application/ld+json"
Excerpt from the response:
{
"@type": "Product",
"code": "PRODUCT-CODE",
"kleinunternehmerNoticeApplies": true
}
Also on the variant and on the cart:
curl -s https://shop.example.com/api/v2/shop/product-variants/VARIANT-CODE \
-H "Accept: application/ld+json"
curl -s https://shop.example.com/api/v2/shop/orders/TOKEN \
-H "Accept: application/ld+json"
Both responses contain "kleinunternehmerNoticeApplies": true or false. In your frontend, show the notice as soon as the flag is true, in the language of your choice.
Error format
The plugin returns no error responses of its own. The standard responses of the Sylius Shop API apply to the field.