A PHP client for Walmart's Marketplace, Content Provider, Drop Ship Vendor, and Warehouse Supplier APIs.

0.1.0 2023-05-26 21:25 UTC

This package is auto-updated.

Last update: 2023-06-01 23:48:42 UTC



Total downloads Latest stable version License

Walmart API for PHP

A PHP library for connecting to Walmart's Marketplace, Drop Ship Vendor, Content Provider, and Warehouse Supplier APIs, for the US, Canada, and Mexico.

Related packages

This package is developed and maintained by Highside Labs. If you need support integrating with Walmart's (or any other e-commerce platform's) APIs, we're happy to help! Shoot us an email at hi@highsidelabs.co.

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!


  • Supports all Walmart API operations for Marketplace Sellers, Drop Ship Vendors, Content Providers, and Warehouse Suppliers as of 5/26/2023 (see here for links to documentation for all calls)
  • Supports the United States, Canada, and Mexico marketplaces
  • Automatically handles all forms of authentication used by Walmart (basic auth, access tokens, and request signatures) with minimal configuration


composer require highsidelabs/walmart-api

Why make this library?

The existing Walmart client libraries for PHP are either incomplete, outdated, or both. This library aims to provide a complete, up-to-date, and easy-to-use interface for all of Walmart's seller- and supplier-side APIs – not just the Marketplace API (which is the only one that other packages cover). We built it to scratch our own itch.

Table of Contents

Getting Started


You need a couple things to get started:

  • A Walmart Seller and/or Supplier account
  • A Walmart Client ID/Client secret pair, and/or a Walmart Consumer ID and private key


The Configuration constructor takes three arguments, which cover all the credentials you need to access the Walmart APIs:

  • A client ID
  • A client secret
  • An optional array of additional configuration parameters
use Walmart\Configuration;

$clientId = '<YOUR CLIENT ID>';
$clientSecret = '<YOUR CLIENT SECRET>';
$config = new Walmart\Configuration($clientId, $clientSecret);

If you are a Marketplace Seller selling in the US (which is likely true of most people using this API), that's all the configuration you need to do to start making calls to the Marketplace API. If you want to call the Drop Ship Vendor, Content Provider, or Warehouse Supplier APIs, or if you sell goods outside the US and need to make calls to the Marketplace API for, you'll need to provide additional configuration parameters, which are detailed in the Configuration section below.

Basic Usage

Once you've created an instance of the Configuration class, you can start making calls to the Walmart APIs. The Walmart class provides an easy interface for retrieving an instance of any API class, from any of the four major API categories (Marketplace, Drop Ship Vendor, Content Provider, Warehouse Supplier). For example, to retrieve an instance of the Marketplace Authentication API and check the status of your authentication token, you can do the following:

use Walmart\Configuration;
use Walmart\Walmart;

$config = new Walmart\Configuration($clientId, $clientSecret);
$authApi = Walmart::marketplace($config)->auth();

// $authApi is an instance of Walmart\Apis\MP\US\AuthenticationApi
$tokenDetail = $authApi->getTokenDetail();
$tokenStatus = $tokenDetail->isValid;

Similarly, the other API categories can be accessed via the Walmart::dropShipVendor(), Walmart::contentProvider(), and Walmart::warehouseSupplier() methods.



The Configuration class is used to configure the client library. It takes three arguments:

  • $clientId: Your Walmart Client ID
  • $clientSecret: Your Walmart Client Secret
  • $options: An optional associative array of additional configuration parameters. Valid options are:
    • country: The country you are selling in. One of Country::US, Country::CA, or Country::MX. Defaults to US.
    • consumerId: Your Walmart Consumer ID. Required if you are making requests to endpoints that use signature-based auth (see the Authorization section)
    • privateKey: Your Walmart private key. Ditto the requirements for the consumerId option.
    • accessToken: An instance of Walmart\AccessToken, containing an access token and its expiration time. If provided, this will be used instead of the client ID and secret to authenticate API calls, until the token expires. This is useful if you want to reuse an access token that you've already retrieved from Walmart. More details on access token auth below.

If you try to instantiate an instance of an API class that is not supported in the country you've specified, an exception will be thrown.

Using API classes

The API classes are divided into four categories: Marketplace, Drop Ship Vendor, Content Provider, and Warehouse Supplier. Each category has its own namespace, and each country has its own sub-namespace. For example, the Marketplace APIs for the US are located in the Walmart\Apis\MP\US namespace, and the Drop Ship Vendor APIs for Canada are located in the Walmart\Apis\DSV\CA namespace.

To create an instance of an API class, start by using the Walmart::marketplace(), Walmart::dropShipVendor(), Walmart::contentProvider(), and Walmart::warehouseSupplier() methods. All four methods take a single argument: an instance of Walmart\Configuration. Each of those methods returns a helper class that provides access to all the API classes in that category for the country you've specified in the Configuration object (US by default). See the Supported API segments section below for a list of all the APIs supported by this library, organized by API category.

Once you have an instance of an API class, you can call any of the endpoint methods defined in the documentation. The API class documentation is divided by API category and then country, because the same API may have different endpoints and/or parameters in different countries. Make sure you're looking at the correct documentation for the country you're actually selling in!

Some endpoints have a LOT of parameters. If you're using PHP 8 or later, you can use named arguments to make your code more readable. For instance, the Marketplace Feeds API in the US has a getAllItems call that takes up to 7 parameters. If you only want to pass some of them, you can do this:

use Walmart\Configuration;
use Walmart\Walmart;

