### Install Shopware API Client via Package Manager

Source: https://github.com/shopware/store-api-reference/blob/main/docs/resources/libraries/javascript.md

Commands to install the @shopware/api-client package using popular Node.js package managers. Choose the command corresponding to your preferred tool.

```bash
pnpm add @shopware/api-client
```

```bash
yarn add @shopware/api-client
```

```bash
npm i @shopware/api-client
```

--------------------------------

### Shopware Store API Request URL Examples

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/request-and-response.md

Demonstrates how to construct request URLs for the Shopware Store API, including paths and query parameters.

```text
https://shop.example.com/store-api/path
```

```text
https://shop.example.com/store-api/path/{query-parameter}
```

--------------------------------

### GET /context

Source: https://github.com/shopware/store-api-reference/blob/main/docs/guides/quick-start/README.md

Retrieves general information about the store, including currency, tax rules, and current customer context.

```APIDOC
## GET /context

### Description
Retrieves the current sales channel context, including store settings, currency, tax rules, and customer session information.

### Method
GET

### Endpoint
/store-api/context

### Parameters
#### Headers
- **sw-access-key** (string) - Required - The API access key for the sales channel.
- **Content-Type** (string) - Required - application/json
- **Accept** (string) - Required - application/json

### Request Example
GET /store-api/context
Headers: {"sw-access-key": "YOUR_ACCESS_KEY"}

### Response
#### Success Response (200)
- **token** (string) - The current session token.
- **salesChannel** (object) - Details about the current sales channel.
- **customer** (object|null) - The current authenticated customer, if any.

#### Response Example
{
  "token": "jDUPcIRg1Mi7WZQJAm1nFTqhoMc0Eqev",
  "customer": null,
  "apiAlias": "sales_channel_context"
}
```

--------------------------------

### POST /example

Source: https://github.com/shopware/store-api-reference/blob/main/docs/resources/guidelines/guidelines-api-documentation.md

This endpoint allows you to retrieve example entities. It supports filtering and sorting via the Criteria object in the request body.

```APIDOC
## POST /example

### Description
This endpoint is designed to fetch a list of example entities. It utilizes the `Criteria` object for advanced filtering and sorting capabilities.

### Method
POST

### Endpoint
/example

### Parameters
#### Request Body
- **Criteria** (object) - Required/Optional - An object conforming to the `Criteria` schema, used for filtering, sorting, and pagination.

### Request Example
```json
{
  "limit": 10,
  "page": 1,
  "filter": [
    {
      "type": "equals",
      "field": "active",
      "value": true
    }
  ]
}
```

### Response
#### Success Response (200)
- **Example** (object) - An object conforming to the `Example` schema, representing the requested example entities.

#### Response Example
```json
{
  "data": [
    {
      "id": "123",
      "name": "Sample Example",
      "createdAt": "2023-10-27T10:00:00+00:00",
      "updatedAt": null
    }
  ],
  "total": 1
}
```
```

--------------------------------

### Execute POST Search Request

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/search-queries.md

Example of a POST request to the product endpoint, including filters, associations, field includes, and aggregations.

```http
POST /store-api/product HTTP/1.1
Content-Type: application/json
sw-access-key: SWSCY1NPSKHPSFNHWGDLTMM5NQ

{
  "filter": [{
    "type": "range",
    "field": "stock",
    "parameters": {
      "gte": 10,
      "lte": 30
    }
  }],
  "associations": {
    "categories": {
      "limit": 1
    }
  },
  "includes": {
    "product": ["id", "name", "categories"],
    "category": ["name"],
    "aggregation_bucket": ["key"]
  },
  "aggregations": [{
    "name": "product-categories",
    "type": "terms",
    "field": "categories.name"
  }]
}
```

--------------------------------

### Shopware Store API Authentication Example

Source: https://github.com/shopware/store-api-reference/blob/main/docs/guides/quick-start/README.md

Demonstrates how to make a POST request to the Shopware Store API, including necessary headers like 'Content-Type', 'Accept', and 'sw-access-key'. This is a foundational step for interacting with the API.

```json
{
  "method": "post",
  "url": "http://localhost/store-api/product",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "sw-access-key": "SWSCDZH3WULKMDGXTMNQS2VRVG"
  },
  "body": {
    "associations": {
      "media": {}
    },
    "includes": {
      "media": ["url"]
    }
  }
}
```

--------------------------------

### Sample Response Structure

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/request-and-response.md

An example of a typical response from the Store API, illustrating the detailed structure of pricing and line items.

