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.

Installation and configuration

  1. Install the library with Composer: composer require jlevers/selling-partner-api
  2. Copy the sample configuration file to the root of your project: cp vendor/jlevers/selling-partner-api/.env.example .env
  3. Fill in the variables in .env with the credentials associated with your app on the Seller Central developer page. You’ll need these pieces of information:
    • AWS access key ID
    • AWS secret access key
    • LWA client ID
    • LWA secret key
    • LWA refresh token

    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.

Features and usage

The three most useful features are, in my mind:

  • Automatic API authentication and request signing. Once you’ve filled in your .env file you don’t have to think about authentication anymore. Just call a request method, and all the boring and finnicky stuff will be dealt with behind the scenes.
  • Dynamic authentication credentials. You can make calls to the SP API using multiple different sets of credentials from within the same application. This is useful if you’re writing an application that will be listed on the Marketplace Appstore.
  • A class for uploading/downloading documents. You don’t have to deal with the encryption/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.

To run the example below successfully, you need to have access to the Selling Partner Insights SP API role. When you want to work with a different part of the SP API, you can find complete documentation for all the *Api classes in the docs/Api folder of the library’s repository. Each *Api class corresponds to one of the major SP API endpoints.

Create a file named index.php with the following contents in your project’s root directory:

1
2
3
4
5
6
7
8
9
10
11
12
<?php
require_once(__DIR__ . '/vendor/autoload.php');

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
Array (
    [0] => SellingPartnerApi\Model\MarketplaceParticipation Object (
        [container:protected] => Array (
            [marketplace] => SellingPartnerApi\Model\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\Participation Object (
                [container:protected] => Array (
                [is_participating] => 1
                [has_suspended_listings] => 
                )
            )
        )
    )
    [1] => SellingPartnerApi\Model\MarketplaceParticipation Object (
        [container:protected] => Array (
            [marketplace] => SellingPartnerApi\Model\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\Participation Object (
                [container:protected] => Array (
                    [is_participating] => 1
                    [has_suspended_listings] => 
                )
            )
        )
    )
    [2] => SellingPartnerApi\Model\MarketplaceParticipation Object (
        [container:protected] => Array (
            [marketplace] => SellingPartnerApi\Model\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\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 12 lines of code vs the Java version’s 150+…and that’s not including all the 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). 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.)