Mirakl PHP SDK for Shop

https://github.com/mirakl/sdk-php-shop
Admin
The official Mirakl PHP API client for the 'shop' role, enabling sellers to interact with the Mirakl...
Tokens:202,738
Snippets:1,456
Trust Score:7
Update:4 days ago
Show doc for...
Tokens:
Raw
### Use ShopApiClient to Get an Offer

Source: https://github.com/mirakl/sdk-php-shop/blob/master/README.md

Instantiate the ShopApiClient with your environment URL, API key, and shop ID. Build a GetOfferRequest with an offer ID, then call getOffer() to receive a ShopOffer object. Use run() or raw()->getOffer() to get the raw PSR-7 response. Exceptions are thrown for not-found or error cases.

```php
<?php
require 'vendor/autoload.php';

use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Offer\GetOfferRequest;

// Environment parameters
$url = 'https://your.env/api';
$apiKey = 'your_api_key';

try {
    // Instantiating the Mirakl API Client
    $api = new ShopApiClient('API_URL', 'API_KEY', 'SHOP_ID');

    // Building request
    $request = new GetOfferRequest('OFFER_ID');

    // Calling the API
    $result = $api->getOffer($request);
    var_dump($result); // \Mirakl\MMP\Shop\Domain\Offer\ShopOffer

    // You can also retrieve raw response by using run() method of API client:
    $result = $api->run($request); // or $api->raw()->getOffer($request)
    var_dump($result); // returns \Psr\Http\Message\ResponseInterface

} catch (\Exception $e) {
    // An exception is thrown if object requested is not found or if an error occurs
    var_dump($e);
}
```

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

### Install Mirakl PHP SDK via Composer

Source: https://github.com/mirakl/sdk-php-shop/blob/master/README.md

Use Composer to install the official Mirakl PHP API client for the shop role. Run this command in your project root.

```bash
composer require mirakl/sdk-php-shop
```

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

### Request Usage Example

Source: https://github.com/mirakl/sdk-php-shop

Example of creating and configuring a request object, then retrieving its method, endpoint, and query parameters.

```APIDOC
## Request Usage Example

### Description
Example of creating and configuring a request object, then retrieving its method, endpoint, and query parameters.

### Code
```php
use Mirakl\MMP\Shop\Request\Order\Get\GetOrdersRequest;

$request = new GetOrdersRequest();
$request->setOrderStates(['SHIPPING', 'SHIPPED'])
    ->setOrderIds(['order-12345'])
    ->setStartUpdateDate(new \DateTime('2024-01-01T00:00:00Z'))
    ->setMax(50)
    ->setOffset(0);

echo $request->getMethod();   // GET
echo $request->getEndpoint(); // /orders
print_r($request->getQueryParams());
```
```

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

### Get all reasons with GetReasonsRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/RE01.md

Use ShopApiClient to retrieve all reasons configured on the platform. Requires the marketplace URL, API key, and shop ID. The result is a ReasonCollection instance.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Reason\GetReasonsRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$request = new GetReasonsRequest();
$result = $api->getReasons($request);
// $result => @see \Mirakl\MMP\Shop\Domain\Collection\Reason\ReasonCollection
```

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

### SeekableCollection instantiation example

Source: https://github.com/mirakl/sdk-php-shop

Example of creating a SeekableCollection decorator with TransactionLineCollection::class and key 'data'.

```php
return new SeekableCollection(TransactionLineCollection::class, 'data');
```

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

### UpdateOffersRequest usage example

Source: https://github.com/mirakl/sdk-php-shop

Shows how to create an UpdateOffer, pass it to UpdateOffersRequest, and call updateOffers to get an OfferImportTracking object. The response contains an import_id that can be echoed.

```php
use Mirakl\MMP\OperatorShop\Domain\Offer\UpdateOffer;
use Mirakl\MMP\Shop\Request\Offer\UpdateOffersRequest;

$offer = (new UpdateOffer())->setOfferId('OFFER_ID')->setPrice(19.99)->setAvailableQuantity(5);
$request = new UpdateOffersRequest([$offer]);
$tracking = $api->updateOffers($request);
echo $tracking->getImportId();
```

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

### GetOffersRequest Usage Example

Source: https://github.com/mirakl/sdk-php-shop

Demonstrates how to create a GetOffersRequest, set filters, and iterate over the returned ShopOfferCollection. This example shows the typical usage pattern for listing offers.

```APIDOC
## GetOffersRequest Usage Example

### Description
Demonstrates how to create a GetOffersRequest, set filters, and iterate over the returned offers.

### Example
```php
$request = new GetOffersRequest('your-shop-id');
$request->setOfferStateCodes(['ACTIVE'])->setSku('SKU-001')->setMax(50);
foreach ($api->getOffers($request) as $offer) {
    echo $offer->getSku() . ' — ' . $offer->getPrice();
}
```
```

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

### Get Offer States with ShopApiClient::getOfferStates()

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/OF61.md

Use this snippet to retrieve the list of offer states configured on the platform. It requires a ShopApiClient instance with the marketplace URL, API key, and shop ID. The result is an OfferStateCollection object.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$result = $api->getOfferStates();
// $result => @see \Mirakl\MMP\Common\Domain\Collection\Offer\State\OfferStateCollection
```

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