```APIDOC
## Sample Response Structure

### Description
This section details a sample response from the Shopware Store API, showcasing the rich structure of pricing information and line items. This structure facilitates API discovery and can be used by libraries to generate user interfaces.

### Method
N/A (This is a response example)

### Endpoint
N/A (This is a response example)

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **price** (object) - Contains detailed pricing information including net price, total price, taxes, and tax rules.
- **lineItems** (array) - An array of items included in the order, each with payload, pricing, and product details.

#### Response Example
```json
{
 "price": {
        "netPrice": 168.22,
        "totalPrice": 180,
        "calculatedTaxes": [
            {
                "tax": 11.78,
                "taxRate": 7,
                "price": 180,
                "apiAlias": "cart_tax_calculated"
            }
        ],
        "taxRules": [
            {
                "taxRate": 7,
                "percentage": 100,
                "apiAlias": "cart_tax_rule"
            }
        ],
        "positionPrice": 180,
        "taxStatus": "gross",
        "rawTotal": 180,
        "apiAlias": "cart_price"
    },
    "lineItems": [
        {
            "payload": {
                "isCloseout": false,
                "customFields": [],
                "createdAt": "2020-08-06 06:26:32.065",
                "releaseDate": null,
                "isNew": false,
                "markAsTopseller": null,
                "productNumber": "SW10423",
                "manufacturerId": "05cd4e976df14c4d90e351f345ff5aa3",
                "taxId": "94f1e03140d24698a894320e258e6d83",
                "tagIds": null,
                "categoryIds": [
                    "525abe8981214bd2ba94fd33942333ec",
                    "bda4b60e845240b2b9d6b60e71196e14"
                ],
                "propertyIds": [
                    "6e3be72d8ad84a4ab73746a17863c1e8"
                ],
                "optionIds": null,
                "options": [],
                "streamIds": [
                    "1318833f46df457981763b94179d9ef0",
                    "89a367082c0d48c88f59424a8bb0265b"
                ],
                "parentId": null,
                "stock": 2389,
                "features": []
            },
            "label": "Ice Cream Scoop",
            "quantity": 1,
            "priceDefinition": {
                "price": 180,
                "taxRules": [
                    {
                        "taxRate": 7,
                        "percentage": 100,
                        "apiAlias": "cart_tax_rule"
                    }
                ],
                "quantity": 1,
                "isCalculated": true,
                "referencePriceDefinition": null,
                "listPrice": null,
                "regulationPrice": null,
                "type": "quantity",
                "apiAlias": "cart_price_quantity"
            },
            "price": {
                "unitPrice": 180,
                "quantity": 1,
                "totalPrice": 180,
                "calculatedTaxes": [
                    {
                        "tax": 11.78,
                        "taxRate": 7,
                        "price": 180,
                        "apiAlias": "cart_tax_calculated"
                    }
                ],
                "taxRules": [
                    {
                        "taxRate": 7,
                        "percentage": 100,
                        "apiAlias": "cart_tax_rule"
                    }
                ],
                "referencePrice": null,
                "listPrice": null,
                "regulationPrice": null,
                "apiAlias": "calculated_price"
            },
            "good": true,
            "description": null,
            "cover": {
                "translated": {
                    "alt": null,
                    "title": null,
                    "customFields": {}
                },
                "createdAt": "2020-08-06T06:26:06.221+00:00",
                "updatedAt": "2020-08-06T06:26:32.029+00:00",
                "mimeType": "image/jpeg",
                "fileExtension": "jpg",
                "fileSize": 44808,
                "title": null,
                "metaData": {
                    "type": 2,
                    "width": 900,
                    "height": 900
                },
                "uploadedAt": "2020-01-14T12:13:35.000+00:00",
                "alt": null,
                "url": "https://shop.example.com/F/S/g/2pFUo/media/01/b0/34/1579004015/943278_Eisportionierer_01.jpg",
                "fileName": "943278_SPLK_Eisportionierer_01",
                "translations": null,
                "thumbnails": [
                    {
                        "translated": [],
                        "createdAt": "2020-08-06T06:26:06.219+00:00",
                        "updatedAt": "2020-08-06T06:26:32.027+00:00",
                        "width": 400,
                        "path": "thumbnail/01/b0/34/1579004015/943278_SPLK_Eisportionierer_01_400x400.jpg",
                        "height": 400,
                        "url": "https://shop.example.com/F/S/g/2pFUo/thumbnail/01/b0/34/1579004015/943278_SPLK_Eis_01_400x400.jpg"
                    }
                ]
            }
        }
    ]
}
```
```

--------------------------------

### Shopware Store API Request Body Example (JSON)

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/request-and-response.md

Provides a sample JSON structure for the request body, detailing common fields like items, quantity, and type.

```json
{
  "items": [
    {
      "id": "01bd7e70a50443ec96a01fd34890dcc5",
      "referencedId": "01bd7e71b277653ec96a01fd34890ecc21",
      "quantity": 1,
      "type": "string",
      "good": true,
      "description": "Metal ice cream scooper",
      "removable": true,
      "stackable": true,
      "modified": true
    }
  ],
  "apiAlias": "string"
}
```

