Merchant API phiên bản v1beta đã ngừng hoạt động và ngừng cung cấp từ ngày 28 tháng 2 năm 2026. Để biết các bước chuyển đổi sang phiên bản ổn định mới nhất, hãy xem phần Di chuyển từ v1beta sang v1.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Hạn mức

Tài liệu này liệt kê những hạn mức áp dụng cho Merchant API.

Merchant API sử dụng hạn mức để giúp đảm bảo một môi trường ổn định và công bằng cho tất cả người dùng. Hạn mức ngăn chặn bất kỳ người dùng API nào đặt tải quá mức lên hệ thống, đảm bảo hiệu suất cao. Việc nắm rõ các hạn mức này là yếu tố then chốt để bạn quản lý dữ liệu sản phẩm và mở rộng quy mô doanh nghiệp của mình trên Google.

Các khái niệm chung

Hạn mức Merchant API được quản lý thông qua các nhóm hạn mức.

Các phương thức API được liên kết với các nhóm hạn mức. Cấu trúc của mối liên kết này có thể khác nhau:

Một phương thức cho mỗi nhóm: Một số nhóm hạn mức áp dụng cho một phương thức API duy nhất. Ví dụ: phương thức nguồn dữ liệu trang thông tin accounts.dataSources.list có nhóm hạn mức riêng.
Nhiều phương thức cho mỗi nhóm (gói): Thông thường, các phương thức có liên quan sẽ được kết hợp thành một nhóm hạn mức duy nhất. Tất cả các phương thức trong nhóm đó đều có cùng giới hạn hằng ngày và giới hạn mỗi phút. Sau đây là một số ví dụ thường gặp:
- Nhóm tất cả các thao tác đọc cho các phương thức và tài nguyên liên quan, chẳng hạn như merchant-accounts-read-methods.
- Nhóm tất cả các thao tác ghi cho các phương thức và tài nguyên liên quan, chẳng hạn như merchant-accounts-write-methods.

Mỗi lệnh gọi phương thức được tính một lần, bất kể loại lệnh gọi là gì. Một yêu cầu list gồm 250 mục chỉ được tính một lần, chứ không phải là 250 yêu cầu get.

Tính năng tạo hàng loạt yêu cầu HTTP tích hợp không ảnh hưởng đến hạn mức. Mỗi yêu cầu riêng lẻ trong một nhóm yêu cầu được tính là một yêu cầu trong hạn mức. Ví dụ: một yêu cầu hàng loạt chứa 500 yêu cầu insert sẽ bị tính phí là 500 yêu cầu riêng lẻ đối với phương thức insert.

Trường hợp ngoại lệ đối với việc xử lý theo lô dành riêng cho khu vực: Các phương thức xử lý theo lô dành riêng cho khu vực (batchCreate, batchUpdate, batchDelete) được tính là một lệnh gọi API duy nhất đối với nhóm hạn mức merchant_regions, bất kể số lượng thao tác theo khu vực có trong tải trọng.

Để quản lý hiệu quả hoạt động tích hợp, bạn nên xem xét nhóm hạn mức cụ thể được liên kết với từng phương thức API mà bạn dự định sử dụng. Bạn có thể tìm thấy những thông tin này trong phương thức danh sách hạn mức. Để biết thêm thông tin, hãy xem phần Giám sát và khả năng hiển thị.

Cập nhật chính sách

Merchant API thực thi các chính sách sau đây về nội dung cập nhật:

Theo mặc định, bạn có thể cập nhật sản phẩm tối đa 2 lần mỗi ngày. Bạn nên phân bổ đều các lệnh gọi trong suốt cả ngày để tuân thủ hạn mức mỗi phút.
Theo mặc định, bạn chỉ có thể cập nhật tài khoản phụ tối đa 2 lần mỗi ngày. Hạn mức cập nhật hằng ngày cho tài khoản phụ là hạn mức tổng hợp dựa trên tổng số tài khoản phụ được phép.
Theo mặc định, bạn chỉ có thể gọi các phương thức nguồn dữ liệu cho tài khoản phụ của mình, chẳng hạn như list hoặc create tối đa 2 lần mỗi tài khoản phụ mỗi ngày.

Hạn mức về giá

Mỗi nhóm hạn mức có 2 loại hạn mức (và mức sử dụng hằng ngày):