### GetReasonsRequest usage example

Source: https://github.com/mirakl/sdk-php-shop

Shows how to call the API to get reasons (RE01) using GetReasonsRequest. Returns a ReasonCollection and iterates over each reason to print its code and label.

```php
use Mirakl\MMP\Shop\Request\Reason\GetReasonsRequest;

$reasons = $api->getReasons(new GetReasonsRequest()); // ReasonCollection
foreach ($reasons as $reason) {
    echo $reason->getCode() . ' — ' . $reason->getLabel();
}
```

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

### Get platform configurations using ShopApiClient

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/PC01.md

Retrieves platform configuration settings for a Mirakl shop. Requires a ShopApiClient instance with the marketplace URL, API key, and shop ID. The result is a PlatformConfigurationResponse object.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\PlatformConfiguration\GetPlatformConfigurationRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$request = new GetPlatformConfigurationRequest();
$result = $api->getPlatformConfiguration($request);

// $result => @see \Mirakl\MMP\Shop\Domain\PlatformConfiguration\PlatformConfigurationResponse
```

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

### MiraklObject mapping example

Source: https://github.com/mirakl/sdk-php-shop

Example of static::$mapping aliasing nested API keys to flat local keys. Used by map(), unmap(), wrap(), and unwrap() for key transformation.

```php
protected static $mapping = [
    'product_sku' => 'product/sku',
];
```

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

### Get reasons by type using GetTypeReasonsRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/RE02.md

Retrieves reasons by type configured on the platform using the Mirakl Shop API client. Requires a valid API URL, API key, and shop ID. The result is a ReasonCollection object.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Reason\GetTypeReasonsRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$request = new GetTypeReasonsRequest();

$result = $api->getTypeReasons($request);
// $result => @see \Mirakl\MMP\Shop\Domain\Collection\Reason\ReasonCollection
```

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

### Get offer details with GetOfferRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/OF22.md

Use this snippet to retrieve information about a specific offer in the Mirakl Shop API. It requires a valid marketplace URL, API key, and shop ID. The result is a ShopOffer object.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Offer\GetOfferRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$request = new GetOfferRequest('OFFER_ID');
$result = $api->getOffer($request);
// $result => @see \Mirakl\MMP\Shop\Domain\Offer\ShopOffer
```

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

### getProducts

Source: https://github.com/mirakl/sdk-php-shop

Gets products using the provided request. Returns a ProductCollection.

```APIDOC
## getProducts

### Description
Gets products using the provided request. Returns a ProductCollection.

### Method
getProducts

### Parameters
- **$request** (GetProductsRequest) - Required - The request object for getting products.

### Response
#### Success Response
- **ProductCollection** - The collection of products.
```

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

### getOffer

Source: https://github.com/mirakl/sdk-php-shop

Gets an offer using the provided request. Returns a ShopOffer.

```APIDOC
## getOffer

### Description
Gets an offer using the provided request. Returns a ShopOffer.

### Method
getOffer

### Parameters
- **$request** (GetOfferRequest) - Required - The request object for getting an offer.

### Response
#### Success Response
- **ShopOffer** - The shop offer.
```

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

### getOffersOnProducts

Source: https://github.com/mirakl/sdk-php-shop

Gets offers on products using the provided request. Returns a ProductWithOffersCollection.

```APIDOC
## getOffersOnProducts

### Description
Gets offers on products using the provided request. Returns a ProductWithOffersCollection.

### Method
getOffersOnProducts

### Parameters
- **$request** (GetOffersOnProductsRequest) - Required - The request object for getting offers on products.

### Response
#### Success Response
- **ProductWithOffersCollection** - The collection of products with offers.
```

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

### Usage example with ShopApiClient

Source: https://github.com/mirakl/sdk-php-shop

Shows how to instantiate ShopApiClient and call getVersion() and getLocales(). Demonstrates the execution chain described in abstract-api-client.md.

```php
$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$version = $api->getVersion();               // \Mirakl\MMP\Common\Domain\Version
echo $version->getVersion();

$locales = $api->getLocales();               // \Mirakl\MMP\Common\Domain\Collection\Locale\LocaleCollection
foreach ($locales as $locale) {
    echo $locale->getCode() . ' ' . $locale->getLabel();
}
```

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

### getPromotions

Source: https://github.com/mirakl/sdk-php-shop

Gets promotions using the provided request. Returns a PromotionCollection.

```APIDOC
## getPromotions

### Description
Gets promotions using the provided request. Returns a PromotionCollection.

### Method
getPromotions

### Parameters
- **$request** (GetPromotionsRequest) - Required - The request object for getting promotions.

