{ "openapi": "3.0.0", "info": { "title": "Customa", "description": "E-Commerce BI & CRM Tool", "version": "3.13.1" }, "servers": [ { "url": "https://www.customa.biz/", "description": "Customa" } ], "paths": { "/api/v3/auth/login": { "post": { "tags": [ "auth" ], "summary": "Authentication of a user for the API.", "description": "A user is authenticated using their username and password and a project ID. If the credentials are valid, a token\nis returned that can be used for further API requests. The token is valid for a limited time and can be refreshed\nusing the refresh endpoint. It is recommended to refresh the token at least 10 minutes before it expires to\nensure uninterrupted access to the API.", "operationId": "auth_login_v3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthLoginRequestV3" } } } }, "responses": { "200": { "description": "The authentication was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponseV3" } } } }, "400": { "description": "The request body is invalid or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseV3" } } } }, "401": { "description": "Invalid credentials provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseV3" } } } }, "403": { "description": "Insufficient permissions to access the API or the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseV3" } } } } }, "deprecated": true, "security": [] } }, "/api/v3/auth/logout": { "post": { "tags": [ "auth" ], "summary": "Manually invalidate an API Auth Token.", "description": "The logout endpoint allows a user to manually invalidate their current API authentication token.", "operationId": "auth_logout_v3", "responses": { "200": { "description": "The current token was successfully deleted." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/auth/refresh": { "post": { "tags": [ "auth" ], "summary": "Refresh an API Auth Token.", "description": "This endpoint allows a user to refresh their current API authentication token. The current token will be\ninvalidated, and a new token will be issued with an updated expiration time.", "operationId": "auth_refresh_v3", "responses": { "200": { "description": "The current token was successfully refreshed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponseV3" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/customer": { "post": { "tags": [ "customer" ], "summary": "Creates a new Customer.", "description": "A new customer is created and the ID of the created customer is returned.", "operationId": "customer_post_v3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrictCustomer" } } } }, "responses": { "201": { "description": "The customer was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCreatedResponse" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/customer/{id}": { "get": { "tags": [ "customer" ], "summary": "Retrieves a customer by their ID.", "operationId": "customer_get_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The customer was found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrictCustomer" } } } }, "404": { "description": "The customer was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] }, "put": { "tags": [ "customer" ], "summary": "Overwrites a customer with the given ID.", "description": "The customer must already exist in the system. All customer data is replaced with the data provided in the\nrequest body.", "operationId": "customer_put_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrictCustomer" } } } }, "responses": { "200": { "description": "The customer was successfully updated." }, "404": { "description": "The customer was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] }, "delete": { "tags": [ "customer" ], "summary": "Deletes a customer with the given ID.", "operationId": "customer_delete_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The customer was found and deleted." }, "404": { "description": "The customer was not found." }, "409": { "description": "The customer could not be deleted because it is referenced by other entities." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] }, "patch": { "tags": [ "customer" ], "summary": "Updates a customer with the given ID partially.", "description": "This method allows for partial updates to a customer's data. Only the fields provided in the request body will\nbe updated, leaving other fields unchanged.", "operationId": "customer_patch_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "responses": { "200": { "description": "The customer was successfully updated." }, "404": { "description": "The customer was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/customer/search": { "post": { "tags": [ "customer" ], "summary": "Searches for customers by the given filters.", "description": "Using the search endpoint, customers can be filtered based on various criteria, which are combined using the\nboolean AND operator. Multiple values can be provided for a filter, these will be combined using the boolean OR\noperator. The results returned are paginated and sorted by the ID in ascending order.\n\n**Please note:** As Customa may choose a lower page size than the provided one, it is recommended to use the\nvalue returned by the first request when scrolling through multiple result pages.", "operationId": "customer_search_v3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "A search response with customers matching the search criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSearchResponse" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/product": { "post": { "tags": [ "product" ], "summary": "Creates a new Product.", "description": "A new product is created using the provided data. The product ID is returned in the response.", "operationId": "product_post_v3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrictProduct" } } } }, "responses": { "201": { "description": "The product was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCreatedResponse" } } } }, "422": { "description": "A product with this number already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseV3" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/product/{id}": { "get": { "tags": [ "product" ], "summary": "Retrieves a product by its ID.", "operationId": "product_get_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The product was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrictProduct" } } } }, "404": { "description": "The product was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] }, "put": { "tags": [ "product" ], "summary": "Overwrites an existing product with the given ID.", "description": "The product must already exist. The provided data will replace the existing product data.", "operationId": "product_put_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrictProduct" } } } }, "responses": { "200": { "description": "The product was successfully updated." }, "404": { "description": "The product was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] }, "delete": { "tags": [ "product" ], "summary": "Deletes a product by its ID.", "operationId": "product_delete_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The product was successfully deleted." }, "404": { "description": "The product was not found." }, "409": { "description": "The product cannot be deleted because it is referenced by other entities." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] }, "patch": { "tags": [ "product" ], "summary": "Updates a product partially by its ID.", "description": "This method allows for partial updates to a product's data. Only the fields provided in the request body will be\nupdated.", "operationId": "product_patch_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" } } } }, "responses": { "200": { "description": "The product was successfully updated." }, "404": { "description": "The product was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/product/search": { "post": { "tags": [ "product" ], "summary": "Searches for products by the given filters.", "description": "Using the search endpoint, products can be filtered based on various criteria, which are combined using the\nboolean AND operator. Multiple values can be provided for a filter, these will be combined using the boolean OR\noperator. The results returned are paginated and sorted by the ID in ascending order.\n\n**Please note:** As Customa may choose a lower page size than the provided one, it is recommended to use the\nvalue returned by the first request when scrolling through multiple result pages.", "operationId": "product_search_v3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "A search response with products matching the search criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSearchResponse" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/receipt": { "post": { "tags": [ "receipt" ], "summary": "Creates a new receipt.", "description": "A receipt is created using the provided JSON data. The ID of the created receipt is returned in the response.", "operationId": "receipt_post_v3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrictReceipt" } } } }, "responses": { "201": { "description": "The receipt was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCreatedResponse" } } } }, "422": { "description": "A receipt with this number already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseV3" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/receipt/{id}": { "get": { "tags": [ "receipt" ], "summary": "Retrieves a receipt by its ID.", "operationId": "receipt_get_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The receipt was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrictReceipt" } } } }, "404": { "description": "The receipt was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] }, "put": { "tags": [ "receipt" ], "summary": "Overwrites an existing receipt with the given ID.", "description": "The receipt must already exist. The provided data will replace the existing receipt data. Any receipt item that\nis not present in the request will be removed from the receipt.", "operationId": "receipt_put_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrictReceipt" } } } }, "responses": { "200": { "description": "The receipt was successfully updated." }, "404": { "description": "The receipt was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] }, "delete": { "tags": [ "receipt" ], "summary": "Deletes a receipt by its ID.", "operationId": "receipt_delete_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The receipt was successfully deleted." }, "404": { "description": "The receipt was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] }, "patch": { "tags": [ "receipt" ], "summary": "Partially updates an existing receipt with the given ID.", "description": "The receipt must already exist. The provided data will be merged with the existing receipt data. Any receipt\nitem that is not present in the request will remain unchanged. If the provided data contains receipt items, the\nexisting receipt items will be replaced with the provided items.", "operationId": "receipt_patch_v3", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "responses": { "200": { "description": "The receipt was successfully updated." }, "404": { "description": "The receipt was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/receipt/search": { "post": { "tags": [ "receipt" ], "summary": "Searches for receipts by the given filters.", "description": "Using the search endpoint, receipts can be filtered based on various criteria, which are combined using the\nboolean AND operator. Multiple values can be provided for a filter, these will be combined using the boolean OR\noperator. The results returned are paginated and sorted by the ID in ascending order.\n\n**Please note:** As Customa may choose a lower page size than the provided one, it is recommended to use the\nvalue returned by the first request when scrolling through multiple result pages.", "operationId": "receipt_search_v3", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "A search response with receipts matching the search criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptSearchResponse" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/segment": { "get": { "tags": [ "segment" ], "summary": "Retrieve Customer Segments.", "description": "Returns an array of customer segments with their RFM metrics (Recency, Frequency, Monetary)\nand lifetime value data for customer segmentation and analysis.", "operationId": "segments_get_v3", "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentList" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/segment/definition": { "get": { "tags": [ "segment" ], "summary": "Returns Customer Segment Data.", "operationId": "definition_get_v3", "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentDefinition" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/settings": { "get": { "tags": [ "settings" ], "summary": "Returns a definition of the available settings.", "operationId": "settings_list_v3", "responses": { "200": { "description": "The settings definition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsDefinition" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/settings/{name}": { "get": { "tags": [ "settings" ], "summary": "Returns the values of a given setting.", "operationId": "settings_get_v3", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The setting was found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Setting" } } } }, "403": { "description": "The setting is confidential and is not readable via the API." }, "404": { "description": "The setting was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/settings/{name}/validate": { "post": { "tags": [ "settings" ], "summary": "Validates the given setting.", "operationId": "settings_validate_v3", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Setting" } } } }, "responses": { "200": { "description": "The setting was found validated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingValidationResponse" } } } }, "404": { "description": "The setting was not found." } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/stats/receipt": { "post": { "tags": [ "stats" ], "summary": "Calculates receipt statistics.", "operationId": "stats_receipt_v3", "requestBody": { "description": "Request body for receipt statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsRequest" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsReceiptGroups" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/stats/receipt/groupings": { "get": { "tags": [ "stats" ], "summary": "Returns a list of grouping options for receipt statistics.", "operationId": "stats_receipt_groupings_v3", "responses": { "200": { "description": "Grouping options for receipt statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChoicesList" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/stats/receipt_item": { "post": { "tags": [ "stats" ], "summary": "Calculates receipt item statistics.", "operationId": "stats_receipt_item_v3", "requestBody": { "description": "Request body for receipt item statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsRequest" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsReceiptItemGroups" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v3/stats/receipt_item/groupings": { "get": { "tags": [ "stats" ], "summary": "Returns a list of grouping options for receipt statistics.", "operationId": "stats_receipt_item_groupings_v3", "responses": { "200": { "description": "Grouping options for receipt statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChoicesList" } } } } }, "deprecated": true, "security": [ { "apiV3Token": [] } ] } }, "/api/v4/auth/login": { "post": { "tags": [ "auth" ], "summary": "API Endpoint for JSON authentication.", "description": "This endpoint allows users to authenticate using their username and password. Upon successful authentication, a token is returned that can be used for subsequent API requests. The token is valid for a limited time and should be refreshed by reauthenticating before it expires to ensure uninterrupted access to the API.", "operationId": "auth_login_v4", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthLoginRequestV4" } } } }, "responses": { "200": { "description": "The authentication was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthTokenResponseV4" } } } }, "400": { "description": "The request body is invalid or malformed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseV4" } } } }, "401": { "description": "Invalid credentials provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseV4" } } } } }, "security": [] } }, "/api/v4/category/{project}": { "post": { "tags": [ "category" ], "summary": "Creates a new category.", "operationId": "category_post_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryV4" } } } }, "responses": { "201": { "description": "The category was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCreatedResponse2" } } } }, "422": { "description": "The provided data is invalid." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/category/{project}/{id}": { "get": { "tags": [ "category" ], "summary": "Retrieves a category by its ID.", "operationId": "category_get_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The category was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryV4" } } } }, "404": { "description": "The category was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] }, "put": { "tags": [ "category" ], "summary": "Overwrites an existing category with the given ID.", "operationId": "category_put_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategoryV4" } } } }, "responses": { "200": { "description": "The category was successfully updated." }, "404": { "description": "The category was not found." }, "422": { "description": "The provided data is invalid or would create a circular reference." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] }, "delete": { "tags": [ "category" ], "summary": "Deletes a category by its ID.", "operationId": "category_delete_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The category was successfully deleted." }, "404": { "description": "The category was not found." }, "409": { "description": "The category cannot be deleted because it is referenced by child categories or products." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/category/{project}/search": { "post": { "tags": [ "category" ], "summary": "Searches for categories by the given filters.", "operationId": "category_search_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "A search response with categories matching the search criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CategorySearchResponseV4" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/customer/{project}": { "post": { "tags": [ "customer" ], "summary": "Creates a new customer.", "description": "A new customer is created using the provided data. The customer ID is returned in the response.", "operationId": "customer_post_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerV4" } } } }, "responses": { "201": { "description": "The customer was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCreatedResponse2" } } } }, "422": { "description": "The request data is invalid." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/customer/{project}/{id}": { "get": { "tags": [ "customer" ], "summary": "Retrieves a customer by their ID.", "operationId": "customer_get_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "\\d+" } } ], "responses": { "200": { "description": "The customer was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerV4" } } } }, "404": { "description": "The customer was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] }, "put": { "tags": [ "customer" ], "summary": "Overwrites an existing customer with the given ID.", "description": "The customer must already exist. The provided data will replace the existing customer data.", "operationId": "customer_put_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "\\d+" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerV4" } } } }, "responses": { "200": { "description": "The customer was successfully updated." }, "404": { "description": "The customer was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] }, "delete": { "tags": [ "customer" ], "summary": "Deletes a customer by their ID.", "operationId": "customer_delete_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "\\d+" } } ], "responses": { "204": { "description": "The customer was successfully deleted." }, "404": { "description": "The customer was not found." }, "409": { "description": "The customer cannot be deleted because it is referenced by other entities." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/customer/{project}/search": { "post": { "tags": [ "customer" ], "summary": "Searches for customers by the given filters.", "description": "Using the search endpoint, customers can be filtered based on various criteria, which are combined using the\nboolean AND operator. Multiple values can be provided for a filter, these will be combined using the boolean OR\noperator. The results returned are paginated and sorted by the ID in ascending order.\n\n**Please note:** As Customa may choose a lower page size than the provided one, it is recommended to use the\nvalue returned by the first request when scrolling through multiple result pages.", "operationId": "customer_search_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "A search response with customers matching the search criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerSearchResponseV4" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/customer/{project}/fields": { "get": { "tags": [ "customer" ], "summary": "Returns a list of fields and allowed filters for customer search.", "operationId": "customer_fields_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fields and filters for customer search.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldDefinitions" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/product/{project}": { "post": { "tags": [ "product" ], "summary": "Creates a new product.", "description": "A new product is created using the provided data. The product ID is returned in the response.", "operationId": "product_post_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductV4" } } } }, "responses": { "201": { "description": "The product was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCreatedResponse2" } } } }, "422": { "description": "A product with this number already exists." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/product/{project}/{id}": { "get": { "tags": [ "product" ], "summary": "Retrieves a product by its ID.", "operationId": "product_get_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "\\d+" } } ], "responses": { "200": { "description": "The product was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductV4" } } } }, "404": { "description": "The product was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] }, "put": { "tags": [ "product" ], "summary": "Overwrites an existing product with the given ID.", "description": "The product must already exist. The provided data will replace the existing product data.", "operationId": "product_put_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "\\d+" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductV4" } } } }, "responses": { "200": { "description": "The product was successfully updated." }, "404": { "description": "The product was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] }, "delete": { "tags": [ "product" ], "summary": "Deletes a product by its ID.", "operationId": "product_delete_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "\\d+" } } ], "responses": { "204": { "description": "The product was successfully deleted." }, "404": { "description": "The product was not found." }, "409": { "description": "The product cannot be deleted because it is referenced by other entities." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/product/{project}/search": { "post": { "tags": [ "product" ], "summary": "Searches for products by the given filters.", "description": "Using the search endpoint, products can be filtered based on various criteria, which are combined using the\nboolean AND operator. Multiple values can be provided for a filter, these will be combined using the boolean OR\noperator. The results returned are paginated and sorted by the ID in ascending order.\n\n**Please note:** As Customa may choose a lower page size than the provided one, it is recommended to use the\nvalue returned by the first request when scrolling through multiple result pages.", "operationId": "product_search_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "A search response with products matching the search criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSearchResponseV4" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/product/{project}/fields": { "get": { "tags": [ "product" ], "summary": "Returns a list of fields and allowed filters for product search.", "operationId": "product_fields_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fields and filters for product search.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldDefinitions" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/project": { "get": { "tags": [ "project" ], "summary": "Returns a list of the User's projects.", "operationId": "project_list_v4", "responses": { "200": { "description": "A list of projects the user has access to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/receipt/{project}": { "post": { "tags": [ "receipt" ], "summary": "Creates a new receipt.", "description": "A new receipt is created using the provided data. The receipt ID is returned in the response.", "operationId": "receipt_post_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptV4" } } } }, "responses": { "201": { "description": "The receipt was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemCreatedResponse2" } } } }, "422": { "description": "A receipt with this number already exists or the request data is invalid." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/receipt/{project}/{id}": { "get": { "tags": [ "receipt" ], "summary": "Retrieves a receipt by its ID.", "operationId": "receipt_get_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "\\d+" } } ], "responses": { "200": { "description": "The receipt was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptV4" } } } }, "404": { "description": "The receipt was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] }, "put": { "tags": [ "receipt" ], "summary": "Overwrites an existing receipt with the given ID.", "description": "The receipt must already exist. The provided data will replace the existing receipt data. Any receipt item\nthat is not present in the request will be removed from the receipt.", "operationId": "receipt_put_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "\\d+" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptV4" } } } }, "responses": { "200": { "description": "The receipt was successfully updated." }, "404": { "description": "The receipt was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] }, "delete": { "tags": [ "receipt" ], "summary": "Deletes a receipt by its ID.", "operationId": "receipt_delete_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "\\d+" } } ], "responses": { "204": { "description": "The receipt was successfully deleted." }, "404": { "description": "The receipt was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/receipt/{project}/search": { "post": { "tags": [ "receipt" ], "summary": "Searches for receipts by the given filters.", "description": "Using the search endpoint, receipts can be filtered based on various criteria, which are combined using the\nboolean AND operator. Multiple values can be provided for a filter, these will be combined using the boolean OR\noperator. The results returned are paginated and sorted by the ID in ascending order.\n\n**Please note:** As Customa may choose a lower page size than the provided one, it is recommended to use the\nvalue returned by the first request when scrolling through multiple result pages.", "operationId": "receipt_search_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "A search response with receipts matching the search criteria.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReceiptSearchResponseV4" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/receipt/{project}/fields": { "get": { "tags": [ "receipt" ], "summary": "Returns a list of fields and allowed filters for receipt search.", "operationId": "receipt_fields_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fields and filters for receipt search.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldDefinitions" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/segment/{project}": { "get": { "tags": [ "segment" ], "summary": "Retrieve Customer Segments.", "description": "Returns an array of customer segments with their RFM metrics (Recency, Frequency, Monetary)\nand lifetime value data for customer segmentation and analysis.", "operationId": "segments_get_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentList" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/segment/{project}/definition": { "get": { "tags": [ "segment" ], "summary": "Returns Customer Segment Data.", "operationId": "definition_get_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentDefinition" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/settings": { "get": { "tags": [ "settings" ], "summary": "Returns a definition of the available settings.", "operationId": "settings_list_v4", "responses": { "200": { "description": "The settings definition.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsDefinition" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/settings/{project}/{name}": { "get": { "tags": [ "settings" ], "summary": "Returns the values of a given setting.", "operationId": "settings_get_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The setting was found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Setting" } } } }, "403": { "description": "The setting is confidential and is not readable via the API." }, "404": { "description": "The setting was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/settings/{project}/{mappingShopId}/{name}": { "get": { "tags": [ "settings" ], "summary": "Returns the value of a setting for a specific marketplace.", "operationId": "settings_get_marketplace_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "mappingShopId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The setting value for the marketplace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingMarketplaceValue" } } } }, "403": { "description": "The setting is confidential and is not readable via the API." }, "404": { "description": "The setting or marketplace was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] }, "put": { "tags": [ "settings" ], "summary": "Saves the value of a setting for a specific marketplace.", "operationId": "settings_set_marketplace_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "mappingShopId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingValueRequest" } } } }, "responses": { "200": { "description": "The updated setting value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingMarketplaceValue" } } } }, "400": { "description": "Invalid request body." }, "404": { "description": "The setting or marketplace was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/settings/{project}/{name}/validate": { "post": { "tags": [ "settings" ], "summary": "Validates the given setting.", "operationId": "settings_validate_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Setting" } } } }, "responses": { "200": { "description": "The setting was found validated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingValidationResponse" } } } }, "404": { "description": "The setting was not found." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/stats/{project}/receipt": { "post": { "tags": [ "stats" ], "summary": "Calculates receipt statistics.", "operationId": "stats_receipt_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Request body for receipt statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsRequest" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsReceiptGroups" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/stats/{project}/receipt/groupings": { "get": { "tags": [ "stats" ], "summary": "Returns a list of grouping options for receipt statistics.", "operationId": "stats_receipt_groupings_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grouping options for receipt statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsGroupings" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/stats/{project}/receipt/fields": { "get": { "tags": [ "stats" ], "summary": "Returns a list of fields and allowed filters for receipt statistics.", "operationId": "stats_receipt_fields_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fields and filters for receipt statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldDefinitions" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/stats/{project}/receipt_item": { "post": { "tags": [ "stats" ], "summary": "Calculates receipt item statistics.", "operationId": "stats_receipt_item_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Request body for receipt item statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsRequest" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsReceiptItemGroups" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/stats/{project}/receipt_item/groupings": { "get": { "tags": [ "stats" ], "summary": "Returns a list of grouping options for receipt statistics.", "operationId": "stats_receipt_item_groupings_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Grouping options for receipt statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsGroupings" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/stats/{project}/receipt_item/fields": { "get": { "tags": [ "stats" ], "summary": "Returns a list of fields and allowed filters for receipt item statistics.", "operationId": "stats_receipt_item_fields_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fields and filters for receipt item statistics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FieldDefinitions" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/traffic/{project}/filters": { "get": { "tags": [ "traffic" ], "summary": "Returns available filter options for the traffic analyzer.", "operationId": "traffic_filters_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Available filter options.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficFiltersResponse" } } } } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } }, "/api/v4/traffic/{project}": { "post": { "tags": [ "traffic" ], "summary": "Returns traffic data for the given project and filters.", "operationId": "traffic_data_v4", "parameters": [ { "name": "project", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficRequest" } } } }, "responses": { "200": { "description": "Traffic data groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrafficResponse" } } } }, "400": { "description": "The request body is invalid or malformed." } }, "security": [ { "apiV4Token": [], "apiV4BasicAuth": [] } ] } } }, "components": { "schemas": { "BasicSearchResponse": { "required": [ "TotalCount", "CurrentPage", "PagesCount", "PageSize" ], "properties": { "TotalCount": { "description": "Total number of items.", "type": "integer", "example": 100 }, "CurrentPage": { "description": "Current page number.", "type": "integer", "example": 1 }, "PagesCount": { "description": "Total number of pages.", "type": "integer", "example": 10 }, "PageSize": { "description": "Number of items per page.", "type": "integer", "example": 10 } }, "type": "object" }, "CustomerSearchResponse": { "required": [ "Customers" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/BasicSearchResponse" }, { "properties": { "Customers": { "description": "List of customers.", "type": "array", "items": { "$ref": "#/components/schemas/StrictCustomer" } } }, "type": "object" } ] }, "ProductSearchResponse": { "required": [ "Products" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/BasicSearchResponse" }, { "properties": { "Products": { "description": "List of products.", "type": "array", "items": { "$ref": "#/components/schemas/StrictProduct" } } }, "type": "object" } ] }, "ReceiptSearchResponse": { "required": [ "Receipts" ], "type": "object", "allOf": [ { "$ref": "#/components/schemas/BasicSearchResponse" }, { "properties": { "Receipts": { "description": "List of receipts.", "type": "array", "items": { "$ref": "#/components/schemas/StrictReceipt" } } }, "type": "object" } ] }, "LegacySearchResponse": { "deprecated": true, "allOf": [ { "$ref": "#/components/schemas/CustomerSearchResponse" }, { "$ref": "#/components/schemas/ProductSearchResponse" }, { "$ref": "#/components/schemas/ReceiptSearchResponse" } ] }, "ItemCreatedResponse": { "required": [ "ID" ], "properties": { "ID": { "description": "ID of the created Item.", "type": "string", "example": "42" } }, "type": "object" }, "Timestamped": { "description": "Response containing a timestamp.", "properties": { "CreationDate": { "description": "Creation Timestamp of the item. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time" }, "ModificationDate": { "description": "Timestamp of the last change of the item in the database. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time" } }, "type": "object" }, "Customer": { "description": "Customer object containing all customer data.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/Timestamped" }, { "properties": { "ID": { "description": "ID of the customer. Set internally by Customa, any given value is ignored.", "type": "string", "example": "12345" }, "Number": { "description": "Customer number from e.g. an external Shop or ERP System.", "type": "string", "example": "K123456", "maxLength": 32 }, "Group": { "description": "Group name of the customer", "type": "string", "example": "group1", "nullable": true, "maxLength": 255 }, "Salutation": { "description": "Salutation of the customer. 'm' for male, 'f' for female and 'x' for neither or unknown.", "type": "string", "enum": [ "m", "f", "x" ] }, "Title": { "description": "(Academical) title of the customer.", "type": "string", "example": "Dr.", "maxLength": 30 }, "FirstName": { "description": "First name of the customer.", "type": "string", "example": "Max", "maxLength": 256 }, "LastName": { "description": "Last name of the customer.", "type": "string", "example": "Mustermann", "maxLength": 256 }, "Company": { "description": "Company of the customer's address", "type": "string", "example": "ACME, Inc.", "maxLength": 256 }, "Address": { "description": "(Street) address of the customer", "type": "string", "example": "Musterweg 42", "maxLength": 256 }, "PostalCode": { "description": "Postal code of the customer's address", "type": "string", "example": 12345, "maxLength": 16 }, "Suburb": { "description": "Suburb of the customer's address", "type": "string", "example": "", "maxLength": 256 }, "City": { "description": "City of the customer's address", "type": "string", "example": "Musterstadt", "maxLength": 256 }, "Country": { "description": "ISO3166-1 Alpha-2 Code of the customer's country", "type": "string", "example": "DE", "maxLength": 2 }, "EMail": { "description": "Email address of the customer.", "type": "string", "format": "email", "maxLength": 128 }, "Phone": { "description": "Phone number of the customer.", "type": "string", "example": "123 456 7890", "maxLength": 256 }, "Birthday": { "description": "Date of birth of the customer.", "type": "string", "format": "date", "example": "1980-01-01", "nullable": true }, "Referrer": { "description": "Referrer (last cookie) of the customer.", "type": "string", "example": "example", "maxLength": 256 }, "ReferrerChannel": { "description": "Referrer Channel of the customer.", "type": "string", "example": "direct", "maxLength": 32 }, "RegisterDate": { "description": "Registration date of the customer.", "type": "string", "format": "date-time" }, "PurchaseDate": { "description": "Purchase date of the customer.", "type": "string", "format": "date-time", "example": "2025-04-04T09:39:19.931Z", "nullable": true }, "AdditionalFields": { "description": "Additional data for the customer.", "type": "array", "items": { "$ref": "#/components/schemas/AdditionalField" } }, "ReferenceCustomer": { "description": "Determines if the customer is a reference customer.", "type": "boolean", "example": false }, "ContactBan": { "description": "Determines if the customer has an active contact ban.", "type": "boolean", "example": false }, "ExternalCustomerID": { "description": "ID/Number of the customer in the source system (e.g. an ERP System)", "type": "integer", "example": 12345 }, "ExternalCustomerExternalID": { "description": "ID/Number of the customer in a secondary source system (e.g. the shop)", "type": "string", "example": "12345", "nullable": true, "maxLength": 64 }, "ExternalOrderType": { "type": "string", "example": "shop", "maxLength": 20 }, "ExternalOrderAccountID": { "type": "integer", "example": 42 }, "ExternalOrderSubAccountID": { "type": "string", "maxLength": 64 }, "Marketplace": { "description": "Marketplace of the customer.", "type": "string", "example": "shop", "maxLength": 64 }, "TestUser": { "type": "boolean", "example": false }, "Newsletter": { "type": "boolean", "example": false }, "Segment": { "description": "Segment of the customer. Read-only, changes via the API will have no effect. Will be required in Q1 2026.", "type": "string", "example": "A1" } }, "type": "object" } ] }, "StrictCustomer": { "required": [ "Number", "Group", "Salutation", "Title", "FirstName", "LastName", "Company", "Address", "PostalCode", "City", "Suburb", "Country", "EMail", "Phone", "Birthday", "Referrer", "ReferrerChannel", "RegisterDate", "PurchaseDate", "AdditionalFields", "ReferenceCustomer", "ContactBan", "ExternalCustomerID", "ExternalCustomerExternalID", "ExternalOrderType", "ExternalOrderAccountID", "ExternalOrderSubAccountID", "TestUser", "Newsletter" ], "allOf": [ { "$ref": "#/components/schemas/Customer" } ] }, "Product": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Timestamped" }, { "properties": { "ID": { "description": "ID of the product. Set internally by Customa, any given value is ignored.", "type": "string", "example": "12345" }, "Parent": { "description": "ID of the parent product. The parent must be standalone and not have a parent itself.", "type": "string", "example": "12344", "nullable": true }, "Number": { "description": "Product number, MUST be unique.", "type": "string", "example": "PROD0001", "maxLength": 255 }, "EAN": { "description": "EAN of the product.", "type": "string", "example": "1234567890123", "maxLength": 32 }, "Name": { "description": "Name of the product.", "type": "string", "example": "Toaster", "maxLength": 255 }, "Manufacturer": { "description": "Manufacturer of the product.", "type": "string", "example": "ACME Inc.", "maxLength": 64 }, "Vendor": { "description": "Vendor of the product.", "type": "string", "example": "ACME Inc.", "maxLength": 128 }, "ShortDescription": { "description": "Short description of the product.", "type": "string", "example": "A toaster made of stainless steel." }, "LongDescription": { "description": "Long description of the product.", "type": "string", "example": "A toaster made of stainless steel with a 2-slice capacity and a 7-setting browning control." }, "ImageSource": { "description": "Source URI of the product image.", "type": "string", "format": "uri", "example": "https://example.com/image.jpg" }, "Status": { "description": "Whether the product is active or inactive.", "type": "boolean", "example": true }, "TaxClass": { "description": "Tax class of the product. For example, in Germany, 19% VAT would be 'Normal' while 7% VAT would be 'Reduced'.", "type": "string", "enum": [ "Normal", "Reduced", "HighlyReduced", "None" ] }, "Stock": { "description": "Stock of the product.", "type": "integer", "example": 100 }, "AdditionalFields": { "description": "Additional field data for the product.", "type": "array", "items": { "$ref": "#/components/schemas/AdditionalField" } }, "PurchasePrice": { "$ref": "#/components/schemas/Price" }, "SalesPrice": { "$ref": "#/components/schemas/Price" }, "RecommendedRetailPrice": { "$ref": "#/components/schemas/Price" } }, "type": "object" } ] }, "StrictProduct": { "required": [ "Parent", "Number", "EAN", "Name", "Manufacturer", "Vendor", "ShortDescription", "LongDescription", "ImageSource", "Status", "TaxClass", "Stock", "AdditionalFields", "PurchasePrice", "SalesPrice", "RecommendedRetailPrice" ], "allOf": [ { "$ref": "#/components/schemas/Product" } ] }, "Receipt": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Timestamped" }, { "properties": { "ID": { "description": "ID of the receipt. Set internally by Customa, any given value is ignored.", "type": "string", "example": "12345" }, "Type": { "description": "Type of the receipt.", "type": "string", "example": "RE", "maxLength": 2 }, "Number": { "description": "Receipt number", "type": "string", "example": "RECEIPT0001", "maxLength": 255 }, "CustomerID": { "description": "ID of the customer.", "type": "string", "example": "12345" }, "ExternalOrderType": { "type": "string", "example": "shop", "maxLength": 20 }, "ExternalOrderID": { "type": "integer", "example": 1234, "nullable": true }, "ExternalOrderExternalID": { "type": "string", "example": "1234567890", "nullable": true, "maxLength": 64 }, "ExternalOrderAccountID": { "type": "integer", "example": 42 }, "ExternalOrderSubAccountID": { "type": "string", "maxLength": 64 }, "Marketplace": { "description": "Marketplace of the receipt.", "type": "string", "maxLength": 64 }, "PurchaseDate": { "description": "Purchase date of the receipt.", "type": "string", "format": "date-time", "example": "2025-04-04T09:39:19.931Z" }, "DeliveryDate": { "description": "Delivery date of the receipt. Will be removed in Q1 2026. Please use ReceiptDate instead.", "type": "string", "format": "date-time", "example": "2025-04-04T09:39:19.931Z", "nullable": true, "deprecated": true }, "ReceiptDate": { "description": "Date of the receipt.", "type": "string", "format": "date-time", "example": "2025-04-04T09:39:19.931Z", "nullable": true }, "Referrer": { "description": "Referrer (last cookie) of the customer when creating this receipt.", "type": "string", "example": "example", "nullable": true, "maxLength": 256 }, "ReferrerChannel": { "description": "Referrer Channel of the customer when creating this receipt.", "type": "string", "example": "direct", "nullable": true, "maxLength": 32 }, "PaymentMethod": { "description": "Payment method of the receipt.", "type": "string", "example": "Credit Card", "maxLength": 64 }, "RevenueNet": { "$ref": "#/components/schemas/Price" }, "RevenueGross": { "$ref": "#/components/schemas/Price" }, "ReceiptStatus": { "description": "Status of the receipt.", "type": "string", "enum": [ "Open", "InProgress", "Completed", "Cancelled" ] }, "PaymentStatus": { "description": "Payment status of the receipt.", "type": "string", "enum": [ "New", "Paid", "Cancelled", "PaidPartially", "Reminded", "InProgress", "Authorized", "Refunded", "RefundedPartially", "Failed", "Chargeback", "Unconfirmed" ] }, "DeliveryStatus": { "description": "Delivery status of the receipt.", "type": "string", "enum": [ "Open", "PartiallyShipped", "Shipped", "Returned", "PartiallyReturned", "Cancelled" ] }, "GoogleClickID": { "description": "Google Click ID of this receipt.", "type": "string", "example": "1234567890", "nullable": true, "maxLength": 128 }, "Items": { "description": "List of items in the receipt.", "type": "array", "items": { "$ref": "#/components/schemas/StrictReceiptItem" } }, "AdditionalFields": { "description": "Additional field data for the receipt.", "type": "array", "items": { "$ref": "#/components/schemas/AdditionalField" } } }, "type": "object" } ] }, "StrictReceipt": { "required": [ "Type", "Number", "CustomerID", "ExternalOrderType", "ExternalOrderID", "ExternalOrderExternalID", "ExternalOrderAccountID", "ExternalOrderSubAccountID", "PurchaseDate", "ReceiptDate", "Referrer", "ReferrerChannel", "PaymentMethod", "RevenueNet", "RevenueGross", "ReceiptStatus", "PaymentStatus", "DeliveryStatus", "GoogleClickID", "Items", "AdditionalFields" ], "allOf": [ { "$ref": "#/components/schemas/Receipt" } ] }, "ReceiptItem": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Timestamped" }, { "properties": { "ProductID": { "description": "ID of the product.", "type": "string", "example": "12345" }, "ProductNumber": { "description": "Product number of the product.", "type": "string" }, "Quantity": { "description": "Quantity of the product.", "type": "integer", "example": 1 }, "SellingPrice": { "$ref": "#/components/schemas/Price" }, "PurchasePrice": { "$ref": "#/components/schemas/Price" }, "TaxClass": { "description": "Tax class of the item. For example, in Germany, 19% VAT would be 'Normal' while 7% VAT would be 'Reduced'.", "type": "string", "enum": [ "Normal", "Reduced", "HighlyReduced", "None" ] } }, "type": "object" } ] }, "StrictReceiptItem": { "required": [ "ProductID", "ProductNumber", "Quantity", "SellingPrice", "TaxClass" ], "allOf": [ { "$ref": "#/components/schemas/ReceiptItem" } ] }, "AdditionalField": { "description": "Additional field data.", "required": [ "Key", "Value" ], "properties": { "Key": { "type": "string", "example": "Example" }, "Value": { "type": "string", "example": "42" } }, "type": "object" }, "OAuthValidationRequest": { "description": "Request body for OAuth Token validation.", "required": [ "ClientID", "Secret" ], "properties": { "ClientID": { "description": "OAuth Client ID.", "type": "string" }, "Secret": { "description": "OAuth Client Secret.", "type": "string" } }, "type": "object", "deprecated": true }, "OAuthValidationResponse": { "description": "Response for OAuth Token validation.", "required": [ "Valid" ], "properties": { "Valid": { "description": "Indicates whether the provided OAuth credentials are valid. If an OAuth App was deactivated, this will always be false.", "type": "boolean" } }, "type": "object", "deprecated": true }, "AuthLoginRequestV3": { "title": "Login Authentication Request", "description": "Request body for authentication.", "required": [ "Username", "Password", "Project" ], "properties": { "Username": { "title": "Username.", "description": "Username (E-Mail address) used for authentication with Customa.", "type": "string", "format": "email", "example": "user@customa.biz" }, "Password": { "title": "Password.", "description": "Password for the User.", "type": "string", "example": "secret123!" }, "Project": { "title": "Project ID.", "description": "ID of the project the user is authenticating for.", "type": "integer", "example": 10 } }, "type": "object" }, "AuthTokenResponseV3": { "title": "Authentication Token Response", "description": "Response body of a successful authentication login request or token refresh.", "required": [ "Token", "Expire" ], "properties": { "Token": { "title": "API Access Token.", "description": "Random, hex encoded 64 Bytes used as a token for authentication. The content of this token is not relevant, but it should be treated as a secret and stored securely. It is recommended to refresh the token at least 10 minutes before it expires to ensure uninterrupted access to the API.", "type": "string", "example": "044600149b8a50a2d00a32bc4ff9ac4bbdcdf82565e6b0900ded9daa4db77b55cb75eb58c71ae17af8634da8cce5d464735379f9b45c9ca4d3367d6eea9ea185" }, "Expire": { "title": "Expiration Timestamp.", "description": "The timestamp on which the token expires, provided in RFC3339 Format.", "type": "string", "format": "date-time", "example": "2024-12-31T23:59:59Z" } }, "type": "object" }, "ErrorResponseV3": { "title": "Error Response", "description": "Response body for an error response.", "required": [ "Message" ], "properties": { "Message": { "title": "Error Message.", "description": "A message giving feedback about the error. The recipient's logic must not rely on its content.", "type": "string", "example": "Something bad happened." } }, "type": "object" }, "FilterType": { "type": "string", "enum": [ "IsEmpty", "IsNotEmpty", "Match", "MatchPrefix", "MatchSuffix", "MatchInfix", "LessThan", "LessThanOrEqual", "GreaterThan", "GreaterThanOrEqual" ] }, "Filter": { "title": "Filter definition", "description": "Definition of a single filter.", "required": [ "Type", "Field", "Values" ], "properties": { "Type": { "$ref": "#/components/schemas/FilterType" }, "Field": { "title": "Field to be filtered.", "description": "The field is the name of the field in the data that should be filtered. It must be a valid field name that can be used in the API requests.", "type": "string" }, "Values": { "title": "Filter values.", "description": "Values to be filtered. The values are combined using boolean OR.", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "SearchRequest": { "title": "Search Request", "description": "Request body of a search request.", "required": [ "Page", "PageSize", "Filter" ], "properties": { "Page": { "title": "Page number.", "description": "Number of the result page to be returned.", "type": "integer", "example": 1, "minimum": 0, "exclusiveMinimum": true }, "PageSize": { "title": "Page size.", "description": "Number of items per result page. Customa may choose a lower value, please check the response.", "type": "integer", "example": 10, "minimum": 0, "exclusiveMinimum": true }, "Filter": { "title": "Filters.", "description": "Filters to be applied to the search. The filters are combined using boolean AND. If a filter contains multiple values, these are combined using boolean OR.", "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } }, "type": "object" }, "SegmentCondition": { "type": "string", "enum": [ "GreaterThan", "GreaterThanOrEqual", "LessThan", "LessThanOrEqual", "Equal", "Undefined" ] }, "SegmentValue": { "title": "Segment Value", "description": "A single segment value.", "required": [ "Condition", "Value" ], "properties": { "Condition": { "$ref": "#/components/schemas/SegmentCondition" }, "Value": { "type": "integer" } }, "type": "object" }, "Segment": { "title": "Segment", "description": "A single customer segment generated from the segment definition.", "required": [ "Frequency", "Monetary", "CustomerLifetimeValue", "Recency", "Description" ], "properties": { "Frequency": { "$ref": "#/components/schemas/SegmentValue" }, "Monetary": { "$ref": "#/components/schemas/SegmentValue" }, "CustomerLifetimeValue": { "$ref": "#/components/schemas/SegmentValue" }, "Recency": { "type": "integer" }, "Description": { "type": "string" } }, "type": "object" }, "SegmentList": { "title": "Segment List", "description": "List of the defined segments.", "required": [ "Segments" ], "properties": { "Segments": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Segment" } } }, "type": "object" }, "SegmentRecency": { "title": "Segment Recency Definition", "description": "Configuration of the recency dimension of the customer segments.", "required": [ "Recency", "Description" ], "properties": { "Recency": { "type": "integer" }, "Description": { "type": "string" } }, "type": "object" }, "SegmentMonetary": { "title": "Segment Monetary Definition", "description": "Configuration of the monetary dimension of the customer segments.", "required": [ "Frequency", "Monetary", "CustomerLifetimeValue", "Description" ], "properties": { "Frequency": { "$ref": "#/components/schemas/SegmentValue" }, "Monetary": { "$ref": "#/components/schemas/SegmentValue" }, "CustomerLifetimeValue": { "$ref": "#/components/schemas/SegmentValue" }, "Description": { "type": "string" } }, "type": "object" }, "SegmentDefinition": { "title": "Segment Definition", "description": "Configuration which generates the customer segments.", "required": [ "Recency", "Monetary" ], "properties": { "Recency": { "title": "Recency dimension.", "description": "The recency dimension of the customer segments is based on the time since the last purchase.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SegmentRecency" } }, "Monetary": { "title": "Monetary dimension.", "description": "The monetary dimension of the customer segments is based on the amount of money spent and frequency of purchases.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SegmentMonetary" } } }, "type": "object" }, "SettingType": { "type": "string", "enum": [ "String", "Integer", "Float", "Boolean" ] }, "SettingDefinition": { "title": "Setting Definition", "description": "Definition of a setting.", "required": [ "Label", "Description", "Type", "IsConfidential", "UseProjectFallback" ], "properties": { "Label": { "title": "Display name of the setting.", "type": "string" }, "Description": { "title": "Description of the setting.", "description": "A detailed explanation of the setting's purpose and usage. This description should provide enough information for users to understand what the setting does, how it affects the application, and any important considerations or implications associated with changing its value.", "type": "string" }, "Type": { "$ref": "#/components/schemas/SettingType" }, "IsConfidential": { "title": "Indicates whether the setting is confidential.", "description": "A confidential setting contains sensitive information that should be protected and not exposed in logs, error messages, or any other output. Examples of confidential settings include API keys, passwords, and other credentials. When a setting is marked as confidential, its value cannot be retrieved through the API.", "type": "boolean" }, "UseProjectFallback": { "title": "Indicates whether the setting supports project fallback.", "description": "If true, the setting can fall back to a project-level value if no marketplace-specific value is set. This allows for a hierarchical configuration where a global value can be overridden by marketplace-specific values, and if those are not set, the system can use a project-level default value.", "type": "boolean" } }, "type": "object" }, "SettingsDefinition": { "title": "Settings Definition", "description": "Definition of all settings.", "required": [ "Settings" ], "properties": { "Settings": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SettingDefinition" } } }, "type": "object" }, "Setting": { "title": "Setting", "description": "Definition of a setting.", "required": [ "Global", "Marketplaces" ], "properties": { "Global": { "title": "Global Setting Value.", "description": "The global value of the setting, which applies when no marketplace-specific value is set and a project fallback is used. This value can be of type string, integer, float, or boolean, depending on the specific setting being represented.", "example": 42, "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number", "format": "float" }, { "type": "boolean" } ] }, "Marketplaces": { "title": "Marketplace Setting Value.", "description": "An associative array where the keys are marketplace identifiers (e.g., 'shop1', 'shop2') and the values are the marketplace-specific values for the setting. These values override the global value for their respective marketplaces. The values can be of type string, integer, float, or boolean, depending on the specific setting being represented.", "type": "object", "example": { "shop1": 43, "shop2": 44 }, "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "integer" }, { "type": "number", "format": "float" }, { "type": "boolean" } ] } } }, "type": "object" }, "SettingValidationResponse": { "title": "Setting Validation Response", "description": "Response body for validation of a setting.", "required": [ "Global", "Marketplaces" ], "properties": { "Global": { "type": "boolean" }, "Marketplaces": { "type": "object", "additionalProperties": { "type": "boolean" } } }, "type": "object" }, "DateField": { "type": "string", "enum": [ "PurchaseDate", "ReceiptDate" ] }, "ProductSetMode": { "type": "string", "enum": [ "Sets", "Parts" ] }, "StatsRequest": { "title": "Stats Request", "description": "Request for statistics data.", "required": [ "From", "To", "DateField", "GroupBy", "Filter" ], "properties": { "From": { "title": "Start timestamp.", "description": "The start timestamp of the period for which the statistics should be calculated.", "type": "string", "format": "date-time" }, "To": { "title": "End timestamp.", "description": "The end timestamp of the period for which the statistics should be calculated. The end timestamp must be greater than the start timestamp.", "type": "string", "format": "date-time" }, "DateField": { "$ref": "#/components/schemas/DateField" }, "ProductSetMode": { "title": "Product set mode.", "description": "Controls how product sets are counted to avoid double-counting.\nUse 'Sets' (default) to count sets as a whole (excludes product_set_mode=2),\nor 'Parts' to count sub-positions (excludes product_set_mode=1).", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/ProductSetMode" } ] }, "GroupBy": { "title": "Grouping type.", "description": "The grouping type determines how the data is grouped in the response.", "type": "string" }, "Filter": { "title": "Filter definitions.", "description": "Filters to be applied to the data before grouping. The filters are combined using boolean AND. If a filter contains multiple values, these are combined using boolean OR.", "type": "array", "items": { "$ref": "#/components/schemas/Filter" } } }, "type": "object" }, "Price": { "title": "Price", "description": "A price value with its currency.", "required": [ "Value", "Currency" ], "properties": { "Value": { "title": "Price.", "description": "A price value in the currency specified in the `Currency` property.", "type": "number", "format": "float" }, "Currency": { "title": "Currency.", "description": "The currency of the price value specified in the `Value` property. The value is a three-letter ISO 4217 currency code, e.g. `EUR` for Euro or `USD` for US Dollar.", "type": "string", "example": "EUR" } }, "type": "object" }, "StatsReceiptType": { "title": "Receipt Statistics Type", "description": "Statistics for a specific receipt type.", "required": [ "ReceiptType", "ReceiptCount", "CustomerCount", "Revenue", "CostOfGoodsSold" ], "properties": { "ReceiptType": { "title": "Receipt Type.", "description": "The type of the receipt.", "type": "string" }, "ReceiptCount": { "title": "Number of Receipts.", "description": "The number of receipts of the specified type.", "type": "integer" }, "CustomerCount": { "title": "Number of Customers.", "description": "The number of customers who had at least one receipt of the specified type. This number may be lower than the `ReceiptCount` if some customers had multiple receipts of the specified type.", "type": "integer" }, "Revenue": { "$ref": "#/components/schemas/Price" }, "CostOfGoodsSold": { "$ref": "#/components/schemas/Price" } }, "type": "object" }, "StatsReceiptGroup": { "title": "Receipt Statistics Group", "description": "A group of receipt statistics for a given period.", "required": [ "GroupKey", "GroupName", "Types" ], "properties": { "GroupKey": { "title": "Group Key.", "description": "The key of the group, e.g. a date for daily grouping, a week number for weekly grouping, a month number for monthly grouping or a year number for yearly grouping.", "type": "string" }, "GroupName": { "title": "Group Name.", "description": "A human-readable name of the group, e.g. a date for daily grouping, a week number for weekly grouping, a month name for monthly grouping or a year number for yearly grouping. This field is only for display purposes and may be localized, e.g. the month name may be localized to the language of the request. The `GroupKey` field should be used for grouping and filtering purposes, as it is not localized and has a consistent format.", "type": "string" }, "Types": { "title": "Receipt Types.", "description": "Statistics for the different receipt types in the group.", "type": "array", "items": { "$ref": "#/components/schemas/StatsReceiptType" } } }, "type": "object" }, "StatsReceiptGroups": { "title": "Receipt Statistics", "description": "A grouped list of receipt statistics for a given period.", "required": [ "Groups" ], "properties": { "Groups": { "title": "Grouped data.", "description": "The data is grouped by the specified grouping key, e.g. by day, week, month or year.", "type": "array", "items": { "$ref": "#/components/schemas/StatsReceiptGroup" } } }, "type": "object" }, "Choice": { "title": "Choice", "description": "A single choice, mapping a key to a label.", "required": [ "Key", "Label" ], "properties": { "Key": { "title": "Key of the choice.", "description": "The key identifies the choice and is used in the API requests. It is unique among the choices of a field.", "type": "string" }, "Label": { "title": "Label of the choice.", "description": "The label is a human-readable name for the choice, which can be displayed in user interfaces. It is not necessarily unique among the choices of a field, so it must not be used for anything other than display purposes.", "type": "string" } }, "type": "object" }, "ChoicesList": { "title": "List of Choices", "description": "List of available choices.", "required": [ "Choices" ], "properties": { "Choices": { "type": "array", "items": { "$ref": "#/components/schemas/Choice" } } }, "type": "object" }, "StatsReceiptItemType": { "title": "Receipt Item Statistics Type", "description": "Statistics for a specific receipt type.", "required": [ "ReceiptType", "ReceiptCount", "CustomerCount", "Amount", "Revenue", "CostOfGoodsSold" ], "properties": { "ReceiptType": { "title": "Receipt Type.", "description": "The type of the receipt.", "type": "string" }, "ReceiptCount": { "title": "Number of Receipts.", "description": "The number of receipts of the specified type.", "type": "integer" }, "CustomerCount": { "title": "Number of Customers.", "description": "The number of customers who had at least one receipt of the specified type. This number may be lower than the `ReceiptCount` if some customers had multiple receipts of the specified type.", "type": "integer" }, "Amount": { "title": "Amount of Items.", "description": "The total amount of items of the receipts of the specified type. This is the sum of the amount of items of all receipts of the specified type.", "type": "integer" }, "Revenue": { "$ref": "#/components/schemas/Price" }, "CostOfGoodsSold": { "$ref": "#/components/schemas/Price" } }, "type": "object" }, "StatsReceiptItemGroup": { "title": "Receipt Item Statistics Group", "description": "A group of receipt item statistics for a given period.", "required": [ "GroupKey", "GroupName", "Types" ], "properties": { "GroupKey": { "title": "Group Key.", "description": "The key of the group, e.g. a date for daily grouping, a week number for weekly grouping, a month number for monthly grouping or a year number for yearly grouping.", "type": "string" }, "GroupName": { "title": "Group Name.", "description": "A human-readable name of the group, e.g. a date for daily grouping, a week number for weekly grouping, a month name for monthly grouping or a year number for yearly grouping. This field is only for display purposes and may be localized, e.g. the month name may be localized to the language of the request. The `GroupKey` field should be used for grouping and filtering purposes, as it is not localized and has a consistent format.", "type": "string" }, "Types": { "title": "Receipt Types.", "description": "Statistics for the different receipt types in the group.", "type": "array", "items": { "$ref": "#/components/schemas/StatsReceiptItemType" } } }, "type": "object" }, "StatsReceiptItemGroups": { "title": "Receipt Item Statistics", "description": "A grouped list of receipt item statistics for a given period.", "required": [ "Groups" ], "properties": { "Groups": { "title": "Grouped data.", "description": "The data is grouped by the specified grouping key, e.g. by day, week, month or year.", "type": "array", "items": { "$ref": "#/components/schemas/StatsReceiptItemGroup" } } }, "type": "object" }, "AuthLoginRequestV4": { "title": "Login Authentication Request", "description": "Request body for JSON authentication.", "required": [ "Username", "Password" ], "properties": { "Username": { "title": "Username.", "description": "Username (E-Mail address) used for authentication with Customa.", "type": "string", "format": "email", "example": "user@customa.biz" }, "Password": { "title": "Password.", "description": "Password for the User.", "type": "string", "example": "secret123!" } }, "type": "object" }, "AuthTokenResponseV4": { "title": "Authentication Token Response", "description": "Response body of a successful authentication login request or token refresh.", "required": [ "Token", "ValidUntil" ], "properties": { "Token": { "title": "API Access Token.", "description": "Random, hex encoded 64 Bytes used as a token for authentication. The content of this token is not relevant, but it should be treated as a secret and stored securely. It is recommended to refresh the token at least 10 minutes before it expires to ensure uninterrupted access to the API.", "type": "string", "example": "044600149b8a50a2d00a32bc4ff9ac4bbdcdf82565e6b0900ded9daa4db77b55cb75eb58c71ae17af8634da8cce5d464735379f9b45c9ca4d3367d6eea9ea185" }, "ValidUntil": { "title": "Expiration Timestamp.", "description": "The timestamp on which the token expires, provided in RFC3339 Format.", "type": "string", "format": "date-time", "example": "2024-12-31T23:59:59Z" } }, "type": "object" }, "ErrorResponseV4": { "title": "Error Response", "description": "Response body for an error response.", "properties": { "Code": { "title": "Error Code.", "description": "A numeric code representing the error. A list of error codes and their meanings can be found in the documentation.", "type": "integer", "example": 42, "default": 0 }, "Message": { "title": "Error Message.", "description": "A message giving feedback about the error. The recipient's logic must not rely on its content.", "type": "string", "example": "Something bad happened.", "default": "" } }, "type": "object" }, "CategoryV4": { "title": "Category", "required": [ "Name", "AdditionalFields" ], "properties": { "ID": { "description": "ID of the category. Set internally by Customa, any given value is ignored.", "type": "string", "nullable": true }, "Name": { "description": "Name of the category.", "type": "string" }, "Parent": { "description": "ID of the parent category. Must not create a circular reference.", "type": "string", "nullable": true }, "Level": { "description": "Hierarchy level of the category. 0 for root categories. Set internally by Customa, any given value is ignored.", "type": "integer", "nullable": true }, "AdditionalFields": { "description": "Additional field data for the category.", "type": "array", "items": { "type": "string" } }, "CreationDate": { "description": "Creation Timestamp of the item. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time", "nullable": true }, "ModificationDate": { "description": "Timestamp of the last change of the item in the database. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "ItemCreatedResponse2": { "title": "Item Created Response", "description": "Response body after successfully creating a new item.", "required": [ "ID" ], "properties": { "ID": { "title": "ID of the created item.", "type": "string", "example": "42" } }, "type": "object" }, "CategorySearchResponseV4": { "title": "Category Search Response", "required": [ "TotalCount", "CurrentPage", "PagesCount", "PageSize" ], "properties": { "Categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryV4" }, "default": [] }, "TotalCount": { "description": "Total number of items.", "type": "integer" }, "CurrentPage": { "description": "Current page number.", "type": "integer" }, "PagesCount": { "description": "Total number of pages.", "type": "integer" }, "PageSize": { "description": "Number of items per page.", "type": "integer" } }, "type": "object" }, "Salutation": { "type": "string", "enum": [ "m", "f", "x" ] }, "CustomerV4": { "title": "Customer", "required": [ "Number", "Salutation", "Title", "FirstName", "LastName", "Company", "Address", "PostalCode", "Suburb", "City", "Country", "EMail", "Phone", "Referrer", "ReferrerChannel", "RegisterDate", "AdditionalFields", "ReferenceCustomer", "ContactBan", "Marketplace", "TestUser", "Newsletter", "Segment" ], "properties": { "ID": { "description": "ID of the customer. Set internally by Customa, any given value is ignored.", "type": "string", "nullable": true }, "Number": { "description": "Customer number from e.g. an external Shop or ERP System.", "type": "string" }, "Group": { "description": "Group name of the customer", "type": "string", "nullable": true }, "Salutation": { "$ref": "#/components/schemas/Salutation" }, "Title": { "description": "(Academical) title of the customer.", "type": "string" }, "FirstName": { "description": "First name of the customer.", "type": "string" }, "LastName": { "description": "Last name of the customer.", "type": "string" }, "Company": { "description": "Company of the customer's address", "type": "string" }, "Address": { "description": "(Street) address of the customer", "type": "string" }, "PostalCode": { "description": "Postal code of the customer's address", "type": "string" }, "Suburb": { "description": "Suburb of the customer's address", "type": "string" }, "City": { "description": "City of the customer's address", "type": "string" }, "Country": { "description": "ISO3166-1 Alpha-2 Code of the customer's country", "type": "string" }, "EMail": { "description": "Email address of the customer.", "type": "string" }, "Phone": { "description": "Phone number of the customer.", "type": "string" }, "Birthday": { "description": "Date of birth of the customer.", "type": "string", "format": "date-time", "nullable": true }, "Referrer": { "description": "Referrer (last cookie) of the customer.", "type": "string" }, "ReferrerChannel": { "description": "Referrer Channel of the customer.", "type": "string" }, "RegisterDate": { "description": "Registration date of the customer.", "type": "string", "format": "date-time" }, "PurchaseDate": { "description": "Purchase date of the customer.", "type": "string", "format": "date-time", "nullable": true }, "AdditionalFields": { "description": "Additional data for the customer.", "type": "object", "additionalProperties": { "type": "string" } }, "ReferenceCustomer": { "description": "Determines if the customer is a reference customer.", "type": "boolean" }, "ContactBan": { "description": "Determines if the customer has an active contact ban.", "type": "boolean" }, "ExternalCustomerID": { "description": "Deprecated, use ExternalID instead.", "type": "integer", "nullable": true, "deprecated": true }, "ExternalID": { "description": "ID/Number of the customer in the source system (e.g. an ERP System)", "type": "string", "nullable": true }, "ExternalCustomerExternalID": { "description": "Deprecated, use ExternalSourceCustomerID instead.", "type": "string", "nullable": true, "deprecated": true }, "ExternalSourceCustomerID": { "description": "ID/Number of the customer in a secondary source system (e.g. the shop)", "type": "string", "nullable": true }, "ExternalOrderType": { "description": "Deprecated, use ExternalType instead.", "type": "string", "nullable": true, "deprecated": true }, "ExternalType": { "description": "External type of the customer.", "type": "string", "nullable": true }, "ExternalOrderAccountID": { "description": "Deprecated, use ExternalAccountID instead.", "type": "integer", "nullable": true, "deprecated": true }, "ExternalAccountID": { "description": "External account ID of the customer.", "type": "string", "nullable": true }, "ExternalOrderSubAccountID": { "description": "Deprecated, use ExternalSourceID instead.", "type": "string", "nullable": true, "deprecated": true }, "ExternalSourceID": { "description": "External source ID of the customer.", "type": "string", "nullable": true }, "Marketplace": { "description": "Marketplace of the customer.", "type": "string" }, "TestUser": { "type": "boolean" }, "Newsletter": { "type": "boolean" }, "Segment": { "description": "Segment of the customer. Read-only, changes via the API will have no effect.", "type": "string" }, "CreationDate": { "description": "Creation Timestamp of the item. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time", "nullable": true }, "ModificationDate": { "description": "Timestamp of the last change of the item in the database. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "CustomerSearchResponseV4": { "title": "Customer Search Response", "required": [ "TotalCount", "CurrentPage", "PagesCount", "PageSize" ], "properties": { "Customers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerV4" }, "default": [] }, "TotalCount": { "description": "Total number of items.", "type": "integer" }, "CurrentPage": { "description": "Current page number.", "type": "integer" }, "PagesCount": { "description": "Total number of pages.", "type": "integer" }, "PageSize": { "description": "Number of items per page.", "type": "integer" } }, "type": "object" }, "TranslatedString": { "required": [ "de", "en" ], "properties": { "de": { "title": "German version of the string.", "type": "string" }, "en": { "title": "English version of the string.", "type": "string" } }, "type": "object" }, "FieldDefinition": { "required": [ "Name", "Description", "AllowedFilters" ], "properties": { "Name": { "$ref": "#/components/schemas/TranslatedString" }, "Description": { "$ref": "#/components/schemas/TranslatedString" }, "AllowedFilters": { "type": "array", "items": { "type": "string" } }, "AllowedValues": { "type": "object", "nullable": true, "additionalProperties": { "$ref": "#/components/schemas/TranslatedString" } } }, "type": "object" }, "FieldDefinitions": { "required": [ "Fields" ], "properties": { "Fields": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/FieldDefinition" } } }, "type": "object" }, "TaxClass": { "type": "string", "enum": [ "NormalTax", "ReducedTax", "HighlyReducedTax", "NoTax" ] }, "ProductSetPartV4": { "title": "Product Set Part", "required": [ "ProductID", "Quantity" ], "properties": { "ProductID": { "type": "string" }, "Quantity": { "type": "integer" } }, "type": "object" }, "ProductV4": { "title": "Product", "required": [ "Number", "EAN", "Name", "Manufacturer", "Vendor", "ShortDescription", "LongDescription", "ImageSource", "Active", "TaxClass", "Stock", "AdditionalFields", "PurchasePrice", "SalesPrice", "RecommendedRetailPrice" ], "properties": { "ID": { "description": "ID of the product. Set internally by Customa, any given value is ignored.", "type": "string", "nullable": true }, "Number": { "description": "Product number, MUST be unique.", "type": "string" }, "Parent": { "description": "ID of the parent product. The parent must be standalone and not have a parent itself.", "type": "string", "nullable": true }, "EAN": { "description": "EAN of the product.", "type": "string" }, "Name": { "description": "Name of the product.", "type": "string" }, "Manufacturer": { "description": "Manufacturer of the product.", "type": "string" }, "Vendor": { "description": "Vendor of the product.", "type": "string" }, "Category": { "description": "Category of the product.", "type": "string", "nullable": true }, "ShortDescription": { "description": "Short description of the product.", "type": "string" }, "LongDescription": { "description": "Long description of the product.", "type": "string" }, "ImageSource": { "description": "Source URI of the product image.", "type": "string" }, "Active": { "description": "Whether the product is active or inactive.", "type": "boolean" }, "TaxClass": { "$ref": "#/components/schemas/TaxClass" }, "Stock": { "description": "Stock of the product.", "type": "integer" }, "AdditionalFields": { "description": "Additional field data for the product.", "type": "object", "additionalProperties": { "type": "string" } }, "SetParts": { "description": "Parts of the product, if this product is a product set.", "type": "array", "items": { "$ref": "#/components/schemas/ProductSetPartV4" }, "nullable": true }, "PurchasePrice": { "$ref": "#/components/schemas/Price" }, "SalesPrice": { "$ref": "#/components/schemas/Price" }, "RecommendedRetailPrice": { "$ref": "#/components/schemas/Price" }, "CreationDate": { "description": "Creation Timestamp of the item. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time", "nullable": true }, "ModificationDate": { "description": "Timestamp of the last change of the item in the database. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "ProductSearchResponseV4": { "title": "Product Search Response", "required": [ "TotalCount", "CurrentPage", "PagesCount", "PageSize" ], "properties": { "Products": { "type": "array", "items": { "$ref": "#/components/schemas/ProductV4" }, "default": [] }, "TotalCount": { "description": "Total number of items.", "type": "integer" }, "CurrentPage": { "description": "Current page number.", "type": "integer" }, "PagesCount": { "description": "Total number of pages.", "type": "integer" }, "PageSize": { "description": "Number of items per page.", "type": "integer" } }, "type": "object" }, "Project": { "required": [ "Name", "AssignedModules" ], "properties": { "Name": { "title": "Name of the project.", "type": "string" }, "AssignedModules": { "title": "Modules assigned to the current user.", "type": "array", "items": { "type": "string" } } }, "type": "object" }, "ProjectList": { "required": [ "Projects" ], "properties": { "Projects": { "title": "A list of projects.", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Project" } } }, "type": "object" }, "ReceiptStatusV4": { "type": "string", "enum": [ "Open", "InProgress", "Completed", "Cancelled" ] }, "PaymentStatusV4": { "type": "string", "enum": [ "New", "Paid", "Cancelled", "PaidPartially", "Reminded", "InProgress", "Authorized", "Refunded", "RefundedPartially", "Failed", "Chargeback", "Unconfirmed" ] }, "DeliveryStatusV4": { "type": "string", "enum": [ "Open", "PartiallyShipped", "Shipped", "Returned", "PartiallyReturned", "Cancelled" ] }, "ReceiptItemV4": { "title": "Receipt Item", "required": [ "ProductID", "ProductNumber", "Quantity", "SellingPrice", "TaxClass" ], "properties": { "ProductID": { "description": "ID of the product.", "type": "string" }, "ProductNumber": { "description": "Product number of the product.", "type": "string" }, "Quantity": { "description": "Quantity of the product.", "type": "integer" }, "SellingPrice": { "$ref": "#/components/schemas/Price" }, "PurchasePrice": { "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/Price" } ] }, "TaxClass": { "$ref": "#/components/schemas/TaxClass" }, "CreationDate": { "description": "Creation Timestamp of the item. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time", "nullable": true }, "ModificationDate": { "description": "Timestamp of the last change of the item in the database. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "ReceiptV4": { "title": "Receipt", "required": [ "Type", "Number", "CustomerID", "Marketplace", "PurchaseDate", "PaymentMethod", "RevenueNet", "RevenueGross", "ReceiptStatus", "PaymentStatus", "DeliveryStatus", "AdditionalFields" ], "properties": { "ID": { "description": "ID of the receipt. Set internally by Customa, any given value is ignored.", "type": "string", "nullable": true }, "Type": { "description": "Type of the receipt.", "type": "string", "maxLength": 2, "minLength": 2 }, "Number": { "description": "Receipt number", "type": "string" }, "CustomerID": { "description": "ID of the customer.", "type": "string" }, "ExternalOrderType": { "description": "Deprecated, use ExternalType instead.", "type": "string", "nullable": true, "deprecated": true }, "ExternalOrderID": { "description": "Deprecated, use ExternalID instead.", "type": "integer", "nullable": true, "deprecated": true }, "ExternalOrderExternalID": { "description": "Deprecated, use ExternalSourceReceiptID instead.", "type": "string", "nullable": true, "deprecated": true }, "ExternalOrderAccountID": { "description": "Deprecated, use ExternalAccountID instead.", "type": "integer", "nullable": true, "deprecated": true }, "ExternalOrderSubAccountID": { "description": "Deprecated, use ExternalSourceID instead.", "type": "string", "nullable": true, "deprecated": true }, "ExternalType": { "description": "Type of the external source system this receipt originates from.", "type": "string", "nullable": true }, "ExternalID": { "description": "ID of the receipt in the external source system.", "type": "string", "nullable": true }, "ExternalSourceReceiptID": { "description": "Receipt ID as provided by the external source system.", "type": "string", "nullable": true }, "ExternalAccountID": { "description": "Account ID in the external source system.", "type": "string", "nullable": true }, "ExternalSourceID": { "description": "Source ID in the external source system.", "type": "string", "nullable": true }, "Marketplace": { "description": "Marketplace of the receipt.", "type": "string" }, "PurchaseDate": { "description": "Purchase date of the receipt.", "type": "string", "format": "date-time" }, "ReceiptDate": { "description": "Date of the receipt.", "type": "string", "format": "date-time", "nullable": true }, "Referrer": { "description": "Referrer (last cookie) of the customer when creating this receipt.", "type": "string", "nullable": true }, "ReferrerChannel": { "description": "Referrer Channel of the customer when creating this receipt.", "type": "string", "nullable": true }, "PaymentMethod": { "description": "Payment method of the receipt.", "type": "string" }, "RevenueNet": { "$ref": "#/components/schemas/Price" }, "RevenueGross": { "$ref": "#/components/schemas/Price" }, "ReceiptStatus": { "$ref": "#/components/schemas/ReceiptStatusV4" }, "PaymentStatus": { "$ref": "#/components/schemas/PaymentStatusV4" }, "DeliveryStatus": { "$ref": "#/components/schemas/DeliveryStatusV4" }, "Items": { "description": "List of items in the receipt.", "type": "array", "items": { "$ref": "#/components/schemas/ReceiptItemV4" }, "default": [] }, "AdditionalFields": { "description": "Additional field data for the receipt.", "type": "object", "additionalProperties": { "type": "string" } }, "CreationDate": { "description": "Creation Timestamp of the item. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time", "nullable": true }, "ModificationDate": { "description": "Timestamp of the last change of the item in the database. Set internally by Customa, any given value is ignored.", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "ReceiptSearchResponseV4": { "title": "Receipt Search Response", "required": [ "TotalCount", "CurrentPage", "PagesCount", "PageSize" ], "properties": { "Receipts": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptV4" }, "default": [] }, "TotalCount": { "description": "Total number of items.", "type": "integer" }, "CurrentPage": { "description": "Current page number.", "type": "integer" }, "PagesCount": { "description": "Total number of pages.", "type": "integer" }, "PageSize": { "description": "Number of items per page.", "type": "integer" } }, "type": "object" }, "SettingMarketplaceValue": { "title": "Setting Marketplace Value", "properties": { "Value": { "description": "The current value as string. Null for confidential settings.", "type": "string", "nullable": true }, "HasValue": { "description": "Whether a non-null value exists. True even for confidential settings.", "type": "boolean", "default": false } }, "type": "object" }, "SettingValueRequest": { "title": "Setting Value Request", "properties": { "Value": { "description": "The new value as string. Pass null or empty string to clear.", "type": "string", "nullable": true } }, "type": "object" }, "StatsGroupings": { "required": [ "Groupings" ], "properties": { "Groupings": { "title": "A map of grouping types.", "type": "object", "additionalProperties": { "type": "string" } } }, "type": "object" }, "TrafficFiltersResponse": { "title": "Traffic Filters Response", "required": [ "Groupings", "Sources", "Marketplaces", "Campaigns" ], "properties": { "Groupings": { "description": "Available grouping options. Key is display label, value is the grouping identifier.", "type": "object", "additionalProperties": { "type": "string" } }, "Sources": { "description": "Available data sources. Key is display label, value is the source identifier.", "type": "object", "additionalProperties": { "type": "string" } }, "Marketplaces": { "description": "Available marketplaces. Key is display label, value is the marketplace ID as string.", "type": "object", "additionalProperties": { "type": "string" } }, "Campaigns": { "description": "Available campaigns. Key is campaign name, value is the campaign ID as string.", "type": "object", "additionalProperties": { "type": "string" } } }, "type": "object" }, "TrafficRequest": { "title": "Traffic Request", "required": [ "StartDate", "EndDate" ], "properties": { "StartDate": { "description": "Start date in YYYY-MM-DD format.", "type": "string", "example": "2024-01-01" }, "EndDate": { "description": "End date in YYYY-MM-DD format.", "type": "string", "example": "2024-01-31" }, "Grouping": { "description": "Grouping dimension.", "type": "string", "example": "day", "default": "day", "enum": [ "day", "month", "year", "source", "campaign", "campaigngroup", "marketplace" ] }, "Source": { "description": "Data source filter (e.g. gads, bads, gsc, mads). Null means no filter.", "type": "string", "nullable": true }, "MarketplaceId": { "description": "Marketplace ID filter. Null means no filter.", "type": "integer", "nullable": true }, "CampaignId": { "description": "Campaign ID filter. Null means no filter.", "type": "integer", "nullable": true } }, "type": "object" }, "TrafficRow": { "title": "Traffic Group", "required": [ "GroupKey", "GroupName", "Impressions", "Clicks", "Ctr", "Conversions", "ConversionRate", "Costs", "Cpc", "Revenue", "Kur" ], "properties": { "GroupKey": { "description": "Group key (date, campaign name, source, etc.)", "type": "string" }, "GroupName": { "description": "Display name for the group.", "type": "string" }, "Impressions": { "description": "Total impressions.", "type": "number", "format": "float" }, "Clicks": { "description": "Total clicks.", "type": "number", "format": "float" }, "Ctr": { "description": "Click-through rate (clicks / impressions).", "type": "number", "format": "float" }, "Conversions": { "description": "Total conversions.", "type": "number", "format": "float" }, "ConversionRate": { "description": "Conversion rate (conversions / clicks).", "type": "number", "format": "float" }, "Costs": { "description": "Total costs.", "type": "number", "format": "float" }, "Cpc": { "description": "Cost per click (costs / clicks).", "type": "number", "format": "float" }, "Revenue": { "description": "Total revenue.", "type": "number", "format": "float" }, "Kur": { "description": "Cost-revenue ratio (costs / revenue).", "type": "number", "format": "float" } }, "type": "object" }, "TrafficResponse": { "title": "Traffic Response", "required": [ "Currency" ], "properties": { "Groups": { "description": "List of traffic data groups.", "type": "array", "items": { "$ref": "#/components/schemas/TrafficRow" }, "default": [] }, "Currency": { "description": "Currency display symbol for cost/revenue values.", "type": "string", "example": "\u20ac" } }, "type": "object" } }, "securitySchemes": { "apiV3Token": { "type": "http", "scheme": "bearer" }, "apiV4Token": { "type": "http", "scheme": "bearer" }, "apiV4BasicAuth": { "type": "http", "scheme": "basic" } } }, "tags": [ { "name": "auth", "description": "auth" }, { "name": "customer", "description": "customer" }, { "name": "product", "description": "product" }, { "name": "receipt", "description": "receipt" }, { "name": "segment", "description": "segment" }, { "name": "settings", "description": "settings" }, { "name": "stats", "description": "stats" }, { "name": "category", "description": "category" }, { "name": "project", "description": "project" }, { "name": "traffic", "description": "traffic" } ] }