Amazon Creators API PHP SDK

https://github.com/thewirecutter/paapi5-php-sdk
Admin
Amazon Creators API PHP SDK is an open-source PHP client library that allows developers to access...
Tokens:72,585
Snippets:439
Trust Score:5.1
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### getItems Usage Example

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

A standard implementation of the getItems operation, including configuration setup and error handling.

```php
use Amazon
atorsAPI\v1\ApiException;
use Amazon
atorsAPI\v1\Configuration;
use Amazon
atorsAPI\v1\com\amazon\creators\api\DefaultApi;
use Amazon
atorsAPI\v1\com\amazon\creators\model\GetItemsRequestContent;
use Amazon
atorsAPI\v1\com\amazon\creators\model\GetItemsResource;

$config = new Configuration();
$config->setCredentialId('client-id')->setCredentialSecret('client-secret')->setVersion('3.1');

$api = new DefaultApi(null, $config);

$request = new GetItemsRequestContent();
$request->setPartnerTag('YOUR-TAG');
$request->setItemIds(['B0DLFMFBJW', 'B0BFC7WQ6R']);
$request->setResources([
    GetItemsResource::IMAGES_PRIMARY_MEDIUM,
    GetItemsResource::ITEM_INFO_TITLE,
    GetItemsResource::OFFERS_V2_LISTINGS_PRICE,
]);

try {
    $response = $api->getItems('www.amazon.com', $request); // GetItemsResponseContent
    foreach ($response->getItemsResult()->getItems() as $item) {
        echo $item->getAsin() . ': ' . $item->getItemInfo()->getTitle()->getDisplayValue() . PHP_EOL;
    }
} catch (ApiException $e) {
    printf("[%d] %s", $e->getCode(), $e->getMessage());
    if ($e->getResponseObject()) {
        echo json_encode($e->getResponseObject(), JSON_PRETTY_PRINT);
    }
}
```

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

### HeaderSelector usage example

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/HeaderSelector.md

Example showing how to instantiate HeaderSelector and use selectHeaders, isJsonMime, and getNextWeight. Demonstrates Accept header generation, JSON mime detection, multipart behavior, and weight stepping.

```php
use Amazon\CreatorsAPI\v1\HeaderSelector;

$selector = new HeaderSelector();

$headers = $selector->selectHeaders(
    ['application/json', 'application/xml'],
    'application/json',
    false
);
// ['Accept' => 'application/json,application/xml;q=0.9', 'Content-Type' => 'application/json']

var_dump($selector->isJsonMime('application/vnd.api+json')); // true
var_dump($selector->isJsonMime('text/html'));                // false

// Multipart: no Content-Type emitted
$headers = $selector->selectHeaders(['application/json'], 'application/json', true);
// ['Accept' => 'application/json']

// Weight series with ≤ 28 headers
echo $selector->getNextWeight(1000, false); // 900
echo $selector->getNextWeight(100, false);  // 90
echo $selector->getNextWeight(2, false);    // 1
```

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

### GetItems Response Example

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/responses.md

Example of reading a GetItems response using the SDK, demonstrating how to access item details, offers, and partial errors.

```APIDOC
## [GET] /paapi5/getitems

### Description
Retrieves product information for one or more items using their ASINs. The response includes item details, offers, and any partial errors.

### Method
GET

### Endpoint
/paapi5/getitems

### Parameters
#### Query Parameters
- **ItemIdType** (string) - Required - The type of item identifier (e.g., ASIN).
- **ItemIds** (array of string) - Required - The item identifiers to look up.
- **PartnerType** (string) - Required - The partner type (e.g., Associates).
- **PartnerTag** (string) - Required - The partner tag (tracking ID).
- **Marketplace** (string) - Optional - The marketplace (e.g., www.amazon.com).
- **Resources** (array of string) - Optional - The list of resource names to include in the response.

### Request Example
```json
{
  "ItemIdType": "ASIN",
  "ItemIds": ["B0XXXXXXXX"],
  "PartnerType": "Associates",
  "PartnerTag": "yourtag-20",
  "Marketplace": "www.amazon.com",
  "Resources": ["ItemInfo.Title", "Offers.Listings.Price"]
}
```

### Response
#### Success Response (200)
- **ItemsResult** (object) - Contains the requested items.
  - **Items** (array of Item) - The list of items.
- **Errors** (array of ErrorData) - Partial errors that occurred during processing.

#### Response Example
```json
{
  "ItemsResult": {
    "Items": [
      {
        "ASIN": "B0XXXXXXXX",
        "DetailPageURL": "https://www.amazon.com/dp/B0XXXXXXXX",
        "ItemInfo": {
          "Title": {
            "DisplayValue": "Example Product"
          }
        },
        "Offers": {
          "Listings": [
            {
              "Price": {
                "Money": {
                  "DisplayAmount": "$19.99"
                }
              }
            }
          ]
        }
      }
    ]
  },
  "Errors": []
}
```
```

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

### searchItems usage example

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Example of configuring a SearchItemsRequestContent object and executing a searchItems request.

