zero-to-prod/spapi

A PHP client library for Amazon's Selling Partner API.

Maintainers

Details

github.com/zero-to-prod/spapi

Homepage

Source

Issues

Documentation

Security Policy

Fund package maintenance!
Github

Installs: 2

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 1

Forks: 0

Open Issues: 0

v3.0.0 2025-02-02 00:00 UTC

Requires

Requires (Dev)

MIT 44fa496e6f5a05bbed9d8a2d7f15b9315d5d2879

spapizero-to-prod

This package is auto-updated.

Last update: 2025-02-22 16:20:18 UTC

README

Repo GitHub Actions Workflow Status GitHub Actions Workflow Status Packagist Downloads php Packagist Version License wakatime Hits-of-Code

Contents

Introduction

A PHP client library for Amazon's Selling Partner API.

Requirements

  • PHP 7.1 or higher.

Installation

Install Zerotoprod\Spapi via Composer:

composer require zero-to-prod/spapi

This will add the package to your project’s dependencies and create an autoloader entry for it.

Authentication

Refresh Token

Use this for calling operations that require authorization from a selling partner. All operations that are not grantless operations require authorization from a selling partner. When specifying this value, include the rrefresh_token parameter.

use Zerotoprod\Spapi\Lwa;
use Zerotoprod\SpapiLwa\SpapiLwa;

$response = SpapiLwa::from(
    'amzn1.application-oa2-client.xxx', // client_id
    'amzn1.oa2-cs.v1.xxx'               // client_secret
)->refreshToken('refresh_token');       // The LWA refresh token. Get this value when the selling partner authorizes your application

$access_token = $response['response']['access_token'];

Client Credentials

Use this for calling grantless operations. When specifying this value, include the scope parameter.

use Zerotoprod\Spapi\Lwa;
use Zerotoprod\SpapiLwa\SpapiLwa;

$response = SpapiLwa::from(
    'amzn1.application-oa2-client.xxx', // client_id
    'amzn1.oa2-cs.v1.xxx',              // client_secret
)->clientCredentials('scope');

$access_token = $response['response']['access_token'];

Restricted Data Token

Use the access token received from Login With Amazon;

use Zerotoprod\Spapi\Tokens;
use \Zerotoprod\SpapiRdt\SpapiRdt;

// Use the SpapiRdt API to get an RDT (Restricted Data Token)
$response = SpapiRdt::from(
    'access_token',                     // Access token received from LWA
    'amzn1.sp.solution.xxx'             // Target Application
)
    ->orders()
    ->getOrder(
        '123-1234567-1234567',           // Amazon Order Id
        ['buyerInfo', 'shippingAddress'] // Restricted Data Elements to Access
);

$access_token = $response['response']['restrictedDataToken'];

Spapi

Instantiate the Spapi from an access_token generated from Login With Amazon or a Restricted Data Token

use Zerotoprod\Spapi\Spapi;

$Spapi = Spapi::from($access_token);

Orders Api

Programmatically retrieve order information.

Use the Orders Selling Partner API to programmatically retrieve order information. With this API, you can develop fast, flexible, and custom applications to manage order synchronization, perform order research, and create demand-based decision support tools.

getOrders

Returns orders that are created or updated during the specified time period. If you want to return specific types of orders, you can apply filters to your request. NextToken doesn't affect any filters that you include in your request; it only impacts the pagination for the filtered orders response.

use Zerotoprod\Spapi\Spapi;

// Access the orders api and get orders.
$Orders = Spapi::from($access_token)
    ->orders()
    ->getOrders(
      ['MarketplaceIds']
      'CreatedAfter'
      'CreatedBefore'
      'LastUpdatedAfter'
      'LastUpdatedBefore'
      '[OrderStatuses']
      ['FulfillmentChannels']
      ['PaymentMethods']
      'BuyerEmail'
      'SellerOrderId'
      MaxResultsPerPage
      ['EasyShipShipmentStatuses']
      ['ElectronicInvoiceStatuses']
      'NextToken'
      ['AmazonOrderIds']
      'ActualFulfillmentSupplySourceId'
      'IsISPU'
      'StoreChainStoreId'
      'EarliestDeliveryDateBefore'
      'EarliestDeliveryDateAfter'
      'LatestDeliveryDateBefore'
      'LatestDeliveryDateAfter'
      ['curl_options'],
);

// Access the orders.
echo $Orders['response']['payload']['Orders'][0]['AmazonOrderId']

// Access errors.
echo $Orders['response']['errors']['code'];

getOrder

Returns the order that you specify.

use Zerotoprod\Spapi\Spapi;

$Order = Spapi::from($access_token)
    ->orders()
    ->getOrder('111-5803802-7417822', ['curl_options']);

// Access the order.
echo $Order['response']['payload']['AmazonOrderId'];

// Access errors.
echo $Order['response']['errors']['code'];

getOrderBuyerInfo

Returns buyer information for the order that you specify.

use Zerotoprod\Spapi\Spapi;