### Response
#### Success Response
- **PromotionCollection** - The collection of promotions.
```

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

### getOffers

Source: https://github.com/mirakl/sdk-php-shop

Gets offers using the provided request. Returns a ShopOfferCollection.

```APIDOC
## getOffers

### Description
Gets offers using the provided request. Returns a ShopOfferCollection.

### Method
getOffers

### Parameters
- **$request** (GetOffersRequest) - Required - The request object for getting offers.

### Response
#### Success Response
- **ShopOfferCollection** - The collection of shop offers.
```

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

### Using AuthApiClient to get credentials

Source: https://github.com/mirakl/sdk-php-shop

Example usage: instantiate AuthApiClient with the marketplace API URL, pass a ClientCredentialsRequest with client ID and secret, then access the token, expiry, and marketplace ID.

```php
use Mirakl\Core\Client\AuthApiClient;
use Mirakl\Core\Request\Auth\ClientCredentialsRequest;

$auth = new AuthApiClient('https://your-marketplace.mirakl.net/api');
$credentials = $auth->getCredentials(new ClientCredentialsRequest('CLIENT_ID', 'CLIENT_SECRET'));
echo $credentials->getAccessToken(); // bearer token
echo $credentials->getExpiresIn();   // lifetime in seconds
echo $credentials->getMarketplaceId();
```

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

### Create Promotions Request Example

Source: https://github.com/mirakl/sdk-php-shop

Shows how to build a promotion payload and call createPromotions(). The request returns void. Configure trigger/reward sub-objects as needed.

```php
use Mirakl\MMP\Common\Domain\Promotion\CreatePromotions\Promotion;   // payload example
use Mirakl\MMP\Shop\Request\Promotion\CreatePromotionsRequest;

$promotion = new \Mirakl\MMP\Common\Domain\Promotion\CreatePromotions\Promotion();
$promotion->setInternalDescription('Summer sale')->setChannels(['DEFAULT']);
// configure trigger/reward...
$api->createPromotions(new CreatePromotionsRequest([$promotion])); // void
```

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

### Using GetOrdersRequest to retrieve orders

Source: https://github.com/mirakl/sdk-php-shop

Example usage: creates GetOrdersRequest, sets order states, order IDs, start update date, and max. Calls $api->getOrders($request) and iterates over ShopOrderCollection, printing order ID and status state, then total count.

```php
use Mirakl\MMP\Shop\Request\Order\Get\GetOrdersRequest;

$request = new GetOrdersRequest();
$request->setOrderStates(['SHIPPING', 'SHIPPED'])
    ->setOrderIds(['order-12345'])
    ->setStartUpdateDate(new \DateTime('2024-01-01T00:00:00Z'))
    ->setMax(50);

$orders = $api->getOrders($request);
foreach ($orders as $order) {
    echo $order->getId() . ' — ' . $order->getStatus()->getState();
}
echo 'Total: ' . $orders->getTotalCount();
```

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

### Initialize ShopApiClient and Fetch an Offer

Source: https://github.com/mirakl/sdk-php-shop

Creates a ShopApiClient with the marketplace URL, API key, and shop ID, then retrieves an offer by ID using GetOfferRequest. The returned offer is a ShopOffer object; the example prints its SKU and price.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Offer\GetOfferRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$offer = $api->getOffer(new GetOfferRequest('OFFER_ID'));   // \Mirakl\MMP\Shop\Domain\Offer\ShopOffer
echo $offer->getSku() . ' — ' . $offer->getPrice();
```

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

### GET /returns/items_to_return

Source: https://github.com/mirakl/sdk-php-shop

Gets items to return (RT12). Sends a GET request to /returns/items_to_return and returns a seekable collection of items.

```APIDOC
## [GET] /returns/items_to_return

### Description
Gets items to return (RT12). Sends a GET request to /returns/items_to_return and returns a seekable collection of items.

### Method
GET

### Endpoint
/returns/items_to_return

### Response
#### Success Response (200)
- **SeekableCollection** - A seekable collection of items to return.
```

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

### Usage example for GetOffersRequest

Source: https://github.com/mirakl/sdk-php-shop

Shows how to instantiate GetOffersRequest with a shop ID, set offer state codes, SKU, and max results, then iterate over the returned ShopOfferCollection to print SKU and price.

```php
$request = new GetOffersRequest('your-shop-id');
$request->setOfferStateCodes(['ACTIVE'])->setSku('SKU-001')->setMax(50);
foreach ($api->getOffers($request) as $offer) {
    echo $offer->getSku() . ' — ' . $offer->getPrice();
}
```

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

### GET /returns

Source: https://github.com/mirakl/sdk-php-shop

Gets returns (RT11). Sends a GET request to /returns with optional filters and returns a seekable collection of returns.