```php
use Amazon\/CreatorsAPI\/v1\/com\/amazon\/creators\/model\/SearchItemsRequestContent;

$search = new SearchItemsRequestContent();
$search->setPartnerTag('YOUR-TAG')
       ->setKeywords('Harry Potter')
       ->setSearchIndex('Books')
       ->setItemCount(2);

$response = $api->searchItems('www.amazon.com', $search);
echo $response->getSearchResult()->getTotalResultCount();
```

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

### Initialize DefaultApi with Configuration

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Example of instantiating the DefaultApi by providing a custom Configuration object while allowing the client and header selector to be auto-created.

```php
use Amazon
íklad
use Amazon

$config = new Configuration();
$config->setCredentialId('client-id');
$config->setCredentialSecret('client-secret');
$config->setVersion('3.1');

$api = new DefaultApi(null, $config); // Guzzle client and HeaderSelector are auto-created
```

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

### Initialize and Configure GetItemsRequestContent

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/requests.md

Example showing how to instantiate the GetItemsRequestContent model and use fluent setters to configure request parameters.

```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\Condition;
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\GetItemsRequestContent;
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\GetItemsResource;

$request = new GetItemsRequestContent(['partnerTag' => 'YOUR-TAG']); // constructor also accepts data array
$request->setItemIds(['B0BFC7WQ6R', 'B0DLFMFBJW'])
        ->setCondition(Condition::_NEW);
```

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

### listFeeds Usage Example

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Example of calling listFeeds and iterating through the returned feed objects.

```php
$response = $api->listFeeds('www.amazon.com');
foreach ($response->getFeeds() as $feed) {
    echo $feed->getFeedName() . ' (' . $feed->getLastUpdated() . ')' . PHP_EOL;
}
```

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

### Instantiate GetBrowseNodesRequestContent

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/requests.md

Example showing how to instantiate and configure the GetBrowseNodesRequestContent object with a partner tag, browse node IDs, and resources.

```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\GetBrowseNodesRequestContent;
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\GetBrowseNodesResource;

$request = new GetBrowseNodesRequestContent();
$request->setPartnerTag('YOUR-TAG')
        ->setBrowseNodeIds(['283155'])
        ->setResources([GetBrowseNodesResource::ANCESTOR, GetBrowseNodesResource::CHILDREN]);
```

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

### Retrieve Product Details with GetItems

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/README.md

Example demonstrating how to configure the API client and request product details for specific ASINs using the GetItems operation.

```php
<?php

require_once(__DIR__ . '/vendor/autoload.php');

use Amazon\
CreatorsAPI\
v1\
Configuration;
use Amazon\
CreatorsAPI\
v1\
com\
amazon\
creators\
api\
DefaultApi;
use Amazon\
CreatorsAPI\
v1\
com\
amazon\
creators\
model\
GetItemsRequestContent;
use Amazon\
CreatorsAPI\
v1\
com\
amazon\
creators\
model\
GetItemsResource;
use Amazon\
CreatorsAPI\
v1\
ApiException;

$config = new Configuration();
$config->setCredentialId('<YOUR CREDENTIAL ID>');
$config->setCredentialSecret('<YOUR CREDENTIAL SECRET>');
$config->setVersion('<YOUR CREDENTIAL VERSION>');

$api = new DefaultApi(null, $config);

$marketplace = 'www.amazon.com';

$resources = [
    GetItemsResource::IMAGES_PRIMARY_MEDIUM,
    GetItemsResource::ITEM_INFO_TITLE,
    GetItemsResource::OFFERS_V2_LISTINGS_PRICE,
];

$request = new GetItemsRequestContent();
$request->setPartnerTag('<YOUR PARTNER TAG>');
$request->setItemIds(['B0DLFMFBJW', 'B0BFC7WQ6R']);
$request->setResources($resources);

try {
    $response = $api->getItems($marketplace, $request);
    echo 'API called successfully' . PHP_EOL;
    echo json_encode($response, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES) . PHP_EOL;
} catch (ApiException $e) {
    echo 'Error calling Creators API!' . PHP_EOL;
    echo $e . PHP_EOL;
} catch (Exception $e) {
    echo 'Unexpected error: ' . $e . PHP_EOL;
}
```

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

### Instantiate GetFeedRequestContent

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/requests.md

Example showing how to instantiate and configure the GetFeedRequestContent object with a feed name.

```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\GetFeedRequestContent;

$request = new GetFeedRequestContent();
$request->setFeedName('product_data_feed_2024-01-01.csv.gz'); // name from listFeeds response
```

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

### Instantiating and Configuring GetVariationsRequestContent

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/requests.md

Example showing how to instantiate the request object and set required and optional properties using the fluent setter methods.

```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\GetVariationsRequestContent;

$request = new GetVariationsRequestContent();
$request->setPartnerTag('YOUR-TAG')
        ->setAsin('B0BFC7WQ6R')
        ->setVariationPage(1)
        ->setVariationCount(10);
```

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

### Install SDK via Composer

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/README.md

Use Composer to add the SDK to your project dependencies.

```sh
composer require thewirecutter/paapi5-php-sdk
```

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

### listReports Usage Example

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Example of calling listReports and iterating through the returned report metadata objects.

