Tích hợp API Walmart Marketplace: Hướng dẫn cho nhà phát triển 2026

API Walmart Marketplace bao gồm những gì?

Walmart Marketplace API là tập hợp các REST endpoint trên marketplace.walmartapis.com, cho phép người bán hoặc Solution Provider được phê duyệt thay mặt người bán quản lý sản phẩm, tồn kho, giá, đơn hàng, hàng trả lại, báo cáo và thông báo trên Walmart.com mà không cần mở Seller Center. Hướng dẫn này tập trung vào cổng phát triển Marketplace tại Mỹ; các cổng dành cho Canada, Mexico và Chile là những hệ thống riêng.

Một hệ thống tích hợp hoàn chỉnh gồm bốn phần chính. Thứ tự dưới đây là thứ tự nên triển khai, có đôi chút khác với thứ tự trong phần tổng quan của Walmart.

Đơn hàng được đặt trước tồn kho có chủ đích. Ngay khi bạn đẩy số lượng dương cho một sản phẩm đang hoạt động, đơn hàng có thể phát sinh. Một hệ thống đã đăng sản phẩm và cập nhật tồn kho nhưng chưa thể xác nhận, giao đơn hàng sẽ rất dễ dẫn đến bán vượt tồn. Vì vậy, hãy giữ số lượng ở mức 0 cho đến khi quy trình đơn hàng hoạt động trọn vẹn. Báo cáo, insights, quảng cáo, hàng trả lại và Walmart Fulfillment Services (WFS) có thể triển khai sau.

Tích hợp trực tiếp hay trở thành Solution Provider được phê duyệt?

Hướng triển khai phụ thuộc vào tài khoản Walmart mà mã nguồn của bạn truy cập. Lựa chọn này ảnh hưởng đến thông tin xác thực, quy trình cấp quyền và cả giới hạn request.

Tài liệu của Walmart nêu rằng Solution Provider mới phải dùng OAuth 2.0, không dùng mô hình delegated access cũ. Giới hạn request được phân bổ theo người bán; các request trực tiếp của người bán và request từ ứng dụng Solution Provider được phê duyệt được tính riêng. Nếu một provider vận hành nhiều ứng dụng, mỗi ứng dụng sẽ có hạn mức riêng.

Nếu Walmart chỉ là một trong nhiều kênh bạn cần đồng bộ, dịch vụ tích hợp marketplace của chúng tôi hỗ trợ Walmart cùng Amazon SP-API, eBay, Etsy, Temu, Shein và Shopee, bao gồm listing, tồn kho, đơn hàng và tracking.

Xác thực Walmart Marketplace API (OAuth 2.0)

Mọi request đến Marketplace API đều phải gửi access token OAuth 2.0 trong header WM_SEC.ACCESS_TOKEN, đồng thời đặt WM_SVC.NAME là Walmart Marketplace. Token được cấp từ Token API tại https://marketplace.walmartapis.com/v3/token và có hiệu lực trong 15 phút; response trả về expires_in là 900 giây. Token API hỗ trợ ba loại grant: client credentials, authorization code và refresh token.

Client ID và Client Secret không phải Consumer ID và Private Key trước đây. Phương thức cũ yêu cầu ký từng request; OAuth loại bỏ chữ ký và giảm số lượng header. Portal tách riêng Production Keys và Sandbox Keys, đồng thời cho phép bạn xem lại secret bất cứ khi nào cần.

Client dưới đây lưu cache token và làm mới trước một phút. Hãy kiểm tra lại tên header và request lấy token theo tài liệu Token API trước khi đưa vào vận hành, vì đoạn minh họa này được viết dựa trên tài liệu chứ chưa chạy với tài khoản người bán thực tế.

import time
import uuid
import requests

TOKEN_URL = 'https://marketplace.walmartapis.com/v3/token'