```APIDOC
## [GET] /returns

### Description
Gets returns (RT11). Sends a GET request to /returns with optional filters and returns a seekable collection of returns.

### Method
GET

### Endpoint
/returns

### Query Parameters
- **order_ids** (array) - Optional - Filter by order IDs.
- **return_ids** (array) - Optional - Filter by return IDs.
- **states** (array) - Optional - Filter by return states.
- **start_creation_date** (date) - Optional - Filter by creation start date.
- **end_creation_date** (date) - Optional - Filter by creation end date.
- **reason_codes** (array) - Optional - Filter by reason codes.

### Response
#### Success Response (200)
- **SeekableCollection** - A seekable collection of returns.
```

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

### getOptions()

Source: https://github.com/mirakl/sdk-php-shop

Returns the current options array.

```APIDOC
## getOptions()

### Description
Returns the current options array.

### Method
`getOptions`

### Returns
array - The current options.
```

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

### GET /promotions

Source: https://github.com/mirakl/sdk-php-shop

Retrieves promotions. This endpoint returns a collection of promotions.

```APIDOC
## GET /promotions

### Description
Retrieves promotions.

### Method
GET

### Endpoint
/promotions

### Response
#### Success Response (200)
- **body** (PromotionCollection) - The collection of promotions.

```

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

### ShopOffer mapping example

Source: https://github.com/mirakl/sdk-php-shop

Real-world mapping from ShopOffer class, showing extensive aliasing of nested API keys to flat local keys for product, category, shipping, availability, and additional fields.

```php
protected static $mapping = [
    'product_brand'                 => 'product/brand',
    'product_description'           => 'product/description',
    'product_sku'                   => 'product/sku',
    'product_title'                 => 'product/title',
    'product_references'            => 'product/references',
    'category_code'                 => 'product/category/code',
    'category_label'                => 'product/category/label',
    'category_type'                 => 'product/category/type',
    'min_shipping_price'            => 'min_shipping/price',
    'min_shipping_price_additional' => 'min_shipping/price_additional',
    'min_shipping_type'             => 'min_shipping/type_code',
    'min_shipping_zone'             => 'min_shipping/zone_code',
    'available_start_date'          => 'availability/start_date',
    'available_end_date'            => 'availability/end_date',
    'offer_additional_fields'       => 'additional_fields',
    'shop_sku'                      => 'sku',
];
```

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

### GET /products

Source: https://github.com/mirakl/sdk-php-shop

Retrieves the list of products. This endpoint returns a collection of products.

```APIDOC
## GET /products

### Description
Retrieves the list of products.

### Method
GET

### Endpoint
/products

### Response
#### Success Response (200)
- **body** (ProductCollection) - The collection of products.

```

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

### GET /orders/taxes

Source: https://github.com/mirakl/sdk-php-shop

Get order taxes. This endpoint retrieves the tax information for orders.

```APIDOC
## [GET] /orders/taxes

### Description
Get order taxes.

### Method
GET

### Endpoint
/orders/taxes

### Response
#### Success Response (200)
- **OrderTaxCollection** - The order tax collection

```

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

### Get order taxes with GetOrderTaxesRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/OR75.md

Use the ShopApiClient to call getOrderTaxes with a GetOrderTaxesRequest. The result is an OrderTaxCollection instance.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Order\Tax\GetOrderTaxesRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$request = new GetOrderTaxesRequest();
$result = $api->getOrderTaxes($request);
// $result => @see \Mirakl\MMP\Shop\Domain\Collection\Order\Tax\OrderTaxCollection
```

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

### Hydration chain with ShopOffer

Source: https://github.com/mirakl/sdk-php-shop

Shows how to instantiate a ShopOffer with nested data. The available_start_date string is converted to \DateTime via $dateFields, and retail_prices is mapped to RetailPriceCollection via $dataTypes. Demonstrates getters and toJSON output.

```php
use Mirakl\MMP\Shop\Domain\Offer\ShopOffer;

$offer = new ShopOffer([
    'product_sku' => 'SKU-001',       // mapped to product/sku
    'available_start_date' => '2024-01-01T00:00:00Z', // \DateTime via $dateFields
    'retail_prices' => [              // RetailPriceCollection via $dataTypes
        ['price' => 12.5, 'currency_iso_code' => 'EUR'],
    ],
]);

echo $offer->getSku();                              // 'SKU-001'
echo $offer->getAvailableStartDate()->format('Y-m-d'); // 2024-01-01
echo $offer->getRetailPrices()->first()->getPrice();    // 12.5
echo $offer->toJSON();
```

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

### GET /orders/{order}/evaluation

Source: https://github.com/mirakl/sdk-php-shop

Get order evaluation. This endpoint retrieves the evaluation for a specific order.

```APIDOC
## [GET] /orders/{order}/evaluation

### Description
Get order evaluation.

### Method
GET

### Endpoint
/orders/{order}/evaluation

### Parameters
#### Path Parameters
- **order** (string) - Required - The order ID

### Response
#### Success Response (200)
- **Evaluation** - The order evaluation