Hạn mức hằng ngày (quotaLimit): Số lượng yêu cầu tối đa được phép mỗi ngày. Hạn mức hằng ngày sẽ được đặt lại vào 12:00 trưa theo giờ UTC.
Giới hạn mỗi phút (quotaMinuteLimit): Số lượng yêu cầu tối đa được phép mỗi phút, kiểm soát tốc độ yêu cầu. Hạn mức mỗi phút sử dụng một cửa sổ trượt, trong đó khoảng thời gian thực thi bắt đầu từ thời điểm thực hiện lệnh gọi API đầu tiên cho phương thức và tài nguyên đó. Ví dụ: nếu bạn gọi vào lúc 10:01:30, thì hạn mức theo phút cho phương thức đó sẽ chạy cho đến 10:02:30.
Mức sử dụng hằng ngày (quotaUsage): Số lượng yêu cầu đã được thực hiện và tính vào giới hạn hằng ngày cho ngày hiện tại. Nếu trường này bị thiếu, thì tức là bạn chưa sử dụng hạn mức nào cho nhóm này.

Bạn có thể tìm thấy 3 trường được mô tả trước đó (quotaLimit, quotaMinuteLimit và quotaUsage) trong phản hồi của phương thức quotas.list.

Giới hạn cụ thể hằng ngày và giới hạn theo phút có sự khác biệt đáng kể giữa các nhóm hạn mức. Các thao tác có số lượng dự kiến cao hơn hoặc chi phí hệ thống thấp hơn, chẳng hạn như đọc dữ liệu sản phẩm, thường có giới hạn cao hơn. Ngược lại, các thao tác chuyên sâu hoặc nhạy cảm hơn, chẳng hạn như sửa đổi tài khoản, có thể có giới hạn thấp hơn.

Hệ thống phân cấp và việc phân bổ hạn mức

Phần này giải thích Merchant API theo dõi và áp dụng mức sử dụng hạn mức thay cho ai:

Nhìn chung, hạn mức được tính dựa trên người dùng đưa ra yêu cầu API.

Tài khoản độc lập: Đối với các tài khoản độc lập xác thực một lệnh gọi API, yêu cầu đó sẽ được tính vào hạn mức của tài khoản đó.
- Ví dụ: Một người bán Cửa hàng giày A (Mã tài khoản: 12345) xác thực bằng tài khoản dịch vụ của riêng mình để gọi products.insert nhắm đến tài khoản của chính mình (accounts/12345). Hạn mức được sử dụng từ nhóm hạn mức của Cửa hàng giày A.
Tài khoản nâng cao: Việc xác thực dưới dạng tài khoản nâng cao sẽ sử dụng hạn mức từ nhóm hạn mức của tài khoản nâng cao, ngay cả khi nhắm đến tài khoản phụ.
- Ví dụ: Một công ty quảng cáo Tài khoản quản lý bán lẻ (Mã tài khoản nâng cao: 12345) quản lý một tài khoản phụ Cửa hàng quần áo B (Mã tài khoản: 11111). Công ty quảng cáo xác thực bằng thông tin đăng nhập của chính mình và gọi products.insert nhắm đến Cửa hàng quần áo B (accounts/11111). Hạn mức được sử dụng từ nhóm hạn mức của công ty quảng cáo mẹ (Mã tài khoản nâng cao: 12345), chứ không phải nhóm hạn mức của tài khoản phụ.
Tài khoản phụ: Khi các lệnh gọi API được xác thực bằng thông tin đăng nhập của tài khoản phụ, hạn mức sẽ được tính vào nhóm hạn mức riêng của tài khoản phụ đó. Tài khoản này hoạt động giống như một tài khoản độc lập, mặc dù do một tài khoản nâng cao của cha mẹ quản lý.
- Ví dụ: Sử dụng cùng một chế độ thiết lập như trước, nếu Cửa hàng quần áo B (Mã tài khoản: 11111) xác thực bằng thông tin đăng nhập được thiết lập riêng cho tài khoản phụ của họ để gọi products.insert nhắm đến tài khoản của riêng họ (accounts/11111), thì hạn mức sẽ được sử dụng từ nhóm hạn mức riêng của Cửa hàng quần áo B mà không ảnh hưởng đến nhóm hạn mức của công ty quảng cáo chính.

Trường hợp ngoại lệ đối với các quy tắc chung

Có một số trường hợp ngoại lệ cụ thể áp dụng cho các quy tắc chung về việc phân bổ hạn mức:

