{ "openapi": "3.0.0", "info": { "title": "AUSGEZEICHNET REST API", "description": " First version of the Ausgezeichnet REST API. \n## Authentication \n\nIn each HTTP request, the following HTTP header is required:\n\n ```\n# API Key\n x-api-key: \n```\n\n \n## Date format\nWe use the timezone `Europe/Berlin`.\n* **date** = *Y-m-d* = `2024-12-31`\n ", "version": "1.0.0" }, "paths": { "/api/v1/invitations": { "post": { "tags": [ "Invitations" ], "summary": "Create a review invitation", "description": "Submit a company or product review invitation email to a customer.\n\n**Authentication:** Send your organization API key in the `X-API-KEY` header.\n\n**Prerequisites**\n- Organization must have the `REVIEW_API` feature enabled (included from Professional upward, or bookable).\n- For `product_review`: organization must have `PRODUCT_RATING` enabled and the `sku` must exist in the organization catalog.\n\n**Email delivery**\n- Invitation emails are sent by the platform. No organization mail server setup is required.\n\n**Security**\n- Treat `invitation_url` in the response as a secret link. Do not log it, expose it in public pages, or share it outside your integration.\n- The request body may be stored as rating metadata when the customer submits a review. Do not send secrets, payment data, or unnecessary PII.\n\n**Invitation types**\n- `company_review` \u2014 sends a company review invitation. Optional `collection_method` controls how the rating URL is generated (default: `after_fulfillment`).\n- `product_review` \u2014 sends a product review invitation. Requires `sku`. The `collection_method` field is ignored for product invitations.\n\n**Minimal payload**\n- `company_review`: `type`, `email`, `name`, `source`, and optionally `collection_method` (default `after_fulfillment`).\n- `product_review`: `type`, `email`, `name`, `sku`, and `source`.\n- `external_reference` is optional. When omitted, retries for the same invitation are detected automatically.\n\n**source** (required)\n- Identifies the calling shop system. **Allowed values:** `woocommerce`, `shopify`, `wordpress`.\n- Values are normalized to lowercase (e.g. `WooCommerce` \u2192 rejected; use `woocommerce`).\n- Used as the rating `source` on the invitation URL.\n- Invalid or missing `source` returns `400` with error key `invite_api.source_is_required` or `invite_api.invalid_integration_source`.\n\n**client_id** (optional)\n- Optional metadata from the calling system (e.g. shop identifier). Stored in rating metadata when the customer submits a review.\n\n**locale** (optional)\n- Email locale for the invitation. Accepts BCP 47 (`en-US`, `de-DE`) or short codes `en` and `de`.\n\n**collection_method** (company_review only)\n- Allowed values: `after_fulfillment`, `point_of_sale`\n- Default when omitted: `after_fulfillment`\n\n**Idempotency**\n- When `external_reference` is provided: a duplicate request returns `already_exists` if the same **email**, **external_reference**, and **SKU** (for product invitations) were already used for your organization.\n- When `external_reference` is omitted: retrying the same invitation request is treated as a duplicate.\n- `product_review`: The **Allow multiple reviews per email address** setting does not apply to product invitations.\n- `company_review`: when **Allow multiple reviews per email address** is enabled, each request without `external_reference` receives a new invitation; otherwise duplicate detection uses email only.\n\n**Multiple products (product_review only)**\n- Pass comma-separated SKUs in the `sku` field (e.g. `\"SKU-A, SKU-B\"`) to invite the customer to review multiple products in one request.\n- Creates one invitation record per SKU, linked by a shared `bundle_id`. **One email** is sent to the customer with a bundle rating URL, where they can review all products on a single page.\n- Duplicate detection is per SKU.\n- Response is an array of per-SKU results (`sku`, `invitation_status`, plus invitation fields). New SKUs return `invitation_status: created`; duplicates return `invitation_status: already_exists`. All newly created invitations in the bundle share the same `invitation_url`.\n- If some SKUs are new and others are duplicates, the new invitations are created and **one** bundle email is sent; duplicate SKUs are reported with `invitation_status: already_exists`.\n- If **all** SKUs are duplicates, the response is `400 invitation already exists`.\n\n**Scheduling (optional)**\n- Omit both `send_at` and `delay_days` to send immediately.\n- Use `send_at` (ISO 8601) **or** `delay_days` (integer \u2265 0), not both.\n- Scheduled invitations return `202` and are processed by a background job when due.", "operationId": "post_api_invitations_create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "email", "name", "source" ], "properties": { "type": { "description": "Invitation type. Use `company_review` for company ratings or `product_review` for product ratings.", "type": "string", "example": "product_review", "enum": [ "company_review", "product_review" ] }, "email": { "description": "Customer email address that receives the invitation.", "type": "string", "format": "email", "example": "customer@example.com" }, "name": { "description": "Customer display name used in the email greeting.", "type": "string", "example": "Max Mustermann" }, "external_reference": { "description": "Optional. Your unique reference (e.g. order ID). Used for idempotency when provided.", "type": "string", "example": "ORDER-100045" }, "sku": { "description": "Product SKU. **Required** when `type` is `product_review`. Must match an existing product SKU in your organization. Supports comma-separated values for multiple products (e.g. `SKU-12345, SKU-67890`); creates one invitation per SKU in a shared bundle and sends **one** bundle email.", "type": "string", "example": "SKU-12345" }, "source": { "description": "**Required.** Integration source that identifies your shop system. Must be exactly one of: `woocommerce`, `shopify`, `wordpress`. Becomes the rating `source` on the invitation link.", "type": "string", "example": "woocommerce", "enum": [ "woocommerce", "shopify", "wordpress" ] }, "client_id": { "description": "Optional metadata from the calling system (e.g. shop identifier). Stored in rating metadata when the customer submits a review.", "type": "string", "example": "shop-123" }, "locale": { "description": "Email locale for the invitation. Accepts BCP 47 (`en-US`, `de-DE`) or short codes `en` and `de`.", "type": "string", "example": "en-US" }, "collection_method": { "description": "Only applies to `company_review`. Allowed values: `after_fulfillment`, `point_of_sale`. Default: `after_fulfillment`.", "type": "string", "example": "after_fulfillment", "enum": [ "after_fulfillment", "point_of_sale" ] }, "send_at": { "description": "Schedule sending at this ISO 8601 datetime. Mutually exclusive with `delay_days`.", "type": "string", "format": "date-time", "example": "2026-06-20T10:00:00+02:00" }, "delay_days": { "description": "Schedule sending after N days from now. `0` means send immediately. Mutually exclusive with `send_at`.", "type": "integer", "example": 7, "minimum": 0 } }, "type": "object" }, "examples": { "minimal_company_review": { "summary": "Minimal company review payload", "description": "Minimum fields required for a company review invitation.", "value": { "type": "company_review", "email": "customer@example.com", "name": "Max Mustermann", "source": "woocommerce", "collection_method": "after_fulfillment" } }, "minimal_product_review": { "summary": "Minimal product review payload", "description": "Minimum fields required for a product review invitation.", "value": { "type": "product_review", "email": "customer@example.com", "name": "Max Mustermann", "sku": "SKU-12345", "source": "woocommerce" } }, "company_review": { "summary": "Company review invitation", "description": "Send a company review invite after order fulfillment.", "value": { "type": "company_review", "email": "customer@example.com", "name": "Max Mustermann", "external_reference": "ORDER-100045", "source": "woocommerce", "client_id": "shop-123", "locale": "en-US", "collection_method": "after_fulfillment" } }, "product_review": { "summary": "Product review invitation", "description": "Send a product review invite for a specific SKU.", "value": { "type": "product_review", "email": "customer@example.com", "name": "Max Mustermann", "sku": "SKU-12345", "external_reference": "ORDER-100045", "source": "shopify", "client_id": "shop-123" } }, "multi_product_review": { "summary": "Multi-product review invitation", "description": "Send one bundle email for multiple SKUs. Each SKU gets its own invitation record; the customer reviews all products on one bundle page.", "value": { "type": "product_review", "email": "customer@example.com", "name": "Max Mustermann", "sku": "SKU-12345, SKU-67890", "external_reference": "ORDER-100045", "source": "woocommerce" } }, "scheduled_product_review": { "summary": "Scheduled product review invitation", "description": "Schedule a product invite 7 days after the request.", "value": { "type": "product_review", "email": "customer@example.com", "name": "Max Mustermann", "sku": "SKU-12345", "external_reference": "ORDER-100046", "source": "wordpress", "delay_days": 7 } } } } } }, "responses": { "201": { "description": "Invitation created and email sent immediately.", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 201 }, "message": { "type": "string", "example": "created" }, "data": { "properties": { "id": { "type": "string", "example": "665f1a2b3c4d5e6f7a8b9c0d" }, "type": { "type": "string", "example": "product_review" }, "external_reference": { "type": "string", "example": "ORDER-100045" }, "status": { "type": "string", "example": "sent" }, "invitation_url": { "description": "Secret rating link for the customer. Treat as confidential; do not log or expose publicly.", "type": "string", "example": "https://www.ausgezeichnet.org/bewerten-produkt/acme-shop/SKU-12345?locale=de-DE&source=woocommerce&invitation_id=..." }, "sent_at": { "type": "string", "format": "date-time", "example": "2026-06-16T12:00:00+02:00" } }, "type": "object" } }, "type": "object" } } } }, "202": { "description": "Invitation accepted and scheduled for later delivery.", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 202 }, "message": { "type": "string", "example": "scheduled" }, "data": { "properties": { "id": { "type": "string", "example": "665f1a2b3c4d5e6f7a8b9c0d" }, "type": { "type": "string", "example": "product_review" }, "external_reference": { "type": "string", "example": "ORDER-100046" }, "status": { "type": "string", "example": "pending" }, "invitation_url": { "type": "string", "example": null, "nullable": true }, "scheduled_at": { "type": "string", "format": "date-time", "example": "2026-06-23T12:00:00+02:00" } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Bad request (validation error or duplicate invitation).", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "validation_failed" }, "data": { "type": "array", "items": { "type": "string" }, "example": [] }, "errors": { "description": "Field-level error codes. Only failed fields are present.", "properties": { "sku": { "type": "string", "example": "sku_not_found" }, "email": { "type": "string", "example": "invalid_email" }, "type": { "type": "string", "example": "invalid_invitation_type" }, "feature": { "type": "string", "example": "invite_api.upgrade_package_required" }, "product_rating": { "type": "string", "example": "invite_api.product_rating_purchase_required" }, "source": { "description": "Also `invite_api.invalid_integration_source` when the value is not `woocommerce`, `shopify`, or `wordpress`.", "type": "string", "example": "invite_api.source_is_required" }, "schedule": { "type": "string", "example": "invite_api.send_at_and_delay_days_conflict" } }, "type": "object" } }, "type": "object" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 401 }, "message": { "type": "string", "example": "Unauthorized" } }, "type": "object" } } } }, "500": { "description": "Email delivery failed after the invitation was accepted.", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 500 }, "message": { "type": "string", "example": "invitation_send_failed" } }, "type": "object" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/ratings/{id}/comment": { "post": { "tags": [ "Ratings" ], "summary": "Post a public comment on a rating", "description": "Creates or replaces the public organization response on a specific rating.", "operationId": "post_api_ratings_comment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "5f7b1b1b7f0000a000000000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "comment" ], "properties": { "comment": { "type": "string", "example": "Thank you for your feedback!", "maxLength": 2000 } }, "type": "object" }, "example": { "comment": "Thank you for your feedback!" } } } }, "responses": { "200": { "description": "Comment saved", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "type": "string" }, "example": [] } }, "type": "object" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "comment is required" } }, "type": "object" } } } }, "404": { "description": "Rating not found", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Rating not found" } }, "type": "object" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/ratings": { "get": { "tags": [ "Ratings" ], "summary": "Fetch Ratings", "description": "Fetch published ratings based on the given filter criteria.", "operationId": "get_api_ratings_index", "parameters": [ { "name": "collectionMethod", "in": "query", "description": "Collection method of the ratings", "required": false, "schema": { "type": "string", "example": "after_fulfillment", "enum": [ "unsolicited", "after_fulfillment", "point_of_sale" ] } }, { "name": "startDate", "in": "query", "description": "Start date of the ratings", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-01-01" } }, { "name": "endDate", "in": "query", "description": "End date of the ratings", "required": false, "schema": { "type": "string", "format": "date", "example": "2024-12-31" } }, { "name": "score", "in": "query", "description": "Score of the ratings (1-5)", "required": false, "schema": { "type": "integer", "example": 5, "maximum": 5, "minimum": 1 } }, { "name": "perPage", "in": "query", "description": "Number of items per page", "required": false, "schema": { "type": "integer", "example": 15, "maximum": 1000, "minimum": 1 } }, { "name": "page", "in": "query", "description": "Page number", "required": false, "schema": { "type": "integer", "example": 1, "minimum": 1 } }, { "name": "sortField", "in": "query", "description": "Field to sort by", "required": false, "schema": { "type": "string", "example": "createdAt", "enum": [ "createdAt", "score" ] } }, { "name": "sortDirection", "in": "query", "description": "Sort direction", "required": false, "schema": { "type": "string", "example": "desc", "enum": [ "asc", "desc" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "success" }, "pagination": { "properties": { "totalItems": { "type": "integer", "example": 1 }, "itemsPerPage": { "type": "integer", "example": 15 }, "currentPage": { "type": "integer", "example": 1 }, "totalPages": { "type": "integer", "example": 1 } }, "type": "object" }, "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "5f7b1b1b7f0000a000000000" }, "organization": { "type": "string", "example": "Organization Name" }, "organizationAccountNo": { "type": "integer", "example": 123456 }, "detailRatingLink": { "type": "string", "example": "https://example.com/bewertung/example-org/abc123/great-service/5f7b1b1b7f0000a000000000" }, "collectionMethod": { "type": "string", "example": "after_fulfillment" }, "raterName": { "type": "string", "example": "John Doe" }, "score": { "type": "number", "example": 5 }, "title": { "type": "string", "example": "Great service" }, "description": { "type": "string", "example": "Very satisfied with the product and delivery." }, "orderDate": { "type": "string", "format": "date", "example": "2024-12-31" }, "orderNumber": { "type": "string", "example": "123456" }, "isPublished": { "type": "boolean", "example": true }, "isChanged": { "type": "boolean", "example": false }, "country": { "type": "string", "example": "DE" }, "verifiedAt": { "type": "string", "format": "date", "example": "2024-12-31" }, "comment": { "type": "string", "example": "Thank you for your feedback!" }, "createdAt": { "type": "string", "format": "date", "example": "2024-12-31" }, "isConciliation": { "type": "boolean", "example": false }, "deletedAt": { "type": "string", "format": "date", "example": null, "nullable": true } }, "type": "object" }, "example": [ { "id": "5f7b1b1b7f0000a000000000", "organization": "Organization Name", "organizationAccountNo": 123456, "detailRatingLink": "https://example.com/bewertung/example-org/abc123/great-service/5f7b1b1b7f0000a000000000", "collectionMethod": "after_fulfillment", "raterName": "John Doe", "score": 5, "title": "Great service", "description": "Very satisfied with the product and delivery.", "orderDate": "2024-12-31", "orderNumber": "123456", "isPublished": true, "isChanged": false, "country": "DE", "verifiedAt": "2024-12-31", "comment": "Thank you for your feedback!", "createdAt": "2024-12-31", "isConciliation": false, "deletedAt": null } ] } }, "type": "object" }, "example": { "code": 200, "message": "success", "pagination": { "totalItems": 1, "itemsPerPage": 15, "currentPage": 1, "totalPages": 1 }, "data": [ { "id": "5f7b1b1b7f0000a000000000", "organization": "Organization Name", "organizationAccountNo": 123456, "detailRatingLink": "https://example.com/bewertung/example-org/abc123/great-service/5f7b1b1b7f0000a000000000", "collectionMethod": "after_fulfillment", "raterName": "John Doe", "score": 5, "title": "Great service", "description": "Very satisfied with the product and delivery.", "orderDate": "2024-12-31", "orderNumber": "123456", "isPublished": true, "isChanged": false, "country": "DE", "verifiedAt": "2024-12-31", "comment": "Thank you for your feedback!", "createdAt": "2024-12-31", "isConciliation": false, "deletedAt": null } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Validation error" }, "errors": { "type": "object", "example": { "collectionMethod": "This value is not valid.", "startDate": "This value is not valid." } } }, "type": "object" } } } } }, "security": [ { "apiKey": [] } ] } }, "/api/v1/ratings/{id}": { "get": { "tags": [ "Ratings" ], "summary": "Fetch published rating details", "description": "Fetch a specific rating by its ID.", "operationId": "get_api_ratings_detail", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "example": "5f7b1b1b7f0000a000000000" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "success" }, "data": { "properties": { "id": { "type": "string", "example": "5f7b1b1b7f0000a000000000" }, "organization": { "type": "string", "example": "Organization Name" }, "organizationAccountNo": { "type": "integer", "example": 123456 }, "detailRatingLink": { "type": "string", "example": "https://example.com/bewertung/example-org/abc123/great-service/5f7b1b1b7f0000a000000000" }, "collectionMethod": { "type": "string", "example": "after_fulfillment" }, "raterName": { "type": "string", "example": "John Doe" }, "score": { "type": "number", "example": 5 }, "title": { "type": "string", "example": "Great service" }, "description": { "type": "string", "example": "Very satisfied with the product and delivery." }, "orderDate": { "type": "string", "format": "date", "example": "2024-12-31" }, "orderNumber": { "type": "string", "example": "123456" }, "isPublished": { "type": "boolean", "example": true }, "isChanged": { "type": "boolean", "example": false }, "country": { "type": "string", "example": "DE" }, "verifiedAt": { "type": "string", "format": "date", "example": "2024-12-31" }, "comment": { "type": "string", "example": "Thank you for your feedback!" }, "createdAt": { "type": "string", "format": "date", "example": "2024-12-31" }, "isConciliation": { "type": "boolean", "example": false }, "deletedAt": { "type": "string", "format": "date", "example": null, "nullable": true } }, "type": "object", "example": { "id": "5f7b1b1b7f0000a000000000", "organization": "Organization Name", "organizationAccountNo": 123456, "detailRatingLink": "https://example.com/bewertung/example-org/abc123/great-service/5f7b1b1b7f0000a000000000", "collectionMethod": "after_fulfillment", "raterName": "John Doe", "score": 5, "title": "Great service", "description": "Very satisfied with the product and delivery.", "orderDate": "2024-12-31", "orderNumber": "123456", "isPublished": true, "isChanged": false, "country": "DE", "verifiedAt": "2024-12-31", "comment": "Thank you for your feedback!", "createdAt": "2024-12-31", "isConciliation": false, "deletedAt": null } } }, "type": "object" }, "example": { "code": 200, "message": "success", "data": { "id": "5f7b1b1b7f0000a000000000", "organization": "Organization Name", "organizationAccountNo": 123456, "detailRatingLink": "https://example.com/bewertung/example-org/abc123/great-service/5f7b1b1b7f0000a000000000", "collectionMethod": "after_fulfillment", "raterName": "John Doe", "score": 5, "title": "Great service", "description": "Very satisfied with the product and delivery.", "orderDate": "2024-12-31", "orderNumber": "123456", "isPublished": true, "isChanged": false, "country": "DE", "verifiedAt": "2024-12-31", "comment": "Thank you for your feedback!", "createdAt": "2024-12-31", "isConciliation": false, "deletedAt": null } } } } }, "404": { "description": "Rating not found", "content": { "application/json": { "schema": { "properties": { "code": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Rating not found" } }, "type": "object" } } } } }, "security": [ { "apiKey": [] } ] } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "description": "Please use the following Format: **X-API-KEY **", "name": "X-API-KEY", "in": "header" } } }, "security": [ { "apiKey": [] } ], "tags": [ { "name": "Invitations", "description": "Submit company and product review invitations from WooCommerce, Shopify, or WordPress. Requires `source` (`woocommerce`, `shopify`, or `wordpress`)." }, { "name": "Ratings", "description": "Fetch published ratings and post public organization comments" } ] }