```

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

### Import offers using ShopApiClient

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/OF01.md

Use this snippet to import offers from a CSV file into the Mirakl marketplace. It creates a ShopApiClient with your marketplace URL, API key, and shop ID, then sends an OfferImportRequest with optional import mode and product inclusion. The result is an OfferImportTracking object.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Offer\Importer\OfferImportRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$file = new \SplFileObject('/path/to/file.csv');
$request = new OfferImportRequest($file);
$request->setImportMode(\Mirakl\MMP\OperatorShop\Domain\Offer\Importer\ImportMode::PARTIAL_UPDATE); // Optional
$request->setWithProducts(true); // Optional
$result = $api->importOffers($request);
// $result => @see \Mirakl\MMP\OperatorShop\Domain\Offer\Importer\OfferImportTracking
```

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

### GetAccountStatisticsRequest — get shop statistics

Source: https://github.com/mirakl/sdk-php-shop

GET /account/statistics with query params 'channel_code' and 'periods'. Returns AccountStatisticsResponse with metric collections.

```php
protected $endpoint = '/account/statistics';
public $queryParams = ['channel_code', 'periods'];
```

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

### List promotions with GetPromotionsRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/PR01.md

Creates a ShopApiClient and a GetPromotionsRequest, sets filters (types, states, ending date, channel codes, max), then calls getPromotions. The result is a PromotionCollection; the loop prints each promotion's start and end dates.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Promotion\GetPromotionsRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$request = new GetPromotionsRequest();
$request->setTypes(['AMOUNT_OFF', 'PERCENTAGE_OFF'])
    ->setStates(['ACTIVE', 'PENDING'])
    ->setEndingAfter(new \DateTime('2024-12-31'))
    ->setChannelCodes(['CHANNEL_WEB'])
    ->setMax(10);

$result = $api->getPromotions($request);
// $result => @see \Mirakl\MMP\Shop\Domain\Collection\Promotion\PromotionCollection

foreach ($result as $promotion) {
    echo $promotion->getStartDate()->format('Y-m-d') . ' - ' . $promotion->getEndDate()->format('Y-m-d');
}
```

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

### Constructor

Source: https://github.com/mirakl/sdk-php-shop

Creates a new ShopApiClient instance with the given base URL, API key, and optional shop ID.

```APIDOC
## Constructor

### Description
Creates a new ShopApiClient instance.

### Method
`__construct`

### Parameters
- `$baseUrl` (string) - Required - Mirakl environment base URL, e.g. `https://your-marketplace.mirakl.net/api`
- `$apiKey` (string) - Required - seller API key (sent as `Authorization` header)
- `$shopId` (string|null) - Optional - shop identifier added as global `shop_id` query parameter on every request

### Example
```php
use Mirakl\MMP\Shop\Client\ShopApiClient;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
```
```

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

### getClient()

Source: https://github.com/mirakl/sdk-php-shop

Returns the lazy default GuzzleHttp\Client.

```APIDOC
## getClient()

### Description
Returns the lazy default `GuzzleHttp\Client`.

### Method
`getClient`

### Returns
GuzzleHttp\Client - The client instance.
```

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

### DownloadOrdersDocumentsRequest (OR73) — download documents

Source: https://github.com/mirakl/sdk-php-shop

GET /orders/documents/download. Set order IDs and call downloadOrdersDocuments to get a FileWrapper, then call download() to save the file.

```php
// GET /orders/documents/download
$request = new DownloadOrdersDocumentsRequest();
$request->setOrderIds(['ORDER_ID_1', 'ORDER_ID_2']);
$file = $api->downloadOrdersDocuments($request); // FileWrapper
$file->download();
```

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

### Instantiate ShopApiClient with baseUrl, apiKey, and shopId

Source: https://github.com/mirakl/sdk-php-shop

Creates a Mirakl shop API client using the constructor signature `__construct($baseUrl, $apiKey, $shopId = null)`. The `baseUrl` is normalized to `rtrim($url, '/') . '/'` for the Guzzle `base_uri`, `apiKey` is sent as the `Authorization` header on every request, and `shopId` sets the global `shop_id` query parameter.

```php
$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
```

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

### Get products by references using GetProductsRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/P31.md

Creates a ShopApiClient and a GetProductsRequest with a ProductReference (type 'EAN', value '0882780560413'), then calls getProducts(). The result is a ProductCollection instance.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Product\GetProductsRequest;
use Mirakl\MMP\Common\Domain\Product\Offer\ProductReference;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$request = new GetProductsRequest([new ProductReference('EAN', '0882780560413')]);
$result = $api->getProducts($request);
// $result => @see \Mirakl\MMP\Shop\Domain\Collection\Product\ProductCollection
```

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

### GetAccountRequest — get shop account information

Source: https://github.com/mirakl/sdk-php-shop

GET /account with no constructor args. Returns ShopAccount with hydrated nested objects. The client convenience method auto-creates the request.

```php
$account = $api->getAccount();               // ShopAccount — client convenience auto-creates request
echo $account->getContactInformation()->getEmail();
```

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

### GetOffersOnProductsRequest: List offers for each product

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/P11.md

