Selling Partner API for PHP

https://github.com/jlevers/selling-partner-api
Admin
A PHP library for connecting to Amazon's Selling Partner API, supporting all operations and handling...
Tokens:374,509
Snippets:1,890
Trust Score:9.6
License:BSD-3-Clause
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### SellingPartnerApi::seller() usage example

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/selling-partner-api.md

Example of creating a SellerConnector using the seller() factory method with named arguments. The example then calls ordersV0() on the connector.

```php
use SellingPartnerApi\SellingPartnerApi;
use SellingPartnerApi\Enums\Endpoint;

$seller = SellingPartnerApi::seller(
    clientId: 'amzn1.application-oa2-client.asdf...',
    clientSecret: 'amzn1.oa2-cs.v1.1234...',
    refreshToken: 'Atzr|IwEBIA...',
    endpoint: Endpoint::NA,
);

$ordersApi = $seller->ordersV0();
```

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

### InMemoryTokenCache usage example

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/authentication.md

Shows how to instantiate InMemoryTokenCache and use its methods. The get method returns an AccessTokenAuthenticator or false when the key is missing or expired.

```php
use SellingPartnerApi\Authentication\InMemoryTokenCache;
use SellingPartnerApi\Contracts\TokenCache;

$cache = new InMemoryTokenCache;
$token = $cache->get('my-key');     // AccessTokenAuthenticator|false
$cache->set('my-key', $authenticator);
$cache->forget('my-key');
$cache->clear();
```

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

### RestrictedDataToken instantiation examples

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/middleware.md

Three examples of instantiating the RestrictedDataToken middleware in generated request constructors, showing different paths, methods, and known data elements.

```php
// src/Seller/OrdersV0/Requests/GetOrders.php:124
$rdtMiddleware = new RestrictedDataToken('/orders/v0/orders', 'GET', ['buyerInfo', 'shippingAddress']);
```

```php
// src/Seller/OrdersV0/Requests/GetOrderAddress.php:33
$rdtMiddleware = new RestrictedDataToken('/orders/v0/orders/{orderId}/address', 'GET', []);
```

```php
// src/Vendor/DirectFulfillmentOrdersV20211228/Requests/GetOrders.php:48
$rdtMiddleware = new RestrictedDataToken('/vendor/directFulfillment/orders/2021-12-28/purchaseOrders', 'GET', []);
```

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

### getAccessToken() usage example

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/selling-partner-api.md

Example of retrieving an access token and handling a token request failure with a try-catch block.

```php
try {
    $authenticator = $connector->getAccessToken();
    $token = $authenticator->getAccessToken();
} catch (\Saloon\Exceptions\Request\RequestException $e) {
    // handle token request failure
}
```

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

### Using Endpoint static helpers

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/enums.md

Demonstrates how to use the static helper methods on the Endpoint enum to resolve endpoints by country code, marketplace ID, or region, and to get the host portion. The example shows that byCountryCode('US') returns Endpoint::NA, byMarketplaceId('A1F83G8C2ARO7P') returns Endpoint::EU, and byRegion('FE', sandbox: true) returns Endpoint::FE_SANDBOX.

```php
use SellingPartnerApi\Enums\Endpoint;

$endpoint = Endpoint::byCountryCode('US');            // Endpoint::NA
$endpoint = Endpoint::byMarketplaceId('A1F83G8C2ARO7P'); // Endpoint::EU (GB marketplace)
$endpoint = Endpoint::byRegion('FE', sandbox: true);  // Endpoint::FE_SANDBOX
echo Endpoint::host(Endpoint::NA);                    // sellingpartnerapi-na.amazon.com
```

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

### getRefreshToken() usage example

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/oauth.md

Example of exchanging the spapi_oauth_code for a refresh token. Includes state verification with hash_equals and error handling for OAuthException.

```php
$code = $request->query->get('spapi_oauth_code');
if (! hash_equals($expectedState, $request->query->get('state'))) {
    // abort — state mismatch
}

try {
    $refreshToken = $oauth->getRefreshToken($code);
    // persist $refreshToken and pass it to SellingPartnerApi::seller(..., refreshToken: $refreshToken)
} catch (\SellingPartnerApi\Exceptions\OAuthException $e) {
    // log and show an error to the seller
    error_log($e->getMessage());
}
```

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

### Instantiate OAuth with named arguments

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/oauth.md

Example of creating an OAuth instance with named arguments. Throws OAuthException if redirectUri is not HTTPS.

```php
use SellingPartnerApi\OAuth;

$oauth = new OAuth(
    clientId: 'amzn1.application-oa2-client.asdf...',
    clientSecret: 'amzn1.oa2-cs.v1.1234...',
    redirectUri: 'https://example.com/redirect',
); // throws OAuthException if redirectUri is not https
```

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

### confirmShipment() usage example with request DTO

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/orders-v0.md

Example of building a ConfirmShipmentRequest with a PackageDetail and calling confirmShipment(). Uses Saloon's AlwaysThrowOnErrors, so the explicit throw() is redundant but safe. HTTP-level failures propagate as Saloon RequestException/Client exceptions.

