omnibus/amazon API reference

Omnibus\Amazon

AmazonGatewayFactory class

final class AmazonGatewayFactory extends GatewayFactory AmazonGatewayFactory.php:26

options: client_id: '%env(AMAZON_LWA_CLIENT_ID)%' # the SP-API app's Login with Amazon credentials client_secret: '%env(AMAZON_LWA_CLIENT_SECRET)%' refresh_token: '%env(AMAZON_REFRESH_TOKEN)%' # the authorised Amazon Shipping account region: eu # eu, na or fe business_id: AmazonShipping_UK # the shipping business (AmazonShipping_UK, _US, _IN, _IT, _ES, _FR, _SA, _AE, _EG, _JP...) carrier_id: AMZN_UK # the carrier a bare tracking number is tracked with (a label's carrierReference names its own) sandbox: true rates: [...] # optional: configured prices instead of getRates

No pickup points: Amazon Shipping delivers to the door.

Options

Api class

final class Api Api.php:15

Amazon Shipping through the Selling Partner API (shipping v2): a Login with Amazon refresh token exchanged for an access token, then the x-amz-access-token header on sellingpartnerapi-<region>.amazon.com.

const LWA = 'https://api.amazon.com/auth/o2/token'

const ENDPOINTS = ['eu' => 'https://sellingpartnerapi-eu.amazon.com', 'na' => 'https://sellingpartnerapi-na.amazon.com', 'fe' => 'https://sellingpartnerapi-fe.amazon.com']

public readonly string $region

public readonly ?string $businessId

public readonly bool $sandbox

public readonly string $carrierId

The carrier a bare tracking number is tracked with (a label's carrierReference names its own)

Api::__construct()

public function __construct(readonly HttpClientInterface $http, readonly string $clientId, readonly string $clientSecret, readonly string $refreshToken, public readonly string $region = 'eu', public readonly ?string $businessId = null, public readonly bool $sandbox = false, readonly int $timeout = 20, public readonly string $carrierId = 'AMZN_UK')

Api::base()

public function base(): string

Api::call()

public function call(string $method, string $path, ?array $body = null, array $query = []): array

Returns

the payload

Mapping class

final class Mapping Mapping.php:11

Shipping v2's shapes for ours.

Mapping::reference()

public static function reference(string $shipmentId, string $carrierId, string $trackingId): string

The label's carrierReference: what getTracking (the rate's carrierId, the trackingId) and cancelShipment (the shipmentId) need, which the tracking id alone does not give.

Mapping::parseReference()

public static function parseReference(string $value): array

Returns

a carrierReference read, or [] for a bare number

Mapping::address()

public static function address(Address $a): array

Mapping::shipDate()

public static function shipDate(Shipment $s): string

The ship date in UTC, as its "Z" says (Shipment::$shippingDate in any time zone, else now).

Mapping::package()

public static function package(Parcel $p, Shipment $s, int $i): array

Mapping::status()

public static function status(?string $code, ?string $description = null): TrackingStatus

Omnibus\Amazon\Action

CancelAction class

final class CancelAction implements ActionInterface, ApiAwareInterface CancelAction.php:18

PUT /shipping/v2/shipments/{shipmentId}/cancel: the shipment id from the label's carrierReference; a bare value is taken as the shipment id itself (not a tracking id: Amazon finds no shipment by it).

CancelAction::__construct()

public function __construct()

CancelAction::supports()

public function supports(Request $request): bool

CancelAction::execute()

public function execute(Request $request): void

RatingAction class

final class RatingAction implements ActionInterface, ApiAwareInterface RatingAction.php:15

POST /shipping/v2/shipments/rates: every service Amazon offers, priced; the rate id travels in the Rate's service for purchase.

RatingAction::__construct()

public function __construct()

RatingAction::supports()

public function supports(Request $request): bool

RatingAction::execute()

public function execute(Request $request): void

ShippingAction class

final class ShippingAction implements ActionInterface, ApiAwareInterface ShippingAction.php:21

getRates then purchaseShipment: the rate matching the service (a serviceId; none: the cheapest) bought with a label (PDF 4x6; ZPL with option label_format).

The label's carrierReference keeps the shipment id and the rate's carrier id, which tracking and cancellation need.

ShippingAction::__construct()

public function __construct()

ShippingAction::supports()

public function supports(Request $request): bool

ShippingAction::execute()

public function execute(Request $request): void

TrackingAction class

final class TrackingAction implements ActionInterface, ApiAwareInterface TrackingAction.php:19

GET /shipping/v2/tracking: the package's event history, oldest first. Given a label's carrierReference, the carrier of the rate bought; given a bare tracking id, the carrier_id option.

TrackingAction::__construct()

public function __construct()

TrackingAction::supports()

public function supports(Request $request): bool

TrackingAction::execute()

public function execute(Request $request): void