--------------------------------

### Shopware Store API Context Response Example

Source: https://github.com/shopware/store-api-reference/blob/main/docs/guides/quick-start/README.md

Illustrates the structure of a successful response from the Shopware Store API's '/context' endpoint. It includes key fields such as 'token', 'currency', 'salesChannel', and 'customer' (which may be null initially).

```javascript
{
  "token": "jDUPcIRg1Mi7WZQJAm1nFTqhoMc0Eqev",
  "currentCustomerGroup": { ... },
  "fallbackCustomerGroup": { ... },
  "currency": { ... },
  "salesChannel": { ... },
  "taxRules": [ ... ],
  "customer": null,
  "paymentMethod": { ... },
  "shippingMethod": { ... },
  "shippingLocation": { ... },
  "rulesIds": [ ... ],
  "rulesLocked": false,
  "permissions": [ ... ],
  "permisionsLocked": false,
  "apiAlias": "sales_channel_context"
}
```

--------------------------------

### Shopware Store API Base Endpoint Example

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/request-and-response.md

Illustrates the base URL structure for the Shopware Store API. This endpoint is the foundation for all subsequent API calls.

```text
https://shop.example.com/store-api
```

--------------------------------

### Product Listing by Category

Source: https://context7.com/shopware/store-api-reference/llms.txt

Get products for a specific category with all listing filters and aggregations.

```APIDOC
## Product Listing by Category

### Description
Get products for a specific category with all listing filters and aggregations.

### Method
POST

### Endpoint
/store-api/product-listing/{categoryId}

### Parameters
#### Path Parameters
- **categoryId** (string) - Required - The ID of the category to list products from.

#### Request Body
- **order** (string) - Optional - The order to sort products by (e.g., "price-asc").
- **limit** (integer) - Optional - The number of products to return per page.
- **p** (integer) - Optional - The current page number.
- **min-price** (number) - Optional - Minimum price filter.
- **max-price** (number) - Optional - Maximum price filter.
- **manufacturer** (string) - Optional - Filter by manufacturer IDs (pipe-separated).
- **properties** (string) - Optional - Filter by property IDs (pipe-separated).
- **shipping-free** (boolean) - Optional - Filter for shipping-free products.
- **rating** (integer) - Optional - Filter by minimum product rating.

### Request Example
```bash
curl -X POST "https://shop.example.com/store-api/product-listing/525abe8981214bd2ba94fd33942333ec" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG" \
  -d '{ 
    "order": "price-asc",
    "limit": 24,
    "p": 1,
    "min-price": 10,
    "max-price": 100,
    "manufacturer": "manufacturer-id-1|manufacturer-id-2",
    "properties": "property-id-1|property-id-2",
    "shipping-free": true,
    "rating": 4
  }'
```

### Response
#### Success Response (200)
- **elements** (array) - List of products in the category.
- **total** (integer) - Total number of products available.
- **aggregations** (object) - Aggregations for filters like price, manufacturer, etc.

#### Response Example
```json
{
  "elements": [
    {
      "id": "product-id-1",
      "name": "Product Name 1",
      "price": {
        "gross": 50.00,
        "net": 42.00
      }
    }
  ],
  "total": 100,
  "aggregations": {
    "price": {
      "min": 10.00,
      "max": 100.00
    }
  }
}
```
```

--------------------------------

### Enable Inheritance in Store API Request

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/inheritance.md

This example demonstrates how to make a POST request to the /store-api/product endpoint with the 'sw-inheritance' header set to 'true' to consider field value inheritance. It includes filtering for products without a parent and specifying the 'name' field in the response.

```http
{
  "method": "post",
  "url": "http://localhost/store-api/product",
  "headers": {
    "sw-inheritance": "true",
    "sw-access-key": "SWSCY1NPSKHPSFNHWGDLTMM5NQ",
    "Content-Type": "application/json"
  },
  "body": {
    "filter": [{
      "type": "not",
      "queries": [{
        "type": "equals",
        "value": null,
        "field": "parentId"
      }]
    }],
    "includes": {
      "product": ["name"]
    }
  }
}
```

--------------------------------

### Retrieve Store API Context via HTTP

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/authentication-authorisation.md

Demonstrates how to perform a GET request to the Store API context endpoint. It requires the 'sw-access-key' header to identify the sales channel.

```http
GET /store-api/context HTTP/1.1
Host: localhost
Content-Type: application/json
sw-access-key: SWSCY1NPSKHPSFNHWGDLTMM5NQ
```

--------------------------------

### Authentication - Get Sales Channel Context

Source: https://context7.com/shopware/store-api-reference/llms.txt

Retrieve the current sales channel context, including customer information, payment/shipping methods, and currency settings. Requires a `sw-access-key` header.

