API reference navigation

Checkouts

Admin

Checkouts groups 3 operations on the admin tier.

Admin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

GET

/api/{version}/admin/checkouts

One cursored page of checkout summaries. Follow the Link: rel="next" header for the next page; a page_info that was not issued for this exact query string is rejected with 422. The rows are summaries, not full checkouts.

AuthenticationToken requiredAdmin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

Query parameters

Name	Type	Description
limit optional	integer (int32)

Responses

200CheckoutListResponseOK
422ApiErrorResponseUnprocessable Content

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

Response200example shape

{
  "checkouts": [
    {
      "token": "00000000-0000-0000-0000-000000000000",
      "email": "string",
      "currency_code": "string",
      "status": "string",
      "total": 1,
      "line_items_count": 1,
      "created_at": "2026-04-01T12:00:00Z",
      "updated_at": "2026-04-01T12:00:00Z"
    }
  ]
}

GET

/api/{version}/admin/checkouts/{token}

One full checkout, addressed by its token (the token a list row carries), not by an id.

AuthenticationToken requiredAdmin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

Path parameters

Name	Type	Description
token required	string (uuid)

Responses

200CheckoutResponseOK
404ApiErrorResponseNot Found

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

Response200example shape

{
  "checkout": {
    "token": "00000000-0000-0000-0000-000000000000",
    "email": "string",
    "currency_code": "string",
    "status": "string",
    "is_completed": true,
    "note": "string",
    "customer_name": "string",
    "line_items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "article_id": "00000000-0000-0000-0000-000000000000",
        "title": "string",
        "sku": "string",
        "quantity": 1,
        "unit_price": 1,
        "unit_price_with_tax": 1,
        "line_total": 1,
        "line_total_with_tax": 1,
        "image_url": "string"
      }
    ],
    "totals": {
      "subtotal": 1,
      "tax_amount": 1,
      "shipping_amount": 1,
      "discount": 1,
      "total": 1,
      "currency_code": "string",
      "price_includes_tax": true
    },
    "shipping_address": {
      "id": "00000000-0000-0000-0000-000000000000",
      "first_name": "string",
      "last_name": "string",
      "company": "string",
      "department": "string",
      "street": "string",
      "po_box": "string",
      "zip_code": "string",
      "location": "string",
      "email": "string",
      "phone_number": "string",
      "mobile_number": "string",
      "country_code": "string",
      "country_name": "string"
    },
    "billing_address": {
      "id": "00000000-0000-0000-0000-000000000000",
      "first_name": "string",
      "last_name": "string",
      "company": "string",
      "department": "string",
      "street": "string",
      "po_box": "string",
      "zip_code": "string",
      "location": "string",
      "email": "string",
      "phone_number": "string",
      "mobile_number": "string",
      "country_code": "string",
      "country_name": "string"
    },
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
}

PUT

/api/{version}/admin/checkouts/{token}

Updates the internal note and the contact email; nothing else on a checkout is admin-editable. A checkout that has already been completed is a 409, not a 422 — the request was well-formed, the resource just cannot take it.

AuthenticationToken requiredAdmin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

Path parameters

Name	Type	Description
token required	string (uuid)

Request body

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

UpdateCheckoutRequest

Body for PUT /api/{version}/admin/checkouts/{token}. The admin edit scope is conservative: only the internal note and the contact email may be changed. Both are optional; only the supplied fields are applied.

notestringnullable
emailstringnullable

Responses

200CheckoutResponseOK
404ApiErrorResponseNot Found
409ApiErrorResponseConflict
422ApiErrorResponseUnprocessable Content

curl -X PUT \
  'https://<your-shop-domain>/api/2026-04-01/admin/checkouts/<token>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstat_<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "note": "string",
  "email": "string"
}'

Response200example shape