Accounts.list: Hạn mức cho phương thức này được tính cho người dùng đã xác thực hoặc tài khoản dịch vụ thực hiện lệnh gọi, chứ không phải mã tài khoản Merchant Center. Mức sử dụng hạn mức của API này sẽ không xuất hiện trên trang chẩn đoán Merchant Center API tiêu chuẩn. Nếu có tài khoản nâng cao, bạn nên sử dụng phương thức accounts.listSubaccounts. Phương thức này sẽ được tính vào hạn mức tài khoản nâng cao của bạn.
Phương thức Issueresolution: Các phương thức này luôn được tính vào hạn mức của tài khoản có vấn đề đang được yêu cầu, ngay cả khi một tài khoản khác đang xác thực yêu cầu.

Hệ thống phân cấp phân bổ

Dịch vụ so sánh giá (CSS): CSS là những trang web tổng hợp các mặt hàng và chuyển người dùng đến trang web của nhà bán lẻ để mua hàng. Khi thực hiện các lệnh gọi API, hạn mức sẽ được áp dụng cho nhóm Dịch vụ so sánh giá, miền CSS, tài khoản hoặc tài khoản phụ cụ thể mà bạn xác thực.

Ví dụ:
- Một nhóm CSS có tên là Nhóm mua sắm ở Châu Âu (Mã tài khoản: 10001) muốn liệt kê các miền CSS được liên kết. Bằng cách xác thực bằng thông tin đăng nhập riêng để thực hiện lệnh gọi API này, hạn mức sẽ được sử dụng trực tiếp từ nhóm hạn mức Europe Shopping Group.
- Miền CSS TopDeals CSS (Mã tài khoản: 20002) xác thực để gọi một phương thức nhắm đến một trong các tài khoản người bán được liên kết (accounts/30003) để chỉ định nhãn. Hạn mức được sử dụng từ nhóm hạn mức của CSS TopDeals, chứ không phải nhóm hạn mức của tài khoản người bán.
Trang web thương mại: Trang web thương mại là nền tảng trực tuyến lưu trữ nhiều người bán cá nhân. Đây là tài khoản nâng cao đặc biệt, cho phép bạn tạo tài khoản phụ riêng cho từng người bán.

Sơ đồ sau đây cho thấy hệ thống phân cấp của các nhóm CSS, CSS, trang web thương mại, tài khoản nâng cao, tài khoản độc lập và tài khoản phụ.

Nhóm Dịch vụ so sánh giá là cấp xác thực bao quát, có thể có Dịch vụ so sánh giá (CSS) riêng lẻ trong đó, tài khoản trong các tài khoản đó và tài khoản phụ là cấp riêng lẻ nhất.

Điều chỉnh hạn mức tự động

Merchant API có một hệ thống quản lý hạn mức tự động cho các dịch vụ cụ thể. Hệ thống này điều chỉnh hạn mức cho những người bán đang phát triển dựa trên mức sử dụng, mặt hàng và quy mô tài khoản của bạn. Merchant API tính toán lại các hạn mức này hằng ngày.

Các nhóm hạn mức được đưa vào quy trình điều chỉnh hạn mức tự động là:

Dịch vụ sản phẩm

Tất cả các nhóm hạn mức của phương thức liên quan đến tài nguyên products và productInputs.
Hạn mức gọi hằng ngày thường được đặt gấp 2 lần số hạn mức mặt hàng mà người bán có. Điều này giả định rằng người bán có thể cần cập nhật từng sản phẩm của họ tối đa 2 lần mỗi ngày.
Bạn có thể cập nhật từng sản phẩm nhiều hơn 2 lần, nhưng tổng số lệnh gọi API hằng ngày không được vượt quá hạn mức tổng số lệnh gọi hằng ngày.

Dịch vụ tài khoản

Tất cả các nhóm hạn mức của các phương thức liên quan đến nhiều tài nguyên chi tiết liên quan đến tài khoản trong Merchant API.
Hạn mức cuộc gọi hằng ngày được đặt thành số lượng tài khoản phụ tối đa được phép cho tài khoản đó. Điều này cho phép tối đa 2 lần gọi đọc mỗi tài khoản phụ mỗi ngày.

Dịch vụ nguồn dữ liệu

Tất cả các nhóm hạn mức của phương thức liên quan đến tài nguyên liên quan đến nguồn dữ liệu trong Merchant API, chẳng hạn như list hoặc create mà một tài khoản nâng cao thực hiện trên các tài khoản phụ của tài khoản đó.
Hạn mức cuộc gọi hằng ngày thường được đặt gấp 2 lần số lượng tài khoản phụ mà tài khoản nâng cao có. Điều này giả định rằng người bán có thể cập nhật nguồn dữ liệu của từng tài khoản phụ tối đa 2 lần mỗi ngày.

