Walmart Commerce Technologies (WCT) provides Marketplace Orders Hub REST API for retailers interested in the programmatic setup of online stores as well as the creation, publishing, and maintenance of store catalogs. You can use the REST API to programmatically access and interact with Hub store and catalog services and resources.
The Hub REST API offers operations for the curation and distribution of catalog listing and enhancement information. To access these operations, you construct and send HTTP requests to endpoints using standard REST methods.
The Hub REST API also offers the programmatic integration of order management, including order creation, update, and notifications.
Requirements
Use of the Hub REST API requires the following:
| Requirement | Description |
WM_CONSUMER.ID | The Walmart Consumer ID of the tenant must be included in the header of every request. Example |
Architecture
Marketplace Orders Hub extends Walmart Store Assist with support for the establishment and operation of online marketplaces and stores. The Hub combines sales channels, facilitates the creation and distribution of stores, and provides increased access to an array of marketplaces.
Your integration with Marketplace Orders Hub is built on the following core components.
Catalog
A catalog contains listings that collectively describe the items in your inventory. Listings have static attributes like name and UPC code, and dynamic attributes like price or availability. A catalog is built from both static and dynamic information. XLS-format files separately supply the static listing and dynamic attributes information. You can use the Publish a catalog operation to programmatically upload and request the processing of a catalog or dynamic attributes file. The Hub provides a user interface for the manual upload of catalog and dynamic attributes files.
Store
A store is an online instance of your retail enterprise. The REST API represents a store as a JSON object. You can programmatically create a store by using the Create stores operation to process an array of store objects. Stores are manually created by specifying and uploading a store-formatted spreadsheet file for processing. You can deploy one store or many to one marketplace or multiple.
Order
An order is a list of items that a customer selects from a catalog. Orders are generated from an order management system (OMS) and managed as an array of catalog items. In this case, the ordered items are contained in a JSON array with information that includes whether the order was requested for pickup or delivery. You can programmatically create or cancel an order by using the Create or cancel an order operation.
Operations
The REST API provides operations in the following functional areas.
Authentication
| Operation | HTTP method and endpoint | Description |
|---|---|---|
| Create an access token | POST /oauth/v1/token | Create an access token. An access token is required to make a request. |
Store management
| Operation | HTTP method and endpoint | Description |
|---|---|---|
| Create stores | POST /v1/stores | Create one or more stores based on the specified attributes. |
| Update stores | PUT /v1/stores | Update the attributes of a store. |
Catalog management
| Operation | HTTP method and endpoint | Description |
|---|---|---|
| Publish a catalog | POST /v1/catalog | Initiate the process of publishing or updating a catalog with the specified catalog listings and dynamic attributes. |
| Catalog bulk update | PUT /v1/catalog | Initiate an asynchronous process to create or update a catalog, including catalog listings and dynamic attributes. |
| Catalog publish webhook | POST /v1/<catalog_notification_event> | Provide notification that a catalog was published to Marketplace. Use of this webhook requires the integrator to provide an endpoint. |
| Verification | GET /v1/catalog/{reference-id} | Check the status of the menu update process for a specific reference-id. |
Order management
| Operation | HTTP method and endpoint | Description |
|---|---|---|
| Create or cancel an order | POST /vi/orders | Create or cancel an order associated with a specific customer and store. |
| Update order status | PUT /v1/orders/{order-id} | Update the status of an order. |
| Order notification webhook | POST /v1/<order_notification_event> | Notify recipients that a new order was created or updated in Marketplace Orders Hub. Use of this webhook requires the integrator to provide an endpoint. |
| Create a delivery quote | POST /v1/deliveries/quotes | Initiate the process of quote creation. |
Rate limits
Rate limits restrict the number of API calls that are allowed for each endpoint each minute. Marketplace Orders Hub has generally established rate limits of 10 requests per minute for each endpoint.
Integrations that exceed the rate limit receive status code HTTP 429 with an error message. If your integration requires adjustments, contact your account representative.