```php
use SellingPartnerApi\Seller\OrdersV0\Dto;

$request = new Dto\ConfirmShipmentRequest(
    packageDetail: new Dto\PackageDetail(
        packageReferenceId: 'PKG123',
        carrierCode: 'USPS',
        trackingNumber: 'ASDF1234567890',
        shipDate: new DateTime('2024-01-01 12:00:00'),
        orderItems: [
            new Dto\ConfirmShipmentOrderItem(orderItemId: '1234567890', quantity: 1),
        ],
    ),
    marketplaceId: 'ATVPDKIKX0DER',
);

try {
    $response = $ordersApi->confirmShipment('123-4567890-1234567', $request);
    $response->throw(); // Saloon's AlwaysThrowOnErrors makes this redundant but it is safe
} catch (\Exception $e) {
    // HTTP-level failures propagate as Saloon RequestException/Client exceptions
}
```

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

### getAuthorizationUri() usage example

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/oauth.md

Example of calling getAuthorizationUri() with named arguments. Uses Marketplace::US and draftApp: false for a published app. The resulting URL is used in a Location header redirect.

```php
use SellingPartnerApi\Enums\Marketplace;

$authUrl = $oauth->getAuthorizationUri(
    appId: 'amzn1.sp.solution.abcdef...',
    state: base64_encode(random_bytes(32)),
    marketplace: Marketplace::US,      // or :EU/:JP/etc.
    draftApp: false,                   // app is published on the Marketplace Appstore
);

header("Location: $authUrl");
```

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

### Create vendor connector and call ordersV1

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/vendor-connector.md

Shows how to instantiate a vendor connector using SellingPartnerApi::vendor() with client credentials and endpoint, then call an accessor method to get an API object and make a request.

```php
use SellingPartnerApi\SellingPartnerApi;
use SellingPartnerApi\Enums\Endpoint;

$vendor = SellingPartnerApi::vendor(
    clientId: '...', clientSecret: '...', refreshToken: '...',
    endpoint: Endpoint::NA,
);
$ordersApi = $vendor->ordersV1();   // SellingPartnerApi\Vendor\OrdersV1\Api
$response = $ordersApi->getPurchaseOrders(limit: 10);
$dto = $response->dto();
```

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

### getOrders() usage example with error handling

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/orders-v0.md

Example of calling getOrders() with named arguments, iterating over the returned orders, and handling API errors via the DTO. The response DTO contains payload (OrdersList) and errors (ErrorList) for statuses 200/400/403/404/429/500/503; otherwise a plain Exception is thrown.

```php
$ordersApi = $connector->ordersV0();

$response = $ordersApi->getOrders(
    createdAfter: new DateTime('2024-01-01')->format(DATE_ATOM),
    marketplaceIds: ['ATVPDKIKX0DER'],
    maxResultsPerPage: 20,
);
$dto = $response->dto();
foreach ($dto->payload->orders as $order) {
    echo $order->amazonOrderId . ' ' . $order->orderStatus . PHP_EOL;
}

// error handling: API errors come back as DTOs too
if ($dto->errors !== null) {
    foreach ($dto->errors->errors as $error) {
        fprintf(STDERR, "[%s] %s\n", $error->code, $error->message);
    }
}
```

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

### Using SellerConnector to fetch orders

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/seller-connector.md

Shows how to instantiate the SellerConnector via SellingPartnerApi::seller() and call the ordersV0() accessor to retrieve orders. Requires client ID, client secret, refresh token, and endpoint. The example fetches orders created after 2024-01-01 for a marketplace and accesses the first order's purchase date.

```php
use SellingPartnerApi\SellingPartnerApi;
use SellingPartnerApi\Enums\Endpoint;

$seller = SellingPartnerApi::seller(
    clientId: '...', clientSecret: '...', refreshToken: '...',
    endpoint: Endpoint::NA,
);
$orders = $seller->ordersV0();   // SellingPartnerApi\Seller\OrdersV0\Api
$r = $orders->getOrders(createdAfter: new DateTime('2024-01-01'), marketplaceIds: ['ATVPDKIKX0DER']);
$dto = $r->dto();
$firstOrderPurchaseDate = $dto->payload->orders[0]->purchaseDate;
```

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

### restrictedAuth() usage example

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/selling-partner-api.md

Example of calling restrictedAuth() directly. Normally you never call this directly; RestrictedDataToken middleware does.

```php
// Normally you never call this directly; RestrictedDataToken middleware does.
$auth = $connector->restrictedAuth('/orders/v0/orders', 'GET', ['buyerInfo', 'shippingAddress']);
```

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

### Access Product Pricing API v0

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Product Pricing API v0 client from the seller connector.

```php
$productPricingApi = $sellerConnector->productPricingV0();
```

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

### apis.json schema example

Source: https://github.com/jlevers/selling-partner-api/blob/main/CONTRIBUTING.md

Shows the general schema of apis.json. Top-level keys are 'seller' and 'vendor'. Each API entry has a name and a list of versions, each with a version code and URL, optionally a selector for HTML schemas.

```jsonc
{
    "seller": {
        "api-name": {
            "name": "API Name",
            "versions": [
                {
                    "version": "version-code",
                    "url": "https://raw.githubusercontent.com/path/to/schema.json"
                },
                {
                    "version": "version-code",
                    "url": "https://example.com/schema.html",
                    "selector": "code[data-lang='json']"
                }
            ]
        }
    },
    "vendor": {
        // ...
    }
}
```

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