Chỉ những dịch vụ được mô tả trước đó mới có chế độ điều chỉnh hạn mức tự động. Các dịch vụ khác có hạn mức mặc định và mọi yêu cầu tăng hạn mức đều phải được thực hiện theo cách thủ công. Để biết thêm thông tin, hãy xem phần Quy trình tăng hạn mức.

Điều gì sẽ xảy ra khi bạn vượt quá hạn mức

Sau khi vượt quá hạn mức, lỗi sẽ xuất hiện trong các phản hồi API và trên trang chẩn đoán trong tài khoản Merchant Center:

Mỗi phút: quota/request_rate_too_high

{
    "error": {
        "code": 429,
        "message": "Quota per minute exceeded. Please distribute your requests over a longer time period. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_REQUEST_RATE_TOO_HIGH"
                }
            }
        ]
    }
}

Mỗi ngày: quota/daily_limit_exceeded

{
    "error": {
        "code": 429,
        "message": "Daily request quota exceeded. Please reduce number of requests. For more information check https://developers.google.com/merchant/api/guides/quotas-limits",
        "status": "RESOURCE_EXHAUSTED",
        "details": [
            {
                "@type": "type.googleapis.com/google.rpc.ErrorInfo",
                "reason": "quotaExceeded",
                "domain": "merchantapi.googleapis.com",
                "metadata": {
                    "HELP_CENTER_LINK": "https://developers.google.com/merchant/api/guides/quotas-limits",
                    "REASON": "QUOTA_TOO_MANY_REQUESTS"
                }
            }
        ]
    }
}

Các lỗi sau đây là giới hạn của Merchant Center và không liên quan đến hạn mức của Merchant API. Bạn có thể thử yêu cầu bổ sung hạn mức cho mặt hàng, nguồn cấp dữ liệu hoặc tài khoản phụ:

too_many_items: Vượt quá hạn mức người bán
too_many_subaccounts: Đã đạt đến số lượng tài khoản phụ tối đa

Giám sát và khả năng hiển thị

Để kiểm tra hạn mức và mức sử dụng lệnh gọi hiện tại cho một tài khoản, hãy gọi quotas.list bằng tên của tài khoản.

POST https://merchantapi.googleapis.com/quota/v1/accounts/{ACCOUNT_ID}/quotas
Content-Type: application/json
Authorization: Bearer {ACCESS_TOKEN}

Thay thế nội dung sau:

ACCOUNT_ID: mã truy cập Merchant Center
ACCESS_TOKEN: mã thông báo uỷ quyền để thực hiện lệnh gọi API

Khi yêu cầu thành công, API sẽ trả về một danh sách các tài nguyên quotaGroups chứa tài nguyên name của nhóm hạn mức, các hạn mức khác nhau và các phương thức mà hạn mức nhóm áp dụng.

{
    "quotaGroups": [
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-quota-listquotagroups",
            "quotaUsage": "2",
            "quotaLimit": "1000",
            "methodDetails": [
                {
                    "method": "quotaservice.listquotagroups",
                    "version": "v1",
                    "subapi": "quota",
                    "path": "quota/v1/quotaservice.listquotagroups"
                }
            ],
            "quotaMinuteLimit": "10"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-commission-group-list",
            "quotaLimit": "10000",
            "methodDetails": [
                {
                    "method": "commissiongroupservice.listcommissiongroups",
                    "version": "v1",
                    "subapi": "youtube",
                    "path": "youtube/v1/commissiongroupservice.listcommissiongroups"
                }
            ],
            "quotaMinuteLimit": "60"
        },
        {
            "name": "accounts/{ACCOUNT_ID}/quotas/merchant-merchantreviews-list",
            "quotaLimit": "20000000",
            "methodDetails": [
                {
                    "method": "merchantreviewsservice.listmerchantreviews",
                    "version": "v1",
                    "subapi": "reviews",
                    "path": "reviews/v1/merchantreviewsservice.listmerchantreviews"
                }
            ],
            "quotaMinuteLimit": "60000"
        }
    ]
}

Quy trình tăng hạn mức

Để yêu cầu hạn mức bổ sung, hãy mở Biểu mẫu liên hệ với nhóm hỗ trợ, chọn Yêu cầu tăng hạn mức cho trường "Vấn đề/Câu hỏi" bắt buộc và điền tất cả các trường bắt buộc, bao gồm cả mã Merchant Center, phương thức mục tiêu và lý do kinh doanh.