Use this snippet to retrieve offers for a list of product SKUs via the Mirakl Shop API. It creates a GetOffersOnProductsRequest with the product SKU 'product-sku-001', sets channel codes to 'CHANNEL_WEB', offer state codes to '11', enables all offers, and limits results to 10. The response is a ProductWithOffersCollection, and the example iterates over the result to echo each product's SKU.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Product\Offer\GetOffersOnProductsRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$request = new GetOffersOnProductsRequest(['product-sku-001']);
$request->setChannelCodes(['CHANNEL_WEB'])
    ->setOfferStateCodes(['11'])
    ->setAllOffers(true)
    ->setMax(10);

$result = $api->getOffersOnProducts($request);
// $result => @see \Mirakl\MMP\Shop\Domain\Collection\Product\Offer\ProductWithOffersCollection

foreach ($result as $product) {
    echo $product->getProduct()->getSku();
}
```

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

### Get additional fields with GetAdditionalFieldRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/AF01.md

Use ShopApiClient to retrieve additional fields for specified entities. The setEntities() call is optional; without it, all entities are returned. The result is an AdditionalFieldCollection.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\AdditionalField\GetAdditionalFieldRequest;
use Mirakl\MMP\Common\Domain\AdditionalField\AdditionalFieldLinkedEntity;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$request = new GetAdditionalFieldRequest();
$request->setEntities([AdditionalFieldLinkedEntity::OFFER, AdditionalFieldLinkedEntity::SHOP]); // Optional
$result = $api->getAdditionalFields($request);
// $result => @see \Mirakl\MMP\Shop\Domain\Collection\AdditionalFieldCollection
```

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

### Create a promotion using CreatePromotionsRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/PR03.md

Creates a promotion via the Mirakl Shop API client. Configures a percentage-off reward, a minimum quantity trigger, and a public description, then sends the request with createPromotions(). The call returns no value.

```php
use Mirakl\MMP\Common\Domain\Collection\Promotion\CreatePromotions\PublicDescriptionCollection;
use Mirakl\MMP\Common\Domain\Promotion\CreatePromotions\PublicDescription;
use Mirakl\MMP\Common\Domain\Promotion\CreatePromotions\Reward\PercentageOffReward;
use Mirakl\MMP\Common\Domain\Promotion\CreatePromotions\Trigger\MinimumQuantityTrigger;
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Promotion\CreatePromotionsRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$reward = (new PercentageOffReward())
    ->setPercentageOff(100.0)
    ->setMaxQuantityToDiscount(1);

$trigger = (new MinimumQuantityTrigger())
    ->setQuantityPurchased(2);

$description = (new PublicDescription())
    ->setLocale('en_US')
    ->setValue('Buy 2, get 1 free');

$request = new CreatePromotionsRequest();
$request->setInternalId('PROMO-BUY2GET1')
    ->setStartDate(new \DateTime('2024-06-01T00:00:00Z'))
    ->setEndDate(new \DateTime('2024-08-31T23:59:59Z'))
    ->setPublicDescriptions(new PublicDescriptionCollection([$description]))
    ->setReward($reward)
    ->setTrigger($trigger);

$api->createPromotions($request);
// No return value
```

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

### Get order evaluation using GetOrderEvaluationRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/OR51.md

Retrieves the evaluation for a specific order in the Mirakl shop API. Requires a ShopApiClient instance with marketplace URL, API key, and shop ID. The result is a Mirakl\MMP\Common\Domain\Evaluation object.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Order\Evaluation\GetOrderEvaluationRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$request = new GetOrderEvaluationRequest('ORDER_ID');
$result = $api->getOrderEvaluation($request);
// $result => @see \Mirakl\MMP\Common\Domain\Evaluation
```

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

### Import a stock file using CreateOffersStockImportsRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/STO01.md

Creates a stock import by sending a CSV file to the Mirakl Shop API. Requires a ShopApiClient with the marketplace URL, API key, and shop ID. The response provides the import ID via getImportId().

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Offer\Stock\CreateOffersStockImportsRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$request = new CreateOffersStockImportsRequest(new \SplFileObject('/path/to/stock.csv'));

$result = $api->createOffersStockImports($request);
// $result => @see \Mirakl\MMP\Common\Domain\Offer\Stock\OffersStockImportsResponse
// $result->getImportId()
```

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

### createPromotions()

Source: https://github.com/mirakl/sdk-php-shop

Creates promotions. Takes an AbstractCreatePromotionsRequest and returns void.

```APIDOC
## createPromotions()

### Description
Creates promotions.

### Parameters
#### Request Body
- **request** (AbstractCreatePromotionsRequest) - Required - The request object containing promotion details.

### Response
#### Success Response
- **void** - No return value.

### Request Example
```php
$api->createPromotions(new CreatePromotionsRequest($promotions));
```
```

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

### Get accounting document request lines with pagination

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/DR12.md