### Access Product Pricing API v2022-05-01

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Product Pricing API v2022-05-01 client from the seller connector.

```php
$productPricingApi = $sellerConnector->productPricingV20220501();
```

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

### Usage example with SellingPartnerApi connector

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/base-classes.md

Shows how to use the SellingPartnerApi connector to make a request and access the DTO. The response is a Saloon\Response; $response->dto() runs Requests\GetFeed::createDtoFromResponse(), which deserializes into a generated Response subclass (or EmptyResponse for empty bodies). DTOs round-trip back to arrays via toArray().

```php
use SellingPartnerApi\SellingPartnerApi;
use SellingPartnerApi\EmptyResponse;

$connector = SellingPartnerApi::seller(/* ... */);
$response = $connector->feedsV20210630()->getFeed('feed123');

// $response is a Saloon\Response; $response->dto() runs
// Requests\GetFeed::createDtoFromResponse(), which deserializes into
// a generated Response subclass (or EmptyResponse for empty bodies).
$dto = $response->dto();

// DTOs round-trip back to arrays for request bodies/query strings
$array = $dto->toArray();
```

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

### Marketplace usage example

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/enums.md

Shows how to use the Marketplace enum: fromCountryCode performs a case-insensitive lookup (e.g., 'uk' returns Marketplace::GB), and accessing the value property returns the MarketplaceId.

```php
use SellingPartnerApi\Enums\Marketplace;

$marketplace = Marketplace::fromCountryCode('uk');   // Marketplace::GB
echo Marketplace::US->value;                          // ATVPDKIKX0DER
```

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

### Access Finances API v0

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Finances API v0 client from the seller connector.

```php
$financesApi = $sellerConnector->financesV0();
```

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

### Generated request class example (CreateFeed)

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/base-classes.md

Example of a generated request class that extends Request and implements HasBody. It uses the HasJsonBody trait, sets the HTTP method to POST, defines a constructor with a public DTO parameter, resolves the endpoint, and creates a response DTO based on the status code. The defaultBody method returns the DTO's array representation.

```php
class CreateFeed extends Request implements HasBody
{
    use HasJsonBody;

    protected Method $method = Method::POST;

    public function __construct(
        public CreateFeedSpecification $createFeedSpecification,
    ) {}

    public function resolveEndpoint(): string  { return '/feeds/2021-06-30/feeds'; }

    public function createDtoFromResponse(Response $response): CreateFeedResponse|ErrorList
    {
        $status = $response->status();
        $responseCls = match ($status) {
            202 => CreateFeedResponse::class,
            400, 401, 403, 404, 415, 429, 500, 503 => ErrorList::class,
            default => throw new Exception("Unhandled response status: {$status}")
        };
        return $responseCls::deserialize($response->json());
    }

    public function defaultBody(): array
    {
        return $this->createFeedSpecification->toArray();
    }
}
```

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

### Catch OAuthException

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/errors.md

Example of catching OAuthException when constructing an OAuth instance and exchanging an authorization code for a refresh token.

```APIDOC
## OAuthException

### Description
Thrown when an OAuth-related client-side failure occurs, such as an invalid redirect URI or a missing refresh token in the authorization code exchange response.

### Trigger Conditions
1. OAuth constructed with a redirectUri that does not start with `https://` - Message: `Redirect URI must use SSL (https://)`
2. Authorization-code token exchange returns a response without a `refresh_token` field - Message: `Authorization code request response did not return a refresh token`

### Catch Example
```php
use SellingPartnerApi\OAuth;
use SellingPartnerApi\Exceptions\OAuthException;

try {
    $oauth = new OAuth($clientId, $clientSecret, $redirectUri);
    $refreshToken = $oauth->getRefreshToken($authCode);
} catch (OAuthException $e) {
    // handle bad redirect URI or Amazon's failure to return a refresh token
}
```
```

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

### Call confirmShipment with ConfirmShipmentRequest DTO

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Shows how to construct a ConfirmShipmentRequest DTO with package details and order items, then pass it to the confirmShipment method of the Orders API. The example uses named arguments and includes a marketplace ID and order ID.

```php
<?php

use SellingPartnerApi\Seller\OrdersV0\Dto;
use SellingPartnerApi\SellingPartnerApi;

$confirmShipmentRequest = new Dto\ConfirmShipmentRequest(
    packageDetail: new Dto\PackageDetail(
        packageReferenceId: 'PKG123',
        carrierCode: 'USPS',
        trackingNumber: 'ASDF1234567890',
        shipDate: new DateTime('2024-01-01 12:00:00'),
        orderItems: [
            new Dto\ConfirmShipmentOrderItem(
                orderItemId: '1234567890',
                quantity: 1,
            ),
            new Dto\ConfirmShipmentOrderItem(
                orderItemId: '0987654321',
                quantity: 2,
            )
        ],
    ),
    marketplaceId: 'ATVPDKIKX0DER',
);