$OrderBuyerInfo = Spapi::from($access_token)
    ->orders()
    ->getOrderBuyerInfo('111-5803802-7417822', ['curl_options']);

// Access the buyer info.
echo $OrderBuyerInfo['response']['payload']['BuyerName'];

// Access errors.
echo $OrderBuyerInfo['response']['errors']['code'];

getOrderAddress

Retrieves the shipping address for the specified order

use Zerotoprod\Spapi\Spapi;

$OrderBuyerInfo = Spapi::from($access_token)
    ->orders()
    ->getOrderAddress('111-5803802-7417822', ['curl_options']);

// Access the buyer info.
echo $OrderBuyerInfo['response']['payload']['BuyerName'];

// Access errors.
echo $OrderBuyerInfo['response']['errors']['code'];

getOrderItems

Returns detailed order item information for the order that you specify. If NextToken is provided, it's used to retrieve the next page of order items.

Note: When an order is in the Pending state (the order has been placed but payment has not been authorized), the getOrderItems operation does not return information about pricing, taxes, shipping charges, gift status or promotions for the order items in the order. After an order leaves the Pending state (this occurs when payment has been authorized) and enters the Unshipped, Partially Shipped, or Shipped state, the getOrderItems operation returns information about pricing, taxes, shipping charges, gift status and promotions for the order items in the order.

use Zerotoprod\Spapi\Spapi;


$Order = Spapi::from($access_token)
    ->orders()
    ->getOrderItems('111-5803802-7417822', ['curl_options']);

// Access the order.
echo $Order['response']['payload']['OrderItems'][0]['SellerSKU'];

// Access errors.
echo $Order['response']['errors']['code'];

Examples

Get an order with a Restricted Data Token

use Zerotoprod\SpapiLwa\SpapiLwa;
use Zerotoprod\Spapi\Spapi;
use \Zerotoprod\SpapiRdt\SpapiRdt;

$lwa = SpapiLwa::from('amzn1.application-oa2-client.xxx','amzn1.oa2-cs.v1.xxx')
    ->refreshToken('Atzr|xxx');

$rdt = SpapiRdt::from($lwa['response']['access_token'],'amzn1.sp.solution.xxx')
    ->orders()
    ->getOrder('123-1234567-1234567', ['buyerInfo', 'shippingAddress']);

$response = Spapi::from($rdt['response']['restrictedDataToken'])
    ->orders()
    ->getOrder('111-5803802-7417822');

$Order = $response['response']['payload'];

Testing

Basic Testing

The package provides a robust testing framework using the SpapiFake class. This allows you to mock API responses without making actual HTTP requests.

use Zerotoprod\Spapi\Support\Testing\SpapiFake;
use Zerotoprod\SpapiOrders\Support\Testing\SpapiOrdersResponseFactory;

// Mock the Spapi response
SpapiFake::fake(
    SpapiOrdersResponseFactory::factory()
        ->set('response.payload', [
            'AmazonOrderId' => '123-1234567-1234567'
        ])
        ->make()
);

// Use the API as normal
$Spapi = Spapi::from('access_token');
$response = $Spapi->orders()->getOrder('123-1234567-1234567');

Testing with Authentication Flow

For testing the complete authentication flow, you'll need to mock both LWA (Login with Amazon) and RDT (Restricted Data Token) responses:

use Zerotoprod\SpapiLwa\Support\Testing\SpapiLwaFake;
use Zerotoprod\SpapiLwa\Support\Testing\SpapiLwaResponseFactory;
use Zerotoprod\SpapiRdt\Support\Testing\SpapiRdtFake;
use Zerotoprod\SpapiRdt\Support\Testing\SpapiRdtResponseFactory;
use Zerotoprod\SpapiLwa\SpapiLwa;
use Zerotoprod\SpapiTokens\SpapiTokens;
use Zerotoprod\SpapiRdt\SpapiRdt;

// Mock LWA response
SpapiLwaFake::fake(
    SpapiLwaResponseFactory::factory()
        ->asRefreshTokenResponse()
        ->make()
);

// Mock RDT response
SpapiRdtFake::fake(
    SpapiRdtResponseFactory::factory()->make()
);

// Get access token (in production code)
$access_token = SpapiLwa::from('client_id', 'client_secret')
    ->refreshToken('refresh_token');

// Get RDT token (in production code)
$rdt = SpapiRdt::from(
    SpapiTokens::from(
        $access_token['response']['access_token'],
        'app'
    )
)->orders()->getOrder('order-id')['response']['restrictedDataToken'];

// Mock Spapi response
SpapiFake::fake(
    SpapiOrdersResponseFactory::factory()
        ->set('response.payload', ['order_data'])
        ->make()
);

// Make the API call (in production code)
$Spapi = Spapi::from($rdt);
$Order = $Spapi->orders()->getOrder('order-id');

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page if you want to contribute.

  1. Fork the repository.
  2. Create a new branch (git checkout -b feature-branch).
  3. Commit changes (git commit -m 'Add some feature').
  4. Push to the branch (git push origin feature-branch).
  5. Create a new Pull Request.