Use GetAccountingDocumentLinesRequest with ShopApiClient to fetch document request lines. The response is a SeekableCollection; loop with getCollection() and paginate using setPageToken() with getNextPageToken().

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\DocumentRequest\GetAccountingDocumentLinesRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$documentRequestId = '681ab1e8-5e70-49b6-9489-36e766d64328';
$request = new GetAccountingDocumentLinesRequest($documentRequestId);

$result = $api->getAccountingDocumentLinesRequests($request);
// $result => @see \Mirakl\MMP\Common\Domain\Collection\SeekableCollection

// Loop on collection with $result->getCollection()
$collection = $result->getCollection();
// $collection => @see \Mirakl\MMP\OperatorShop\Domain\Collection\DocumentRequest\DocumentRequestLineResponseCollection

// Get next results with token from response:
$request = new GetAccountingDocumentLinesRequest($documentRequestId);
$request->setPageToken($result->getNextPageToken());
$result = $api->getAccountingDocumentLinesRequests($request);
// $result => @see \Mirakl\MMP\Common\Domain\Collection\SeekableCollection
```

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

### Get shop information with ShopApiClient::getAccount()

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/A01.md

Retrieve the shop account details using the Mirakl MMP Shop API client. Requires the marketplace URL, API key, and shop ID. The result is a ShopAccount domain object.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Offer\GetAccountRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$result = $api->getAccount();
// $result => @see \Mirakl\MMP\Shop\Domain\Shop\ShopAccount
```

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

### POST /promotions

Source: https://github.com/mirakl/sdk-php-shop

Creates promotions. This endpoint returns no content.

```APIDOC
## POST /promotions

### Description
Creates promotions.

### Method
POST

### Endpoint
/promotions

### Response
#### Success Response (200)
- **body** (void) - No content.

```

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

### getOptions()

Source: https://github.com/mirakl/sdk-php-shop

Returns an array of all current request options.

```APIDOC
## getOptions()

### Description
Returns an array of all current request options.

### Returns
- **array** - All request options.
```

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

### Example Version class using @method annotations

Source: https://github.com/mirakl/sdk-php-shop

Shows how to use @method phpdoc annotations to expose magic getter/setter methods on a MiraklObject subclass.

```php
/** @method string  getVersion()
 *  @method Version setVersion(string $version) */
class Version extends MiraklObject {}
```

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

### Get accounting documents requests with pagination using GetAccountingDocumentsRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/DR11.md

Initializes the ShopApiClient and retrieves accounting document requests. The response is a SeekableCollection; use getCollection() to access items and setPageToken() with getNextPageToken() to fetch subsequent pages.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\DocumentRequest\GetAccountingDocumentsRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$request = new GetAccountingDocumentsRequest();

$result = $api->getAccountingDocumentsRequests($request);
// $result => @see \Mirakl\MMP\Common\Domain\Collection\SeekableCollection

// Loop on collection with $result->getCollection()
$collection = $result->getCollection();
// $collection => @see \Mirakl\MMP\OperatorShop\Domain\Collection\DocumentRequest\AccountingDocumentRequestResponseCollection

// Get next results with token from response:
$request = new GetAccountingDocumentsRequest();
$request->setPageToken($result->getNextPageToken());
$result = $api->getAccountingDocumentsRequests($request);
// $result => @see \Mirakl\MMP\Common\Domain\Collection\SeekableCollection
```

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

### ShopApiClient usage example

Source: https://github.com/mirakl/sdk-php-shop

Shows how to instantiate a `ShopApiClient` with an auto-set shop ID, switch scope with `setShopId`, and retrieve the current value with `getShopId`.

```php
$api = new ShopApiClient('https://env/api', 'key', 'SHOP-123'); // shopId auto-set
$api->setShopId('OTHER-SHOP'); // switch scope
echo $api->getShopId(); // 'OTHER-SHOP'
```

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

### Instantiate ShopApiClient

Source: https://github.com/mirakl/sdk-php-shop

Create a new ShopApiClient instance with a Mirakl environment base URL, seller API key, and shop ID. The shop ID is sent as a global shop_id query parameter on every request.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
```

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

### Get shop statistics with GetAccountStatisticsRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/A21.md

Use ShopApiClient to retrieve shop statistics. Set a channel code and periods (e.g., 'ALL_SINCE_BEGINNING', 'LAST_MONTH') before calling getAccountStatistics. The result is an AccountStatisticsResponse object with methods like getApprovalRate(), getOrdersCount(), and getGrade().

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Account\GetAccountStatisticsRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$request = new GetAccountStatisticsRequest();
$request->setChannelCode('CHANNEL_WEB');
$request->setPeriods(['ALL_SINCE_BEGINNING', 'LAST_MONTH']);

$result = $api->getAccountStatistics($request);
// $result => @see \Mirakl\MMP\Shop\Domain\Account\AccountStatisticsResponse