$response = $ordersApi->confirmShipment(
    orderId: '123-4567890-1234567',
    confirmShipmentRequest: $confirmShipmentRequest,
);
```

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

### Access Replenishment API v2022-11-07

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Replenishment API v2022-11-07 client from the seller connector.

```php
$replenishmentApi = $sellerConnector->replenishmentV20221107();
```

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

### Access Product Fees API v0

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Product Fees API v0 client from the seller connector.

```php
$productFeesApi = $sellerConnector->productFeesV0();
```

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

### Access Finances API v2024-06-19

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Finances API v2024-06-19 client from the seller connector.

```php
$financesApi = $sellerConnector->financesV20240619();
```

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

### Using debugToFile() to log requests and responses

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/selling-partner-api.md

Example usage of debugToFile() to write request and response dumps to a log file. After making calls, the file contains the dumps.

```php
$connector->debugToFile('/tmp/spapi-debug.log');

// ...make calls; /tmp/spapi-debug.log now contains request+response dumps
```

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

### Uploading a feed document with UploadsDocument

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/traits.md

Shows how to get the content type for a feed type and upload a feed file. Throws RuntimeException if upload is rejected by Amazon.

```php
use SellingPartnerApi\Seller\FeedsV20210630\Responses\CreateFeedDocumentResponse;

$contentType = CreateFeedDocumentResponse::getContentType('POST_PRODUCT_PRICING_DATA'); // text/xml
$feedDocument = $createDocumentResponse->dto(); // CreateFeedDocumentResponse
try {
    $feedDocument->upload('POST_PRODUCT_PRICING_DATA', file_get_contents('your/feed/file.xml'));
} catch (\RuntimeException $e) {
    // upload rejected by Amazon
}
```

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

### Access Seller Wallet API v2024-03-01

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Seller Wallet API v2024-03-01 client from the seller connector.

```php
$sellerWalletApi = $sellerConnector->sellerWalletV20240301();
```

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

### OAuth Connector Constructor Signature

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/configuration.md

Constructor for the OAuth connector. Requires client ID, client secret, and redirect URI. The redirect URI must start with https:// and match an allowed redirect URI in Seller Central, otherwise an OAuthException is thrown.

```php
new SellingPartnerApi\OAuth(string $clientId, string $clientSecret, string $redirectUri)
```

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

### Access Listings Items API v2020-09-01

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Listings Items API v2020-09-01 client from the seller connector.

```php
$listingsItemsApi = $sellerConnector->listingsItemsV20200901();
```

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

### Access Product Type Definitions API v2020-09-01

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Product Type Definitions API v2020-09-01 client from the seller connector.

```php
$productTypeDefinitionsApi = $sellerConnector->productTypeDefinitionsV20200901();
```

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

### Create a seller connector with SellingPartnerApi::seller()

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/configuration.md

Shows how to instantiate a seller connector with the required client ID, client secret, refresh token, and endpoint, plus optional data elements, delegatee, authentication client, and cache. The refresh token can be a dummy string like 'grantless' when only grantless operations are used. The cache can be set to null to disable caching or to a custom TokenCache implementation.

```php
use SellingPartnerApi\SellingPartnerApi;
use SellingPartnerApi\Enums\Endpoint;
use SellingPartnerApi\Authentication\InMemoryTokenCache;

$connector = SellingPartnerApi::seller(
    clientId: $clientId,
    clientSecret: $clientSecret,
    refreshToken: $refreshToken,
    endpoint: Endpoint::EU,
    dataElements: ['buyerInfo', 'shippingAddress'],   // getOrder/getOrders RDTs include PII
    delegatee: null,                                   // or 'amzn1.application-oa2-client.delegate...'
    authenticationClient: null,                         // or new \GuzzleHttp\Client([...])
    cache: new InMemoryTokenCache,                     // or null to disable, or your TokenCache
);
```

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

### Package class with static metadata helpers

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/generator.md

Provides static methods version(), name(), and namespace() that return metadata from resources/generator-config.json and composer.json. Used by SellingPartnerApi::getUserAgent() and the version command.

```php
class Package
{
    public static function version(): string   // ['version'] from resources/generator-config.json
    public static function name(): string      // ['name'] from composer.json
    public static function namespace(): string // ['namespace'] from resources/generator-config.json
}
```

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

### Download Seller Orders and Merchant Fulfillment APIs

Source: https://github.com/jlevers/selling-partner-api/blob/main/CONTRIBUTING.md

Runs the schema:download command with the seller category and two schema names. The --category and --schema options can accept multiple values.

```bash
$ php bin/console schema:download \
    --category seller \
    --schema orders --schema merchant-fulfillment
```

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

### Example generated DTO: Money

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/base-classes.md

Example of a generated DTO extending Dto. It declares an attribute map and public readonly constructor properties.

```php
final class Money extends Dto
{
    protected static array $attributeMap = ['currencyCode' => 'CurrencyCode', 'amount' => 'Amount'];

    public function __construct(
        public ?string $currencyCode = null,
        public ?string $amount = null,
    ) {}
}
```

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

### Access Seller APIs via SellingPartnerApi::seller()

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Shows how to create a seller connector instance using the SellingPartnerApi::seller() class method. This is the entry point for accessing all Seller API segments.

```php
<?php
use SellingPartnerApi\SellingPartnerApi;

$sellerConnector = SellingPartnerApi::seller(/* ... */);
```

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

### upload()

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/traits.md

PUTs data to the presigned upload URL. Accepts string, StreamInterface, callable, or Iterator as body. Sends Content-Type and Host headers. Throws RuntimeException for responses >= 300.

```APIDOC
## upload()

