{"openapi":"3.1.0","info":{"title":"OpenAPI","version":"1.0.0"},"paths":{"/api/app/oauth/access_token":{"post":{"tags":["API: OAuth 2.0 Authentication"],"responses":{"200":{"description":"Access token issued successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"token_type":{"type":"string","description":"Token type. Always `Bearer`.","example":"Bearer"},"access_token":{"type":"string","description":"JWT access token. Pass this in the `Authorization` header as `Bearer `."},"expires_in":{"type":"integer","description":"Token lifetime in seconds from the time of issuance.","example":3600}}}}}},"400":{"description":"Invalid request — missing or malformed parameters, unsupported grant type, wrong Content-Type, JSON body, query parameters, or missing/invalid scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"401":{"description":"Authentication failed — invalid client credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationException"}}}}},"summary":"Obtain an OAuth 2.0 access token","description":"Issues a Bearer access token using the **Client Credentials** grant.\nUse the returned `access_token` in the `Authorization: Bearer ` header for all subsequent API requests.\n\n#### Prerequisites — Application User Account:\nBefore calling this endpoint, the external application must be installed via `POST /api/app/application/`.\nA dedicated **Application User Account** must also be created manually in the shop administration. This account:\n- is separate from regular shop user accounts and cannot access the shop administration UI\n- serves as the identity under which all API actions are logged\n- has its `clientId` (UUID) used as `client_id` and a generated UUID `client_secret`\n\n#### Client authentication:\nInclude `client_id` and `client_secret` as form fields in the request body.\n\n#### Scope:\nThe `scope` field is **required** — omitting it or providing a value other than `all` results in a 400 error. Only `all` scope is allowed for this endpoint.\n\n#### Token lifetime:\nTokens are valid for **1 hour** (3600 seconds). After expiry, request a new token using the same credentials.\nTo verify a token is valid, call `GET /api/app/test`.\n\n#### Request format:\nContent-Type must be `application/x-www-form-urlencoded`. Example request body:\n```\ngrant_type=client_credentials&scope=all&client_id=a3f7c912-1d4b-4e6f-8c2a-3b9d0e5f7a18&client_secret=b2e4f781-3c9d-4a7e-91f5-6d2c0b8e3a14\n```","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","required":["grant_type","scope","client_id","client_secret"],"properties":{"grant_type":{"type":"string","enum":["client_credentials"],"description":"OAuth 2.0 grant type. Must be `client_credentials`.","example":"client_credentials"},"scope":{"type":"string","enum":["all"],"description":"Requested access scope. Required — omitting it or providing a value other than `all` results in a 400 error. Only `all` is allowed.","example":"all"},"client_id":{"type":"string","format":"uuid","description":"UUID of the application.","example":"a3f7c912-1d4b-4e6f-8c2a-3b9d0e5f7a18"},"client_secret":{"type":"string","format":"uuid","description":"Secret of the application.","example":"b2e4f781-3c9d-4a7e-91f5-6d2c0b8e3a14"}}},"example":{"grant_type":"client_credentials","scope":"all","client_id":"a3f7c912-1d4b-4e6f-8c2a-3b9d0e5f7a18","client_secret":"b2e4f781-3c9d-4a7e-91f5-6d2c0b8e3a14"}}}}}},"/api/app/openapi":{"get":{"tags":["API: OpenAPI Schema"],"responses":{"200":{"description":"OpenAPI schema as a JSON object."}},"summary":"Get OpenAPI schema","description":"Returns the full OpenAPI schema for this API as a JSON object.\nYou can paste the response URL directly into SwaggerUI or Redoc to explore the API interactively."}},"/api/app/test/id/{id}":{"get":{"tags":["API: Test"],"parameters":[{"name":"id","in":"path","description":"Numeric ID to echo back in the response.","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"The provided ID echoed back alongside a static test value."}},"summary":"GET test with path parameter","description":"Echoes back the provided `id` path parameter alongside a static test value."}},"/api/app/test":{"get":{"tags":["API: Test"],"responses":{"200":{"description":"Static OK response confirming the API is reachable."}},"summary":"Simple GET test","description":"Returns a static OK response to verify the API is reachable."},"post":{"tags":["API: Test"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestEntity"}}},"required":true,"description":"Test entity payload."},"responses":{"200":{"description":"The test entity with testString overridden to a static value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestEntity"}}}}},"summary":"POST test with request body","description":"Accepts a TestEntity, overrides `testString` with a static value, and returns the entity."}},"/api/app/application/webhook-log":{"get":{"tags":["Application + Webhooks"],"parameters":[{"name":"webhookType","in":"query","description":"Filter by webhook type (e.g. 'order_created'). If omitted, all types are returned.","required":false,"schema":{"type":"string"}},{"name":"dateTimeFrom","in":"query","description":"Start of the time range filter (ISO 8601 or date string). Defaults to the start of the given day if no time part is provided.","required":false,"schema":{"type":"string"}},{"name":"dateTimeTo","in":"query","description":"End of the time range filter (ISO 8601 or date string). Defaults to the end of the given day if no time part is provided.","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number (1-based). Defaults to 1. Each page contains up to 100 items.","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated list of webhook delivery log entries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pagination"}}}}},"summary":"Get paginated webhook logs","description":"Returns a paginated list of webhook delivery logs for the currently installed external application.\n\n#### Filtering:\n- Use `webhookType` to narrow results to a specific event type.\n- Use `dateTimeFrom` and `dateTimeTo` to filter by delivery time (both are optional and independent).\n - `dateTimeFrom` defaults to the **start of day** when no time part is given.\n - `dateTimeTo` defaults to the **end of day** when no time part is given.\n\n#### Pagination:\n- Each page contains up to **100 items**.\n- Use the `page` parameter to navigate (1-based, defaults to `1`).\n- Check `hasNextPage` in the response to determine if further pages exist.\n\n#### Included log levels:\n- `INFO` — successful delivery\n- `ERROR` / `CRITICAL` — failed delivery attempts"}},"/api/app/application":{"delete":{"tags":["Application + Webhooks"],"responses":{"200":{"description":"Application uninstalled successfully."}},"summary":"Uninstall an external application","description":"Permanently uninstalls the currently installed external application.\n\n- All associated webhooks are removed.\n- The application configuration cannot be recovered after deletion.\n- To reinstall, call `POST /api/app/application/` with a new configuration."},"get":{"tags":["Application + Webhooks"],"responses":{"200":{"description":"The currently installed application configuration including all registered webhooks.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Application"}}}}},"summary":"Get the currently installed external application","description":"Returns the full configuration of the currently installed external application, including all registered webhooks."},"post":{"tags":["Application + Webhooks"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Application"}}},"required":true,"description":"Application configuration to install or update, including the full list of desired webhooks."},"responses":{"200":{"description":"The installed or updated application configuration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Application"}}}},"422":{"description":"Validation error — e.g. the webhooks array exceeds the maximum of 50 entries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationException"}}}}},"summary":"Install or update an external application","description":"Installs a new external application or updates the configuration of the currently installed one.\n\n#### Idempotency:\n- Calling this endpoint multiple times with the same data is safe — it updates the existing application in place.\n\n#### Webhook synchronization:\n- The `webhooks` array is treated as the **full desired state** and is fully synchronized on every call.\n- Webhooks in the request but not yet persisted are **created**.\n- Webhooks no longer present in the request are **deleted**.\n- Maximum **50 webhooks** can be registered per application.\n\n#### Response:\n- Returns the complete application object as persisted after the operation.","callbacks":{"onWebhookDispatch":{"{targetUrl}":{"post":{"parameters":[{"name":"Accept-Language","in":"header","schema":{"type":"string"}},{"name":"X-Signature-Sha256","in":"header","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}},"description":"callback successfully processed"}}}}}}}},"/api/app/cart/item/{uuid}":{"delete":{"tags":["Cart"],"parameters":[{"name":"uuid","in":"path","description":"Cart UUID.","required":true,"schema":{"type":"string"}},{"name":"productCodename","in":"query","description":"Codename of the product to remove.","required":true,"schema":{"type":"string"}},{"name":"supplyId","in":"query","description":"Supply ID to target a specific supply line. If omitted, the default supply line is removed.","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Updated cart after removing the item. Items are always included.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"Invalid cart UUID format or product codename not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Cart not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Remove an item from a cart","description":"Removes a product line from the cart and returns the updated cart with all items loaded.\n\n- `productCodename` must match an existing product in the shop, otherwise 400 is returned.\n- Use `supplyId` to target a specific supply line; if omitted, the default supply line is removed.\n- If the product+supply combination is not in the cart, the request is silently ignored and the cart is returned unchanged."},"patch":{"tags":["Cart"],"parameters":[{"name":"uuid","in":"path","description":"Cart UUID.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartItemRequest"}}}},"responses":{"200":{"description":"Updated cart after modifying the item. Items are always included.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"Invalid cart UUID format, product codename not found, or supply ID not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Cart not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Update a cart item","description":"Sets the absolute quantity of an existing item in the cart and returns the updated cart with all items loaded.\n\n- Identify the item by `productCodename` and optionally `supplyId`.\n- `productCodename` must match an existing product in the shop, otherwise 400 is returned.\n- If `supplyId` is provided it must exist, otherwise 400 is returned.\n- Setting `count` to `0` removes the item from the cart.\n- If the product+supply combination is not already in the cart, the request is silently ignored and the cart is returned unchanged."},"post":{"tags":["Cart"],"parameters":[{"name":"uuid","in":"path","description":"Cart UUID.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartItemRequest"}}}},"responses":{"200":{"description":"Updated cart after adding the item. Items are always included.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"Invalid cart UUID format, product codename not found, or supply ID not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Cart not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Add an item to a cart","description":"Adds a product to the cart identified by the given UUID and returns the updated cart with all items loaded.\n\n- `productCodename` must match an existing product in the shop, otherwise 400 is returned.\n- If `supplyId` is provided it must exist, otherwise 400 is returned.\n- If `supplyId` is omitted, the default (primary) supply for the product is used.\n- If the product already exists in the cart (same product + supply combination), the quantity is increased by `count`."}},"/api/app/cart/search":{"get":{"tags":["Cart"],"parameters":[{"name":"page","in":"query","description":"Page number (1-based, defaults to 1).","required":false,"schema":{"type":"integer"}},{"name":"pageSize","in":"query","description":"Number of items per page (1–100, defaults to 20).","required":false,"schema":{"type":"integer"}},{"name":"type","in":"query","description":"Filter by cart type. Allowed: 'main' (primary cart) or 'custom' (merchant-defined). Optional.","schema":{"oneOf":[{"$ref":"#/components/schemas/CartFilter-type"},{"type":"null"}],"example":"main"},"required":false},{"name":"lastActivityDatetimeFrom","in":"query","description":"Filter by last activity datetime from (inclusive). Mandatory.","schema":{"allOf":[{"$ref":"#/components/schemas/DateTimeInterface"}],"example":"2024-06-15T09:30:00+00:00"},"required":true},{"name":"lastActivityDatetimeTo","in":"query","description":"Filter by last activity datetime to (inclusive).","schema":{"oneOf":[{"$ref":"#/components/schemas/DateTimeInterface"},{"type":"null"}],"example":"2024-06-15T09:30:00+00:00"},"required":false},{"name":"userAccountUuids","in":"query","schema":{"type":["null","array"],"items":{"allOf":[{"$ref":"#/components/schemas/UuidInterface"}],"description":"Filter by user account UUIDs."}},"required":false},{"name":"hasEmail","in":"query","description":"Filter by email presence. True: returns carts where either the contact address email or the linked user account email is set. False: returns carts where both are absent. Null (omitted): no filter applied.","schema":{"type":["boolean","null"],"example":true,"default":true},"required":false},{"name":"userGroupType","in":"query","description":"Filter by user group type.","schema":{"oneOf":[{"$ref":"#/components/schemas/CartFilter-userGroupType"},{"type":"null"}],"example":"custom"},"required":false},{"name":"userGroupCodename","in":"query","description":"Filter by user group codename.","schema":{"type":["string","null"],"example":"vipcustomers"},"required":false},{"name":"userGroups","in":"query","schema":{"type":["null","array"],"example":["custom-vipcustomers","registered-registered"],"items":{"type":"string","description":"Filter by user groups. Each value is a concatenation of userGroupType and userGroupCodename separated by a hyphen, e.g. 'custom-vipcustomers'. Optional."}},"required":false},{"name":"page","in":"query","description":"Page number (1-based, defaults to 1).","schema":{"type":["integer","null"],"minimum":1,"example":1},"required":false},{"name":"pageSize","in":"query","description":"Number of items per page (1–100, defaults to 20).","schema":{"type":["integer","null"],"minimum":1,"maximum":100,"example":20},"required":false}],"responses":{"200":{"description":"Paginated list of carts matching the filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CartPagination"}}}}},"summary":"Search carts","description":"Returns a paginated list of carts matching the given filter criteria.\n\n#### Filtering:\n- Use `lastActivityDatetimeFrom` (required) and `lastActivityDatetimeTo` to narrow results by activity time.\n- Use `type`, `userAccountUuids`, `hasEmail`, `userGroupType`, or `userGroupCodename` to further refine results.\n\n#### Pagination:\n- Each page contains up to **100 items** (default: 20).\n- Use the `page` and `pageSize` parameters to navigate.\n- Check `hasNextPage` in the response to determine if further pages exist."}},"/api/app/cart/{uuid}":{"delete":{"tags":["Cart"],"parameters":[{"name":"uuid","in":"path","description":"Cart UUID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cart deleted successfully."},"400":{"description":"Invalid UUID format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Cart not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Delete a cart","description":"Permanently deletes the cart and all its items."},"get":{"tags":["Cart"],"parameters":[{"name":"uuid","in":"path","description":"Cart UUID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The cart.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Cart"}}}},"400":{"description":"Invalid UUID format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Cart not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Get a cart by UUID","description":"Returns the full cart object for the given UUID. Cart items are always included in this response."}},"/api/app/cash-register/registers":{"get":{"tags":["Cash Register"],"responses":{"200":{"description":"Paginated list of cash registers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashRegisterPagination"}}}}},"summary":"List cash registers","description":"Returns a paginated list of cash registers configured in the shop.\n\nA cash register represents a physical or logical point of sale with its own currency and session history.\n\n#### Pagination:\n- Use the `page` parameter to navigate pages (1-based, defaults to 1).\n- Page size is controlled by the shared paginator configuration.","parameters":[{"name":"page","in":"query","description":"Page number (1-based, defaults to 1).","schema":{"type":["integer","null"],"example":1},"required":false},{"name":"pageSize","in":"query","schema":{"type":["integer","null"],"readOnly":true},"required":false}]}},"/api/app/cash-register/sessions":{"get":{"tags":["Cash Register"],"responses":{"200":{"description":"Cursor-paginated list of cash register sessions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CashRegisterSessionCursorPagination"}}}}},"summary":"List cash register sessions","description":"Returns a cursor-paginated list of cash register sessions.\n\nA session represents a single opening-to-closing period of a cash register. Sessions contain all cash transactions (cash in, cash out, blind close, close) that occurred during the period.\n\n#### Filtering:\n- `cashRegisterUuid` filters sessions to a specific cash register.\n- `openDateFrom` and `openDateTo` filter by the session open date (inclusive start, exclusive end). Time parts are ignored.\n\n#### Pagination:\n- Use `cursor` to continue from the previous response.\n- Results are ordered by session ID descending (newest first).","parameters":[{"name":"cursor","in":"query","description":"Opaque cursor string for continuing pagination from a previous response. Omit for the first page.","schema":{"type":["string","null"]},"required":false},{"name":"cashRegisterUuid","in":"query","description":"Filter sessions to a specific cash register UUID.","schema":{"oneOf":[{"$ref":"#/components/schemas/UuidInterface"},{"type":"null"}],"example":"550e8400-e29b-41d4-a716-446655440001"},"required":false},{"name":"openDateFrom","in":"query","description":"Filter by session open date from (inclusive). Time part is ignored (midnight is used).","schema":{"oneOf":[{"$ref":"#/components/schemas/DateTimeInterface"},{"type":"null"}],"example":"2024-06-15"},"required":false},{"name":"openDateTo","in":"query","description":"Filter by session open date to (exclusive — the day after is used internally). Time part is ignored.","schema":{"oneOf":[{"$ref":"#/components/schemas/DateTimeInterface"},{"type":"null"}],"example":"2024-06-20"},"required":false}]}},"/api/app/category/paths":{"get":{"tags":["Category"],"responses":{"200":{"description":"Cursor-paginated list of categories.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryPagination"}}}},"400":{"description":"More than 50 non-empty paths.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}}},"summary":"Find categories by paths","description":"Returns categories whose full path matches one of the given path strings.\n\n- Each element of `categoryPaths` is a path of category names separated by `>`, `;` or `|`, e.g. \"Car Parts > Brakes > Brake Pads\".\n- Names are matched case-insensitively, level by level, against existing categories.\n- Paths that do not match any existing category are silently skipped. If none match, an empty pagination is returned.\n- At most 50 non-empty paths are allowed, otherwise 400 is returned.","parameters":[{"name":"categoryPaths","in":"query","schema":{"type":"array","example":["Car Parts > Brakes > Brake Pads","Car Parts > Brakes > Brake Discs"],"minItems":1,"items":{"type":"string","description":"Category paths. Each element is a path of category names separated by `>`, `;` or `|`, e.g. 'Car Parts > Brakes > Breaking Pads'. Must contain at least 1 path"},"default":[]},"required":true}]},"post":{"tags":["Category"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryPathsRequest"}}},"description":"Category paths to create."},"responses":{"200":{"description":"Cursor-paginated list of categories.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryPagination"}}}},"400":{"description":"More than 50 paths.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}}},"summary":"Create categories by paths","description":"Creates the category hierarchy described by the given paths and returns the resulting categories.\n\n- Each element of `categoryPaths` is a path of category names separated by `>`, `;` or `|`, e.g. \"Car Parts > Brakes > Brake Pads\".\n- Categories already existing at a given level are reused; missing ones are created.\n- The response contains the categories of each matched or created path, ordered by path order.\n- `categoryPaths` must contain at least one path.\n- At most 50 paths are allowed, otherwise 400 is returned."}},"/api/app/category/products-assign":{"post":{"tags":["Category"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryProductsAssignRequest"}}},"description":"Products to assign or unassign and the target categories."},"responses":{"200":{"description":"Result of the assignment operation including task state, task UUID and notifications.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UseCaseResponse"}}}},"400":{"description":"Another task for the same use case is already running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"422":{"description":"The context contains no category paths.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationException"}}}}},"summary":"Assign or unassign products to categories","description":"Assigns or removes the products selected by `productFilter` to or from the categories identified by `context.categoryPaths`.\n\n- `context.assignmentAction` `add` assigns the filtered products to the categories; `remove` unassigns them.\n- `context.assignmentScope` `fullPath` targets every category along each path; `leafOnly` targets only the last (leaf) category of each path.\n- `context.categoryPaths` must contain at least one path, otherwise 422 is returned.\n- For up to 100 matching products the operation runs synchronously and the response `taskState` is `done`.\n- For larger selections the operation is dispatched to a background queue and the response contains an in-progress task state and the task UUID."}},"/api/app/category/search":{"get":{"tags":["Category"],"responses":{"200":{"description":"Cursor-paginated list of categories.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryPagination"}}}},"400":{"description":"Invalid or mismatched cursor, or the parent category does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}}},"summary":"Search categories","description":"Returns a cursor-paginated list of categories ordered by ID ascending.\n\n#### Filtering:\n- Use `parentUuid` to return only direct children of a category. Pass the zero UUID `00000000-0000-0000-0000-000000000000` to return root categories (categories without a parent). The parent category must exist, otherwise 400 is returned.\n- Use `search` to fulltext-search category names in the current request language.\n- Set `onlyLeaves` to `true` to return only leaf categories (categories with no child categories).\n\n#### Pagination:\n- Page size is fixed at 30 items.\n- Use `nextCursor` / `previousCursor` from the response to navigate.\n- The cursor is signed and bound to the filter; using a cursor with a changed filter returns 400.","parameters":[{"name":"cursor","in":"query","description":"Opaque pagination cursor. Pass the `nextCursor` or `previousCursor` value returned by the previous response to navigate. The cursor is signed and bound to the current filter combination; using it with a changed filter returns 400.","schema":{"type":["string","null"],"example":"eyJpZCI6NDJ9.aB3dEfG"},"required":false},{"name":"parentUuid","in":"query","description":"Filter by parent category UUID. Returns only direct children of the given category. Pass the zero UUID `00000000-0000-0000-0000-000000000000` to return root categories (categories without a parent). The parent category must exist, otherwise 400 is returned.","schema":{"oneOf":[{"$ref":"#/components/schemas/UuidInterface"},{"type":"null"}],"example":"00000000-0000-0000-0000-000000000000"},"required":false},{"name":"search","in":"query","description":"Fulltext search term matched against category names in the current request language. Optional.","schema":{"type":["string","null"],"example":"Brake Pad"},"required":false},{"name":"onlyLeaves","in":"query","description":"Whether to return only leaf categories (categories that have no child categories). Defaults to false.","schema":{"type":"boolean","example":false,"default":false},"required":true}]}},"/api/app/category/uuids/{uuids}":{"get":{"tags":["Category"],"parameters":[{"name":"uuids","in":"path","description":"Comma-separated list of UUIDs","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated list of categories.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryPagination"}}}},"400":{"description":"Invalid UUID format or more than 30 UUIDs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}}},"summary":"Find categories by UUIDs","description":"Returns categories matching the given comma-separated UUIDs, ordered by ID ascending.\n\n- `uuids` must contain valid UUID strings, otherwise 400 is returned.\n- At most 30 UUIDs are allowed, otherwise 400 is returned.\n- Categories whose UUID is not found are silently omitted from the response."}},"/api/app/delivery-setup/delivery/search":{"get":{"tags":["Delivery Setup"],"parameters":[{"name":"page","in":"query","description":"Page number (1-based, defaults to 1).","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated list of delivery options.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverySetupDeliveryPagination"}}}}},"summary":"List delivery options","description":"Returns a paginated list of all delivery options configured in the shop across all delivery setups (country/currency combinations).\n\n#### Pagination:\n- Each page contains up to **30 items** (fixed; no pageSize parameter).\n- Use the `page` parameter to navigate pages.\n- Check `hasNextPage` in the response to determine if further pages exist."}},"/api/app/delivery-setup/payment/search":{"get":{"tags":["Delivery Setup"],"parameters":[{"name":"page","in":"query","description":"Page number (1-based, defaults to 1).","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated list of delivery setup payment methods.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverySetupPaymentPagination"}}}}},"summary":"Search delivery setup payments","description":"Returns a paginated list of payment methods configured in the shop's delivery setups.\n\n#### Pagination:\n- Each page contains up to 30 items.\n- Use the `page` parameter to navigate (1-based, defaults to 1).\n- Check `hasNextPage` in the response to determine if further pages exist."}},"/api/app/discount/search":{"get":{"tags":["Discount"],"responses":{"200":{"description":"Paginated list of discounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pagination"}}}},"400":{"description":"Invalid uuid format in filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}}},"summary":"Search discounts","description":"Returns a paginated list of discounts matching the filter criteria.\n\n#### Filtering:\n- Use `uuid`, `code`, `ids`, `codes`, `types`, `userAccountEmails`, `productCodenames`, `userGroupTypes`, `userGroupCodenames`, `productGroupTypes`, or `productGroupCodenames` to narrow results.\n- `types` accepts short class names: \"ProductDiscount\" or \"Coupon\".\n\n#### Pagination:\n- Each page contains up to 30 items.\n- Use the `page` parameter to navigate (1-based, defaults to 1).\n- Check `hasNextPage` in the response to determine if further pages exist."}},"/api/app/discount/{uuid}":{"patch":{"tags":["Discount"],"parameters":[{"name":"uuid","in":"path","description":"Discount UUID.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"}}},"required":true},"responses":{"200":{"description":"Updated discount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"}}}},"400":{"description":"Invalid UUID format, invalid input, or duplicate coupon code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Discount not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Update a discount","description":"Updates an existing discount identified by UUID and returns the updated object.\n\n#### Behavior:\n- The existing discount is fetched, then merged with the provided fields.\n- All validation rules from POST apply.\n- Fields not provided remain unchanged (they are taken from the existing discount)."}},"/api/app/discount":{"delete":{"tags":["Discount"],"parameters":[{"name":"uuid","in":"query","description":"Discount UUID.","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","description":"Coupon code.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Discount deleted."},"202":{"description":"No rows were deleted."},"400":{"description":"Neither uuid nor code was specified, or invalid uuid format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Discount not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Delete a discount","description":"Deletes a discount by UUID or coupon code.\n\n#### Constraints:\n- At least one of `uuid` or `code` must be provided. Returns 400 if both are omitted.\n\n#### Response:\n- Returns 200 on successful deletion.\n- Returns 202 Accepted if no rows were deleted (discount may have already been removed)."},"get":{"tags":["Discount"],"parameters":[{"name":"uuid","in":"query","description":"Discount UUID.","required":false,"schema":{"type":"string"}},{"name":"code","in":"query","description":"Coupon code.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Discount details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"}}}},"400":{"description":"Neither uuid nor code was specified, or invalid uuid format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Discount not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Get a discount","description":"Returns a single discount by UUID or coupon code.\n\n#### Constraints:\n- At least one of `uuid` or `code` must be provided. Returns 400 if both are omitted."},"post":{"tags":["Discount"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"}}},"required":true},"responses":{"200":{"description":"Created discount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Discount"}}}},"400":{"description":"Invalid input or duplicate coupon code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}}},"summary":"Create a discount","description":"Creates a new discount and returns the created object.\n\n#### Discount type:\n- Provide `_type: \"ProductDiscount\"` for a product-level discount, or `_type: \"Coupon\"` for a coupon.\n- Omitting `_type` causes a deserialization error because Discount is abstract.\n\n#### Validation constraints:\n- At least one of `amount` or `percents` must be non-zero.\n- `productGroupType` and `productGroupCodename` must both be provided or both omitted.\n- `userGroupType` and `userGroupCodename` must both be provided or both omitted.\n- A discount cannot be assigned to both a product (`productCodename`) and a product group at the same time.\n- A discount cannot be assigned to both a user (`userAccountEmail`) and a user group at the same time.\n- ProductDiscount must be assigned to at least a product, product group, user, or user group.\n\n#### Defaults:\n- `isEnabled` defaults to true if omitted.\n- `isSummable` defaults to false if omitted.\n- `isAllowedWithStrikethroughPrice` defaults to true.\n- `currency` defaults to the shop's default currency if omitted.\n- For Coupon, `code` auto-generates as an 8-character uppercase string if omitted."}},"/api/app/message/order":{"post":{"tags":["Order"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderMessage"}}}},"responses":{"200":{"description":"Message sent successfully."},"404":{"description":"Order not found for the given order code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Send a message to an order","description":"Sends an email message to the customer associated with the given order.\nIf `sendSms` is set to true, the message is also sent as an SMS.\n\n#### Inputs:\n- `orderCode` — Mandatory. Must match an existing order in the shop.\n- `subject` — Mandatory. Subject line of the message.\n- `body` — Mandatory. Body text of the message.\n- `sendSms` — Optional. Defaults to false. It will be sent only if the SMS module is enabled.\n- `attachments` — Optional. Files to attach to the email. Ignored for SMS.\n\n#### Behavior:\n- The email is always sent; there is no option to disable it.\n- If the order code does not exist, a 404 error is returned."}},"/api/app/order/detail/delivery/{code}":{"patch":{"tags":["Order"],"parameters":[{"name":"code","in":"path","description":"Order code.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDeliveryChangeRequest"}}}},"responses":{"200":{"description":"Updated order detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDetail"}}}},"404":{"description":"Order or delivery setup not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationException"}}}}},"summary":"Change order delivery","description":"Changes the delivery method of the order.\n\n- The `deliverySetupDeliveryId` must exist, otherwise 404 is returned."}},"/api/app/order/detail/delivery-store/{code}":{"patch":{"tags":["Order"],"parameters":[{"name":"code","in":"path","description":"Order code.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDeliveryStoreChangeRequest"}}}},"responses":{"200":{"description":"Updated order detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDetail"}}}},"404":{"description":"Order or store not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationException"}}}}},"summary":"Change order delivery store","description":"Changes the pickup store (parcel point) for the order.\n\n- The `storeCode` must exist, otherwise 404 is returned."}},"/api/app/order/detail/payment/{code}":{"patch":{"tags":["Order"],"parameters":[{"name":"code","in":"path","description":"Order code.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPaymentChangeRequest"}}}},"responses":{"200":{"description":"Updated order detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDetail"}}}},"404":{"description":"Order or payment setup not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationException"}}}}},"summary":"Change order payment","description":"Changes the payment method of the order.\n\n- The `deliverySetupPaymentId` must exist, otherwise 404 is returned."}},"/api/app/order/detail/reverse-charge/{code}":{"post":{"tags":["Order"],"parameters":[{"name":"code","in":"path","description":"Order code.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order detail with reverse charge applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDetail"}}}},"404":{"description":"Order not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Apply reverse charge","description":"Applies reverse charge VAT to the order if it has not already been applied.\nIf the order is already reverse charged, the order is returned unchanged."}},"/api/app/order/detail/webservice-supplier-order/{code}":{"post":{"tags":["Order"],"parameters":[{"name":"code","in":"path","description":"Order code.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated order detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDetail"}}}},"400":{"description":"Webservice supplier order module not enabled or order item validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}}},"summary":"Sync webservice supplier order","description":"Triggers synchronization of the order with the webservice supplier.\nThis creates or updates supply transactions for the order items.\n\n- The webservice supplier order module must be enabled, otherwise 400 is returned."}},"/api/app/order/detail/{code}":{"get":{"tags":["Order"],"parameters":[{"name":"code","in":"path","description":"Order code.","required":true,"schema":{"type":"string"}},{"name":"include","in":"query","description":"Comma-separated list of additional data to include. Use `payments` to include payment transactions.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDetail"}}}},"404":{"description":"Order not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Get order detail","description":"Returns the order detail for the given order code.\n- `orderItems` are always included and paginated (20 items per page, page 1).\n- Use the `include` query parameter to request additional data:\n - `payments` — includes payment transactions in the response.\n\n#### For the fully detailed information about an order, use one of these read-only endpoints:\n- GET `/api/app/order/json/{code}`\n- GET `/api/app/order/xml/{code}`"},"patch":{"tags":["Order"],"parameters":[{"name":"code","in":"path","description":"Order code.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated order detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDetail"}}}},"400":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Order not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Update order detail","description":"Partially updates the order detail for the given order code.\nOnly the fields provided in the request body are updated.\nThe `orderItems` field cannot be modified through this endpoint.\n\n- `orderState` must be a valid existing state codename. An invalid codename results in a 500 server error.\n- Tags are fully replaced by the provided list.\n- Changing `isPaid` dispatches payment state change events.\n- If the order does not exist, 404 is returned."}},"/api/app/order/detail":{"put":{"tags":["Order"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCreateRequest"}}}},"responses":{"200":{"description":"Created order detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderDetail"}}}},"400":{"description":"Invalid country or currency.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationException"}}}}},"summary":"Create a new order","description":"Creates a new order for the given user account email, country, and currency.\n\n- `userAccountEmail` must be a valid email format, otherwise 422 is returned.\n- The `country` and `currency` must be allowed in the shop configuration, otherwise 400 is returned.\n- If `domainName` is omitted, the primary shop domain is used."}},"/api/app/order/history/{code}":{"get":{"tags":["Order"],"parameters":[{"name":"code","in":"path","description":"Order code.","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number (1-based, defaults to 1).","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated order history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pagination"}}}},"404":{"description":"Order not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Get order history","description":"Returns a paginated history of events for the given order code.\nEach entry represents a change, action, or system event related to the order.\n\n- History entries are ordered chronologically.\n- Pagination uses 100 items per page."}},"/api/app/order/item/supply/{uuid}":{"delete":{"tags":["Order"],"parameters":[{"name":"uuid","in":"path","description":"Order item UUID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order item with supply removed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderItem"}}}},"400":{"description":"Invalid UUID format or invalid item type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Order item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Remove order item supply","description":"Removes the supply association from the order item.\n\n- The item must be a product type. Non-product items return 400."},"patch":{"tags":["Order"],"parameters":[{"name":"uuid","in":"path","description":"Order item UUID.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderItemSupplyChangeRequest"}}}},"responses":{"200":{"description":"Updated order item with new supply.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderItem"}}}},"400":{"description":"Invalid UUID format, invalid item type, or supply validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Order item or supply not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Change order item supply","description":"Changes the supply (source) of the order item.\n\n- The item must be a product type. Non-product items return 400.\n- Provide either `supplyId` or both `supplyCode` and `supplierCodename`.\n- Omitting all three fields or providing an incomplete combination returns 400."}},"/api/app/order/item/{uuid}":{"delete":{"tags":["Order"],"parameters":[{"name":"uuid","in":"path","description":"Order item UUID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order item deleted successfully."},"400":{"description":"Invalid UUID format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}},"404":{"description":"Order item not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Delete order item","description":"Deletes the order item with the given UUID.\nThe order must not be locked."},"get":{"tags":["Order"],"parameters":[{"name":"uuid","in":"path","description":"Order item UUID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Order item detail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderItem"}}}},"400":{"description":"Invalid UUID format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}}},"summary":"Get order item","description":"Returns the order item with the given UUID."},"patch":{"tags":["Order"],"parameters":[{"name":"uuid","in":"path","description":"Order item UUID.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated order items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pagination"}}}},"400":{"description":"Invalid UUID format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestException"}}}}},"summary":"Update order item","description":"Partially updates the order item with the given UUID.\nOnly the fields provided in the request body are updated.\nThe order must not be locked."}},"/api/app/order/item/{code}":{"put":{"tags":["Order"],"parameters":[{"name":"code","in":"path","description":"Order code.","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderItem"}}}},"responses":{"200":{"description":"Created or updated order items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pagination"}}}},"404":{"description":"Order not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}}},"summary":"Create or update order item","description":"Creates a new order item or updates an existing one.\n\n- If `uuid` is omitted in the request body, a new item is created and linked to the order specified by `code`.\n- If `uuid` is provided, the existing item is updated.\n- The order must not be locked.\n- Returns a paginated list containing the created or updated item(s)."}},"/api/app/order/items/{code}":{"get":{"tags":["Order"],"parameters":[{"name":"code","in":"path","description":"Order code.","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number (1-based, defaults to 1).","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Paginated list of order items.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pagination"}}}}},"summary":"List order items","description":"Returns a paginated list of items for the given order code.\nItems are ordered by ID ascending.\nPagination uses 20 items per page."}},"/api/app/order/json/{code}":{"get":{"tags":["Order"],"parameters":[{"name":"code","in":"path","description":"Unique order code identifying the order to export.","required":true,"schema":{"type":"string"}}],"responses":{"404":{"description":"Order not found for the given code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundRequestException"}}}},"200":{"description":"Order data serialized as JSON.","content":{"text/json":{"schema":{"type":"object"}}}}},"summary":"Get order as JSON","description":"Returns the full order data for the given order code serialized as JSON.\n\nJSON Structure Notes:\nThe JSON preserves the same hierarchy as the XML export, with these structural differences:\n1. XML attributes become JSON object keys prefixed with `@`.\n XML: ``\n JSON: `\"status\": [{\"@code\": \"1\", \"@name\": \"New\"}]`\n2. Text content becomes `\"#text\"`.\n XML: `Please leave at door`\n JSON: `\"comment\": [{\"#text\": \"Please leave at door\"}]`\n3. Repeated child elements become arrays.\n XML: `12345678901239876543210987`\n JSON: `\"ean\": [{\"#text\": \"1234567890123\"}, {\"#text\": \"9876543210987\"}]`\n4. Single child elements also become arrays with one item.\n XML: `