API-Referenz-Navigation

Storefront Cart

Storefront

Storefront Cart groups 8 operations on the storefront tier.

Storefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

GET

/api/{version}/cart

Return the current visitor's cart as JSON. Returns an empty cart (200) rather than 404 when none exists yet.

AuthentifizierungAnonymStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Antworten

200StorefrontCartResponseOK

curl -X GET \
  'https://<your-shop-domain>/api/2026-04-01/cart' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>'

Antwort200Beispielstruktur

{
  "cart": {
    "currency": "string",
    "show_net_prices": true,
    "item_count": 1,
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "product_id": "00000000-0000-0000-0000-000000000000",
        "sku": "string",
        "title": "string",
        "url": "string",
        "quantity": 1,
        "price": 1,
        "net_price": 1,
        "gross_price": 1,
        "discount_percent": 1,
        "line_price": 1,
        "image": {},
        "vendor": "string",
        "grams": 1,
        "year": "string",
        "size": "string",
        "color": "string"
      }
    ],
    "items_subtotal_price": 1,
    "total_discount": 1,
    "total_price": 1,
    "total_weight": 1,
    "discount_code": "string"
  }
}

DELETE

/api/{version}/cart

Empty the cart. Idempotent; returns the now-empty cart (200).

AuthentifizierungAnonymStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Antworten

200StorefrontCartResponseOK

curl -X DELETE \
  'https://<your-shop-domain>/api/2026-04-01/cart' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>'

Antwort200Beispielstruktur

{
  "cart": {
    "currency": "string",
    "show_net_prices": true,
    "item_count": 1,
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "product_id": "00000000-0000-0000-0000-000000000000",
        "sku": "string",
        "title": "string",
        "url": "string",
        "quantity": 1,
        "price": 1,
        "net_price": 1,
        "gross_price": 1,
        "discount_percent": 1,
        "line_price": 1,
        "image": {},
        "vendor": "string",
        "grams": 1,
        "year": "string",
        "size": "string",
        "color": "string"
      }
    ],
    "items_subtotal_price": 1,
    "total_discount": 1,
    "total_price": 1,
    "total_weight": 1,
    "discount_code": "string"
  }
}

POST

/api/{version}/cart/items

{ article_id, quantity } — add a line, or increment an existing one by quantity. quantity defaults to 1 when omitted.

AuthentifizierungAnonymStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Request-Body