class WalmartAuth:
    def __init__(self, client_id, client_secret):
        self.client_id = client_id
        self.client_secret = client_secret
        self._token = None
        self._expires_at = 0.0

    def invalidate(self):
        self._token = None

    def token(self):
        # refresh 60 seconds early so no call starts with a dying token
        if self._token is None or time.time() > self._expires_at - 60:
            resp = requests.post(
                TOKEN_URL,
                auth=(self.client_id, self.client_secret),
                headers={
                    'Accept': 'application/json',
                    'WM_SVC.NAME': 'Walmart Marketplace',
                    'WM_QOS.CORRELATION_ID': str(uuid.uuid4()),
                },
                data={'grant_type': 'client_credentials'},
                timeout=30,
            )
            resp.raise_for_status()
            body = resp.json()
            self._token = body['access_token']
            self._expires_at = time.time() + int(body['expires_in'])
        return self._token

    def headers(self):
        return {
            'WM_SEC.ACCESS_TOKEN': self.token(),
            'WM_SVC.NAME': 'Walmart Marketplace',
            'WM_QOS.CORRELATION_ID': str(uuid.uuid4()),
            'Accept': 'application/json',
        }

Những lỗi thường gặp khi tích hợp xác thực

• Mỗi request dùng một token. Token có hiệu lực 15 phút nên nhiều người dễ lấy token mới cho từng job. Hãy lưu cache; nếu chạy nhiều worker, dùng chung cache hoặc khóa lúc refresh để mười worker không cùng làm mới token.
• Dùng mẫu code lỗi thời. Ít nhất một hướng dẫn inventory hàng loạt vẫn hiển thị header Basic Authorization tạo từ consumer key và secret. Hiện tại tài liệu yêu cầu OAuth, vì vậy mọi mẫu ký request hoặc dùng Consumer ID nên được xem là legacy.
• Retry 401 vô hạn. Khi nhận 401, hãy vô hiệu hóa token và retry một lần. Nếu tiếp tục nhận 401, nguyên nhân có thể là credential sai, nhầm môi trường (sandbox key gọi production) hoặc thiếu scope; lặp lại request sẽ không giải quyết được.
• Không để ý scope. OAuth gắn scope với từng bộ credential và Walmart sẽ từ chối request nằm ngoài scope đó. Credential của người bán có quyền truy cập đầy đủ; credential có scope hẹp sẽ bị từ chối khi gọi chức năng bên ngoài scope.

Giới hạn Walmart API và lỗi 429

Walmart áp dụng giới hạn theo hai cách: giới hạn tần suất request cho từng API, trả về 429 Too Many Requests khi vượt mức; và giới hạn kích thước file theo loại feed, trả về 413 Payload Too Large. Giới hạn sử dụng mô hình token bucket. Mỗi request tiêu tốn một token và bucket được nạp lại theo tốc độ cố định, vì vậy giới hạn 20 request mỗi giờ có thể được bổ sung một request sau mỗi 3 phút thay vì reset vào đầu giờ.

Mỗi response gửi kèm ngân sách còn lại của API trong header x-current-token-count, cùng thời điểm số lượng token tiếp theo tăng lên. Hai trang tài liệu ghi tên header thứ hai khác nhau (X-Next-Replenishment-Time trên trang rate limit và x-next-replenish-time trong FAQ), vì vậy hãy hỗ trợ cả hai cách viết và log đúng giá trị thực tế nhận được.

Dưới đây là các giới hạn mặc định được công bố cho cá nhân và doanh nghiệp nhỏ, lấy từ trang giới hạn request của Walmart. Hãy xem trang này để biết bảng đầy đủ, vì bảng cũng bao gồm endpoint WFS, insights, reports và advertising.

Thiết kế hệ thống để không vượt giới hạn

• Phân bổ ngân sách theo người bán, không theo process. Giới hạn thuộc về tài khoản người bán, vì vậy hệ thống multi-tenant cần một bucket cho mỗi người bán được kết nối. Một bộ throttle toàn cục sẽ làm các shop nhỏ bị thiếu hạn mức hoặc để một shop lớn dùng hết ngân sách của các shop còn lại.
• Lưu cache item spec. Endpoint lấy item spec chỉ cho phép 10 request mỗi phút. Hãy tải mỗi phiên bản spec một lần, lưu lại và validate payload feed cục bộ trước khi gửi.
• Poll feed tiết kiệm, tải error report có chọn lọc. Poll trạng thái có hạn mức rộng 5000 mỗi phút, trong khi error report chỉ có 60 mỗi giờ. Chỉ tải báo cáo khi trạng thái cho thấy có lỗi ở dòng sản phẩm.
• Backoff kèm jitter khi gặp 429. Độ trễ tăng theo cấp số nhân cộng thêm thành phần ngẫu nhiên giúp nhiều worker không retry cùng một thời điểm.

import random
import time
import requests