```APIDOC
## GET /store-api/context

### Description
Retrieve the current sales channel context including customer information, selected payment/shipping methods, and currency settings. The `sw-access-key` header identifies your sales channel and is required for all API calls.

### Method
GET

### Endpoint
/store-api/context

### Parameters
#### Headers
- **sw-access-key** (string) - Required - Your sales channel access key.
- **Content-Type** (string) - Required - `application/json`

### Request Example
```bash
curl -X GET "https://shop.example.com/store-api/context" \
  -H "Content-Type: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG"
```

### Response
#### Success Response (200)
- **customer** (object) - Current customer details (if logged in).
- **paymentMethod** (object) - Selected payment method.
- **shippingMethod** (object) - Selected shipping method.
- **currency** (object) - Currency settings.
- **language** (object) - Language settings.

#### Response Example
(Response structure varies based on context, includes customer, payment, shipping, currency, and language details)
```

--------------------------------

### Fetch Shopware Store API Context

Source: https://github.com/shopware/store-api-reference/blob/main/docs/guides/quick-start/README.md

Shows how to perform a GET request to the '/context' endpoint of the Shopware Store API to retrieve general information about the store and the current user session. The response includes details like the API token, currency, and customer information.

```json
{
  "method": "get",
  "url": "http://localhost/store-api/context",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "sw-access-key": "SWSCDZH3WULKMDGXTMNQS2VRVG"
  }
}
```

--------------------------------

### Get Single Product by ID

Source: https://context7.com/shopware/store-api-reference/llms.txt

Fetches a single product's details using its unique ID. This endpoint allows for optional inclusion of associated data and specific field projections for a tailored response.

```bash
curl -X POST "https://shop.example.com/store-api/product/eaf1ee42ef884f3c941f22596aa0163f" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG" \
  -d '{ \
    "associations": { \
      "manufacturer": {}, \
      "categories": {} \
    }, \
    "includes": { \
      "product": ["id", "name", "translated", "calculatedPrice", "manufacturer"], \
      "product_manufacturer": ["id", "name", "translated"] \
    } \
  }'
```

--------------------------------

### Encoding Criteria for GET Requests

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/search-queries.md

Explains how to encode complex search criteria into URL query parameters for GET requests, using PHP's http_build_query as an example.

```APIDOC
### Description
When using `GET` requests for search functionality, complex criteria objects must be encoded as URL query parameters. This ensures that the API can correctly parse and apply the search filters.

### Method
GET

### Endpoint
Any endpoint supporting search criteria via GET parameters.

### Parameters
#### Query Parameters
- **criteria** (string) - Required - The search criteria object, URL-encoded.

### Request Example
To pass the following criteria object:
```json
{
  "associations": {
    "lineItems": {
      "limit": 5
    }
  },
  "limit": 1
}
```

Encode it into a query parameter string. For example, using PHP's `http_build_query` function, it would become:

`?associations[lineItems][limit]=5&limit=1`

### Response
#### Success Response (200)
- The response structure will depend on the specific `GET` endpoint being called, but it will reflect the filtered and limited results based on the encoded criteria.
```

--------------------------------

### Encode Search Criteria for GET Requests

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/search-queries.md

Demonstrates how to convert a complex JSON criteria object into a URL-encoded query string for GET requests using standard HTTP query parameter conventions.

```json
{
  "associations": {
    "lineItems": {
      "limit": 5
    }
  },
  "limit": 1
}
```

```text
?associations[lineItems][limit]=5&limit=1
```

--------------------------------

### Get Countries

Source: https://context7.com/shopware/store-api-reference/llms.txt

Fetches a list of available countries with their details, used for forms and address information.

```APIDOC
## POST /store-api/country - Get Countries

### Description
Retrieves a list of countries available in the system, including their IDs, names, and ISO codes. This data is essential for customer registration and address forms.

### Method
POST

### Endpoint
https://shop.example.com/store-api/country

### Parameters
#### Request Body
- **includes** (object) - Optional - Specifies which fields to include in the response.
  - **country** (array) - Optional - List of country fields to include (e.g., "id", "name", "translated", "iso").

### Request Example
```json
{
  "includes": {
    "country": ["id", "name", "translated", "iso"]
  }
}
```

### Response
#### Success Response (200)
(Response structure not provided in the source text)

#### Response Example
(Response example not provided in the source text)
```

--------------------------------

### Get Single Product

Source: https://context7.com/shopware/store-api-reference/llms.txt

Fetch a single product by its ID with optional associations and field projections.

