highsidelabs / laravel-spapi
A Laravel wrapper for Amazon's Selling Partner API (via jlevers/selling-partner-api)
Installs: 11 611
Dependents: 0
Suggesters: 0
Security: 0
Stars: 17
Watchers: 2
Forks: 11
Open Issues: 1
Requires
- php: >=8.2
- illuminate/cache: ^11.0
- illuminate/database: ^11.0
- illuminate/support: ^11.0
- jlevers/selling-partner-api: ^7.1
Requires (Dev)
- laravel/pint: ^1.17
- orchestra/testbench: ^9.2
- phpunit/phpunit: ^11.2
README
Selling Partner API wrapper for Laravel
Simplify connecting to the Selling Partner API with Laravel. Uses jlevers/selling-partner-api under the hood.
Related packages
jlevers/selling-partner-api
: A PHP library for Amazon's Selling Partner API.highsidelabs/laravel-spapi
is a Laravel wrapper aroundjlevers/selling-partner-api
.highsidelabs/walmart-api
: A PHP library for Walmart's seller and supplier APIs, including the Marketplace, Drop Ship Vendor, Content Provider, and Warehouse Supplier APIs.highsidelabs/amazon-business-api
: A PHP library for Amazon's Business API, with a near-identical interface tojlevers/selling-partner-api
.
This package is developed and maintained by Highside Labs. If you need support integrating with Amazon's (or any other e-commerce platform's) APIs, we're happy to help! Shoot us an email at hi@highsidelabs.co. We'd love to hear from you :)
If you've found any of our packages useful, please consider becoming a Sponsor, or making a donation via the button below. We appreciate any and all support you can provide!
There is a more in-depth guide to using this package on our blog.
Installation
$ composer require highsidelabs/laravel-spapi
Table of Contents
Overview
This library has two modes:
- Single-seller mode, which you should use if you only plan to make requests to the Selling Partner API with a single set of credentials (most people fall into this category, so if you're not sure, this is probably you).
- Multi-seller mode, which makes it easy to make requests to the Selling Partner API from within Laravel when you have multiple sets of SP API credentials (for instance, if you operate multiple seller accounts, or operate one seller account in multiple regions).
Single-seller mode
Setup
- Publish the config file:
$ php artisan vendor:publish --tag="spapi-config"
- Add these environment variables to your
.env
:
SPAPI_LWA_CLIENT_ID= SPAPI_LWA_CLIENT_SECRET= SPAPI_LWA_REFRESH_TOKEN= # Optional # SPAPI_ENDPOINT_REGION=
Set SPAPI_ENDPOINT_REGION
to the region code for the endpoint you want to use (EU for Europe, FE for Far East, or NA for North America). The default is North America.
Usage
SellerConnector
and VendorConnector
can be type-hinted, and the connector classes can be used to create instances of all APIs supported by jlevers/selling-partner-api. This example assumes you have access to the Selling Partner Insights
role in your SP API app configuration (so that you can call SellingPartnerApi\Seller\SellersV1\Api::getMarketplaceParticipations()
), but the same principle applies to calling any other Selling Partner API endpoint.
use Illuminate\Http\JsonResponse; use Saloon\Exceptions\Request\RequestException; use SellingPartnerApi\Seller\SellerConnector; class SpApiController extends Controller { public function index(SellerConnector $connector): JsonResponse { try { $api = $connector->sellersV1(); $result = $api->getMarketplaceParticipations(); return response()->json($result->json()); } catch (RequestException $e) { $response = $e->getResponse(); return response()->json($response->json(), $e->getStatus()); } } }
Multi-seller mode
Setup
- Publish the config file:
# Publish config/spapi.php file $ php artisan vendor:publish --provider="HighsideLabs\LaravelSpApi\SellingPartnerApiServiceProvider"
-
Change the
installation_type
inconfig/spapi.php
tomulti
. -
Publish the multi-seller migrations:
# Publish migrations to database/migrations/ $ php artisan vendor:publish --tag="spapi-multi-seller"
- Run the database migrations to set up the
spapi_sellers
andspapi_credentials
tables (corresponding to theHighsideLabs\LaravelSpApi\Models\Seller
andHighsideLabs\LaravelSpApi\Models\Credentials
models, respectively):
$ php artisan migrate
Usage
First you'll need to create a Seller
, and some Credentials
for that seller. The Seller
and Credentials
models work just like any other Laravel model.
use HighsideLabs\LaravelSpApi\Models\Credentials; use HighsideLabs\LaravelSpApi\Models\Seller; $seller = Seller::create(['name' => 'My Seller']); $credentials = Credentials::create([ 'seller_id' => $seller->id, // You can find your selling partner ID/merchant ID by going to // https://<regional-seller-central-domain>/sw/AccountInfo/MerchantToken/step/MerchantToken 'selling_partner_id' => '<AMAZON SELLER ID>', // Can be NA, EU, or FE 'region' => 'NA', // The LWA client ID and client secret for the SP API application these credentials were created with 'client_id' => 'amzn....', 'client_secret' => 'fec9/aw....', // The LWA refresh token for this seller 'refresh_token' => 'IWeB|....', ]);
Note
client_id
and client_secret
are nullable. If you are authorizing multiple sellers on a single SP API application, they will all use the same client ID and client secret. If you leave client_id
and client_secret
empty, the library will try to load those values from the SPAPI_LWA_CLIENT_ID
and SPAPI_LWA_CLIENT_SECRET
environment variables that are used in single-seller mode. That means that the single-seller credentials can effectively be used as master credentials in multi-seller mode.
Once you have credentials in the database, you can use them to retrieve a SellerConnector
instance, from which you can get an instance of any seller API:
use HighsideLabs\LaravelSpApi\Models\Credentials; use Illuminate\Http\JsonResponse; use Saloon\Exceptions\Request\RequestException; $creds = Credentials::first(); /** @var SellingPartnerApi\Seller\SellersV1\Api $api */ $api = $creds->sellerConnector()->sellersV1(); try { $result = $api->getMarketplaceParticipations(); $dto = $result->dto(); } catch (RequestException $e) { $responseBody = $e->getResponse()->json(); }
The same goes for a VendorConnector
instance:
use HighsideLabs\LaravelSpApi\Models\Credentials; use Illuminate\Http\JsonResponse; use Saloon\Exceptions\Request\RequestException; $creds = Credentials::first(); /** @var SellingPartnerApi\Vendor\DirectFulfillmentShippingV1\Api $api */ $api = $creds->vendorConnector()->directFulfillmentShippingV1();
Troubleshooting
If you encounter an error like String data, right truncated: 7 ERROR: value too long for type character varying(255)
, it's probably because you're using Laravel's database cache, which by default has a 255-character limit on cache keys and values. This library has a migration available to fix this:
$ php artisan vendor:publish --tag="spapi-database-cache"
$ php artisan migrate