### Description
PUTs `$data` to the presigned upload URL. Accepts anything Guzzle can send as a body: string, `StreamInterface`, callable, or `Iterator`. Sends `Content-Type` (from `getContentType()`) and `Host` headers. **Throws** `RuntimeException("Document upload failed ({$statusCode}): {$body}")` for any response ≥ 300.

### Method
PUT

### Endpoint
Presigned upload URL (provided by Amazon)

### Parameters
- **feedType** (string) - Required - The feed type identifier (e.g., `POST_PRODUCT_PRICING_DATA`).
- **data** (string|StreamInterface|callable|Iterator) - Required - The data to upload.
- **charset** (?string) - Optional - Character set to append to content type.
- **client** (?Client) - Optional - Guzzle client to use for the request.

### Request Example
```php
$feedDocument->upload('POST_PRODUCT_PRICING_DATA', file_get_contents('your/feed/file.xml'));
```

### Response
#### Success Response
No return value (void).

#### Error Response
Throws `RuntimeException` with message `Document upload failed ({$statusCode}): {$body}` for any response ≥ 300.
```

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

### Access Sellers API v1

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Sellers API v1 client from the seller connector.

```php
$sellersApi = $sellerConnector->sellersV1();
```

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

### Access Supply Sources API v2020-07-01

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Initializes the Supply Sources API client using the seller connector. Use this to interact with supply source endpoints.

```php
$supplySourcesApi = $sellerConnector->supplySourcesV20200701();
```

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

### Using AccessTokenAuthenticator

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/authentication.md

Shows how to instantiate AccessTokenAuthenticator with an access token and expiry, then authenticate a pending request. The resulting request will include the X-AMZ-Access-Token header.

```php
use SellingPartnerApi\Authentication\AccessTokenAuthenticator;

$auth = new AccessTokenAuthenticator('Atzr|...', expiresAt: new DateTimeImmutable('+3600 seconds'));
$pendingRequest->authenticate($auth); // X-AMZ-Access-Token: Atzr|...
```

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

### Access Sales API v1

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Sales API v1 client from the seller connector.

```php
$salesApi = $sellerConnector->salesV1();
```

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

### OAuth Connector Constructor

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/configuration.md

Creates a new OAuth connector instance for the Selling Partner API. Requires LWA client credentials and a redirect URI.

```APIDOC
## OAuth Connector Constructor

### Description
Creates a new OAuth connector instance for the Selling Partner API. Requires LWA client credentials and a redirect URI.

### Method
Constructor

### Endpoint
`new SellingPartnerApi\OAuth(string $clientId, string $clientSecret, string $redirectUri)`

### Parameters
#### Constructor Parameters
- **clientId** (string) - Required - LWA client ID
- **clientSecret** (string) - Required - LWA client secret
- **redirectUri** (string) - Required - Must start with `https://` (else `OAuthException`); must match an allowed redirect URI in Seller Central

### Notes
- Token endpoint constant: `OAuth::TOKEN_URL = 'https://api.amazon.com/auth/o2/token'`
```

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

### Access Reports API v2021-06-30

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Reports API v2021-06-30 client from the seller connector.

```php
$reportsApi = $sellerConnector->reportsV20210630();
```

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

### Access Orders API v2026-01-01

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Orders API v2026-01-01 client from the seller connector.

```php
$ordersApi = $sellerConnector->ordersV20260101();
```

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

### Order DTO constructor with promoted properties

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/types.md

Constructor for SellingPartnerApi\Seller\OrdersV0\Dto\Order with 48 promoted public properties. Returned nested inside GetOrdersResponse/GetOrderResponse payload. Key fields include amazonOrderId, purchaseDate, lastUpdateDate, orderStatus (required), and optional fields like orderTotal, shippingAddress, buyerInfo, buyerTaxInformation, paymentMethodDetails, marketplaceId, numberOfItemsShipped, numberOfItemsUnshipped. Restricted data fields (shippingAddress, buyerInfo, buyerTaxInformation) are only available via RDT.

```php
public function __construct(
    public string $amazonOrderId,
    public string $purchaseDate,
    public string $lastUpdateDate,
    public string $orderStatus,
    public ?string $sellerOrderId = null,
    public ?string $fulfillmentChannel = null,
    public ?string $salesChannel = null,
    public ?string $orderChannel = null,
    public ?string $shipServiceLevel = null,
    public ?Money $orderTotal = null,
    public ?int $numberOfItemsShipped = null,
    public ?int $numberOfItemsUnshipped = null,
    public ?array $paymentExecutionDetail = null,
    public ?string $paymentMethod = null,
    public ?array $paymentMethodDetails = null,
    public ?string $marketplaceId = null,
    public ?string $shipmentServiceLevelCategory = null,
    public ?string $easyShipShipmentStatus = null,
    public ?string $cbaDisplayableShippingLabel = null,
    public ?string $orderType = null,
    public ?string $earliestShipDate = null,
    public ?string $latestShipDate = null,
    public ?string $earliestDeliveryDate = null,
    public ?string $latestDeliveryDate = null,
    public ?bool $isBusinessOrder = null,
    public ?bool $isPrime = null,
    public ?bool $isPremiumOrder = null,
    public ?bool $isGlobalExpressEnabled = null,
    public ?string $replacedOrderId = null,
    public ?bool $isReplacementOrder = null,
    public ?string $promiseResponseDueDate = null,
    public ?bool $isEstimatedShipDateSet = null,
    public ?bool $isSoldByAb = null,
    public ?bool $isIba = null,
    public ?Address $defaultShipFromLocationAddress = null,
    public ?string $buyerInvoicePreference = null,
    public ?BuyerTaxInformation $buyerTaxInformation = null,
    public ?FulfillmentInstruction $fulfillmentInstruction = null,
    public ?bool $isIspu = null,
    public ?bool $isAccessPointOrder = null,
    public ?MarketplaceTaxInfo $marketplaceTaxInfo = null,
    public ?string $sellerDisplayName = null,
    public ?Address $shippingAddress = null,
    public ?BuyerInfo $buyerInfo = null,
    public ?AutomatedShippingSettings $automatedShippingSettings = null,
    public ?bool $hasRegulatedItems = null,
    public ?string $electronicInvoiceStatus = null,
) {}
```

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

### Build an OAuth authorization URI

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Creates an OAuth instance with client credentials and redirect URI, then generates a seller-specific authorization URI. Requires app ID, LWA client ID and secret, a matching redirect URI, and a base64-encoded state string. The marketplace parameter specifies the target marketplace; optionally pass draftApp: false if the app is published on the Marketplace Appstore.

```php
use SellingPartnerApi\Enums\Marketplace;
use SellingPartnerApi\OAuth;

