Working with SP API credentials

This project provides a Laravel-native interface for interacting with the Selling Partner API via the highsidelabs/laravel-spapi package. It includes Seller and Credentials models for managing and storing SP API credentials.

Note that whenever the Credentials and/or Seller models are referenced, I'm talking about the App\Models\Credentials and App\Models\Seller classes, respectively.

This section will refer to two different types of credentials:

1. Master credentials. These are credentials specified in your .env, which are used as the basis for OAuth, notifications setup, and all other SP API operations unless another set of credentials is explicitly specified.

2. Child credentials. These are dynamic credentials that are stored in the database, either as a result of manually creating them via the Credentials model, or from a seller authorizing your app via the OAuth flow.

Master credentials

You can specify a set of master SP API credentials by filling in the SPAPI_LWA_* environment variables. Master credentials have a few different use cases with slightly varying setups:

• If you're only working with a single seller account in a single region, you only need to fill in the refresh token for that region, and specify which region you want to use in the SPAPI_LWA_DEFAULT_REGION environment variable. You can then retrieve your credentials with Credentials::master().

• If you have a single seller with credentials for multiple regions, you can pass the region code for the credentials you want to retrieve to Credentials::master(), like Credentials::master('EU').

• In multi-seller setups, master credentials are used for certain operations that need to be done with your own internal SP API credentials, rather than a set of credentials from a seller who has authorized your app via OAuth. Examples include OAuth and subscribing to notifications.

Master credentials are required for this system to work. After you specify a set of master credentials, or update your existing master credentials, run php artisan update-master-credentials to fetch the merchant IDs for the credentials and store them in the database.

Child credentials

If you're only working with a single seller account, you can skip this section. Master credentials are all you need.

As mentioned above, the Credentialsand Seller models make it possible to store credentials in the database, and to associate multiple sets of Selling Partner API credentials with a particular seller. The reason a given Seller can have multiple sets of credentials is because Selling Partner API credentials are different across regions (and across marketplaces within the Far East region), so a single seller could in theory have up to 5 sets of Selling Partner API credentials (one set each for the North America, Europe, Australia, Japan, and Singapore regions/marketplaces). This package further expands on that setup by associating the Seller model with a User model, so a single user in the Laravel app can have custody of multiple sellers.

You can either manually create sellers and credentials by using the model classes, or you can authorize external sellers on your app using OAuth.

Interacting with the Selling Partner API

Once you have a set of credentials set up in your application, you can use them to interact with the SP API by using the Credentials model. If you're working with master credentials, that's as simple as this:

$credentials = Credentials::master();

In a more complex, multi-seller setting, retrieving the North America credentials for a particular seller looks like this:

$seller = Auth::user()->sellers()->first();
$credentials = $seller->credentials->where('region', 'NA')->first();

The Credentials::sellerConnector() and Credentials::vendorConnector() methods produce SellingPartnerApi\Seller\SellerConnector and SellingPartnerApi\Vendor\VendorConnector instances from the jlevers/selling-partner-api library, which you can use to make requests to the SP API on behalf of the seller or vendor. For instance:

/** @var SellingPartnerApi\Seller\SellersV1\Api $api */
$api = $credentials->sellerConnector()->sellersV1();

try {
    $result = $api->getMarketplaceParticipations();
    $dto = $result->dto();
} catch (RequestException $e) {
    $responseBody = $e->getResponse()->json();
}

More info on this behavior in the highsidelabs/laravel-spapi documentation, here.