{
  "checkout": {
    "token": "00000000-0000-0000-0000-000000000000",
    "email": "string",
    "currency_code": "string",
    "status": "string",
    "is_completed": true,
    "note": "string",
    "customer_name": "string",
    "line_items": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "article_id": "00000000-0000-0000-0000-000000000000",
        "title": "string",
        "sku": "string",
        "quantity": 1,
        "unit_price": 1,
        "unit_price_with_tax": 1,
        "line_total": 1,
        "line_total_with_tax": 1,
        "image_url": "string"
      }
    ],
    "totals": {
      "subtotal": 1,
      "tax_amount": 1,
      "shipping_amount": 1,
      "discount": 1,
      "total": 1,
      "currency_code": "string",
      "price_includes_tax": true
    },
    "shipping_address": {
      "id": "00000000-0000-0000-0000-000000000000",
      "first_name": "string",
      "last_name": "string",
      "company": "string",
      "department": "string",
      "street": "string",
      "po_box": "string",
      "zip_code": "string",
      "location": "string",
      "email": "string",
      "phone_number": "string",
      "mobile_number": "string",
      "country_code": "string",
      "country_name": "string"
    },
    "billing_address": {
      "id": "00000000-0000-0000-0000-000000000000",
      "first_name": "string",
      "last_name": "string",
      "company": "string",
      "department": "string",
      "street": "string",
      "po_box": "string",
      "zip_code": "string",
      "location": "string",
      "email": "string",
      "phone_number": "string",
      "mobile_number": "string",
      "country_code": "string",
      "country_name": "string"
    },
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
}

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.

CheckoutAddressDto

An address on the admin checkout. Country is conveyed by code (and a localized name).

idstring (uuid)nullable
first_namestringnullable
last_namestringnullable
companystringnullable
departmentstringnullable
streetstringnullable
po_boxstringnullable
zip_codestringnullable
locationstringnullable
emailstringnullable
phone_numberstringnullable
mobile_numberstringnullable
country_codestringnullable
country_namestringnullable

CheckoutDto

Admin representation of a checkout (the checkouts resource, backed by the existing OrderConfirmation domain). Admins view and edit abandoned / in-progress checkouts; this is the full projection returned by the get and update endpoints. Serialized snake_case via explicit [JsonPropertyName] attributes, because the host's global JSON policy is camelCase.

tokenstring (uuid)
Opaque checkout token (the order-confirmation id).
emailstringnullable
Contact email (read from the primary address item).
currency_codestringnullable
statusstringnullable
Lifecycle status, e.g. Cart, Checkout, PaymentPending, Completed.
is_completedboolean
Whether the checkout has been completed (status is Completed).
notestringnullable
Internal note on the checkout (the order-confirmation comments).
customer_namestringnullable
Display name of the customer/client on the checkout.
line_itemsCheckoutLineDto[]nullable
totalsCheckoutTotalsDto
shipping_addressCheckoutAddressDto
billing_addressCheckoutAddressDto
created_atstring (date-time)
updated_atstring (date-time)nullable

CheckoutLineDto

A single checkout line item.

idstring (uuid)
Order-line id.
article_idstring (uuid)nullable
titlestringnullable
skustringnullable
quantitynumber (double)
unit_pricenumber (double)
unit_price_with_taxnumber (double)
line_totalnumber (double)
line_total_with_taxnumber (double)
image_urlstringnullable

CheckoutListResponse

Envelope returned by GET /admin/checkouts. One page of checkouts. Paging is cursored: when more exist, the response carries a Link header of the form <https://…?limit=50&page_info=…>; rel="next". Follow that URL verbatim — the cursor embeds a fingerprint of the query that produced the page, and a request whose query string no longer matches is rejected with 422. There is no total count and no last page link.

checkoutsCheckoutSummaryDto[]nullable
The page of checkouts as Cloudwawi.Shop.Api.V2026_04_01.CheckoutSummaryDto — a different, lighter type from the Cloudwawi.Shop.Api.V2026_04_01.CheckoutDto the single read returns. It carries a total and a line_items_count instead of the line items, the totals breakdown and the addresses; read the single checkout by token for those. Always present; an empty array when nothing matches.

CheckoutResponse

Envelope returned by GET /admin/checkouts/{token} and PUT /admin/checkouts/{token}.

checkoutCheckoutDto

CheckoutSummaryDto

Light list-row representation of a checkout (omits line items, totals breakdown and addresses).

tokenstring (uuid)
emailstringnullable
currency_codestringnullable
statusstringnullable
totalnumber (double)
line_items_countinteger (int32)
created_atstring (date-time)
updated_atstring (date-time)nullable

CheckoutTotalsDto

Checkout totals. All money is in currency_code.

subtotalnumber (double)
tax_amountnumber (double)
shipping_amountnumber (double)
discountnumber (double)
totalnumber (double)
currency_codestringnullable
price_includes_taxboolean

UpdateCheckoutRequest

notestringnullable
emailstringnullable