```php
$response = $api->listReports('www.amazon.com');
foreach ($response->getReports() as $report) {
    echo $report->getFilename() . ' (' . $report->getLastModified() . ')' . PHP_EOL;
}
```

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

### getVariations usage example

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Example of configuring a GetVariationsRequestContent object and executing a getVariations request.

```php
use Amazon\/CreatorsAPI\/v1\/com\/amazon\/creators\/model\/GetVariationsRequestContent;
use Amazon\/CreatorsAPI\/v1\/com\/amazon\/creators\/model\/GetVariationsResource;

$request = new GetVariationsRequestContent();
$request->setPartnerTag('YOUR-TAG');
$request->setAsin('B0BFC7WQ6R');
$request->setVariationPage(1);
$request->setVariationCount(10);
$request->setResources([
    GetVariationsResource::VARIATION_SUMMARY_PRICE_HIGHEST_PRICE,
    GetVariationsResource::VARIATION_SUMMARY_PRICE_LOWEST_PRICE,
]);

$response = $api->getVariations('www.amazon.com', $request);
echo count($response->getVariationsResult()->getItems()); \/\/ up to 10 items on this page
```

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

### Configuring SearchItemsRequestContent

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/requests.md

Example of initializing a SearchItemsRequestContent object and setting various search parameters like keywords, index, and sorting.

```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\SearchItemsRequestContent;
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\SortBy;

$search = new SearchItemsRequestContent();
$search->setPartnerTag('YOUR-TAG');
$search->setKeywords('electric kettle');
$search->setSearchIndex('Kitchen');
$search->setItemCount(5)->setItemPage(1);
$search->setSortBy(SortBy::PRICELOW_TO_HIGH);
$search->setMaxPrice(50.0)->setMinReviewsRating(4);
```

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

### Initialize GetReportRequestContent

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/requests.md

Example of instantiating the GetReportRequestContent model and setting the required filename property.

```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\GetReportRequestContent;

$request = new GetReportRequestContent();
$request->setFilename('report_2024-01-01.csv.gz'); // name from listReports response
```

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

### ApiException

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/ApiException.md

Documentation for the ApiException class, including constructor, methods, and usage examples.

```APIDOC
## ApiException

### Description
Exception thrown by `DefaultApi` for every failed HTTP call: transport errors, non-2xx status codes, and JSON decoding failures. Extends `\Exception` and adds response body, headers, and a deserialized error model.

### Constructor

```php
public function __construct(string $message = "", int $code = 0, ?array $responseHeaders = [], mixed $responseBody = null)
```

#### Parameters
- **$message** (string) - Optional - Error message; also passed to `Exception::__construct()`
- **$code** (int) - Optional - HTTP status code; surfaces through `getCode()`
- **$responseHeaders** (?string[][]) - Optional - HTTP response headers
- **$responseBody** (mixed) - Optional - Raw/decoded response body

### Methods

#### getResponseHeaders()

```php
public function getResponseHeaders(): array|null
```

Returns the HTTP headers of the failed response (null when the transport failed before a response).

#### getResponseBody()

```php
public function getResponseBody(): mixed
```

Returns the HTTP body as decoded JSON (`\stdClass`) or raw string.

#### setResponseObject(mixed $obj): void

Attaches the deserialized error model (called internally by `DefaultApi`).

#### getResponseObject()

```php
public function getResponseObject(): mixed
```

Returns the deserialized error content model (e.g. `ValidationExceptionResponseContent`), or null if never deserialized.

### Inherited Methods

Inherited from `\Exception`: `getMessage()`, `getCode()`, `getFile()`, `getLine()`, `getPrevious()`, `getTrace()`, `__toString()`.

### When it is thrown

All thrown by `DefaultApi`:

| Condition | Message shape | HTTP code |
|-----------|---------------|-----------|
| Guzzle `RequestException` (4xx/5xx with response) | `"[{status}] {message}"` — body + headers attached from the response | `(int)$e->getCode()` |
| Guzzle `ConnectException` (network-level failure) | `"[{code}] {message}"` — headers/body null | `(int)$e->getCode()` |
| Non-2xx status not in the known set (not 200/400/401/403/404/429/500) | `"[%d] Error connecting to the API (%s)"` with request URI | actual status code |
| JSON decode failure of a 2xx response body | `"Error JSON decoding server response (%s)"` | `$response->getStatusCode()` |

For statuses 400/401/403/404/429/500 the caught exception has `setResponseObject()` applied before it is rethrown. For `Async` variants the rejected promise's `ApiException` carries the raw body string but no deserialized response object.

### Example

```php
use Amazon\CreatorsAPI\v1\ApiException;
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\ValidationExceptionResponseContent;

$api = new DefaultApi(null, $config);

try {
    $response = $api->getItems('www.amazon.com', $request);
} catch (ApiException $e) {
    echo 'HTTP ' . $e->getCode() . ': ' . $e->getMessage() . PHP_EOL;

    // Response body — as \stdClass or string
    var_dump($e->getResponseBody());

    // Deserialized error model for the recognized error statuses
    $obj = $e->getResponseObject();
    if ($obj instanceof ValidationExceptionResponseContent) {
        echo $obj->getMessage() . PHP_EOL;
        echo $obj->getReason() . PHP_EOL;
        foreach ($obj->getFieldList() as $field) {
            echo $field->getName() . ': ' . $field->getMessage() . PHP_EOL;
        }
    }

    // Inspect response headers, e.g. rate-limit headers on 429
    foreach ($e->getResponseHeaders() ?? [] as $name => $values) {
        echo $name . ': ' . implode(', ', $values) . PHP_EOL;
    }
}
```
```

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

