A PHP testing library for connecting to Amazon's Selling Partner API.
If you've found this library useful, please consider becoming a Sponsor, or making a one-time donation via the button below. I appreciate any and all support you can provide!
Document
helper class for uploading and downloading feed/report documentscomposer require jlevers/selling-partner-api
You need a few things to get started:
If you're looking for more information on how to set those things up, check out this blog post. It provides a detailed walkthrough of the whole setup process.
The Configuration
constructor takes a single argument: an associative array with all the configuration information that's needed to connect to the Selling Partner API:
If you created your Selling Partner API application using an IAM role ARN instead of a user ARN, pass that role ARN in the configuration array:
Getter and setter methods exist for the Configuration
class's lwaClientId
, lwaClientSecret
, lwaRefreshToken
, awsAccessKeyId
, awsSecretAccessKey
, and endpoint
properties. The methods are named in accordance with the name of the property they interact with: getLwaClientId
, setLwaClientId
, getLwaClientSecret
, etc.
$config
can then be passed into the constructor of any SellingPartnerApi\Api\*Api
class. See the Example
section for a complete example.
The array passed to the Configuration
constructor accepts the following keys:
lwaClientId (string)
: Required. The LWA client ID of the SP API application to use to execute API requests.lwaClientSecret (string)
: Required. The LWA client secret of the SP API application to use to execute API requests.lwaRefreshToken (string)
: The LWA refresh token of the SP API application to use to execute API requests. Required, unless you're only using the Configuration
instance to call grantless operations.awsAccessKeyId (string)
: Required. AWS IAM user Access Key ID with SP API ExecuteAPI permissions.awsSecretAccessKey (string)
: Required. AWS IAM user Secret Access Key with SP API ExecuteAPI permissions.endpoint (array)
: Required. An array containing a url
key (the endpoint URL) and a region
key (the AWS region). There are predefined constants for these arrays in lib/Endpoint.php
: (NA
, EU
, FE
, and NA_SANDBOX
, EU_SANDBOX
, and FE_SANDBOX
. See here for more details.accessToken (string)
: An access token generated from the refresh token.accessTokenExpiration (int)
: A Unix timestamp corresponding to the time when the accessToken
expires. If accessToken
is given, accessTokenExpiration
is required (and vice versa).onUpdateCredentials (callable|Closure)
: A callback function to call when a new access token is generated. The function should accept a single argument of type SellingPartnerApi\Credentials
.roleArn (string)
: If you set up your SP API application with an AWS IAM role ARN instead of a user ARN, pass that ARN here.authenticationClient (GuzzleHttp\ClientInterface)
: Optional GuzzleHttp\ClientInterface
object that will be used to generate the access token from the refresh tokentokensApi (SellingPartnerApi\Api\TokensApi)
: Optional SellingPartnerApi\Api\TokensApi
object that will be used to fetch Restricted Data Tokens (RDTs) when you call a restricted operationThis example assumes you have access to the Seller Insights
Selling Partner API role, but the general format applies to any Selling Partner API request.
To get debugging output when you make an API request, you can call $config->setDebug(true)
. By default, debug output goes to stdout
via php://output
, but you can redirect it a file with $config->setDebugFile('<path>')
.
When you call a restricted operation, a Restricted Data Token (RDT) is automatically generated. If you're calling a restricted operation that accepts a dataElements
parameter, you can pass dataElements
values as a parameter to the API call. Check out the getOrders, getOrder, and getOrderItems documentation to see how to pass dataElements
values to those calls. (At the time of writing, those are the only restricted operations that accept dataElements
values.)
The Feeds and Reports APIs include operations that involve uploading and downloading documents to and from Amazon. Amazon encrypts all documents they generate, and requires that all uploaded documents be encrypted. The SellingPartnerApi\Document
class handles all the encryption/decryption, given an instance of one of the Model\Reports\ReportDocument
, Model\Feeds\FeedDocument
, or Model\Feeds\CreateFeedDocumentResponse
classes. Instances of those classes are in the response returned by Amazon when you make a call to the getReportDocument
, getFeedDocument
, and createFeedDocument
endpoints, respectively.
This works very similarly to downloading a report document:
Most operations have one or more models associated with it. These models are classes that contain the data needed to make a certain kind of request to the API, or contain the data returned by a given request type. All of the models share the same general interface: you can either specify all the model's attributes during initialization, or use setter methods to set each attribute after the fact. Here's an example using the Service API's Buyer
model (docs, (source).
The Buyer
model has four attributes: buyer_id
, name
, phone
, and is_prime_member
. (If you're wondering how you would figure out which attributes the model has on your own, check out the docs
link above.) To create an instance of the Buyer
model with all those attributes set:
Alternatively, you can create an instance of the Buyer
model and then populate its fields:
Each model also has the getter methods you might expect:
Models can (and usually do) have other models as attributes:
Amazon includes some useful headers with each SP API response. If you need those for any reason, you can get an associative array of response headers by calling getHeaders()
on the response object. For instance: