### Shopware Version Response Example Source: https://github.com/shopware/admin-api-reference/blob/main/docs/guides/quick-start/01-introduction.md An example of the JSON response received when querying the Shopware version endpoint. ```json { "version": "6.5.3.0" } ``` -------------------------------- ### Shopware Admin API Base Route Example Source: https://github.com/shopware/admin-api-reference/blob/main/docs/guides/quick-start/01-introduction.md Illustrates the base route for the Shopware Admin API, which is relative to your Shopware instance host. ```text https://shop.example.com/api/ ``` -------------------------------- ### Shopware Admin API Base Endpoint Example Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/request-response-structure.md This is the base URL to which all other Admin API endpoints are relative. Replace 'shop.example.com' with your actual Shopware host URL. ```text https://shop.example.com/api ``` -------------------------------- ### HTTP Request for Creating a Product (with errors) Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/writing-entities/README.md Illustrates a POST request to create a product entity. This example shows a scenario where required fields are missing, leading to API errors. ```http { "method": "POST", "url": "http://localhost/api/product", "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN" }, "body": { "name" : "test" } } ``` -------------------------------- ### Create a CMS Layout/Page Source: https://github.com/shopware/admin-api-reference/blob/main/docs/guides/quick-start/06-cms-handling.md This example demonstrates how to create a new CMS layout or page by providing its structure, including sections, blocks, and slots, in the request body. ```APIDOC ## POST /api/cms-page ### Description Creates a new CMS layout or page. ### Method POST ### Endpoint /api/cms-page ### Request Body - **name** (string) - Required - The name of the CMS page. - **type** (string) - Required - The type of the CMS page (e.g., "landingpage"). - **sections** (array) - Required - An array of section objects that define the layout. - **position** (integer) - Required - The order of the section. - **type** (string) - Required - The type of the section (e.g., "default"). - **sizingMode** (string) - Optional - The sizing mode of the section (`boxed` or `full-width`). - **backgroundColor** (string) - Optional - The background color of the section (hex code). - **pageId** (string) - Required - The unique ID of the page this section belongs to. - **blocks** (array) - Required - An array of block objects within the section. - **position** (integer) - Required - The order of the block. - **type** (string) - Required - The type of the block (e.g., "image-text"). - **sectionPosition** (string) - Optional - The position of the block within the section (`main` or `side-bar`). - **marginTop** (string) - Optional - The top margin of the block. - **marginBottom** (string) - Optional - The bottom margin of the block. - **marginLeft** (string) - Optional - The left margin of the block. - **marginRight** (string) - Optional - The right margin of the block. - **backgroundColor** (string) - Optional - The background color of the block (hex code). - **slots** (array) - Required - An array of slot objects within the block. - **type** (string) - Required - The type of the slot (e.g., "text", "image"). - **slot** (string) - Optional - The position of the slot (`right` or `left`). - **config** (object) - Optional - Configuration for the slot content and styling. - **content** (object) - Required - The content of the slot. - **value** (string) - Required - The actual content value. - **source** (string) - Required - The source of the content (e.g., "static"). ### Request Example ```json { "name": "Summer BBQ", "type": "landingpage", "sections": [ { "position": 1, "type": "default", "sizingMode": "boxed", "backgroundColor": "#c9e4e6ff", "pageId": "f565491912994bcca19657c40b646836", "blocks": [ { "position": 0, "type": "image-text", "sectionPosition": "main", "marginTop": "169px", "marginBottom": "169px", "marginLeft": "20px", "marginRight": "20px", "backgroundColor": "#c9e4e6ff", "sectionId": "034982027a3f41f99981ba6886dc38f4", "slots": [ { "type": "text", "slot": "right", "config": { "content": { "value": "S U M M E R   T R E N D S

Be prepared for the best?
party this summer

Summer is finally here and lures us outside with its warm rays of sunshine. The heat is better tolerated with cool snacks, drinks and fresh treats.