### Multipart payload preparation

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/FormDataProcessor.md

Example demonstrating how to prepare a multipart payload including nested arrays and file objects, and how to use the static flatten method.

```php
use Amazon\/CreatorsAPI\/v1\/FormDataProcessor;
use SplFileObject;

$processor = new FormDataProcessor();

$fields = $processor->prepare([
    'title'  => 'Report 2024',
    'active' => true,                        // stringified to "true"
    'meta'   => ['source' => 'api', 'page' => 2],
    'upload' => new SplFileObject('/tmp/data.csv'),
]);

var_dump($processor->has_file);              // true
// $fields: ['title' => 'Report 2024', 'active' => 'true', 'meta[source]' => 'api', 'meta[page]' => '2', 'upload' => <resource>]

// Static flattening without files
$flat = FormDataProcessor::flatten(['a' => ['b' => [1, 2]]]);
// ['a[b][0]' => '1', 'a[b][1]' => '2']
```

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

### Example usage of OAuth2Config with LWA version 3.1

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/OAuth2Config.md

Creates an OAuth2Config with version '3.1' and demonstrates isLwa(), getScope(), getTokenEndpoint(), and getGrantType(). Outputs: true, creatorsapi::default, https://api.amazon.com/auth/o2/token, client_credentials.

```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\auth\OAuth2Config;

$config = new OAuth2Config('client-id', 'client-secret', '3.1', null);

echo $config->isLwa();          // true
echo $config->getScope();       // creatorsapi::default
echo $config->getTokenEndpoint(); // https://api.amazon.com/auth/o2/token
echo $config->getGrantType();   // client_credentials
```

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

### Error handling example for unsupported version

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/OAuth2Config.md

Creates an OAuth2Config with version '1.0' and catches the \InvalidArgumentException thrown by getTokenEndpoint(). The error message is 'Unsupported version: 1.0. Supported versions are: 2.1, 2.2, 2.3, 3.1, 3.2, 3.3'.

```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\auth\OAuth2Config;

$config = new OAuth2Config('id', 'secret', '1.0', null);

try {
    $config->getTokenEndpoint();
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage();
    // "Unsupported version: 1.0. Supported versions are: 2.1, 2.2, 2.3, 3.1, 3.2, 3.3"
}
```

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

### Initialize Configuration

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/Configuration.md

Demonstrates how to instantiate and configure the SDK with credentials, host settings, and debug options. Optionally sets the global default configuration.

```php
use Amazon\CreatorsAPI\v1\Configuration;

$config = new Configuration();
$config
    ->setCredentialId('client-id')
    ->setCredentialSecret('client-secret')
    ->setVersion('3.1')
    ->setHost('https://creatorsapi.amazon')
    ->setDebug(true)
    ->setDebugFile('/tmp/creatorsapi.log')
    ->setUserAgent('my-app/1.0');

// Optional: replace the global default so `new DefaultApi()` picks these up
Configuration::setDefaultConfiguration($config);

$report = Configuration::toDebugReport(); // includes PHP version, SDK version, temp folder
```

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

### Configuration Class Static and Instance Methods

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/Configuration.md

A list of static and instance methods available in the Configuration class for managing SDK settings and host resolution.

```php
public static function getDefaultConfiguration(): Configuration
public static function setDefaultConfiguration(Configuration $config): void
public static function toDebugReport(): string
public static function getHostString(array $hostSettings, int $hostIndex, ?array $variables = null): string
public function getHostSettings(): array
public function getHostFromSettings(int $index, ?array $variables = null): string
```

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

### Constructor

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Initializes a new DefaultApi instance with optional HTTP client, configuration, header selector, and host index.

```APIDOC
## Constructor

### Description
Creates an instance of the DefaultApi class.

### Method
__construct

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$client` | `?GuzzleHttp\ClientInterface` | no | `null` -> creates `new GuzzleHttp\Client()` | HTTP client used to send requests and token requests |
| `$config` | `?\Amazon\CreatorsAPI\v1\Configuration` | no | `null` -> `Configuration::getDefaultConfiguration()` | Credential and transport options |
| `$selector` | `?\Amazon\CreatorsAPI\v1\HeaderSelector` | no | `null` -> `new HeaderSelector()` | Accept/Content-Type negotiation |
| `$hostIndex` | `int` | no | `0` | Index into host settings (see `Configuration::getHostSettings()`) |

### Returns
- The `DefaultApi` instance.

### Throws
- Nothing from the constructor itself. A `\InvalidArgumentException` is deferred to the first API call if OAuth2 credentials are missing.