```APIDOC
## Get Single Product

### Description
Fetch a single product by its ID with optional associations and field projections.

### Method
POST

### Endpoint
/store-api/product/{productId}

### Parameters
#### Path Parameters
- **productId** (string) - Required - The ID of the product to retrieve.

#### Request Body
- **associations** (object) - Optional - An object defining associations to load.
  - **manufacturer** (object) - Optional - Load product manufacturer.
  - **categories** (object) - Optional - Load product categories.
- **includes** (object) - Optional - An object specifying which fields to include for different entity types.
  - **product** (array) - Optional - Fields to include for the product.
  - **product_manufacturer** (array) - Optional - Fields to include for the product manufacturer.

### Request Example
```bash
curl -X POST "https://shop.example.com/store-api/product/eaf1ee42ef884f3c941f22596aa0163f" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG" \
  -d '{ 
    "associations": {
      "manufacturer": {}, 
      "categories": {}
    },
    "includes": {
      "product": ["id", "name", "translated", "calculatedPrice", "manufacturer"],
      "product_manufacturer": ["id", "name", "translated"]
    }
  }'
```

### Response
#### Success Response (200)
- **id** (string) - The product ID.
- **name** (string) - The product name.
- **translated** (object) - Translated product details.
- **calculatedPrice** (object) - Calculated price information.
- **manufacturer** (object) - Manufacturer details.

#### Response Example
```json
{
  "id": "eaf1ee42ef884f3c941f22596aa0163f",
  "name": "Example Product",
  "translated": {
    "name": "Example Product"
  },
  "calculatedPrice": {
    "totalPrice": 99.99
  },
  "manufacturer": {
    "id": "manufacturer-id",
    "name": "Example Manufacturer",
    "translated": {
      "name": "Example Manufacturer"
    }
  }
}
```
```

--------------------------------

### Get Salutations

Source: https://context7.com/shopware/store-api-reference/llms.txt

Fetches a list of available salutations (e.g., Mr., Ms., Dr.) for customer forms.

```APIDOC
## POST /store-api/salutation - Get Salutations

### Description
Retrieves a list of available salutations (e.g., Mr., Ms., Dr.) used in customer forms and communications.

### Method
POST

### Endpoint
https://shop.example.com/store-api/salutation

### Parameters
#### Request Body
- **includes** (object) - Optional - Specifies which fields to include in the response.
  - **salutation** (array) - Optional - List of salutation fields to include (e.g., "id", "displayName", "translated").

### Request Example
```json
{
  "includes": {
    "salutation": ["id", "displayName", "translated"]
  }
}
```

### Response
#### Success Response (200)
(Response structure not provided in the source text)

#### Response Example
(Response example not provided in the source text)
```

--------------------------------

### Refine Product Search with Sorting and Filtering

Source: https://github.com/shopware/store-api-reference/blob/main/docs/guides/quick-start/search-for-products.md

Demonstrates how to apply sorting criteria and range filters to a product search request. This allows for more granular control over the returned product listing.

```http
{
  "method": "post",
  "url": "http://localhost/store-api/search",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "sw-access-key": "SWSCDZH3WULKMDGXTMNQS2VRVG"
  },
  "body": {
    "search": "abc",
    "order": "topseller",
    "filter": [
      {
        "type": "range",
        "field": "stock",
        "parameters": {
          "lt": 50
        }
      }
    ]
  }
}
```

```javascript
// POST /store-api/search

{
    "search": "braeburn",
    "order": "topseller",
    "filter": [
        {
            "type": "range",
            "field": "stock",
            "parameters": {
                "lt": 50.0
            }
        }
    ]
}
```

--------------------------------

### Get Current Customer API

Source: https://context7.com/shopware/store-api-reference/llms.txt

Verify login status and retrieve current customer information. Returns 403 if not logged in.

```APIDOC
## POST /store-api/account/customer

### Description
Verify login status and retrieve current customer information. Returns 403 if not logged in.

### Method
POST

### Endpoint
/store-api/account/customer

### Parameters
#### Headers
- **sw-access-key** (string) - Required - Your sales channel access key.
- **sw-context-token** (string) - Required - The context token for the session.
- **Content-Type** (string) - Required - `application/json`
- **Accept** (string) - Required - `application/json`

### Request Example
```bash
curl -X POST "https://shop.example.com/store-api/account/customer" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG" \
  -H "sw-context-token: PwSFY3T3IZCWdq658ku3nZMPouLmAlJU"
```

### Response
#### Success Response (200)
- **customer** (object) - The customer's data.

#### Error Response (403)
- **errors** (array) - An array of error objects.
  - **status** (string) - HTTP status code.
  - **code** (string) - Error code.
  - **title** (string) - Error title.
  - **detail** (string) - Error description.

#### Response Example (Success)
(Returns customer data object)

#### Response Example (Error)
```json
{
  "errors": [{
    "status": "403",
    "code": "CHECKOUT__CUSTOMER_NOT_LOGGED_IN",
    "title": "Forbidden",
    "detail": "Customer is not logged in."
  }]
}
```
```

