Skip to content
Vinosoft2026-04-01
en/de
API reference 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.

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

Responses

curl -X GET \
  'https://<your-shop-domain>/api/2026-04-01/cart' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>'
Response200example shape
{
  "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).

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

Responses

curl -X DELETE \
  'https://<your-shop-domain>/api/2026-04-01/cart' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>'
Response200example shape
{
  "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.

AuthenticationAnonymousStorefront 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)required

    The article (variant) id to add.

  • quantitynumber (double)

Responses

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"
}'
Response200example shape
{
  "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.

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

Path parameters

NameTypeDescription
id
required
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)

Responses

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
}'
Response200example shape
{
  "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.

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

Path parameters

NameTypeDescription
id
required
string (uuid)

Responses

curl -X DELETE \
  'https://<your-shop-domain>/api/2026-04-01/cart/items/<id>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>'
Response200example shape
{
  "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.

AuthenticationAnonymousStorefront 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.

Responses

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"
}'
Response200example shape
{
  "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.

AuthenticationAnonymousStorefront 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.

  • codestringrequired

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

Responses

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"
}'
Response200example shape
{
  "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.

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

Responses

curl -X DELETE \
  'https://<your-shop-domain>/api/2026-04-01/cart/discount_code' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstss_<token>'
Response200example shape
{
  "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)required

    The article (variant) id to add.

  • quantitynumber (double)

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.

StorefrontCartDiscountCodeRequest

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

  • codestringrequired

    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.

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)