def call_walmart(auth, method, url, max_attempts=5, **kwargs):
    resp = None
    refreshed = False
    for attempt in range(max_attempts):
        resp = requests.request(
            method, url, headers=auth.headers(), timeout=60, **kwargs
        )
        if resp.status_code == 401 and not refreshed:
            refreshed = True
            auth.invalidate()  # one fresh token per call, then give up
            continue
        if resp.status_code != 429:
            return resp
        # record the remaining budget; the docs spell the second header two ways
        print(
            'walmart throttle',
            resp.headers.get('x-current-token-count'),
            resp.headers.get('X-Next-Replenishment-Time')
            or resp.headers.get('x-next-replenish-time'),
        )
        time.sleep(min(2 ** attempt, 60) + random.random())
    return resp

Thiết lập sản phẩm bằng feed và item spec 5.0

Sản phẩm mới và các cập nhật sản phẩm được gửi qua Bulk Item Setup API, một feed endpoint: bạn POST tới /v3/feeds với tham số feedType và nhận về feed ID. Mỗi request có thể chứa tối đa 10.000 sản phẩm. Walmart khuyến nghị giữ file dưới 25 MB để xử lý nhanh; riêng feed fitment ô tô (FITMENT_ACES và FITMENT_PIES) được phép tối đa 50 MB. Bạn có thể gửi file dưới dạng attachment hoặc đặt JSON payload trong request body.

Nội dung sản phẩm được validate theo item spec và spec này thay đổi khá nhanh. Walmart đã phát hành build 5.0 mới vào 14 tháng 5 năm 2026, một build khác vào 22 tháng 6 năm 2026, rồi công bố phiên bản khuyến nghị mới vào 28 tháng 7 năm 2026, theo thông báo item spec tháng 7 năm 2026 của Walmart. Đó là ba lần phát hành trong chưa đầy 12 tuần, cùng áp dụng cho MP_ITEM, MP_MAINTENANCE, MP_WFS_ITEM và OMNI_WFS.

Điều này dẫn đến hai lưu ý thực tế. Thứ nhất, không hard-code chuỗi phiên bản spec; hãy đọc phiên bản được khuyến nghị trong bảng Item spec reporting and version, tải schema tương ứng và lưu phiên bản cùng mỗi feed gửi đi để có thể truy nguyên lỗi về thay đổi spec. Thứ hai, build tháng 7 bổ sung thuộc tính item_assortment_type cho Collectibles ở thêm 20 loại sản phẩm, nhưng chỉ người bán được phê duyệt tham gia chương trình Collectibles mới được gửi các trường dành riêng cho collectible. Bộ mapper catalog tự động điền mọi thuộc tính tùy chọn có thể tìm thấy sẽ khiến người bán chưa được phê duyệt bị từ chối.

Feed được tiếp nhận trước khi được áp dụng

Response thành công từ POST chỉ cho biết Walmart đã nhận file, không có nghĩa sản phẩm đã live. Kết quả được trả về sau ở cấp từng dòng thông qua Feed Status API. Hãy xây dựng vòng xử lý gồm gửi feed, lưu feed ID, poll trạng thái rồi xử lý kết quả từng sản phẩm: đánh dấu sản phẩm đã publish, đưa lỗi vào hàng đợi sửa và chỉ sau đó mới tải error report. Việc retry toàn bộ feed vì ba dòng bị lỗi sẽ tiêu tốn một lần gửi và gửi lại 9.997 dòng vốn đã đúng.

def submit_feed(auth, feed_type, path):
    url = 'https://marketplace.walmartapis.com/v3/feeds'
    with open(path, 'rb') as fh:
        data = fh.read()  # bytes, so a 429 retry can resend the body
    resp = call_walmart(
        auth, 'POST', url,
        params={'feedType': feed_type},
        files={'file': (path, data)},
    )
    resp.raise_for_status()
    return resp.json()['feedId']

Đồng bộ tồn kho và giá với Walmart API

Có ba cách cập nhật tồn kho; lựa chọn chủ yếu phụ thuộc vào khối lượng dữ liệu và mức độ khẩn cấp.

Bulk feed nhận JSON theo spec 1.5 (nhiều node) hoặc 1.4 (một node), và XML theo spec 1.4. Tương tự item feed, feed này trả về feed ID và báo cáo kết quả từng dòng qua Feed Status API.

