Developer notes

Technical reference for developers who customize Walmart Marketplace Connector.

Add-on identity

Item	Value
Add-on id	kv_walmart
Function prefix	fn_kv_walmart_
Language variables	kv_walmart.*
CSS scope	.kv-walmart
PHP namespace	Tygh\Addons\KvWalmart
Preset	marketplace (generated by kv new --kind integration)

Structure

Class	Role
Client\BaseClient	HTTP (cURL, TLS verification, timeouts), JSON, error mapping, masked logging
Client\Api	Walmart Marketplace API calls: client credentials token (POST /v3/token, Basic id:secret, cached below its 15 minute expiry), WM_SEC.ACCESS_TOKEN + WM_QOS.CORRELATION_ID (new GUID per call) + WM_SVC.NAME on every call, sandbox (sandbox.walmartapis.com + WM_SANDBOX: v2) and production hosts, Orders (list, get, acknowledge, ship, cancel), Returns (read), Inventory, Price, Feeds (MP_ITEM_MATCH, feed status), throttling headers
Drivers\Walmart\Driver	Implements Hub\DriverInterface: one pseudo category, offers by feed, per-SKU inventory and price calls, order polling with acknowledge, shipment and cancel, returns read
Drivers\Walmart\Mapper	Pure translation (no HTTP): hub listing to MPItem, feed status to batch result, Walmart order to the hub order shape (line statuses to one order status, charges to prices), shipment and cancellation bodies, return orders to claims
Client	Client per company, the connection test
Accounts, Secret	Credentials (test and live) sealed with AES-256-GCM; one account per store owner or per vendor
Config, Access	Settings, owner mode, who may see and manage what
Queue, Jobs, JobException	Job queue: back-off 5 min / 15 min / 1 h / 3 h / 12 h, per-job isolation, overlap lock; handlers in Jobs::handle(), recurring work in Jobs::schedule()
Log	Event log with masking, filters, CSV, retention
Webhook	Scaffold endpoint (signature check, event ids); not used, the hub polls Walmart

Database tables

Table	Purpose
?:kv_walmart_accounts	Credentials per company (secrets sealed), last connection check, token cache
?:kv_walmart_log	Log
?:kv_walmart_jobs	Queue
?:kv_walmart_product_map, ?:kv_walmart_order_map	Product mapping and imported orders
?:kv_walmart_category_map, ?:kv_walmart_attr_map, ?:kv_walmart_options	Category mapping, attribute mapping (not used by Walmart), rules
?:kv_walmart_batches, ?:kv_walmart_cache, ?:kv_walmart_returns	Open listing batches, reference cache, return orders

Hooks used

PHP: update_product_post, delete_product_post (mark mapped products for the next push) and init_templater_post. Backend template hooks only add the license badge and styles.

Walmart specifics

• Walmart US only in 1.0 (Client\Api::country()); Canada and Mexico use other hosts and specs and are not part of this version.
• SKU on Walmart = the barcode of the product map. The GTIN is that barcode as GTIN-14 (8, 12, 13 and 14 digit codes, left padded with zeros). Other values never leave: the product shows a readable error.
• Offers: one POST /v3/feeds?feedType=MP_ITEM_MATCH with an inline JSON body (MPItemFeedHeader: businessUnit WALMART_US, locale, 5.x item spec version; MPItem: sku, productIdentifiers GTIN, condition New, price, ShippingWeight). The answer is a feed id; the batch stays open until GET /v3/feeds/{id}?includeDetails=true reports PROCESSED, then each SKU is SUCCESS or carries Walmart’s ingestion errors. The item spec version can be overridden per account (Connection page, Advanced).
• Stock: PUT /v3/inventory?sku= (unit EACH, default ship node). Price: PUT /v3/price (BASE, USD). Both one call per SKU, spaced by Client\Api::$pace. A SKU Walmart does not know is an item error; throttling, token and server errors are retried by the job.
• Orders: GET /v3/orders with lastModifiedStartDate and limit; list.meta.nextCursor is the query string of the next page and is followed. Lines whose only status is Cancelled are left out; an order whose lines are all cancelled is imported as cancelled. Order status = work left (Created / Acknowledged) wins, then Shipped, then Delivered. Prices are the PRODUCT charge of a line divided by its quantity. New orders are acknowledged (POST /v3/orders/{po}/acknowledge) when they are read.
• Hub order id = purchaseOrderId, hub order number = customerOrderId, line id = lineNumber.
• Shipment: POST /v3/orders/{po}/shipping with trackingInfo (known carriers UPS, USPS, FedEx, DHL, OnTrac by name; any other carrier as otherCarrier with the tracking URL, built from the tracking URL template). Method code is Standard. Cancel: POST /v3/orders/{po}/cancel with one of the five documented reasons.
• Returns: GET /v3/returns (read only); refunds are issued in Seller Center.
• Throttling: Walmart uses token buckets per API. x-current-token-count and X-Next-Replenishment-Time are read from every answer; a drained bucket is waited for (at most 5 seconds), a 429 answer is retryable and its message names the time the next call is possible.
• The access token is sent as the plain value in WM_SEC.ACCESS_TOKEN, as in Walmart’s request examples (one page of the documentation shows a Basic prefix; the reference examples do not).

Test the HTTP layer without the provider

The base URL can be overridden for tests in config.local.php (development only):

$config['kv_walmart_base_url'] = 'http://127.0.0.1:11963';

node tests/mock-server/server.js 11963 starts a local stand-in of the Walmart API built from the documentation; node tests/e2e/e2e.mjs runs the HTTP end-to-end test against it; php tests/unit.php runs the unit tests.

Template overrides

Admin templates live in design/backend/templates/addons/kv_walmart/. Do not edit them in a store; they are replaced on update.