--------------------------------

### GET /media/{id}

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/request-and-response.md

Retrieves detailed information about a specific media entity, including its associated thumbnails and custom fields.

```APIDOC
## GET /media/{id}

### Description
Retrieves the details of a specific media file, including metadata and thumbnail configurations.

### Method
GET

### Endpoint
/media/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the media resource.

### Request Example
GET /store-api/media/70477ce7dda548b186036e8b3197e9ef

### Response
#### Success Response (200)
- **mediaId** (string) - The ID of the media file.
- **customFields** (object|null) - Custom fields associated with the media.
- **id** (string) - The unique identifier of the thumbnail.
- **apiAlias** (string) - The API alias for the media thumbnail entity.

#### Response Example
{
  "mediaId": "394243c9602e4bf7a288b9a0ba845ac6",
  "customFields": null,
  "id": "70477ce7dda548b186036e8b3197e9ef",
  "apiAlias": "media_thumbnail"
}
```

--------------------------------

### Product Search with Criteria

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/search-queries.md

Demonstrates how to search for products using a POST request with detailed filter, association, include, and aggregation criteria.

```APIDOC
## POST /store-api/product

### Description
This endpoint allows for searching and filtering products based on a comprehensive set of criteria, including stock ranges, associations, and aggregations.

### Method
POST

### Endpoint
/store-api/product

### Parameters
#### Request Body
- **filter** (array) - Required - Criteria to filter the product results. Example: range filter on stock.
- **associations** (object) - Optional - Specifies related data to include, like categories, with nested criteria.
- **includes** (object) - Optional - Restricts the output to specific fields for products and their associations.
- **aggregations** (array) - Optional - Defines aggregations to compute on the fly, such as terms aggregation on category names.

### Request Example
```json
{
  "filter": [
    {
      "type": "range",
      "field": "stock",
      "parameters": {
        "gte": 10,
        "lte": 30
      }
    }
  ],
  "associations": {
    "categories": {
      "limit": 1
    }
  },
  "includes": {
    "product": ["id", "name", "categories"],
    "category": ["name"],
    "aggregation_bucket": ["key"]
  },
  "aggregations": [
    {
      "name": "product-categories",
      "type": "terms",
      "field": "categories.name"
    }
  ]
}
```

### Response
#### Success Response (200)
- **total** (integer) - The total number of products matching the criteria.
- **data** (array) - An array of product objects matching the search criteria.
- **aggregations** (object) - An object containing the computed aggregations.

#### Response Example
```json
{
  "total": 5,
  "data": [
    {
      "id": "012cd563cf8e4f0384eed93b5201cc98",
      "name": "Example Product 1",
      "categories": [
        {
          "id": "a1b2c3d4e5f678901234567890abcdef",
          "name": "Category A",
          "apiAlias": "category"
        }
      ],
      "apiAlias": "product"
    }
  ],
  "aggregations": {
    "product-categories": {
      "buckets": [
        {
          "key": "Category A",
          "docCount": 3
        }
      ]
    }
  }
}
```
```

--------------------------------

### Register New Customer Account

Source: https://context7.com/shopware/store-api-reference/llms.txt

Registers a new customer with billing address details. Requires valid salutationId and countryId, and returns a new context token.

```bash
curl -X POST "https://shop.example.com/store-api/account/register" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG" \
  -H "sw-context-token: my-frontend-token" \
  -d '{
    "salutationId": "32d6c76401d749d2b025eba20a511e54",
    "firstName": "Alice",
    "lastName": "Apple",
    "email": "alice.apple@example.com",
    "password": "ilovefruits",
    "storefrontUrl": "http://localhost",
    "billingAddress": {
      "street": "Apple Alley 42",
      "zipcode": "1234-5",
      "city": "Appleton",
      "countryId": "de7ca8cbb8934e63bed964f8d592d501"
    }
  }'
```

--------------------------------

### Handle Payment Initiation

Source: https://context7.com/shopware/store-api-reference/llms.txt

Initiates the payment process for an order. For asynchronous payment methods (e.g., PayPal, Stripe), this endpoint returns a redirect URL to the payment provider. For synchronous methods, it may return a success status immediately. The user is redirected to specified `finishUrl` or `errorUrl` upon payment completion.

```bash
curl -X POST "https://shop.example.com/store-api/handle-payment" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG" \
  -H "sw-context-token: my-frontend-token" \
  -d '{
    "orderId": "order-id-from-checkout",
    "finishUrl": "https://myshop.com/checkout/finish",
    "errorUrl": "https://myshop.com/checkout/error",
    "paymentDetails": {
      "creditCardId": "saved-card-id"
    }
  }'
```

--------------------------------

### Initiate Payment via Store API (POST /handle-payment)