$oauth = new OAuth(
    clientId: 'amzn1.application-oa2-client.asdfqwertyuiop...',
    clientSecret: 'amzn1.oa2-cs.v1.1234567890asdfghjkl...',
    redirectUri: 'https://example.com/redirect',
);

$authUrl = $oauth->getAuthorizationUri(
    appId: 'amzn1.sp.solution...',
    state: 'unique-base64-encoded-string',
    // The marketplace that you want to authorize the seller in
    marketplace: Marketplace::US,
    // If your app is published on the Marketplace Appstore, pass this parameter:
    // draftApp: false,
);

// Redirect your user to $authUrl...
```

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

### Access Orders API v0

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Orders API v0 client from the seller connector.

```php
$ordersApi = $sellerConnector->ordersV0();
```

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

### Access Notifications API v1

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Notifications API v1 client from the seller connector.

```php
$notificationsApi = $sellerConnector->notificationsV1();
```

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

### Downloading and streaming report documents

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/traits.md

Shows how to download a report document with parsing, stream huge documents in chunks, and handle exceptions. Presigned URLs expire after 5 minutes, so catch RuntimeException for missing/expired documents and InvalidArgumentException for unknown or missing document types.

```php
$reportDocument = $response->dto(); // ReportsV20210630\Responses\ReportDocument
try {
    $rows = $reportDocument->download('GET_MERCHANT_LISTINGS_DATA');
    foreach ($rows as $row) { /* ... */ }

    // or stream huge documents:
    $stream = $reportDocument->downloadStream();
    while (! $stream->eof()) { fwrite($out, $stream->read(8192)); }
} catch (\RuntimeException $e) {
    // document missing/expired (presigned URLs expire after 5 minutes)
} catch (\InvalidArgumentException $e) {
    // unknown document type or missing type with postProcess=true
}
```

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

### Access Messaging API v1

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Messaging API v1 client from the seller connector.

```php
$messagingApi = $sellerConnector->messagingV1();
```

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

### ProductFeesV0

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/endpoints.md

Endpoints for estimating fees for products.

```APIDOC
## POST /products/fees/v0/items/{asin}/feesEstimate

### Description
Estimates fees for an item identified by ASIN.

### Method
POST

### Endpoint
/products/fees/v0/items/{asin}/feesEstimate

### Parameters
#### Path Parameters
- **asin** (string) - Required - The ASIN of the item.

## POST /products/fees/v0/listings/{sellerSku}/feesEstimate

### Description
Estimates fees for a listing identified by seller SKU.

### Method
POST

### Endpoint
/products/fees/v0/listings/{sellerSku}/feesEstimate

### Parameters
#### Path Parameters
- **sellerSku** (string) - Required - The seller SKU of the listing.

## POST /products/fees/v0/feesEstimate

### Description
Estimates fees for a product.

### Method
POST

### Endpoint
/products/fees/v0/feesEstimate
```

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

### Access Invoices API v2024-06-19

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Invoices API v2024-06-19 client from the seller connector.

```php
$invoicesApi = $sellerConnector->invoicesV20240619();
```

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

### Access Services API v1

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Initializes the Services API client using the seller connector. Use this to interact with services-related endpoints.

```php
$servicesApi = $sellerConnector->servicesV1();
```

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

### CreateFeedSpecification DTO constructor

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/types.md

Constructor for SellingPartnerApi\Seller\FeedsV20210630\Dto\CreateFeedSpecification. Accepted by FeedsV20210630::createFeed().

```php
public function __construct(
    public string $feedType,
    public array $marketplaceIds,       // string[]
    public string $inputFeedDocumentId,
    public ?array $feedOptions = null,
) {}
```

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

### Access Feeds API v2021-06-30

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Feeds API v2021-06-30 client from the seller connector.

```php
$feedsApi = $sellerConnector->feedsV20210630();
```

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

### Access Merchant Fulfillment API v0

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Merchant Fulfillment API v0 client from the seller connector.

```php
$merchantFulfillmentApi = $sellerConnector->merchantFulfillmentV0();
```

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

### Access Tokens API v2021-03-01

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Initializes the Tokens API client using the seller connector. Use this to interact with token endpoints.

```php
$tokensApi = $sellerConnector->tokensV20210301();
```

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

### Access Listings Restrictions API v2021-08-01

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Listings Restrictions API v2021-08-01 client from the seller connector.

```php
$listingsRestrictionsApi = $sellerConnector->listingsRestrictionsV20210801();
```

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

### Access Uploads API v2020-11-01

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Initializes the Uploads API client using the seller connector. Use this to interact with upload endpoints.

```php
$uploadsApi = $sellerConnector->uploadsV20201101();
```

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

### Create Vendor Connector with SellingPartnerApi::vendor()

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to create a vendor connector instance. The vendor() method is the entry point for accessing all vendor-specific APIs.

```php
<?php
use SellingPartnerApi\SellingPartnerApi;