Check out Summer Trends
", "source": "static" } }, "blockId": "99a324f2f2dd4f76a36700bae20977f5" } ] } ] } ] } ``` ``` -------------------------------- ### Update Product Stocks Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/writing-entities/bulk-payloads.md Example of updating product stocks in bulk using the `/api/_action/sync` endpoint. ```APIDOC ## Update Product Stocks This example demonstrates how to perform bulk updates on product stocks. ### Method POST ### Endpoint /api/_action/sync ### Request Body - **stock-updates** (object) - A transaction for updating product stocks. - **entity**: "product" - **action**: "upsert" - **payload**: An array of objects, each representing a product stock update. Requires `id` for each object. - **id** (string) - The UUID of the product. - **stock** (integer) - The new stock quantity. ### Request Example ```json { "method": "POST", "url": "http://localhost/api/_action/sync", "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN" }, "body": { "stock-updates": { "entity": "product", "action": "upsert", "payload": [ { "id": "", "stock": 42 }, { "id": "", "stock": 42 }, { "id": "", "stock": 42 } ] } } } ``` ``` -------------------------------- ### Get Shopware Version using Bearer Token Source: https://github.com/shopware/admin-api-reference/blob/main/docs/guides/quick-start/01-introduction.md Demonstrates how to make a GET request to retrieve the Shopware version after obtaining an access token. Ensure to replace YOUR_ACCESS_TOKEN with your actual token. ```json { "method": "get", "url": "http://localhost/api/_info/version", "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN" } } ``` -------------------------------- ### HTTP Request for Creating a Product (successful) Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/writing-entities/README.md An example of a successful POST request to create a product entity, including all necessary fields such as name, productNumber, stock, price, and tax details. ```http { "method": "POST", "url": "http://localhost/api/product", "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN" }, "body": { "name" : "test", "productNumber" : "random", "stock" : 10, "price" : [ { "currencyId" : "b7d2554b0ce847cd82f3ac9bd1c0dfca", "gross": 15, "net": 10, "linked" : false } ], "tax" : { "name": "test", "taxRate": 15 } } } ``` -------------------------------- ### Assigning Properties and Categories Source: https://github.com/shopware/admin-api-reference/blob/main/docs/guides/quick-start/02-product-management.md Example payload for assigning multiple properties and categories to a product. ```APIDOC ## Assigning Properties and Categories ### Description This endpoint allows for the assignment of multiple properties and categories to a product. ### Request Body - **name** (string) - Required - The name of the product. - **productNumber** (string) - Required - The unique product number. - **stock** (integer) - Required - The current stock level. - **taxId** (string) - Required - The ID of the tax rule. - **properties** (array) - Optional - A list of property objects to assign. - **id** (string) - Required - The ID of the property. - **categories** (array) - Optional - A list of category objects to assign. - **id** (string) - Required - The ID of the category. ### Request Example ```json { "name": "test", "productNumber": "random", "stock": 10, "taxId": "db6f3ed762d14b0395a3fd2dc460db42", "properties": [ { "id": "b6dd111fff0f4e3abebb88d02fe2021e"}, { "id": "b9f4908785ef4902b8d9e64260f565ae"} ], "categories": [ { "id": "b7d2554b0ce847cd82f3ac9bd1c0dfca" }, { "id": "cdea94b4f9452254a20b91ec1cd538b9" } ] } ``` ``` -------------------------------- ### Create a parent product with variants Source: https://context7.com/shopware/admin-api-reference/llms.txt This example demonstrates creating a parent product that includes multiple variants. The parent product defines general information and `configuratorSettings`, while `children` array specifies individual variants with their unique `productNumber`, `stock`, and `options`. ```bash curl -X POST https://shop.example.com/api/product \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJ0..." \ -d '{ "name": "Classic T-Shirt", "productNumber": "TSHIRT-CLASSIC", "stock": 0, "taxId": "9d4a11eeaf3a41bea44fdfb599d57058", "price": [{ "currencyId": "b7d2554b0ce847cd82f3ac9bd1c0dfca", "gross": 19.99, "net": 16.80, "linked": true }], "configuratorSettings": [ { "optionId": "0b9627a94fc2446498ec6abac0f03581" }, { "optionId": "4053fb11b4114d2cac7381c904651b6b" }, { "optionId": "ae821a4395f34b22b6dea9963c7406f2" }, { "optionId": "ea14a701771148d6b04045f99c502829" } ], "children": [ { "productNumber": "TSHIRT-RED-XL", "stock": 10, "options": [{ "id": "0b9627a94fc2446498ec6abac0f03581" }, { "id": "ea14a701771148d6b04045f99c502829" }] }, { "productNumber": "TSHIRT-RED-L", "stock": 15, "options": [{ "id": "0b9627a94fc2446498ec6abac0f03581" }, { "id": "4053fb11b4114d2cac7381c904651b6b" }] }, { "productNumber": "TSHIRT-YEL-XL", "stock": 8, "options": [{ "id": "ae821a4395f34b22b6dea9963c7406f2" }, { "id": "ea14a701771148d6b04045f99c502829" }] }, { "productNumber": "TSHIRT-YEL-L", "stock": 12, "options": [{ "id": "ae821a4395f34b22b6dea9963c7406f2" }, { "id": "4053fb11b4114d2cac7381c904651b6b" }] } ] }' ``` -------------------------------- ### Shopware Admin API Request Body Example Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/request-response-structure.md An example of a JSON-encoded request body for the Shopware Admin API. ```APIDOC ## Request Body Example ```json { "id": "01bd7e70a50443ec96a01fd34890dcc5", "name": "Example product", "taxId": "792203a53e564e28bcb7ffa1867fb485", "stock": 708, "createdAt": "2018-09-13T10:17:05+02:00" } ``` ``` -------------------------------- ### Define Product Prices in Multiple Currencies Source: https://github.com/shopware/admin-api-reference/blob/main/docs/guides/quick-start/02-product-management.md This JavaScript example demonstrates how to define prices for a product in different currencies. Each price entry requires a currency ID, gross, net, and linked status. ```javascript { "name": "test", "productNumber": "random", "stock": 10, "taxId": "db6f3ed762d14b0395a3fd2dc460db42", "price": [ { // euro price "currencyId" : "db6f3ed762d14b0395a3fd2dc460db42", "gross": 15, "net": 10, "linked" : false }, { // dollar price "currencyId" : "16a190bd85b741c08873cfeaeb0ad8e1", "gross": 120, "net": 100.84, "linked" : true }, { // pound price "currencyId" : "b7d2554b0ce847cd82f3ac9bd1c0dfca", "gross": 66, "net": 55.46, "linked" : true } ] } ``` -------------------------------- ### Creating a Product Variant with Specific Price Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/writing-entities/product-data.md This example demonstrates how to create a product variant with its own defined price, overriding the parent product's price. ```APIDOC ## POST /api/product ### Description Creates a new product or product variant. This example shows how to set a specific price for a variant. ### Method POST ### Endpoint /api/product ### Request Body - **id** (string) - Required - The unique identifier for the product. - **parentId** (string) - Optional - The ID of the parent product if this is a variant. - **productNumber** (string) - Required - The product number for the variant. - **stock** (integer) - Required - The stock quantity. - **options** (array) - Optional - An array of option IDs for the variant. - **price** (array) - Optional - An array of price definitions for the variant. - **currencyId** (string) - Required - The ID of the currency. - **gross** (number) - Required - The gross price. - **net** (number) - Required - The net price. - **linked** (boolean) - Required - Whether the price is linked. ### Request Example ```json { "id": "0d0adf2a3aa1488eb177288cfac9d47e", "parentId": "17f255e0a12848c38b7ec6767a6d6adf", "productNumber": "child.1", "stock": 10, "options": [ {"id": "0584efb5f86142aaac44cc3beeeeb84f"}, {"id": "0a30f132eb1b4f34a05dcb1c6493ced7"} ], "price": [ { "currencyId" : "b7d2554b0ce847cd82f3ac9bd1c0dfca", "gross": 15, "net": 10, "linked" : false } ] } ``` ### Response #### Success Response (200) - **id** (string) - The ID of the created product. - **message** (string) - A success message. #### Response Example ```json { "id": "0d0adf2a3aa1488eb177288cfac9d47e", "message": "Product created successfully." } ``` ``` -------------------------------- ### PHP Example for Hashing Primary Keys Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/writing-entities/README.md Demonstrates how to hash a record's unique identifier to use as a Shopware ID for import purposes. This pattern can also be applied to related entities. ```php $payload[] = [ 'id' => md5($product->getUniqueIdentifier()); ] ``` -------------------------------- ### Entity Reference Example Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/reading-entities.md Illustrates how an entity like `ManufacturerEntity` is registered and accessed via API routes. It also shows how to access associated entities, such as the manufacturer of a product. ```text final public const ENTITY_NAME = 'product_manufacturer'; ``` -------------------------------- ### Create quantity- and rule-based pricing tiers Source: https://context7.com/shopware/admin-api-reference/llms.txt This example demonstrates how to update product prices to include quantity-based tiers. It uses a PATCH request to the product endpoint with a JSON payload specifying price ranges and associated rules. ```APIDOC ## PATCH /api/product/{id} ### Description Updates product pricing to include quantity- and rule-based tiers. ### Method PATCH ### Endpoint /api/product/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The ID of the product to update. #### Request Body - **prices** (array) - Required - An array of price tier objects. - **id** (string) - Required - The ID of the price tier. - **quantityStart** (integer) - Required - The starting quantity for this price tier. - **quantityEnd** (integer | null) - Optional - The ending quantity for this price tier. `null` indicates no upper limit. - **ruleId** (string) - Required - The ID of the rule associated with this price tier. - **price** (array) - Required - An array of price objects for different currencies. - **currencyId** (string) - Required - The ID of the currency. - **gross** (number) - Required - The gross price. - **net** (number) - Required - The net price. - **linked** (boolean) - Required - Indicates if the price is linked. ### Request Example ```json { "prices": [ { "id": "9fa35118fe7c4502947986849379d564", "quantityStart": 1, "quantityEnd": 10, "ruleId": "43be477b241448ecacd7ea2a266f8ec7", "price": [{ "currencyId": "b7d2554b0ce847cd82f3ac9bd1c0dfca", "gross": 20.00, "net": 16.81, "linked": true }] }, { "id": "db6f3ed762d14b0395a3fd2dc460db42", "quantityStart": 11, "quantityEnd": null, "ruleId": "43be477b241448ecacd7ea2a266f8ec7", "price": [{ "currencyId": "b7d2554b0ce847cd82f3ac9bd1c0dfca", "gross": 19.00, "net": 15.97, "linked": true }] } ] } ``` ``` -------------------------------- ### Restoring Inheritance for Product Price Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/writing-entities/product-data.md This example shows how to remove a specific price definition from a product variant, thereby restoring inheritance from the parent product. ```APIDOC ## PATCH /api/product/{id} ### Description Updates an existing product. Setting the `price` field to `null` restores inheritance from the parent product. ### Method PATCH ### Endpoint /api/product/{id} ### Parameters #### Path Parameters - **id** (string) - Required - The ID of the product to update. ### Request Body - **price** (null) - Required - Set to `null` to restore inheritance. ### Request Example ```json { "price": null } ``` ### Response #### Success Response (200) - **id** (string) - The ID of the updated product. - **message** (string) - A success message. #### Response Example ```json { "id": "0fa91ce3e96a4bc2be4bd9ce752c3425", "message": "Product updated successfully." } ``` ``` -------------------------------- ### Example Request Body for Admin API Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/request-response-structure.md This JSON object demonstrates the expected format for a request body. Ensure values are type-safe and dates are in ISO 8601 format. ```json { "id": "01bd7e70a50443ec96a01fd34890dcc5", "name": "Example product", "taxId": "792203a53e564e28bcb7ffa1867fb485", "stock": 708, "createdAt": "2018-09-13T10:17:05+02:00" } ``` -------------------------------- ### Writing Entities in Bulk (Upsert) Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/writing-entities/bulk-payloads.md This example demonstrates how to perform bulk upsert operations for multiple entities like tax, category, and country using the Sync API. Each operation specifies the entity, action ('upsert'), and a payload containing records to be inserted or updated. ```APIDOC ## POST /api/_action/sync ### Description Performs bulk write operations (create/update/delete) for multiple entities simultaneously using the Sync API. This endpoint supports 'upsert' for inserting or updating records and 'delete' for removing them. ### Method POST ### Endpoint /api/_action/sync ### Request Body - **write-tax** (object) - Key for the tax operation. Contains 'entity', 'action', and 'payload'. - **entity** (string) - 'tax' - **action** (string) - 'upsert' - **payload** (array) - List of tax records to upsert. - **name** (string) - Name of the tax rate. - **taxRate** (number) - The tax rate value. - **write-category** (object) - Key for the category operation. Contains 'entity', 'action', and 'payload'. - **entity** (string) - 'category' - **action** (string) - 'upsert' - **payload** (array) - List of category records to upsert. - **name** (string) - Name of the category. - **write-country** (object) - Key for the country operation. Contains 'entity', 'action', and 'payload'. - **entity** (string) - 'country' - **action** (string) - 'upsert' - **payload** (array) - List of country records to upsert. - **name** (string) - Name of the country. ### Request Example ```json { "write-tax": { "entity": "tax", "action": "upsert", "payload": [ { "name": "tax-1", "taxRate": 16 }, { "name": "tax-2", "taxRate": 15 } ] }, "write-category": { "entity": "category", "action": "upsert", "payload": [ { "name": "category-1" }, { "name": "category-2" } ] }, "write-country": { "entity": "country", "action": "upsert", "payload": [ { "name": "country-1" }, { "name": "country-2" } ] } } ``` ### Response #### Success Response (200) Returns a JSON object containing arrays of IDs for the entities that were successfully written, categorized by entity type. It also includes arrays for related entities (like translations) and lists of not found or deleted items. #### Response Example ```json { "extensions": [], "data": { "category": [ "0189bf2a627a7296adbc83527ba9ac29", "0189bf2a627b719999a9bf3afdc5c5ac" ], "category_translation": [ { "categoryId": "0189bf2a627a7296adbc83527ba9ac29", "languageId": "2fbb5fe2e29a4d70aa5854ce7ce3e20b" }, { "categoryId": "0189bf2a627b719999a9bf3afdc5c5ac", "languageId": "2fbb5fe2e29a4d70aa5854ce7ce3e20b" } ], "country": [ "0189bf2a627e723dbf691bd638113c02", "0189bf2a627e723dbf691bd638ca0a34" ], "country_translation": [ { "countryId": "0189bf2a627e723dbf691bd638113c02", "languageId": "2fbb5fe2e29a4d70aa5854ce7ce3e20b" }, { "countryId": "0189bf2a627e723dbf691bd638ca0a34", "languageId": "2fbb5fe2e29a4d70aa5854ce7ce3e20b" } ], "tax": [ "0189bf2a627971fcb6de1311115ee7fe", "0189bf2a627971fcb6de131111ad13cd" ] }, "notFound": [], "deleted": [] } ``` ``` -------------------------------- ### JSON:API Response Structure Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/request-response-structure.md This example shows the JSON:API compliant response structure. It includes 'data' for primary resources, 'included' for related resources, 'links' for navigation and self-reference, and 'meta' for additional information. Use this format when full API discoverability and relationship management are required. ```javascript // Accept: application/vnd.api+json (default) { "data": [ { "id": "01bd7e70a50443ec96a01fd34890dcc5", "type": "product", "attributes": { "active": true, "stock": 708, "createdAt": "2018-09-13T10:17:05+02:00", "manufacturerId": "f85bda8491fd4d61bcd2c7982204c638", "taxId": "792203a53e564e28bcb7ffa1867fb485", "price": { "net": 252.94117647058826, "gross": 301, "linked": true } }, "links": { "self": "http://localhost:8000/api/product/01bd7e70a50443ec96a01fd34890dcc5" }, "relationships": { "children": { "data": [], "links": { "related": "http://localhost:8000/api/product/01bd7e70a50443ec96a01fd34890dcc5/children" } } } } ], "included": [ { "id": "792203a53e564e28bcb7ffa1867fb485", "type": "tax", "attributes": { "taxRate": 20, "name": "20%", "createdAt": "2018-09-13T09:54:01+02:00" }, "links": { "self": "http://localhost:8000/api/tax/792203a53e564e28bcb7ffa1867fb485" }, "relationships": { "products": { "data": [], "links": { "related": "http://localhost:8000/api/tax/792203a53e564e28bcb7ffa1867fb485/products" } } } } ], "links": { "first": "http://localhost:8000/api/product?limit=1&page=1", "last": "http://localhost:8000/api/product?limit=1&page=50", "next": "http://localhost:8000/api/product?limit=1&page=2", "self": "http://localhost:8000/api/product?limit=1" }, "meta": { "fetchCount": 1, "total": 50 }, "aggregations": [] } ``` -------------------------------- ### Bulk Deletion of Standard and Mapping Entities Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/writing-entities/bulk-payloads.md This example demonstrates how to delete multiple standard entities (like 'category') and mapping entities (like 'product_category') in a single API request by providing their IDs or foreign keys in the payload. ```APIDOC ## Bulk Delete Entities ### Description Use the `_action/sync` endpoint with a POST request to delete multiple entities in bulk. The `payload` should be an array of objects, where each object represents an entity to be deleted. For standard entities, provide the `id`. For mapping entities, provide the relevant foreign keys (e.g., `productId`, `categoryId`). ### Method POST ### Endpoint `/api/_action/sync` ### Request Body ```json { "delete-tax": { "entity": "category", "action": "delete", "payload": [ { "id": "1d0943f296a94b06b785dfb4b017c18b" }, { "id": "046e9574bdae4478b854f49a8f22c275" }, { "id": "0a5bff83cbdf45968d37d30c31beac69" } ] }, "delete-product-category": { "entity": "product_category", "action": "delete", "payload": [ { "productId": "000bba26e2044b98a3ee4a84b03f9551", "categoryId": "0446a1eb394c4e729178699a7bc2833f" }, { "productId": "5deed0c33b2a4866a6b2c88fa215561c", "categoryId": "0446a1eb394c4e729178699a7bc2833f" } ] } } ``` ### Response (Details of the response structure for a successful bulk delete operation would be provided here, typically indicating the number of deleted entities or success status for each operation.) ``` -------------------------------- ### Obtain Access Token using Client Credentials Grant Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/authentication-authorisation.md Use this request to obtain an access token for machine-to-machine communication. Requires a setup integration with an Access key ID and Secret access key. The token is valid for 10 minutes. ```http { "method": "POST", "url": "http://localhost/api/oauth/token", "headers": { "Content-Type": "application/json", "Accept": "application/json" }, "body": { "grant_type": "client_credentials", "client_id": "", "client_secret": "" } } ``` ```javascript { "token_type": "Bearer", "expires_in": 600, "access_token": "xxxxxxxxxxxxxx" } ``` -------------------------------- ### Simple JSON Response Structure Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/request-response-structure.md This example demonstrates a simplified JSON response format. It omits JSON:API specific fields and embeds associations directly within entities, making it less verbose and potentially easier for clients to consume. Use this format when a more compact representation is preferred. ```javascript // Accept: application/json { "total": 50, "data": [ { "taxId": "792203a53e564e28bcb7ffa1867fb485", "manufacturerId": "f85bda8491fd4d61bcd2c7982204c638", "active": true, "price": { "net": 252.94117647058826, "gross": 301, "linked": true, "extensions": [] }, "stock": 708, "tax": { "taxRate": 20, "name": "20%", "createdAt": "2018-09-13T09:54:01+02:00", "id": "792203a53e564e28bcb7ffa1867fb485" }, "manufacturer": { "catalogId": "20080911ffff4fffafffffff19830531", "name": "Arnold", "createdAt": "2018-09-13T10:17:04+02:00", "products": null, "id": "f85bda8491fd4d61bcd2c7982204c638" }, "parent": null, "children": null, "id": "01bd7e70a50443ec96a01fd34890dcc5" } ], "aggregations": [] } ``` -------------------------------- ### Example of OneToMany Association Write Error Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/writing-entities/associations.md This example demonstrates a POST request to a OneToMany association that results in a `400 Bad Request` error due to invalid data types and missing required fields. The error response details the specific issues and their locations within the payload. ```http { "method": "POST", "url": "http://localhost/api/country", "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN" }, "body": { "name" : "new country", "states": [ { "name": "state-a", "shortCode": "A" }, { "name": "state-b", "shortCode": 1 }, { "name": "state-c" } ] } } ``` -------------------------------- ### Create quantity- and rule-based pricing tiers Source: https://context7.com/shopware/admin-api-reference/llms.txt Use PATCH to update product prices, defining quantity ranges and associated rules. Ensure correct currency IDs and gross/net values are provided. ```bash curl -X PATCH https://shop.example.com/api/product/a55ca50a2cef46d5b11a12c4b4614988 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJ0..." \ -d '{ "prices": [ { "id": "9fa35118fe7c4502947986849379d564", "quantityStart": 1, "quantityEnd": 10, "ruleId": "43be477b241448ecacd7ea2a266f8ec7", "price": [{ "currencyId": "b7d2554b0ce847cd82f3ac9bd1c0dfca", "gross": 20.00, "net": 16.81, "linked": true }] }, { "id": "db6f3ed762d14b0395a3fd2dc460db42", "quantityStart": 11, "quantityEnd": null, "ruleId": "43be477b241448ecacd7ea2a266f8ec7", "price": [{ "currencyId": "b7d2554b0ce847cd82f3ac9bd1c0dfca", "gross": 19.00, "net": 15.97, "linked": true }] } ] }' ``` -------------------------------- ### Create Document Type Source: https://github.com/shopware/admin-api-reference/blob/main/docs/guides/quick-start/04-document-management.md Create a new custom document type, for example, a 'return note', by providing its name and technical name. ```APIDOC ## POST /api/document-type ### Description Creates a new document type. ### Method POST ### Endpoint /api/document-type ### Request Body - **name** (string) - Required - The display name of the document type. - **technicalName** (string) - Required - The technical name for the document type. ### Request Example ```json { "name": "return note", "technicalName": "return-note" } ``` ``` -------------------------------- ### Create Order Return Source: https://context7.com/shopware/admin-api-reference/llms.txt Initiates a return for an order, specifying line items and quantities. Requires 'Content-Type: application/json' and 'Authorization' headers. ```bash # Create an order return with line items curl -X POST "https://shop.example.com/api/_proxy/order/558efc15fe604829b4d0607df75187e0/return" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJ0..." \ -d '{ "lineItems": [ { "orderLineItemId": "c90e05c82c5a4457844cba7403c7ef96", "quantity": 1, "internalComment": "Defective item" } ], "internalComment": "Customer requested return" }' ``` -------------------------------- ### Get Customer Turnover Source: https://context7.com/shopware/admin-api-reference/llms.txt Retrieves the total turnover for a specific customer, calculated as orders minus returns. Requires 'Accept: application/json' and 'Authorization' headers. ```bash # Get customer total turnover (orders minus returns) curl -X GET "https://shop.example.com/api/_action/customer/558efc15fe604829b4d0607df75187e0/turnover" \ -H "Accept: application/json" \ -H "Authorization: Bearer eyJ0..." ``` -------------------------------- ### Create a new product with a simple payload Source: https://github.com/shopware/admin-api-reference/blob/main/docs/guides/quick-start/02-product-management.md Use this payload to create a new product with minimal required fields. Ensure to replace placeholder IDs and access tokens with your actual values. ```http { "method": "post", "url": "http://localhost/api/product", "headers": { "Content-Type": "application/json", "Accept": "application/json", "Authorization": "Bearer YOUR_ACCESS_TOKEN" }, "body": { "name": "test", "productNumber": "random", "stock": 10, "taxId": "a5da76b447db4d0aba62e6512dadf45b", "price": [ { "currencyId" : "b7d2554b0ce847cd82f3ac9bd1c0dfca", "gross": 15, "net": 10, "linked" : false } ] } } } ``` ```json_schema { "type": "object", "title": "MinimalProductPayload", "description": "Parameters for product creation.", "properties": { "name": { "description": "Name of the product.", "type": "string" }, "productNumber": { "description": "Any random number given to product.", "type": "string" }, "stock": { "description": "Availability of stock.", "type": "string" }, "taxId": { "description": "ID of [tax](../../../adminapi.json/components/schemas/Tax)", "type": "string" }, "price": [] "currencyId": { "description": "ID of [currency](../../../adminapi.json/components/schemas/Currency).", "type": "string" }, "gross": { "description": "Gross price of a product.", "type": "string" }, "net": { "description": "Net price of a product.", "type": "string" }, "linked": { "description": "If set to true, net price is automatically calculated based on gross price and stored tax rate.", "type": "boolean" } } } ``` -------------------------------- ### Associate media with a product Source: https://context7.com/shopware/admin-api-reference/llms.txt This step involves creating a `product_media` association to link existing media entities to a product. Use a PATCH request on the product endpoint, providing an array of media objects with their respective IDs. ```bash curl -X PATCH https://shop.example.com/api/product/a55ca50a2cef46d5b11a12c4b4614988 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer eyJ0..." \ -d '{ "media": [{ "id": "0fa91ce3e96a4bc2be4bd9ce752c3425", "media": { "id": "cfbd5018d38d41d8adca10d94fc8bdf0" } }] }' ``` -------------------------------- ### Create an Entity using POST /api/{entity} Source: https://context7.com/shopware/admin-api-reference/llms.txt Use this endpoint to create a new entity. Ensure all fields marked as `required` in the entity schema are provided. A successful request returns `204 No Content`. Validation failures result in a `400` response with detailed error messages. ```bash # Create a product (minimum required fields) curl -X POST https://shop.example.com/api/product \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Bearer eyJ0..." \ -d '{ "name": "Blue Running Shoes", "productNumber": "RUN-SHOES-001", "stock": 25, "taxId": "a5da76b447db4d0aba62e6512dadf45b", "price": [ { "currencyId": "b7d2554b0ce847cd82f3ac9bd1c0dfca", "gross": 89.99, "net": 75.62, "linked": false } ] }' # Success: HTTP 204 No Content # Failure response (missing required fields): # { # "errors": [ # { "code": "c1051bb4...", "status": "400", "detail": "This value should not be blank.", "source": { "pointer": "/0/taxId" } }, # { "code": "c1051bb4...", "status": "400", "detail": "This value should not be blank.", "source": { "pointer": "/0/stock" } } # ] # } ``` -------------------------------- ### Customer Group List Endpoint Source: https://github.com/shopware/admin-api-reference/blob/main/docs/concepts/endpoint-structure/reading-entities.md Use this endpoint to fetch a list of all customer group entities. This is a standard GET request to the entity's list route. ```http GET /api/customer-group ```