### Example
```php
use Amazon\CreatorsAPI\v1\Configuration;
use Amazon\CreatorsAPI\v1\com\amazon\creators\api\DefaultApi;

$config = new Configuration();
$config->setCredentialId('client-id');
$config->setCredentialSecret('client-secret');
$config->setVersion('3.1');

$api = new DefaultApi(null, $config); // Guzzle client and HeaderSelector are auto-created
```

```

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

### isLwa() method signature

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/OAuth2Config.md

Returns true when the version starts with '3.' (LWA), false otherwise.

```php
public function isLwa(): bool
```

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

### Configuration Constructor

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/Configuration.md

Initializes a new Configuration instance with default values, setting the temporary folder path to the system's default temporary directory.

```php
public function __construct()
```

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

### Host Index Accessors

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Methods to get and set the host index for OpenAPI multi-host specifications.

```php
public function setHostIndex(int $hostIndex): void
public function getHostIndex(): int
```

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

### Validation & error handling (shared)

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/requests.md

Shared validation and error handling behavior for model setters in the SDK, including examples with GetItemsRequestContent.

```APIDOC
## Validation & Error Handling (Shared)

### Description
All model setters in the SDK throw `\InvalidArgumentException` when given out-of-range values or null for non-nullable properties. Validation only covers currently-set properties.

### Behavior
- Out-of-range values: throws `\InvalidArgumentException` with a message like `"invalid value for $itemIds when calling GetItemsRequestContent., number of items must be less than or equal to 10."`
- Null for non-nullable properties: throws `"non-nullable {property} cannot be null"`
- Optional properties: set by simply not calling the setter

### Example
```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\GetItemsRequestContent;

$request = new GetItemsRequestContent();
$request->setPartnerTag('YOUR-TAG');

try {
    $request->setItemIds([]); // violates 1–10 element rule
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage();
    // invalid value for $itemIds when calling GetItemsRequestContent., number of items must be greater than or equal to 1.
}

var_dump($request->valid());                  // true — validation covers only currently-set properties
var_dump($request->listInvalidProperties());  // ["'partnerTag' can't be null", "'itemIds' can't be null"] when unset
```
```

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

### Handle HTTP info and asynchronous requests

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/responses.md

Demonstrates how to retrieve HTTP status and headers using searchItemsWithHttpInfo and how to process asynchronous responses using listFeedsAsync with a promise.

```php
[$body, $status, $headers] = $api->searchItemsWithHttpInfo('www.amazon.com', $search);
echo $status; // int 200
echo $body->getSearchResult()->getTotalResultCount();

// Async: resolve with just the model
$promise = $api->listFeedsAsync('www.amazon.com');
$promise->then(function (ListFeedsResponseContent $response) {
    foreach ($response->getFeeds() as $feed) {
        echo $feed->getFeedName() . PHP_EOL;
    }
})->wait();
```

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

### setDefaultConfiguration(Configuration $config): void

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/Configuration.md

Replaces the singleton Configuration instance.

```APIDOC
## setDefaultConfiguration(Configuration $config): void

### Description
Replaces the singleton Configuration instance.

### Method
Static method

### Signature
php
public static function setDefaultConfiguration(Configuration $config): void


### Parameters
- **$config** (Configuration) - Required - The new Configuration instance to set as the default.
```

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

### Condition Enum Class Definition

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/ModelInterface.md

Example of an enum class structure showing constant definitions and the getAllowableEnumValues method used for validation.

```php
class Condition
{
    /**
     * Possible values of this enum
     */
    public const ANY = 'Any';

    public const _NEW = 'New';

    /**
     * Gets allowable values of the enum
     * @return string[]
     */
    public static function getAllowableEnumValues(): array
    {
        return [
            self::ANY,
            self::_NEW
        ];
    }
}
```

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

### getHostSettings(): array

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/Configuration.md

Returns the host settings array, which contains a single host with no variables.

```APIDOC
## getHostSettings(): array

### Description
Returns the host settings array, which contains a single host with no variables.

### Method
Instance method

### Signature
php
public function getHostSettings(): array


### Returns
- **array** - An array containing a single host setting: `[['url' => '', 'description' => 'No description provided']]`.
```

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

### Configuration class methods

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/Configuration.md

A list of available setter and getter methods for the Configuration class. Most setters are fluent and return the instance, while specific methods handle API keys, credentials, and environment settings.

```php
public function setApiKey(string $apiKeyIdentifier, string $key): self
public function getApiKey(string $apiKeyIdentifier): string|null
public function setApiKeyPrefix(string $apiKeyIdentifier, string $prefix): self
public function getApiKeyPrefix(string $apiKeyIdentifier): string|null
public function getApiKeyWithPrefix(string $apiKeyIdentifier): string|null
public function setAccessToken(string $accessToken): self
public function getAccessToken(): string
public function setBooleanFormatForQueryString(string $booleanFormat): self
public function getBooleanFormatForQueryString(): string
public function setUsername(string $username): self
public function getUsername(): string
public function setPassword(string $password): self
public function getPassword(): string
public function setCredentialId(string $credentialId): self
public function getCredentialId(): string
public function setCredentialSecret(string $credentialSecret): self
public function getCredentialSecret(): string
public function setVersion(string $version): self
public function getVersion(): string
public function setAuthEndpoint(string $authEndpoint): self
public function getAuthEndpoint(): string
public function setHost(string $host): self
public function getHost(): string
public function setUserAgent(string $userAgent): self
public function getUserAgent(): string
public function setDebug(bool $debug): self
public function getDebug(): bool
public function setDebugFile(string $debugFile): self
public function getDebugFile(): string
public function setTempFolderPath(string $tempFolderPath): self
public function getTempFolderPath(): string
```

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

### Public property: has_file

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/FormDataProcessor.md

Set to true during prepare() whenever a file resource, SplFileObject, or stream enters the payload; reset to false at the start of each prepare() call.

```APIDOC
## Public property: has_file