application/json, text/json, application/*+json · optional

StorefrontCartAddItemRequest

Body of POST /api/{version}/cart/items — add a variant to the cart. quantity is optional and defaults to 1; it is the amount to add (increment), not the resulting absolute quantity.

article_idstring (uuid)erforderlich
The article (variant) id to add.
quantitynumber (double)

Antworten

200StorefrontCartResponseOK

curl -X POST \
  'https://<your-shop-domain>/api/2026-04-01/cart/items' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "article_id": "00000000-0000-0000-0000-000000000000"
}'

Antwort200Beispielstruktur

{
  "cart": {
    "currency": "string",
    "show_net_prices": true,
    "item_count": 1,
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "product_id": "00000000-0000-0000-0000-000000000000",
        "sku": "string",
        "title": "string",
        "url": "string",
        "quantity": 1,
        "price": 1,
        "net_price": 1,
        "gross_price": 1,
        "discount_percent": 1,
        "line_price": 1,
        "image": {},
        "vendor": "string",
        "grams": 1,
        "year": "string",
        "size": "string",
        "color": "string"
      }
    ],
    "items_subtotal_price": 1,
    "total_discount": 1,
    "total_price": 1,
    "total_weight": 1,
    "discount_code": "string"
  }
}

PUT

/api/{version}/cart/items/{id}

{ quantity } — set a line's absolute quantity ({id} is the article/variant Guid). A quantity of 0 removes the line.

AuthentifizierungAnonymStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Pfad-Parameter

Name	Typ	Beschreibung
id erforderlich	string (uuid)

Request-Body

application/json, text/json, application/*+json · optional

StorefrontCartSetQuantityRequest

Body of PUT /api/{version}/cart/items/{id} — set a line's absolute quantity. A quantity of 0 removes the line.

quantitynumber (double)

Antworten

200StorefrontCartResponseOK

curl -X PUT \
  'https://<your-shop-domain>/api/2026-04-01/cart/items/<id>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "quantity": 0
}'

Antwort200Beispielstruktur

{
  "cart": {
    "currency": "string",
    "show_net_prices": true,
    "item_count": 1,
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "product_id": "00000000-0000-0000-0000-000000000000",
        "sku": "string",
        "title": "string",
        "url": "string",
        "quantity": 1,
        "price": 1,
        "net_price": 1,
        "gross_price": 1,
        "discount_percent": 1,
        "line_price": 1,
        "image": {},
        "vendor": "string",
        "grams": 1,
        "year": "string",
        "size": "string",
        "color": "string"
      }
    ],
    "items_subtotal_price": 1,
    "total_discount": 1,
    "total_price": 1,
    "total_weight": 1,
    "discount_code": "string"
  }
}

DELETE

/api/{version}/cart/items/{id}

Remove a line entirely ({id} is the article/variant Guid). Returns the updated cart (200); idempotent for a line not in the cart.

AuthentifizierungAnonymStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Pfad-Parameter

Name	Typ	Beschreibung
id erforderlich	string (uuid)

Antworten

200StorefrontCartResponseOK

curl -X DELETE \
  'https://<your-shop-domain>/api/2026-04-01/cart/items/<id>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>'

Antwort200Beispielstruktur

{
  "cart": {
    "currency": "string",
    "show_net_prices": true,
    "item_count": 1,
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "product_id": "00000000-0000-0000-0000-000000000000",
        "sku": "string",
        "title": "string",
        "url": "string",
        "quantity": 1,
        "price": 1,
        "net_price": 1,
        "gross_price": 1,
        "discount_percent": 1,
        "line_price": 1,
        "image": {},
        "vendor": "string",
        "grams": 1,
        "year": "string",
        "size": "string",
        "color": "string"
      }
    ],
    "items_subtotal_price": 1,
    "total_discount": 1,
    "total_price": 1,
    "total_weight": 1,
    "discount_code": "string"
  }
}

PUT

/api/{version}/cart/currency

{ currency_id } or { code } — re-price the cart into another currency. Both forms come from GET /currencies. Returns the re-priced cart, or 422 when the tenant publishes no such currency.

AuthentifizierungAnonymStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Request-Body

application/json, text/json, application/*+json · optional

StorefrontCartCurrencyRequest

Body of PUT /api/{version}/cart/currency — re-price the cart into another tenant currency. Name the target either by currency_id or by ISO code; both come from GET /currencies, and at least one is required. When both are sent the id wins.

currency_idstring (uuid)nullable
The currency's id, as emitted by GET /currencies.
codestringnullable
ISO 4217 code, e.g. "CHF". Case-insensitive. Alternative to currency_id.

Antworten

200StorefrontCartResponseOK
422ApiErrorResponseUnprocessable Content

curl -X PUT \
  'https://<your-shop-domain>/api/2026-04-01/cart/currency' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "currency_id": "00000000-0000-0000-0000-000000000000",
  "code": "string"
}'

Antwort200Beispielstruktur

{
  "cart": {
    "currency": "string",
    "show_net_prices": true,
    "item_count": 1,
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "product_id": "00000000-0000-0000-0000-000000000000",
        "sku": "string",
        "title": "string",
        "url": "string",
        "quantity": 1,
        "price": 1,
        "net_price": 1,
        "gross_price": 1,
        "discount_percent": 1,
        "line_price": 1,
        "image": {},
        "vendor": "string",
        "grams": 1,
        "year": "string",
        "size": "string",
        "color": "string"
      }
    ],
    "items_subtotal_price": 1,
    "total_discount": 1,
    "total_price": 1,
    "total_weight": 1,
    "discount_code": "string"
  }
}

POST

/api/{version}/cart/discount_code

{ code } — apply a coupon to the cart. Returns the re-priced cart with discount_code and total_discount set, or 422 with a machine-readable code naming why the coupon was refused.

AuthentifizierungAnonymStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Request-Body

application/json, text/json, application/*+json · optional

StorefrontCartDiscountCodeRequest

Body of POST /api/{version}/cart/discount_code — apply a coupon to the cart.

codestringerforderlich
The coupon code as the shopper typed it. Matched exactly, as the MVC checkout matches it.

Antworten

200StorefrontCartResponseOK
422ApiErrorResponseUnprocessable Content

curl -X POST \
  'https://<your-shop-domain>/api/2026-04-01/cart/discount_code' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "string"
}'

Antwort200Beispielstruktur

{
  "cart": {
    "currency": "string",
    "show_net_prices": true,
    "item_count": 1,
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "product_id": "00000000-0000-0000-0000-000000000000",
        "sku": "string",
        "title": "string",
        "url": "string",
        "quantity": 1,
        "price": 1,
        "net_price": 1,
        "gross_price": 1,
        "discount_percent": 1,
        "line_price": 1,
        "image": {},
        "vendor": "string",
        "grams": 1,
        "year": "string",
        "size": "string",
        "color": "string"
      }
    ],
    "items_subtotal_price": 1,
    "total_discount": 1,
    "total_price": 1,
    "total_weight": 1,
    "discount_code": "string"
  }
}

DELETE

/api/{version}/cart/discount_code

Clear the applied coupon. Idempotent; returns the re-priced cart (200) whether or not one was applied.

AuthentifizierungAnonymStorefront tier. Reachable anonymously; a public vnstss_ token may be sent to identify the storefront.

Antworten

200StorefrontCartResponseOK

curl -X DELETE \
  'https://<your-shop-domain>/api/2026-04-01/cart/discount_code' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>'

Antwort200Beispielstruktur

{
  "cart": {
    "currency": "string",
    "show_net_prices": true,
    "item_count": 1,
    "items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "product_id": "00000000-0000-0000-0000-000000000000",
        "sku": "string",
        "title": "string",
        "url": "string",
        "quantity": 1,
        "price": 1,
        "net_price": 1,
        "gross_price": 1,
        "discount_percent": 1,
        "line_price": 1,
        "image": {},
        "vendor": "string",
        "grams": 1,
        "year": "string",
        "size": "string",
        "color": "string"
      }
    ],
    "items_subtotal_price": 1,
    "total_discount": 1,
    "total_price": 1,
    "total_weight": 1,
    "discount_code": "string"
  }
}

Schemas

ApiErrorResponse

The error envelope every non-2xx response from this API uses. Documentation shape: actions build it as an anonymous object, so this type exists to give the OpenAPI document a schema to point at.

errorsstringnullable
Human-readable description of what went wrong, e.g. Not Found, Invalid page_info.
codestringnullable
Machine-readable error code. Only a few endpoints (checkout) emit one; omitted everywhere else.

StorefrontCartAddItemRequest

Body of POST /api/{version}/cart/items — add a variant to the cart. quantity is optional and defaults to 1; it is the amount to add (increment), not the resulting absolute quantity.

article_idstring (uuid)erforderlich
The article (variant) id to add.
quantitynumber (double)

StorefrontCartCurrencyRequest

currency_idstring (uuid)nullable
The currency's id, as emitted by GET /currencies.
codestringnullable
ISO 4217 code, e.g. "CHF". Case-insensitive. Alternative to currency_id.

StorefrontCartDiscountCodeRequest

Body of POST /api/{version}/cart/discount_code — apply a coupon to the cart.

codestringerforderlich
The coupon code as the shopper typed it. Matched exactly, as the MVC checkout matches it.

StorefrontCartDto

Storefront representation of the cart. Money is a decimal value in currency, quantities are decimal, and show_net_prices tells the client whether the price/total figures are tax-exclusive.

currencystringnullable
show_net_pricesboolean
When true, every price/total below is net (tax-exclusive); otherwise gross.
item_countinteger (int32)
itemsStorefrontCartLineDto[]nullable
items_subtotal_pricenumber (double)
Sum of line totals before the cart-level discount.
total_discountnumber (double)
total_pricenumber (double)
Payable total — subtotal minus the cart discount.
total_weightnumber (double)
discount_codestringnullable
Applied coupon code, or null when none.

StorefrontCartLineDto

Versioned (2026-04-01) storefront representation of a cart line. id is the article (variant) id — the same id used to address the line in PUT/DELETE /cart/items/{id}. price is the unit price and line_price the line total, both following the cart's show_net_prices rule; net_price/gross_price expose both unit figures unambiguously.

idstring (uuid)
product_idstring (uuid)
skustringnullable
titlestringnullable
urlstringnullable
quantitynumber (double)
pricenumber (double)
Unit price following the cart's net/gross display rule.
net_pricenumber (double)
gross_pricenumber (double)
discount_percentnumber (double)
line_pricenumber (double)
Line total after the line discount, following the cart's net/gross display rule.
imageStorefrontImageDto
vendorstringnullable
gramsnumber (double)
yearstringnullable
sizestringnullable
colorstringnullable

StorefrontCartResponse

Envelope returned by every action on /cart — GET /cart, POST /cart/items, PUT /cart/items/{id}, DELETE /cart/items/{id}, DELETE /cart and PUT /cart/currency. Every one of them answers with the full cart after the change, not a delta and not just the touched line, so a client never needs a follow-up GET to refresh a mini-cart. The cart itself is resolved from the request identity (shopper claim or the anonymous cookie) — there is no cart id in any route, and a visitor with no cart yet gets an empty one with 200 rather than a 404.

cartStorefrontCartDto

StorefrontCartSetQuantityRequest

Body of PUT /api/{version}/cart/items/{id} — set a line's absolute quantity. A quantity of 0 removes the line.

quantitynumber (double)

StorefrontImageDto

Storefront representation of a product image. An image is an object (id, src, alt, position, width, height) rather than a bare URL, so clients get the gallery order, accessibility text, and intrinsic dimensions.

idstring (uuid)
srcstringnullable
preview_srcstringnullable
altstringnullable
positioninteger (int32)
widthinteger (int32)
heightinteger (int32)