$vendorConnector = SellingPartnerApi::vendor(/* ... */);
```

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

### Access Listings Items API v2021-08-01

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the Listings Items API v2021-08-01 client from the seller connector.

```php
$listingsItemsApi = $sellerConnector->listingsItemsV20210801();
```

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

### Access FBA Outbound API v2020-07-01

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the FBA Outbound API v2020-07-01 client from the seller connector.

```php
$fbaOutboundApi = $sellerConnector->fbaOutboundV20200701();
```

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

### Access FBA Inventory API v1

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the FBA Inventory API v1 client from the seller connector.

```php
$fbaInventoryApi = $sellerConnector->fbaInventoryV1();
```

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

### CreateFeedDocumentSpecification DTO constructor

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/types.md

Constructor for SellingPartnerApi\Seller\FeedsV20210630\Dto\CreateFeedDocumentSpecification. Accepted by FeedsV20210630::createFeedDocument(). contentType should be e.g. text/xml (use CreateFeedDocumentResponse::getContentType()).

```php
public function __construct(
    public string $contentType,   // e.g. text/xml (use CreateFeedDocumentResponse::getContentType())
) {}
```

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

### download()

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/traits.md

Downloads and optionally parses the presigned document URL. Returns parsed data (array, SimpleXMLElement, or string) depending on content type, or raw bytes when postProcess is false.

```APIDOC
## download()

### Description
Downloads and optionally parses the presigned document URL. Returns parsed data (array, SimpleXMLElement, or string) depending on content type, or raw bytes when postProcess is false.

### Method
PHP method (trait)

### Signature
```php
public function download(
    ?string $documentType = null,
    bool $postProcess = true,
    ?string $encoding = null,
    ?Client $client = null,
): array|string|SimpleXMLElement
```

### Parameters
- **documentType** (?string) - Optional - Feed/report type name (e.g. `GET_MERCHANT_LISTINGS_DATA`); required when `postProcess` is `true`
- **postProcess** (bool) - Optional - When `false`, returns raw (possibly decompressed) bytes without parsing
- **encoding** (?string) - Optional - Document encoding override; default behavior detects from response headers/contents
- **client** (?Client) - Optional - Custom Guzzle client

### Return Value
- CSV/TAB/XLSX → `array` of associative rows (first row is the header; uses OpenSpout readers; TAB uses `\t` delimiters; enclosure char disabled via `chr(0)` unless `quoteEnclosure` is set in `reports.json`).
- JSON → decoded array via `json_decode($contents, true)`.
- XML → `SimpleXMLElement`.
- PDF/PLAIN → raw string.

GZIP-compressed documents (`compressionAlgorithm === 'GZIP'`) are decompressed via `gzdecode()` before parsing. Non-XLSX/PDF content is re-encoded to UTF-8 from the detected encoding (defaults `UTF-8`, with `CP932`/header-decoded charset as alternates; `Cp1252` is normalized to `ISO-8859-1`).

### Throws
| Exception | Condition |
|-----------|-----------|
| `InvalidArgumentException` | `postProcess` is `true` and no `documentType` given (`'Document type is required to parse document data...'`) |
| `RuntimeException` | Document URL returns 404 (`"Document not found (404): ..."`) |
| `InvalidArgumentException` | Unknown document type (`"Unknown document type '$documentTypeName'"`) |
| `GuzzleHttp\Exception\ClientException` | Other 4xx/5xx responses |

### Example
```php
$reportDocument = $response->dto(); // ReportsV20210630\Responses\ReportDocument
try {
    $rows = $reportDocument->download('GET_MERCHANT_LISTINGS_DATA');
    foreach ($rows as $row) { /* ... */ }
} catch (\RuntimeException $e) {
    // document missing/expired (presigned URLs expire after 5 minutes)
} catch (\InvalidArgumentException $e) {
    // unknown document type or missing type with postProcess=true
}
```
```

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

### GetOrdersResponse

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/orders-v0.md

Example of a generated response DTO for the GetOrders operation. It extends the base Response class and contains an optional OrdersList payload and an optional ErrorList.

```APIDOC
## GetOrdersResponse

### Description
Generated response DTO for the GetOrders operation. Extends `SellingPartnerApi\Response` and contains an optional `OrdersList` payload and an optional `ErrorList`.