### Description
Set to `true` during `prepare()` whenever a file resource, `SplFileObject`, or stream enters the payload; reset to `false` at the start of each `prepare()` call.

### Type
bool

### Default
false

### Example
```php
$processor = new FormDataProcessor();
$processor->prepare(['upload' => new SplFileObject('/tmp/data.csv')]);
var_dump($processor->has_file); // true
```
```

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

### Standalone OAuth2TokenManager usage

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/OAuth2TokenManager.md

Demonstrates initializing the manager with OAuth2Config, fetching tokens, utilizing the internal cache, and manually clearing the token.

```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\auth\OAuth2Config;
use Amazon\CreatorsAPI\v1\com\amazon\creators\auth\OAuth2TokenManager;

$manager = new OAuth2TokenManager(
    new OAuth2Config('client-id', 'client-secret', '3.1', null)
);

$token   = $manager->getToken();          // fetches once...
$token2  = $manager->getToken();          // ...served from cache
var_dump($manager->getTokenInfo());       // ['hasToken' => true, 'isValid' => true, ...]

$manager->clearToken();                   // force re-fetch next time
```

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

### Handling ApiException in a try-catch block

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/ApiException.md

Example of catching ApiException, accessing the response body, deserialized error model, and response headers. Includes checking for ValidationExceptionResponseContent and iterating over field list.

```php
use Amazon\CreatorsAPI\v1\ApiException;
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\ValidationExceptionResponseContent;

$api = new DefaultApi(null, $config);

try {
    $response = $api->getItems('www.amazon.com', $request);
} catch (ApiException $e) {
    echo 'HTTP ' . $e->getCode() . ': ' . $e->getMessage() . PHP_EOL;

    // Response body — as \stdClass or string
    var_dump($e->getResponseBody());

    // Deserialized error model for the recognized error statuses
    $obj = $e->getResponseObject();
    if ($obj instanceof ValidationExceptionResponseContent) {
        echo $obj->getMessage() . PHP_EOL;
        echo $obj->getReason() . PHP_EOL;
        foreach ($obj->getFieldList() as $field) {
            echo $field->getName() . ': ' . $field->getMessage() . PHP_EOL;
        }
    }

    // Inspect response headers, e.g. rate-limit headers on 429
    foreach ($e->getResponseHeaders() ?? [] as $name => $values) {
        echo $name . ': ' . implode(', ', $values) . PHP_EOL;
    }
}
```

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

### flatten(array $source, string $start = ''): array (static)

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/FormDataProcessor.md

Recursively flattens a multi-level array into a single level using bracket notation. Scalar leaves are stringified with ObjectSerializer::toString().

```APIDOC
## flatten(array $source, string $start = ''): array (static)

### Description
Recursively flattens a multi-level array into a single level using bracket notation: `['a' => ['b' => 1]]` → `['a[b]' => '1']`. Lists use `a[0]`-style keys; the algorithm is borrowed from the FlatPHP project. Scalar leaves are stringified with `ObjectSerializer::toString()`.

### Method
flatten

### Parameters
- **$source** (array) - Required - The multi-level array to flatten
- **$start** (string) - Optional - Prefix for keys (default '')

### Returns
- **array** - The flattened array

### Example
```php
$flat = FormDataProcessor::flatten(['a' => ['b' => [1, 2]]]);
// ['a[b][0]' => '1', 'a[b][1]' => '2']
```
```

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

### Reading offers from item results with DefaultApi

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/offers.md

Use this snippet to fetch items with OFFERS_V2_LISTINGS_* resources and iterate over each item's offers. It prints the ASIN, display amount, buy box winner status, savings percentage, merchant name, and condition. Assumes $api and $request are already set up.

```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\api\DefaultApi;

$response = $api->getItems('www.amazon.com', $request); // request includes OFFERS_V2_LISTINGS_* resources

foreach ($response->getItemsResult()->getItems() as $item) {
    $listing = $item->getOffersV2()?->getListings()[0] ?? null;
    if ($listing === null) {
        echo $item->getAsin() . ': no offers' . PHP_EOL;
        continue;
    }

    $price = $listing->getPrice()?->getMoney();
    echo $item->getAsin() . ': ' . ($price?->getDisplayAmount() ?? 'n/a') . PHP_EOL;

    if ($listing->getIsBuyBoxWinner()) {
        echo '  buy box winner' . PHP_EOL;
    }

    $savings = $listing->getPrice()?->getSavings();
    if ($savings?->getPercentage()) {
        echo '  saved ' . $savings->getPercentage() . '%' . PHP_EOL;
    }

    echo '  by: ' . ($listing->getMerchantInfo()?->getName() ?? 'unknown') . PHP_EOL;
    echo '  condition: ' . ($listing->getCondition()?->getValue() ?? 'unknown') . PHP_EOL;
}
```

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

### Error handling for unopenable files

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/FormDataProcessor.md

Demonstrates catching a RuntimeException when attempting to process a file that cannot be opened.

```php
use Amazon\/CreatorsAPI\/v1\/FormDataProcessor;
use SplFileObject;