Về giá, Walmart hiện cung cấp pricing and promotions management API với tùy chọn bulk, đồng thời đánh dấu Price management API cũ là deprecated. Hãy xây dựng trên API mới. Feed PRICE_AND_PROMOTION bị giới hạn 10 request mỗi giờ; đây là mức cần dùng để thiết kế hệ thống: price feed là một batch cần lập kế hoạch, không phải thứ nên gửi sau mọi thay đổi nhỏ.

Mẫu đồng bộ có thể chịu được giới hạn

• Duy trì outbox thay vì lịch đẩy toàn bộ. Ghi mỗi thay đổi tồn kho hoặc giá thành một record, gộp các thay đổi liên tiếp của cùng SKU rồi mới flush.
• Phân loại theo mức độ khẩn cấp. Gửi thay đổi sắp hết hoặc hết hàng qua request đơn lẻ với tối đa 200 request mỗi phút; các thay đổi còn lại gửi theo batch feed. Số lượng từ 2 xuống 0 không nên nằm chờ trong queue.
• Đối soát theo chu kỳ dài hơn. Chạy full feed theo lịch để sửa sai lệch và xem đây là bước khắc phục, không phải phương thức đồng bộ chính.
• Theo dõi trạng thái phía Walmart. Các webhook event như inventory out of stock, offer published và offer unpublished cho biết Walmart đang nhìn nhận trạng thái ra sao; đây thường là nơi phát hiện sai lệch đầu tiên.

Lấy, xác nhận và giao đơn hàng Walmart

Mỗi dòng đơn hàng đi qua một số trạng thái: Created (đã đặt và sẵn sàng xác nhận), Acknowledged (bạn đã xác nhận và dự định hoàn tất), Shipped (đã đánh dấu giao kèm tracking), Canceled và Delivered. Quy trình thực tế là lấy các đơn đã được release, xác nhận từng đơn, giao với tên đơn vị vận chuyển và mã tracking, đồng thời xử lý hủy và hoàn tiền khi phát sinh.

Bạn có thể biết đơn hàng mới bằng cách poll order endpoint hoặc đăng ký webhook event. Walmart cung cấp các event như purchase order created, purchase order line auto-canceled và order intent to cancel. Ở mức mặc định, việc tạo subscription được phép 200 lần mỗi phút.

Quy tắc xử lý đơn hàng để tránh giao trùng

• Giả định hệ thống giao ít nhất một lần. Nếu dùng cả webhook và polling, cùng một purchase order có thể đến hai lần. Hãy định danh record bằng purchase order ID và số dòng, đồng thời thiết kế thao tác acknowledge và ship có thể lặp lại an toàn.
• Luôn giữ polling làm phương án dự phòng. Webhook không nhận được sẽ không thể nhìn thấy. Poll định kỳ các đơn đã release giúp khép lại khoảng trống này với chi phí thấp.
• Giao theo dòng đơn hàng. Ship endpoint hoạt động trên từng dòng và giới hạn 60 request mỗi phút, vì vậy hãy gộp đơn nhiều dòng vào một request thay vì gửi từng dòng.
• Gửi đúng dữ liệu đơn vị vận chuyển và tracking. Walmart công bố danh sách tên carrier được hỗ trợ và cung cấp các chỉ số hiệu suất như valid tracking rate và on-time shipment qua Insights API. Hãy ánh xạ carrier của bạn với tên Walmart một cách rõ ràng thay vì gửi văn bản tự do.
• Lưu ý cấu trúc phí. Dòng đơn hàng có phí PRODUCT và SHIPPING; phí SHIPPING phải bao gồm shipDateTime theo UTC. Hãy chuyển đổi timestamp tại ranh giới hệ thống và lưu trữ nội bộ theo UTC.

Walmart cũng có tài liệu di chuyển Multi-Line Multi-Quantity (MLMQ). Nếu đang đọc code tích hợp cũ hoặc dùng thư viện bên thứ ba, hãy kiểm tra xem hệ thống có giả định mỗi đơn chỉ có một dòng và một số lượng hay không.

Kiểm thử trong Walmart sandbox trước khi go-live

Walmart cung cấp hai sandbox. Static sandbox cho bạn sandbox credential, hướng dẫn kiểm thử Marketplace API, kiểm tra feed và trang giới hạn riêng. Dynamic sandbox có các kịch bản để kiểm tra hoàn tất đơn hàng, hàng trả lại, hoàn tiền và tồn kho không dùng WFS. Sandbox key được cấp riêng với production key trên Developer Portal.