$approvalRate = $result->getApprovalRate();
$ordersCount = $result->getOrdersCount();
$grade = $result->getGrade();
```

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

### List shop roles with GetUsersShopsRolesRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/RO02.md

Use this snippet to retrieve the list of roles for the current shop. It creates a ShopApiClient with your marketplace URL, API key, and shop ID, then sends a GetUsersShopsRolesRequest. The result is a RoleCollection; iterate over it and call toArray() on each role to access its data.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\User\Shop\GetUsersShopsRolesRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$request = new GetUsersShopsRolesRequest();
$result = $api->getUsersShopsRoles($request);
// $result => @see \Mirakl\MMP\Common\Domain\Collection\User\Shop\RoleCollection

foreach ($result as $role) {
    $role->toArray();
}
```

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

### Get product import statuses with Mirakl Shop API

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/P51.md

Use this snippet to retrieve product import statuses from the Mirakl Shop API. It creates a ShopApiClient with your marketplace URL, API key, and shop ID, then sends a ProductImportStatusesRequest. The result is a ProductImportResultCollection object.

```php
use Mirakl\MCI\Shop\Client\ShopApiClient;
use Mirakl\MCI\Shop\Request\Product\ProductImportStatusesRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$request = new ProductImportStatusesRequest();

$result = $api->getProductImportStatuses($request);
// $result => @see \Mirakl\MCI\Common\Domain\Collection\Product\ProductImportResultCollection
```

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

### Usage with GetOrdersRequest

Source: https://github.com/mirakl/sdk-php-shop

Shows how to instantiate a request, set query parameters, and inspect the method, endpoint, and query parameters. The output comments indicate GET and /orders.

```php
use Mirakl\MMP\Shop\Request\Order\Get\GetOrdersRequest;

$request = new GetOrdersRequest();
$request->setOrderStates(['SHIPPING', 'SHIPPED'])
    ->setOrderIds(['order-12345'])
    ->setStartUpdateDate(new \DateTime('2024-01-01T00:00:00Z'))
    ->setMax(50)
    ->setOffset(0);

echo $request->getMethod();   // GET
echo $request->getEndpoint(); // /orders
print_r($request->getQueryParams());
```

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

### Get product import status with ProductImportStatusRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/P42.md

Use ShopApiClient::getProductImportStatus() with a ProductImportStatusRequest to retrieve the status of a product import by its import ID. The result is a ProductImportResult object. Requires a valid API key and shop ID.

```php
use Mirakl\MCI\Shop\Client\ShopApiClient;
use Mirakl\MCI\Shop\Request\Product\ProductImportStatusRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$request = new ProductImportStatusRequest('IMPORT_ID');
$result = $api->getProductImportStatus($request);
// $result => @see \Mirakl\MCI\Common\Domain\Product\ProductImportResult
```

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

### Instantiate a Mirakl API client

Source: https://github.com/mirakl/sdk-php-shop

Creates a client with a Mirakl environment base URL and an API key. The API key sets the Authorization header on the default client when provided.

```php
$client = new SomeApiClient('https://your-marketplace.mirakl.net/api', 'my-api-key');
```

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

### Export offers to file with OffersExportFileRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/OF51.md

Creates a ShopApiClient and an OffersExportFileRequest, sets includeInactiveOffers to true, and calls exportOffersToFile to retrieve a FileWrapper result. Use this to get offers updated and deleted since the last request date.

```php
use Mirakl\MMP\Shop\Client\ShopApiClient;
use Mirakl\MMP\Shop\Request\Offer\OffersExportFileRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');

$request = new OffersExportFileRequest();
$request->setIncludeInactiveOffers(true);

$result = $api->exportOffersToFile($request);
// $result => @see \Mirakl\Core\Domain\FileWrapper;
```

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

### Get value lists items with GetValueListsItemsRequest

Source: https://github.com/mirakl/sdk-php-shop/blob/master/docs/examples/shop/VL11.md

Use this snippet to retrieve the operator's value lists from the Mirakl Shop API. It requires a ShopApiClient instance with your marketplace URL, API key, and shop ID. The result is a ValueLists domain object.

```php
use Mirakl\MCI\Shop\Client\ShopApiClient;
use Mirakl\MCI\Shop\Request\ValueList\GetValueListsItemsRequest;

$api = new ShopApiClient('https://your-marketplace.mirakl.net/api', 'your-api-key', 'your-shop-id');
$request = new GetValueListsItemsRequest();
$result = $api->getValueLists($request);
// $result => @see \Mirakl\MCI\Common\Domain\ValueLists

```

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

### GET /hierarchies

Source: https://github.com/mirakl/sdk-php-shop

Retrieves the list of hierarchies.

```APIDOC
## GET /hierarchies

### Description
Retrieves the list of hierarchies.

### Method
GET

### Endpoint
/hierarchies

### Response
#### Success Response (200)
- `hierarchies` (array) - A list of hierarchies.
  - `code` (string) - The hierarchy code.
  - `label` (string) - The hierarchy label.
  - `parent_code` (string) - The parent hierarchy code.
```
Tokens:
Raw