How to use my Selling Partner API PHP library

(You need Selling Partner API developer credentials to follow along with this post. If you don’t have those credentials, my post How to Access the Amazon Selling Partner API guides you through the process of getting them.)

I wrote in my first Selling Partner API post that I thought it was likely Amazon would release a PHP library for the Selling Partner API at some point. I was wrong—months later, there is still no sign of an official SP API library for PHP. So I wrote one!

Background

I wrote this library with three goals in mind:

1. It should be easy to install, because Amazon’s Java and C# libraries require the user to generate the majority of the library using Swagger, and the Java authentication library has to be integrated into the Swagger-generated library by hand. (I cover how to do all that in my last post.)
2. It should be easy to use. There are parts of the SP API that are poorly documented and confusing to work with, but a good client library should hide that from the user as much as possible.
3. It should be open to community contributions and bug reports, and should respond to them quickly, because the SP API itself has many fixable problems but has not noticeably improved despite ample community feedback.

Features and usage

The three most useful features are, in my mind:

• Automatic API authentication and request signing. Once you’ve created a Configuration object and passed it to an API class, you don’t have to think about authentication anymore. Just call a request method, and all the boring and finicky stuff will be dealt with behind the scenes.
• Behind-the-scenes Restricted Data Token generation. Certain SP API calls (mostly those that return PII) require an additional request to generate a special Restricted Data Token before you can make the call. The library automatically generates those RDTs when you call an endpoint where they’re needed, so you can focus on the business logic and skip the extra step in your code.
• A class for uploading/downloading documents. You don’t have to deal with the upload/download/compression aspects of the Reports and Feeds APIs by hand.

A more complete description of the library’s features, and usage examples for those features, can be found in the README. For that reason, I’m only giving a basic usage example here.

Example

To run this example successfully, you need to have access to the Selling Partner Insights SP API role. If you want to work with a different part of the SP API, you can find complete documentation for all the *Api classes linked in the README. Each *Api class corresponds to one of the major SP API endpoints.

Create a new Composer project with composer init, and install the library with composer require jlevers/selling-partner-api. Then, create a file named index.php inside your Composer project, and add the following contents:

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

use SellingPartnerApi\Api\SellersV1Api as SellersApi;
use SellingPartnerApi\Configuration;
use SellingPartnerApi\Endpoint;

$config = new Configuration([
    "lwaClientId" => "<LWA client ID>",
    "lwaClientSecret" => "<LWA client secret>",
    "lwaRefreshToken" => "<LWA refresh token>",
    "awsAccessKeyId" => "<AWS access key ID>",
    "awsSecretAccessKey" => "<AWS secret access key>",
    "endpoint" => Endpoint::NA  // or another endpoint from lib/Endpoint.php
]);

$api = new SellersApi($config);
try {
    $result = $api->getMarketplaceParticipations();
    print_r($result);
} catch (Exception $e) {
    echo 'Exception when calling SellersApi->getMarketplaceParticipations: ',
        $e->getMessage(),
        PHP_EOL;
}

Replace the placeholders in the Configuration constructor with your LWA credentials (client ID, secret key, and refresh token) and AWS IAM user credentials (access key ID and secret access key)

The AWS credentials should come from the AWS IAM user whose ARN you gave when you created your SP API application. The LWA credentials are associated with the SP API application itself. You can read more about the AWS credentials in the Registering your Selling Partner API application section of this post, and more about the LWA credentials in the Self-authorize the application to run on your Seller Central account section of this post.

Now run php index.php, and you should see output similar to this:

Array (
    [0] => SellingPartnerApi\Model\SellersV1\MarketplaceParticipation Object (
        [container:protected] => Array (
            [marketplace] => SellingPartnerApi\Model\SellersV1SellersV1\Marketplace Object (
                [container:protected] => Array (
                    [id] => A1AM78C64UM0Y8
                    [name] => Amazon.com.mx
                    [country_code] => MX
                    [default_currency_code] => MXN
                    [default_language_code] => es_MX
                    [domain_name] => www.amazon.com.mx
                )
            )
            [participation] => SellingPartnerApi\Model\SellersV1\Participation Object (
                [container:protected] => Array (
                [is_participating] => 1
                [has_suspended_listings] => 
                )
            )
        )
    )
    [1] => SellingPartnerApi\Model\SellersV1\MarketplaceParticipation Object (
        [container:protected] => Array (
            [marketplace] => SellingPartnerApi\Model\SellersV1\Marketplace Object (
                [container:protected] => Array (
                    [id] => A2EUQ1WTGCTBG2
                    [name] => Amazon.ca
                    [country_code] => CA
                    [default_currency_code] => CAD
                    [default_language_code] => en_CA
                    [domain_name] => www.amazon.ca
                )
            )
            [participation] => SellingPartnerApi\Model\SellersV1\Participation Object (
                [container:protected] => Array (
                    [is_participating] => 1
                    [has_suspended_listings] => 
                )
            )
        )
    )
    [2] => SellingPartnerApi\Model\SellersV1\MarketplaceParticipation Object (
        [container:protected] => Array (
            [marketplace] => SellingPartnerApi\Model\SellersV1\Marketplace Object (
                [container:protected] => Array (
                    [id] => ATVPDKIKX0DER
                    [name] => Amazon.com
                    [country_code] => US
                    [default_currency_code] => USD
                    [default_language_code] => en_US
                    [domain_name] => www.amazon.com
                )
            )
            [participation] => SellingPartnerApi\Model\SellersV1\Participation Object (
                [container:protected] => Array (
                    [is_participating] => 1
                    [has_suspended_listings] => 
                )
            )
        )
    )
)

It’s worth noting that index.php has the exact same functionality as the Java application from my last post. This implementation is 24 lines of code vs the Java version’s 150+…and that’s not including all of the Java app’s setup and configuration.

Wrapup

If you find any bugs in the library, please open a GitHub issue. If you have any questions or comments on this post, please feel free to email me! I’d love to hear from you.

Next time, I’ll explain how to write an SP API application that can be listed on the Marketplace Appstore so that other sellers can install it (I know I said that last time, but this time I swear it’s true). (Update: read that post here.)

If you found this post helpful, you can subscribe to get the next post right in your inbox!

(I help Amazon sellers optimize and automate business processes using the Selling Partner API—if you’re interested in upgrading the tools you use to sell on Amazon, shoot me an email at jesse@jesseevers.com.)

Changelog

• 5/28/2022: Updated code to match v5 of the library, and updated documentation links.
• 8/20/2021: Updated broken links, and added link to authorization flow post.
• 7/3/2021: Updated the example to use the simpler Configuration authentication setup that was published in v3.0.0, and added Restricted Data Token generation to the features and usage section.
• 5/26/2021: Updated the example to use the newer ConfigurationOptions authentication strategy, instead of putting credentials in .env.