try {
    $processor = new FormDataProcessor();
    $processor->prepare(['file' => new SplFileObject('/nonexistent/file.csv')]);
    // SplFileObject::__construct already throws \RuntimeException when the file cannot be opened
} catch (\RuntimeException $e) {
    echo $e->getMessage(); // "SplFileObject::__construct(/nonexistent/file.csv): Failed to open stream..."
}
```

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

### setHostIndex(int $hostIndex): void / getHostIndex(): int

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Sets and gets the host index for the API instance. The host index is retained for OpenAPI multi-host specs, but this SDK uses a single host from Configuration.

```APIDOC
## setHostIndex(int $hostIndex): void / getHostIndex(): int

### Description
Get/set the host index. The host actually used for requests is `Configuration::getHost()`; `hostIndex` is retained for OpenAPI multi-host specs (this SDK's `getHostSettings()` returns a single empty-URL entry, and `getHostFromSettings()` is not invoked by `DefaultApi`).

### Methods
```php
public function setHostIndex(int $hostIndex): void
public function getHostIndex(): int
```

### Parameters
- `$hostIndex` (int) - Required - The host index to set.

### Return Type
`void` for `setHostIndex()`, `int` for `getHostIndex()`. 

### Source
`src/com/amazon/creators/api/DefaultApi.php:161,171`
```

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

### toDebugReport(): string

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/Configuration.md

Returns a multi-line report with OS/PHP version, OpenAPI document version, SDK package version, and the default configuration's temp folder.

```APIDOC
## toDebugReport(): string

### Description
Returns a multi-line report with OS/PHP version, "OpenAPI document: 2024-08-16", "SDK Package Version: 1.0.0", and the default configuration's temp folder.

### Method
Static method

### Signature
php
public static function toDebugReport(): string


### Returns
- **string** - A multi-line debug report string.
```

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

### Condition enum class definition

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/enums.md

Example of an enum class in the SDK. It defines public constants and a static method returning the allowable values. The ObjectSerializer uses this to validate enum membership, throwing \InvalidArgumentException for invalid values.

```php
class Condition
{
    public const ANY = 'Any';
    public const _NEW = 'New';

    public static function getAllowableEnumValues(): array
    {
        return [self::ANY, self::_NEW];
    }
}
```

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

### Extend DefaultApi and CachingTokenManager for persistent token caching

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/README.md

Use this PHP example to implement file-based, Redis, or other persistent caching for OAuth2 tokens. The CachedApi class overrides buildAuthenticatedHeaders() to use a CachingTokenManager that checks a PSR-16 cache before fetching a new token. The CachingTokenManager stores tokens with a 55-minute TTL (3300 seconds) to stay within Amazon's 60-minute token expiry. Both classes are required together for the caching workflow.

```PHP
class CachedApi extends DefaultApi
{
    public function __construct(
        private readonly CachingTokenManager $cachingTokenManager, // Inject a caching token manager that extends OAuth2TokenManager.
        ?ClientInterface                     $client = null,
        ?Configuration                       $config = null,
        ?HeaderSelector                      $selector = null,
        int                                  $hostIndex = 0
    ) {
        parent::__construct($client, $config, $selector, $hostIndex);
    }

    protected function buildAuthenticatedHeaders(string $resourcePath): array
    {
        $token   = $this->cachingTokenManager->getToken(); // This will use the cached token if available, or fetch a new one if not.
        $version = $this->config->getVersion();

        if (str_starts_with($version, '3.')) {
            return ['Authorization' => "Bearer {$token}"];
        }

        return ['Authorization' => "Bearer {$token}, Version {$version}"];
    }

    public function clearToken(): void
    {
        $this->cachingTokenManager->clearToken();
    }
}
```

```PHP
class CachingTokenManager extends OAuth2TokenManager
{
    // $cache is any PSR-16 CacheInterface implementation (files, Redis, Memcached, etc.)

    private const string CACHE_KEY = 'amazon_unique_token_cache_key'; // Use a unique cache key to avoid collisions with other cached data.
    private const int CACHE_TTL_SECONDS = 3300; // 55 minutes — 5 minutes less than Amazon's 60 minute token expiry

    public function __construct(
        private readonly \Psr\SimpleCache\CacheInterface $cache,
        OAuth2Config $config
    ) {
        parent::__construct($config);
    }

    public function getToken(): string
    {
        $cached = $this->cache->get(self::CACHE_KEY);

        if ($cached !== null) {
            return $cached;
        }

        $token = parent::getToken();
        $this->cache->set(self::CACHE_KEY, $token, self::CACHE_TTL_SECONDS);

        return $token;
    }

    public function clearToken(): void
    {
        $this->cache->delete(self::CACHE_KEY);
    }
}
```

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

### createHttpClientOption() Method

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Builds Guzzle request options, including debug settings if enabled in the configuration.

```php
protected function createHttpClientOption(): array
```

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

### Method prepare

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/FormDataProcessor.md

The prepare method resets the processor state and maps input values into a form-data-safe array.

```php
public function prepare(array $values): array
```

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

### getHostFromSettings(int $index, ?array $variables = null): string

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/Configuration.md

Convenience wrapper that calls getHostString with the instance's host settings.

```APIDOC
## getHostFromSettings(int $index, ?array $variables = null): string

### Description
Convenience wrapper that calls `getHostString($this->getHostSettings(), $index, $variables)`.

### Method
Instance method

### Signature
php
public function getHostFromSettings(int $index, ?array $variables = null): string


### Parameters
- **$index** (int) - Required - The index of the host to resolve.
- **$variables** (?array) - Optional - Variables to substitute in the host URL template.

### Returns
- **string** - The resolved host URL.
```

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

### getConfig() Method

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Returns the Configuration bound to the DefaultApi instance.

```php
public function getConfig(): Configuration
```

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

### getConfig()

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Returns the Configuration instance bound to this DefaultApi instance, either the one passed to the constructor or the default singleton.

```APIDOC
## getConfig()

### Description
Returns the `Configuration` bound to this instance (the one passed to the constructor, or the default singleton).

### Method
`getConfig()`

### Signature
```php
public function getConfig(): Configuration
```

### Return Type
`Configuration`

### Source
`src/com/amazon/creators/api/DefaultApi.php:179`
```

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

### Retrieve a signed download URL using getFeed

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/DefaultApi.md

Fetches a single product data feed by name to obtain a signed download URL.

```php
use Amazon\CreatorsAPI\v1\com\amazon\creators\model\GetFeedRequestContent;

$request = new GetFeedRequestContent();
$request->setFeedName('product_data_feed_2024-01-01.csv.gz');

$response = $api->getFeed('www.amazon.com', $request);
echo $response->getUrl(); // signed download URL
```

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

### Using ArrayAccess and JSON Serialization

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/ModelInterface.md

Shows how to access model properties using array syntax and serialize the model to JSON or header values.

```php
$model = new GetItemsRequestContent(['partnerTag' => 'TAG', 'itemIds' => ['X']]);
echo $model['partnerTag'];                      // TAG  (ArrayAccess get)
$model['partnerTag'] = 'OTHER';                 // ArrayAccess set
echo json_encode($model);                       // {"partnerTag":"OTHER","itemIds":["X"]}
echo $model->toHeaderValue();                   // {"partnerTag":"OTHER","itemIds":["X"]}
```

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

### DefaultApi constructor instantiation

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/configuration.md

The DefaultApi constructor accepts optional parameters for the HTTP client, configuration, header selector, and host index.

```php
new DefaultApi(?ClientInterface $client = null, ?Configuration $config = null, ?HeaderSelector $selector = null, int $hostIndex = 0)
```

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

### Constructor: __construct(OAuth2Config $config)

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/OAuth2TokenManager.md

Creates an OAuth2TokenManager instance with the given OAuth2Config for credentials and endpoint.

```APIDOC
## Constructor: __construct(OAuth2Config $config)

### Description
Creates an OAuth2TokenManager instance using the provided OAuth2Config for credential/endpoint configuration.

### Method
__construct

### Parameters
- **$config** (OAuth2Config) - Required - Credential/endpoint configuration.

### Notes
- Creates an internal GuzzleHttp\Client() for token requests.
- Starts with no cached token.

### Source
`src/com/amazon/creators/auth/OAuth2TokenManager.php:59`
```

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

### OffersV2

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/models/offers.md

Represents the offersV2 subtree containing a list of offer listings for an item. Access via Item::getOffersV2() when offersV2.listings.* resources are requested.

```APIDOC
## OffersV2

### Description
Represents the offersV2 subtree containing a list of offer listings for an item. Access via Item::getOffersV2() when offersV2.listings.* resources are requested.

### Class
`Amazon\CreatorsAPI\v1\com\amazon\creators\model\OffersV2`

### Constructor
`__construct(?array $data = null)`

### Properties
- **listings** (OfferListingV2[]) - Getter: `getListings(): array|null`

### Methods
- `getListings(): array|null` - Returns the list of offer listings.
```

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

### Handle Configuration Errors

Source: https://github.com/thewirecutter/paapi5-php-sdk/blob/main/_autodocs/api-reference/Configuration.md

Shows how to catch InvalidArgumentException when providing invalid values to setUserAgent or accessing out-of-range host settings.

```php
try {
    $config->setUserAgent(null); // will throw \InvalidArgumentException before assignment
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "User-agent must be a string."
}

try {
    $url = Configuration::getHostString($config->getHostSettings(), 5); // index out of range
} catch (\InvalidArgumentException $e) {
    echo $e->getMessage(); // "Invalid index 5 when selecting the host. Must be less than 1"
}
```
Tokens:
Raw