API-Referenz-Navigation

Customers

Admin

Customers groups 5 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/customers

One cursored page of customers. 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.

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

Query-Parameter

Name	Typ	Beschreibung
limit optional	integer (int32)

Antworten

200CustomerListResponseOK
422ApiErrorResponseUnprocessable Content

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

Antwort200Beispielstruktur

{
  "customers": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "email": "string",
      "is_active": true,
      "is_email_confirmed": true,
      "type": "string",
      "currency_id": "00000000-0000-0000-0000-000000000000",
      "default_address": {
        "id": "00000000-0000-0000-0000-000000000000",
        "first_name": "string",
        "last_name": "string",
        "company": "string",
        "department": "string",
        "street": "string",
        "zip_code": "string",
        "location": "string",
        "country_id": "00000000-0000-0000-0000-000000000000",
        "phone_number": "string",
        "mobile_number": "string",
        "fax_number": "string",
        "email": "string",
        "website": "string",
        "title_id": "00000000-0000-0000-0000-000000000000"
      },
      "created_at": "2026-04-01T12:00:00Z",
      "updated_at": "2026-04-01T12:00:00Z"
    }
  ]
}

POST

/api/{version}/admin/customers

Creates a customer and returns it as stored. A missing body, a duplicate email and a rejected field all surface as 422.

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

Request-Body

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

CreateCustomerRequest

Body for POST /api/{version}/admin/customers. email is required; type defaults to customer.

emailstringnullable
is_activeboolean
is_email_confirmedboolean
typestringnullable
currency_idstring (uuid)nullable

Antworten

201CustomerResponseCreated
422ApiErrorResponseUnprocessable Content

curl -X POST \
  'https://<your-shop-domain>/api/2026-04-01/admin/customers' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstat_<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "string",
  "is_active": true,
  "is_email_confirmed": true,
  "type": "string",
  "currency_id": "00000000-0000-0000-0000-000000000000"
}'

Antwort201Beispielstruktur