Source: https://github.com/shopware/store-api-reference/blob/main/docs/guides/quick-start/handling-the-payment.md

Initiates the payment process for a given order. This endpoint requires the orderId, and optionally accepts finishUrl and errorUrl for redirecting the user after payment. It can also include paymentDetails for specific payment method integrations.

```javascript
// POST /store-api/handle-payment

{
  "orderId": "<id-of-the-order>",
  "finishUrl": "<url-for-successful-payment>",
  "errorUrl": "<url-for-unsuccessful-payment>"
}
```

```javascript
// POST /store-api/handle-payment

{
  "orderId": "<id-of-the-order>",
  "finishUrl": "<url-for-successful-payment>",
  "errorUrl": "<url-for-unsuccessful-payment>",
  "paymentDetails": {
    "creditCardId": "<credit-card-id>"
  }
}
```

--------------------------------

### GET /payment/finalize-transaction

Source: https://github.com/shopware/store-api-reference/blob/main/docs/guides/quick-start/handling-the-payment.md

Finalizes a payment transaction after a user is redirected back from a payment provider. It decrypts the payment token and routes the user to the appropriate finish or error URL.

```APIDOC
## GET /payment/finalize-transaction

### Description
Finalizes the payment transaction after the user returns from the payment provider. It processes the `_sw_payment_token` to determine the outcome and redirects the user accordingly.

### Method
GET

### Endpoint
/payment/finalize-transaction

### Parameters
#### Query Parameters
- **_sw_payment_token** (string) - Required - The JWT token containing payment information.

### Response
#### Success Response (302)
- Redirects to the `finishUrl` or `errorUrl` based on the payment outcome.
```

--------------------------------

### Retrieve Sales Channel Context

Source: https://context7.com/shopware/store-api-reference/llms.txt

Fetches the current sales channel context, including customer state, payment methods, and currency settings. Requires the sw-access-key header for authorization.

```bash
curl -X GET "https://shop.example.com/store-api/context" \
  -H "Content-Type: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG"
```

--------------------------------

### POST /store-api/product (Inheritance)

Source: https://github.com/shopware/store-api-reference/blob/main/docs/concepts/inheritance.md

Retrieves product data while considering parent-child inheritance by including the sw-inheritance header.

```APIDOC
## POST /store-api/product

### Description
Fetches product records from the Store API. By providing the `sw-inheritance` header, the API will resolve field values from parent products if they are not explicitly set on the variant.

### Method
POST

### Endpoint
/store-api/product

### Parameters
#### Headers
- **sw-inheritance** (boolean) - Required - Set to 'true' to enable inheritance resolution.
- **sw-access-key** (string) - Required - The API access key for authentication.

#### Request Body
- **filter** (array) - Optional - Criteria to filter the product list.
- **includes** (object) - Optional - Defines the fields to be returned in the response.

### Request Example
{
  "filter": [{
    "type": "not",
    "queries": [{
      "type": "equals",
      "value": null,
      "field": "parentId"
    }]
  }],
  "includes": {
    "product": ["name"]
  }
}

### Response
#### Success Response (200)
- **data** (array) - List of products with inherited values resolved.

#### Response Example
{
  "total": 1,
  "elements": [
    {
      "name": "Example Product"
    }
  ]
}
```

--------------------------------

### Register Customer

Source: https://github.com/shopware/store-api-reference/blob/main/docs/guides/quick-start/register-a-customer.md

Registers a new customer by providing personal details, billing address, and storefront URL. The storefront URL is crucial for generating confirmation links in a double opt-in scenario.

```APIDOC
## POST /store-api/account/register

### Description
Registers a new customer with their personal information, password, and billing address. Requires `salutationId` and `countryId` which can be fetched from respective endpoints.

### Method
POST

### Endpoint
/store-api/account/register

### Parameters
#### Request Body
- **salutationId** (string) - Required - The ID of the customer's salutation.
- **firstName** (string) - Required - The customer's first name.
- **lastName** (string) - Required - The customer's last name.
- **email** (string) - Required - The customer's email address.
- **password** (string) - Required - The customer's desired password.
- **storefrontUrl** (string) - Required - The base URL of the storefront for confirmation links.
- **billingAddress** (object) - Required - The customer's billing address details.
  - **street** (string) - Required - Street name and number.
  - **zipcode** (string) - Required - Postal code.
  - **city** (string) - Required - City name.
  - **countryId** (string) - Required - The ID of the customer's country.

### Request Example
```json
{
  "salutationId": "32d6c76401d749d2b025eba20a511e54",
  "firstName": "Alice",
  "lastName": "Apple",
  "email": "alice.apple@example.com",
  "password": "ilovefruits",
  "storefrontUrl": "http://localhost",
  "billingAddress": {
    "street": "Apple Alley 42",
    "zipcode": "1234-5",
    "city": "Appleton",
    "countryId": "de7ca8cbb8934e63bed964f8d592d501"
  }
}
```

### Response
#### Success Response (200)
Returns the newly created customer object.

#### Response Example
(Customer object details)

#### Error Response
- **400 Bad Request**: If required fields are missing or invalid.
- **409 Conflict**: If the email address is already in use.
```