Đối với những tài nguyên có hạn mức tự động (products, accounts và datasources đối với tài khoản nâng cao): Bạn chỉ có thể yêu cầu tăng hạn mức tạm thời cho các trường hợp đặc biệt, chẳng hạn như ra mắt ở một thị trường mới hoặc trong các mùa mua sắm có lưu lượng truy cập cao. Chúng tôi không chấp nhận yêu cầu tăng hạn mức vĩnh viễn cho các loại tài nguyên này.
Đối với tất cả các tài nguyên khác không có hạn mức tự động: Yêu cầu tăng hạn mức khi cần.

Bạn nên kiểm tra hạn mức định kỳ để đảm bảo bạn có đủ hạn mức cho việc triển khai và xem hạn mức của bạn được điều chỉnh tự động như thế nào. Sử dụng phương thức quotas.list để xem hạn mức hằng ngày hiện tại, hạn mức theo phút và mức sử dụng hằng ngày hiện tại cho từng nhóm phương thức API.

Các phương pháp hay nhất

Việc triển khai các phương pháp hay nhất này giúp đảm bảo quá trình tích hợp diễn ra suôn sẻ, tránh các lỗi ngoài ý muốn về hạn mức và sử dụng hiệu quả các tài nguyên của Merchant Center.

Tối ưu hoá việc phân phối yêu cầu

Phân phối yêu cầu một cách đồng đều: Tránh gửi nhiều yêu cầu cùng lúc. Phân bổ đều các lệnh gọi API hằng ngày trong suốt cả ngày để không vượt quá hạn mức theo phút (quotaMinuteLimit).
Điều tiết chủ động: Triển khai tính năng giới hạn tốc độ (điều tiết) phía máy khách trong ứng dụng của bạn. Đừng chỉ dựa vào các máy chủ của Google để từ chối lưu lượng truy cập dư thừa. Kiểm soát tỷ lệ yêu cầu tại nguồn.

Xử lý lỗi một cách hiệu quả

Xử lý HTTP 429: Ứng dụng của bạn phải chuẩn bị để xử lý lỗi 429 Quá nhiều yêu cầu (quota/request_rate_too_high).
Thuật toán đợi luỹ thừa có độ trễ ngẫu nhiên: Khi thử lại các yêu cầu không thành công (đặc biệt là sau lỗi 429), hãy sử dụng thuật toán đợi luỹ thừa (tăng thời gian chờ) và thêm "độ trễ ngẫu nhiên" (độ trễ ngẫu nhiên). Độ trễ ngẫu nhiên ngăn chặn "bão thử lại", trong đó nhiều phiên bản ứng dụng thử lại cùng một lúc, khiến máy chủ bị quá tải trở lại.
Tôn trọng gợi ý thử lại: Nếu phản hồi API chứa thông tin chi tiết hoặc tiêu đề về việc thử lại, hãy sử dụng thông tin đó để xác định thời điểm tiếp tục gọi.

Giảm thiểu các lệnh gọi dư thừa

Ngăn chặn các lệnh gọi cũ (404 NOT_FOUND): Tránh yêu cầu hoặc xoá các tài nguyên không còn tồn tại. Ngay cả những lệnh gọi không thành công cũng tiêu tốn hạn mức API. Giám sát các lỗi NOT_FOUND trong API Diagnostics của Merchant Center để phát hiện trạng thái theo dõi không còn hiệu lực hoặc việc thăm dò ý kiến không cần thiết.
Xác minh trước khi cập nhật: Trước khi gửi yêu cầu cập nhật, hãy kiểm tra xem dữ liệu có thực sự thay đổi hay không. Tránh gửi các bản cập nhật ghi cùng một giá trị.
Sử dụng tính năng lưu vào bộ nhớ đệm: Lưu các phản hồi đọc vào bộ nhớ đệm (ví dụ: chi tiết sản phẩm, chế độ cài đặt) cục bộ khi thích hợp để tránh các lệnh gọi get hoặc list lặp đi lặp lại cho dữ liệu không thay đổi.

Điều hướng hệ thống phân cấp hạn mức và trường hợp ngoại lệ

Tài khoản nâng cao và tài khoản phụ: Nếu bạn là tài khoản nâng cao, hãy xác thực ở cấp tài khoản nâng cao nếu bạn muốn các lệnh gọi được tính vào nhóm dùng chung của tài khoản nâng cao.
Sử dụng listSubaccounts: Đối với tài khoản nâng cao, hãy sử dụng accounts.listSubaccounts thay vì accounts.list. Hạn mức accounts.list được tính cho người dùng gọi (không phải mã nhận dạng MC) và không xuất hiện trong thông tin chẩn đoán tiêu chuẩn. listSubaccounts được tính vào hạn mức tài khoản người bán đa quốc gia.

Overview

Tiếp

Merchant Center limits