$config = new Configuration($clientId, $clientSecret);
$itemsApi = Walmart::marketplace($config)->items();

$response = $itemsApi->getAllItems(
    sku: '1234567890',
    lifecycleStatus: 'PUBLISHED',
    variantGroupId: '9876543210'

Instead of this:

use Walmart\Configuration;
use Walmart\Walmart;

$config = new Configuration($clientId, $clientSecret);
$itemsApi = Walmart::marketplace($config)->items();

$response = $itemsApi->getAllItems(
    null,  // $nextCursor
    '1234567890',  // $sku,
    null,  // $offset
    null,  // $limit
    'PUBLISHED',  // $lifecycleStatus
    null,  // $publishedStatus
    '9876543210'  // $variantGroupId

API methods often take model classes as parameters, and return them as API responses – let's look at how model classes work.

Using model classes

In order to represent the various data structures that the APIs ingest and return, this library uses model classes. Each model class represents a single data structure, and has a constructor that takes an associative array of data. The model class documentation is divided by API category, country, and API class. Documentation for each model class is nested inside the docs/Models folder corresponding to the model class's location in the src/Models folder. For instance, the response model for the Marketplace Authorization API's getTokenDetail method in the US is Walmart\Models\MP\US\Authorization\TokenDetailResponse, and the docs are at docs/Models/MP/US/Authorization/TokenDetailResponse.md.


Walmart uses three different forms of authentication for its APIs: basic auth, access tokens, and request signatures. This library handles all three automatically, so you shouldn't have to think about them much...but if you're curious about how it works, read on.

Basic auth

This the standard, simplest form of authentication. It uses the Walmart client ID and client secret that are passed to the Configuration constructor in order to generate an authorization header value. It's also used to generate an access token if necessary, which is why these are the two required parameters for the Configuration constructor.

Access token auth

For a lot of the Marketplace API, Walmart uses access token authentication. The access token is a short-lived token (15min) that is generated by Walmart with the client ID and client secret, and then used to authenticate API calls. This library automatically handles the generation and renewal of access tokens, so you don't have to worry about it. If you want to reuse an access token that you've already retrieved from Walmart, you can pass it to the Configuration constructor via the accessToken option.

Request signature auth

For most of the rest of the APIs aside from the Marketplace API, Walmart uses request signature auth. This is just another value that is passed as a header, and it is generated using the request method and path, a timestamp, and your consumer ID and private key. If you're making requests that involve signature auth, you need to pass the privateKey and consumerId options to the Configuration constructor's options array.

Debug mode

To get debugging output when you make an API request, you can call $config->setDebug(). By default, debug output goes to stdout via php://output, but you can redirect it a file with $config->setDebugFile('log/file/path.log').

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

use Walmart\Configuration;

$config = new Configuration($clientId, $clientSecret);
// To redirect debug info to a file:

Supported API segments

This is an exhaustive list of all the APIs supported by this library, organized by API category. Not all APIs are supported in all countries. For more information on each API, see the Walmart Developer Portal.


  • Authentication API: Walmart::marketplace($config)->auth() (MX, US)
  • Events API: Walmart::marketplace($config)->events() (CA only)
  • Feeds API: Walmart::marketplace($config)->feeds() (CA, MX, US)
  • Fulfillment API: Walmart::marketplace($config)->fulfillment() (US)
  • Insights API: Walmart::marketplace($config)->insights() (US only)
  • International Shipping API: Walmart::marketplace($config)->internationalShipping() (CA, MX)
  • Inventory API: Walmart::marketplace($config)->inventory() (CA, MX, US)
  • Items API: Walmart::marketplace($config)->items() (CA, MX, US)
  • Lag Time API: Walmart::marketplace($config)->lagTime() (US only)
  • Listing Quality API: Walmart::marketplace($config)->listingQuality() (US only)
  • Notifications API: Walmart::marketplace($config)->notifications() (US only)
  • On Request Reports API: Walmart::marketplace($config)->onRequestReports() (US only)
  • Orders API: Walmart::marketplace($config)->orders() (CA, MX, US)
  • Prices API: Walmart::marketplace($config)->prices() (CA, MX, US)
  • Promotions API: Walmart::marketplace($config)->promotions() (CA, US)
  • Reports API: Walmart::marketplace($config)->reports() (CA, MX, US)
  • Returns API: Walmart::marketplace($config)->returns() (MX, US)
  • Rules API: Walmart::marketplace($config)->rules() (US only)
  • Settings API: Walmart::marketplace($config)->settings() (US only)
  • Utilities API: Walmart::marketplace($config)->utilities() (US only)

Drop Ship Vendor

Note: The Drop Ship Vendor APIs are currently only available in the US.

  • Cost API: Walmart::dropShipVendor($config)->cost()
  • Feeds API: Walmart::dropShipVendor($config)->feeds()
  • Inventory API: Walmart::dropShipVendor($config)->inventory()
  • Items API: Walmart::dropShipVendor($config)->items()
  • Lag Time API: Walmart::dropShipVendor($config)->lagTime()
  • Orders API: Walmart::dropShipVendor($config)->orders()
  • Reports API: Walmart::dropShipVendor($config)->reports()

Content Provider

Note: The Content Provider APIs are currently only available in the US.

  • Feeds API: Walmart::contentProvider($config)->feeds()

Warehouse Supplier

Note: The Warehouse Supplier APIs are currently only available in the US.

  • Feeds API: Walmart::warehouseSupplier($config)->feeds()
  • Items API: Walmart::warehouseSupplier($config)->items()
  • Reports API: Walmart::warehouseSupplier($config)->reports()