### Properties
- **payload** (`?OrdersList`) - Optional - The list of orders and pagination token.
- **errors** (`?ErrorList`) - Optional - A list of error responses returned when the request is unsuccessful.

### Example
```php
final class GetOrdersResponse extends Response
{
    public function __construct(
        public readonly ?OrdersList $payload = null,
        public readonly ?ErrorList $errors = null,
    ) {}
}
```
```

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

### OAuth::__construct

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/oauth.md

Creates a new OAuth instance with the LWA client ID, client secret, and redirect URI. Throws an OAuthException if the redirect URI does not use HTTPS.

```APIDOC
## OAuth::__construct

### Description
Creates a new OAuth connector instance for the website authorization workflow.

### Method
Constructor

### Signature
```php
public function __construct(
    protected string $clientId,
    protected string $clientSecret,
    protected string $redirectUri
)
```

### Parameters
- **clientId** (string) - Required - LWA client ID of the SP API application
- **clientSecret** (string) - Required - LWA client secret
- **redirectUri** (string) - Required - OAuth redirect URI (`https://` only)

### Throws
- `SellingPartnerApi\Exceptions\OAuthException` when `redirectUri` does not start with `https://` (message: `'Redirect URI must use SSL (https://)'`)

### Example
```php
use SellingPartnerApi\OAuth;

$oauth = new OAuth(
    clientId: 'amzn1.application-oa2-client.asdf...',
    clientSecret: 'amzn1.oa2-cs.v1.1234...',
    redirectUri: 'https://example.com/redirect',
); // throws OAuthException if redirectUri is not https
```
```

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

### Access FBA Inbound Eligibility API v1

Source: https://github.com/jlevers/selling-partner-api/blob/main/README.md

Use this snippet to get the FBA Inbound Eligibility API v1 client from the seller connector.

```php
$fbaInboundEligibility = $sellerConnector->fbaInboundEligibilityV1();
```

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

### Using RestrictedReport middleware

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/middleware.md

Shows how to instantiate the RestrictedReport middleware. Saloon invokes it during the request pipeline, and unsupported report types surface as InvalidArgumentException.

```php
use SellingPartnerApi\Middleware\RestrictedReport;

$middleware = new RestrictedReport;
// Saloon invokes $middleware($pendingRequest) during the request pipeline;
// errors surface as InvalidArgumentException for unsupported report types.
```

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

### GET /catalog/2024-11-01/automotive/vehicles

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/endpoints.md

Retrieves automotive vehicle information from the catalog. This endpoint is part of the Vehicles API (version 2024-11-01) and is accessed via the $seller->vehiclesV20241101() client.

```APIDOC
## GET /catalog/2024-11-01/automotive/vehicles

### Description
Retrieves automotive vehicle information from the catalog.

### Method
GET

### Endpoint
/catalog/2024-11-01/automotive/vehicles

```

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

### SellingPartnerApi::seller()

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/api-reference/selling-partner-api.md

Static factory method that creates a SellerConnector for the Seller APIs. Parameters are identical to the constructor.

```APIDOC
## SellingPartnerApi::seller()

### Description
Creates a `SellerConnector` for the Seller APIs. Parameters are identical to the constructor.

### Method
Static factory method

### Signature
```php
public static function seller(
    string $clientId,
    string $clientSecret,
    string $refreshToken,
    Endpoint $endpoint,
    array $dataElements = [],
    ?string $delegatee = null,
    ?Client $authenticationClient = null,
    ?TokenCache $cache = new InMemoryTokenCache,
): SellerConnector
```

### Parameters
- **clientId** (string) - Required - The client ID for the application.
- **clientSecret** (string) - Required - The client secret for the application.
- **refreshToken** (string) - Required - The refresh token for the user.
- **endpoint** (Endpoint) - Required - The endpoint (e.g., `Endpoint::NA`).
- **dataElements** (array) - Optional - Data elements for restricted data operations.
- **delegatee** (?string) - Optional - Delegatee for the connection.
- **authenticationClient** (?Client) - Optional - Guzzle client for authentication requests.
- **cache** (?TokenCache) - Optional - Token cache, defaults to `new InMemoryTokenCache`.

### Returns
- **SellerConnector** - The connector instance for Seller APIs.

### Example
```php
use SellingPartnerApi\SellingPartnerApi;
use SellingPartnerApi\Enums\Endpoint;

$seller = SellingPartnerApi::seller(
    clientId: 'amzn1.application-oa2-client.asdf...',
    clientSecret: 'amzn1.oa2-cs.v1.1234...',
    refreshToken: 'Atzr|IwEBIA...',
    endpoint: Endpoint::NA,
);

$ordersApi = $seller->ordersV0();
```
```

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

### GET /finances/transfers/2024-06-01/paymentMethods

Source: https://github.com/jlevers/selling-partner-api/blob/main/_autodocs/endpoints.md

Retrieves the payment methods available for transfers. This endpoint is part of the Transfers API (version 2024-06-01) and is accessed via the $seller->transfersV20240601() client.

```APIDOC
## GET /finances/transfers/2024-06-01/paymentMethods

### Description
Retrieves the payment methods available for transfers.

### Method
GET

### Endpoint
/finances/transfers/2024-06-01/paymentMethods

```
Tokens:
Raw