{
  "customer": {
    "id": "00000000-0000-0000-0000-000000000000",
    "email": "string",
    "is_active": true,
    "is_email_confirmed": true,
    "type": "string",
    "currency_id": "00000000-0000-0000-0000-000000000000",
    "default_address": {
      "id": "00000000-0000-0000-0000-000000000000",
      "first_name": "string",
      "last_name": "string",
      "company": "string",
      "department": "string",
      "street": "string",
      "zip_code": "string",
      "location": "string",
      "country_id": "00000000-0000-0000-0000-000000000000",
      "phone_number": "string",
      "mobile_number": "string",
      "fax_number": "string",
      "email": "string",
      "website": "string",
      "title_id": "00000000-0000-0000-0000-000000000000"
    },
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
}

GET

/api/{version}/admin/customers/{id}

One customer.

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

Pfad-Parameter

Name	Typ	Beschreibung
id erforderlich	string (uuid)

Antworten

200CustomerResponseOK
404ApiErrorResponseNot Found

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

Antwort200Beispielstruktur

{
  "customer": {
    "id": "00000000-0000-0000-0000-000000000000",
    "email": "string",
    "is_active": true,
    "is_email_confirmed": true,
    "type": "string",
    "currency_id": "00000000-0000-0000-0000-000000000000",
    "default_address": {
      "id": "00000000-0000-0000-0000-000000000000",
      "first_name": "string",
      "last_name": "string",
      "company": "string",
      "department": "string",
      "street": "string",
      "zip_code": "string",
      "location": "string",
      "country_id": "00000000-0000-0000-0000-000000000000",
      "phone_number": "string",
      "mobile_number": "string",
      "fax_number": "string",
      "email": "string",
      "website": "string",
      "title_id": "00000000-0000-0000-0000-000000000000"
    },
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
}

PUT

/api/{version}/admin/customers/{id}

Applies the supplied fields and returns the customer as stored.

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

Pfad-Parameter

Name	Typ	Beschreibung
id erforderlich	string (uuid)

Request-Body

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

UpdateCustomerRequest

Body for PUT /api/{version}/admin/customers/{id}. Every field is optional; only the supplied ones are applied.

emailstringnullable
is_activebooleannullable
is_email_confirmedbooleannullable
typestringnullable
currency_idstring (uuid)nullable

Antworten

200CustomerResponseOK
404ApiErrorResponseNot Found
422ApiErrorResponseUnprocessable Content

curl -X PUT \
  'https://<your-shop-domain>/api/2026-04-01/admin/customers/<id>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstat_<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "string",
  "is_active": true,
  "is_email_confirmed": true,
  "type": "string",
  "currency_id": "00000000-0000-0000-0000-000000000000"
}'

Antwort200Beispielstruktur

{
  "customer": {
    "id": "00000000-0000-0000-0000-000000000000",
    "email": "string",
    "is_active": true,
    "is_email_confirmed": true,
    "type": "string",
    "currency_id": "00000000-0000-0000-0000-000000000000",
    "default_address": {
      "id": "00000000-0000-0000-0000-000000000000",
      "first_name": "string",
      "last_name": "string",
      "company": "string",
      "department": "string",
      "street": "string",
      "zip_code": "string",
      "location": "string",
      "country_id": "00000000-0000-0000-0000-000000000000",
      "phone_number": "string",
      "mobile_number": "string",
      "fax_number": "string",
      "email": "string",
      "website": "string",
      "title_id": "00000000-0000-0000-0000-000000000000"
    },
    "created_at": "2026-04-01T12:00:00Z",
    "updated_at": "2026-04-01T12:00:00Z"
  }
}

DELETE

/api/{version}/admin/customers/{id}

Deletes the customer. Returns 204 with no body; deleting an already-deleted customer is a 404, not a no-op success.

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

Pfad-Parameter

Name	Typ	Beschreibung
id erforderlich	string (uuid)

Antworten

204No Content
404ApiErrorResponseNot Found

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

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.

CreateCustomerRequest

Body for POST /api/{version}/admin/customers. email is required; type defaults to customer.

emailstringnullable
is_activeboolean
is_email_confirmedboolean
typestringnullable
currency_idstring (uuid)nullable

CustomerDefaultAddressDto

The customer's primary billing address, as it appears under default_address on the admin Cloudwawi.Shop.Api.V2026_04_01.CustomerDto. The field set mirrors the shopper-facing customers/me address shape, but this is deliberately a separate type from the customer tier's CustomerAddressDto: the two tiers version independently, and a shared type would also collide on its OpenAPI schema id, which is derived from the unqualified type name.

idstring (uuid)
first_namestringnullable
last_namestringnullable
companystringnullable
departmentstringnullable
streetstringnullable
zip_codestringnullable
locationstringnullable
country_idstring (uuid)nullable
phone_numberstringnullable
mobile_numberstringnullable
fax_numberstringnullable
emailstringnullable
websitestringnullable
title_idstring (uuid)nullable

CustomerDto

Admin representation of a customer (the customers resource, backed by the existing ShopUser domain — api-design.md §17.4). Serialized snake_case via explicit [JsonPropertyName] attributes, because the host's global JSON policy is camelCase.

idstring (uuid)
emailstringnullable
is_activeboolean
Whether the customer account is enabled.
is_email_confirmedboolean
Whether the customer has confirmed their email address.
typestringnullable
Customer kind: customer, corporate, or reseller.
currency_idstring (uuid)nullable
Preferred currency; null when the customer follows the shop default.
default_addressCustomerDefaultAddressDto
created_atstring (date-time)
updated_atstring (date-time)nullable

CustomerListResponse

Envelope returned by GET /admin/customers. One page of customers. 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.

customersCustomerDto[]nullable
The page of customers. Always present; an empty array when the tenant has none. This is the admin view — it is not restricted to the customers of the calling shopper, which is what customers/me returns.

CustomerResponse

Envelope returned by GET /admin/customers/{id}, POST /admin/customers (201) and PUT /admin/customers/{id}.

customerCustomerDto

UpdateCustomerRequest

Body for PUT /api/{version}/admin/customers/{id}. Every field is optional; only the supplied ones are applied.

emailstringnullable
is_activebooleannullable
is_email_confirmedbooleannullable
typestringnullable
currency_idstring (uuid)nullable