--------------------------------

### Shopware Store API: Get Salutations

Source: https://context7.com/shopware/store-api-reference/llms.txt

Retrieves a list of available salutations (e.g., Mr., Ms., Dr.) from the Shopware store. This information is essential for populating salutation fields in customer forms.

```bash
# Get salutations
curl -X POST "https://shop.example.com/store-api/salutation" \
  -H "Content-Type: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG" \
  -d '{
    "includes": {
      "salutation": ["id", "displayName", "translated"]
    }
  }'
```

--------------------------------

### Shopware Store API: Get Countries

Source: https://context7.com/shopware/store-api-reference/llms.txt

Fetches a list of countries available in the Shopware store, including their IDs, names, translated names, and ISO codes. This data is typically used for customer registration forms.

```bash
# Get countries
curl -X POST "https://shop.example.com/store-api/country" \
  -H "Content-Type: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG" \
  -d '{
    "includes": {
      "country": ["id", "name", "translated", "iso"]
    }
  }'
```

--------------------------------

### Perform Simple Product Search

Source: https://github.com/shopware/store-api-reference/blob/main/docs/guides/quick-start/search-for-products.md

Executes a basic search request to retrieve products matching a search string. This demonstrates the standard POST request structure for the /search endpoint.

```http
{
  "method": "post",
  "url": "http://localhost/store-api/search",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "sw-access-key": "SWSCDZH3WULKMDGXTMNQS2VRVG"
  },
  "body": {
    "search": "abc"
  }
}
```

```javascript
// POST /store-api/search

{
    "search": "braeburn"
}
```

--------------------------------

### Authenticate Customer Login

Source: https://context7.com/shopware/store-api-reference/llms.txt

Authenticates a customer using email and password. Returns a new context token to maintain the session.

```bash
curl -X POST "https://shop.example.com/store-api/account/login" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG" \
  -H "sw-context-token: my-frontend-token" \
  -d '{
    "email": "alice.apple@example.com",
    "password": "ilovefruits"
  }'
```

--------------------------------

### Guest Customer Registration

Source: https://github.com/shopware/store-api-reference/blob/main/docs/guides/quick-start/register-a-customer.md

To create a guest customer, set `guest: true` in the registration request. The rest of the registration flow is similar to a standard user registration. Note that guest sessions cannot be re-obtained after logout.

```APIDOC
## Guest Customer Registration

### Description
Register a new customer as a guest by setting the `guest` property to `true` in the registration payload. This allows for one-time purchases without requiring account creation.

### Method
POST

### Endpoint
/store-api/account/register

### Parameters
#### Request Body
- **guest** (boolean) - Required - Set to `true` to register a guest customer.
- **email** (string) - Required - The email address of the customer.
- **password** (string) - Required - The password for the customer account.
- **firstName** (string) - Required - The first name of the customer.
- **lastName** (string) - Required - The last name of the customer.

### Request Example
```json
{
  "guest": true,
  "email": "guest.user@example.com",
  "password": "securepassword123",
  "firstName": "Guest",
  "lastName": "User"
}
```

### Response
#### Success Response (200)
- **registered** (boolean) - Indicates if the customer was successfully registered.
- **customerId** (string) - The ID of the newly registered customer.

#### Response Example
```json
{
  "registered": true,
  "customerId": "some_customer_id"
}
```
```

--------------------------------

### Get Available Shipping Methods

Source: https://context7.com/shopware/store-api-reference/llms.txt

Lists available shipping methods along with their delivery time information. The `onlyAvailable=1` parameter ensures that only methods applicable to the current cart are returned. The response includes details like name, active status, and delivery time.

```bash
curl -X POST "https://shop.example.com/store-api/shipping-method?onlyAvailable=1" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG" \
  -H "sw-context-token: my-frontend-token" \
  -d '{
    "includes": {
      "shipping_method": ["id", "name", "active", "deliveryTime"],
      "delivery_time": ["name", "unit"]
    }
  }'
```

--------------------------------

### Create Shopping Cart

Source: https://context7.com/shopware/store-api-reference/llms.txt

Creates a new shopping cart associated with a given context token. The cart persists across requests using the same token and can be named.

```bash
curl -X POST "https://shop.example.com/store-api/checkout/cart" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "sw-access-key: SWSCDZH3WULKMDGXTMNQS2VRVG" \
  -H "sw-context-token: my-frontend-token" \
  -d '{ \
    "name": "my-cart" \
  }'
```