README

This package provides Walmart Marketplace OAuth 2.0 support for the PHP League's OAuth 2.0 Client.

This package is compliant with PSR-1, PSR-2 and PSR-4. If you notice compliance oversights, please send a patch via pull request.

Features

• Client Credentials Grant - For sellers accessing their own Walmart Marketplace account
• Authorization Code Grant - For solution providers acting on behalf of sellers
• Refresh Token Grant - Automatically refresh expired access tokens
• Multi-Marketplace Support - US, Canada, and Mexico marketplaces

Requirements

To use this package, you will need a Walmart client ID and client secret. These are referred to as {walmart-client-id} and {walmart-client-secret} in the documentation.

For Sellers

Follow the Get started as a seller guide to create your API credentials.

For Solution Providers

Follow the Get started as a Solution Provider guide to register your application.

Installation

To install, use composer:

composer require lulacanci/oauth2-walmart

Usage

Option 1: Client Credentials Grant (Sellers)

Use this when your application is accessing your own Walmart seller account only.

require __DIR__ . '/vendor/autoload.php';

use Lulacanci\OAuth2\Client\Provider\Walmart;
use Lulacanci\OAuth2\Client\Provider\WalmartMarketplace;

$provider = new Walmart(
    [
        'clientId'     => '{walmart-client-id}',
        'clientSecret' => '{walmart-client-secret}',
    ],
    [],
    WalmartMarketplace::US // or CANADA, MEXICO
);

// Get access token using client credentials
$token = $provider->getAccessTokenWithClientCredentials();

echo 'Access Token: ' . $token->getToken() . "\n";
echo 'Expires in: ' . $token->getExpires() . " seconds\n";

// Use the token with Walmart APIs
// Include it in the WM_SEC.ACCESS_TOKEN header

Option 2: Authorization Code Grant (Solution Providers)

Use this when your application acts on behalf of other sellers. The seller must authorize your app first.

require __DIR__ . '/vendor/autoload.php';

use Lulacanci\OAuth2\Client\Provider\Walmart;
use Lulacanci\OAuth2\Client\Provider\WalmartMarketplace;

session_start();

$clientId = '{walmart-client-id}';
$clientSecret = '{walmart-client-secret}';
$redirectUri = 'https://example.com/callback-url';

$provider = new Walmart(
    [
        'clientId'     => $clientId,
        'clientSecret' => $clientSecret,
        'redirectUri'  => $redirectUri,
    ],
    [],
    WalmartMarketplace::US
);

if (empty($_GET['code'])) {
    // Step 1: Redirect to Walmart authorization URL
    // The seller will be prompted to log in and authorize your app
    
    $authorizationUrl = $provider->getAuthorizationUrl();
    $_SESSION['oauth2state'] = $provider->getState();
    
    header('Location: ' . $authorizationUrl);
    exit;
    
} elseif (empty($_GET['state']) || ($_GET['state'] !== $_SESSION['oauth2state'])) {
    // State is invalid, possible CSRF attack in progress
    unset($_SESSION['oauth2state']);
    exit('Invalid state');
    
} else {
    // Step 2: Exchange authorization code for access token + refresh token
    
    $token = $provider->getAccessToken('authorization_code', [
        'code' => $_GET['code'],
        'redirect_uri' => $redirectUri,
    ]);

    // Store these tokens securely!
    $accessToken = $token->getToken();           // Valid for 15 minutes
    $refreshToken = $token->getRefreshToken();   // Valid for 1 year
    
    echo 'Access Token: ' . $accessToken . "\n";
    echo 'Refresh Token: ' . $refreshToken . "\n";
}

Option 3: Refresh Token Grant

Access tokens expire after 15 minutes. Use the refresh token to get a new access token without requiring user interaction. Refresh tokens are valid for 1 year.

require __DIR__ . '/vendor/autoload.php';

use Lulacanci\OAuth2\Client\Provider\Walmart;
use Lulacanci\OAuth2\Client\Provider\WalmartMarketplace;

$provider = new Walmart([
        'clientId'     => '{walmart-client-id}',
        'clientSecret' => '{walmart-client-secret}',
        'redirectUri'  => 'https://example.com/callback-url',
    ],
    [],
    WalmartMarketplace::US
);

// Use your stored refresh token
$storedRefreshToken = 'your-stored-refresh-token';

$newToken = $provider->getAccessToken('refresh_token', [
    'refresh_token' => $storedRefreshToken,
]);

$accessToken = $newToken->getToken();
// Store the new access token securely

Multi-Marketplace Support

The package supports all Walmart marketplaces:

use Lulacanci\OAuth2\Client\Provider\WalmartMarketplace;

// US Marketplace (default)
$provider = new Walmart($options, [], WalmartMarketplace::US);
// Sets clientType=seller

// Canada Marketplace
$provider = new Walmart($options, [], WalmartMarketplace::CANADA);
// Sets clientType=seller-ca

// Mexico Marketplace
$provider = new Walmart($options, [], WalmartMarketplace::MEXICO);
// Sets clientType=seller-mx

Using the Access Token with Walmart APIs

Include the access token in the WM_SEC.ACCESS_TOKEN header for all Walmart Marketplace API calls:

$client = new GuzzleHttp\Client();

$response = $client->get('https://marketplace.walmartapis.com/v3/items', [
    'headers' => [
        'WM_SEC.ACCESS_TOKEN' => $token->getToken(),
        'WM_SVC.NAME' => 'Walmart Marketplace',
        'WM_QOS.CORRELATION_ID' => uniqid(),
        'Accept' => 'application/json',
    ],
]);

Scopes

Scopes can be set by using the scope parameter when generating the authorization URL:

$authorizationUrl = $provider->getAuthorizationUrl([
    'scope' => ['items', 'orders', 'inventory'],
]);

See the API scopes documentation for available scopes.

Testing

Tests can be run with:

./vendor/bin/phpunit

Or with the watcher:

composer test

Documentation

• Walmart OAuth 2.0 Authorization
• Get an Access Token
• Log in and Authorize App Scope
• API Scopes for Walmart Marketplace

Credits

• Iulian Danaila
• All Contributors

Sponsors

Aureus POS - The Gold Standard Of Bullion & Collectibles Software

License

The MIT License (MIT). Please see License File for more information.