Sandbox có giới hạn request riêng, vì vậy một lần chạy thành công ở đó không cho biết nhiều về dư địa trong production. Hãy dùng sandbox để kiểm chứng tính đúng đắn; dùng trang rate limit để lập kế hoạch năng lực.

Trước khi chuyển sang production, hãy chủ động kiểm thử lỗi thay vì chỉ kiểm thử happy path:

1. Để token hết hạn giữa chừng và xác nhận client làm mới một lần rồi tiếp tục.
2. Buộc phát sinh 429 và kiểm tra backoff hoạt động, đồng thời log các header ngân sách còn lại.
3. Gửi feed có một số dòng hợp lệ và một số dòng không hợp lệ, rồi xác nhận chỉ các dòng lỗi được đưa vào hàng đợi sửa.
4. Gửi cùng một đơn hàng hai lần qua webhook và poll, rồi xác nhận chỉ có một lần acknowledge và một lần ship.
5. Đưa vào parser response có thêm field và giá trị enum chưa biết, rồi xác nhận parser không bị crash.

Duy trì tích hợp Walmart: deprecation và changelog

Walmart đã công bố Marketplace API Deprecation Guide vào 11 tháng 3 năm 2026. Tài liệu định nghĩa các giai đoạn Legacy (vẫn được hỗ trợ nhưng không khuyến nghị cho tích hợp mới), Deprecated (đã lên lịch loại bỏ, có ngày deprecation và sunset được công bố) và Sunset, bên cạnh các API Active được hỗ trợ đầy đủ. Trạng thái được công bố trong tài liệu và truyền qua response header của API, vì vậy hệ thống có log response header có thể nhận cảnh báo trực tiếp từ API.

Walmart cũng có changelog API tập trung cho Mỹ, được giới thiệu vào tháng 4 năm 2025. Các mục changelog liệt kê API, parameter, response property và enum value được thêm hoặc xóa, cũng như các property chuyển giữa bắt buộc và tùy chọn. Những thay đổi gần đây, chẳng hạn bản phát hành ngày 23 tháng 7 năm 2026, chủ yếu bổ sung field tùy chọn trong request và response. Đây là dạng thay đổi phổ biến, cho thấy parser nên có tính linh hoạt: bỏ qua field chưa biết và không bao giờ xem giá trị enum chưa biết là lỗi nghiêm trọng.

Deprecation thực sự xảy ra trên các endpoint đang vận hành. Điều hướng developer portal hiện đánh dấu Price management API cũ và Simplified Shipping Settings API là deprecated; một thay đổi Price Incentives trước đó đã thay CPpreference endpoint bằng endpoint mới, trong đó endpoint cũ được lên lịch sunset sau ngày 30 tháng 12 năm 2025. Một quy trình ngắn sẽ giúp bạn chủ động: xem changelog định kỳ, cảnh báo khi có deprecation header và duy trì contract test dựa trên schema có thể tải từ Walmart để thay đổi làm hỏng bài test thay vì làm gián đoạn đơn hàng khách.

Tự xây dựng hay bàn giao cho đơn vị chuyên môn?

Token client và feed submitter ở trên có thể hoàn thành trong một buổi chiều. Phần tốn thời gian là mọi thứ xung quanh: ánh xạ catalog vào các product-type spec thay đổi vài tuần một lần, đối soát trạng thái đơn hàng để không giao trùng và duy trì một nguồn dữ liệu tồn kho thống nhất giữa Walmart cùng mọi kênh bán khác.

Hãy tự xây dựng nếu Walmart là kênh duy nhất, catalog nhỏ và đội ngũ có thể tiếp nhận các thay đổi spec. Nên tìm hỗ trợ nếu bạn bán trên nhiều marketplace, catalog ánh xạ không đồng đều với các product type của Walmart hoặc không thể chấp nhận rủi ro bán vượt tồn trong giai đoạn hệ thống ổn định.

Nếu bạn muốn nhận dự toán cho một hệ thống tích hợp Walmart hoặc mô hình bán hàng đa kênh có Walmart, hãy yêu cầu báo giá miễn phí từ Netalith. Chi phí được tính theo phạm vi công việc và không yêu cầu tạo tài khoản hay cam kết sử dụng.