Lưu ý quan trọng: Content API for Shopping đã ngừng hoạt động từ ngày 18 tháng 8 năm 2026.

Kể từ ngày 1 tháng 9 năm 2026, các yêu cầu Content API for Shopping sẽ gặp phải lỗi tăng dần. Xem hướng dẫn về việc ngừng cung cấp Content API.

Nếu cần thêm thời gian để di chuyển sang Merchant API, hãy đăng ký gia hạn quyền truy cập vào Content API for Shopping.

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ê các hạn mức áp dụng cho Merchant API.

Merchant API sử dụng hạn mức để đảm bảo 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 liệt kê nguồn dữ liệu 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 được nhóm lại với nhau 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 hạn mức hằng ngày và hạn mức 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 có 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. 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 gộp theo lô HTTP tích hợp sẵn không ảnh hưởng đến hạn mức. Mỗi yêu cầu đơn lẻ trong một lô yêu cầu được tính là một yêu cầu đối với hạn mức. Ví dụ: một yêu cầu theo lô chứa 500 yêu cầu insert sẽ được tính phí là 500 yêu cầu phương thức insert riêng lẻ.

Ngoại lệ đối với việc phân lô theo khu vực chuyên biệt: Các phương thức phân lô theo khu vực chuyên biệt (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ả việc tích hợp, bạn nên xem xét nhóm hạn mức cụ thể liên quan đến 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ề việc 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 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 tài khoản phụ hằng ngày 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 hai lần cho mỗi tài khoản phụ mỗi ngày.

Hạn mức về tốc độ

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

Giới hạn 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 lúc 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 theo phút sử dụng khoảng thời gian luân phiên, trong đó khoảng thời gian thực thi bắt đầu từ thời điểm lệnh gọi API đầu tiên cho phương thức và tài nguyên đó được thực hiện. Ví dụ: nếu bạn thực hiện lệnh gọi lúc 10:01:30 sáng, thì khoảng thời gian hạn mức mỗi phút cho phương thức đó sẽ kéo dài đến 10:02:30 sáng.
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 thiếu trường này, thì nhóm này chưa sử dụng hạn mức nào.

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.

Hạn mức cụ thể hằng ngày và mỗi phút có sự khác biệt đáng kể giữa các nhóm hạn mức. Những thao tác có khối 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ó hạn mức 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.

Phân bổ và phân cấp hạn mức

Phần này giải thích Merchant API theo dõi và áp dụng hạn mức sử dụng 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 tài khoản độc lập xác thực 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ụ: 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 chính 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 tài khoản nâng cao, ngay cả khi nhắm đến một tài khoản phụ.
- Ví dụ: Tài khoản người quản lý bán lẻ của một công ty (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 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 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 xác thực của tài khoản phụ, hạn mức sẽ được tính vào nhóm 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ù được quản lý bởi một tài khoản nâng cao mẹ.
- 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 chính 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, không ảnh hưởng đến nhóm hạn mức của đại lý chính.

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

Có một vài 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 trong trang chẩn đoán API Merchant Center 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 giải quyết vấn đề: 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 sản phẩm và chuyển người dùng đến trang web của nhà bán lẻ để mua hàng. Khi thực hiện 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 Dịch vụ so sánh giá có tên là Europe Shopping Group (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 xác thực của chính mình để 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 của Europe Shopping Group.
- Một 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 nhà bán hàng được liên kết (accounts/30003) để chỉ định một nhãn. Hạn mức được sử dụng từ nhóm hạn mức của TopDeals CSS, chứ không phải nhóm hạn mức của tài khoản nhà bán hàng.
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. Các tài khoản này hoạt động như tài khoản nâng cao đặc biệt, cho phép bạn tạo các tài khoản phụ riêng lẻ 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 nhất, trong đó có thể có từng Dịch vụ so sánh giá (CSS), các tài khoản trong đó và tài khoản phụ là cấp riêng lẻ nhất.

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

Merchant API có một hệ thống quản lý hạn mức tự động cho một số 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, sản phẩm 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 điều chỉnh tự động bao gồm:

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 lệnh gọi hằng ngày thường được đặt gấp 2 lần số lượng ưu đãi 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 hai lần mỗi ngày.
Bạn có thể cập nhật từng sản phẩm nhiều hơn hai 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 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 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 hai lần gọi đọc cho 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 có 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 mình.
Hạn mức lệnh gọi hằng ngày thường được đặt gấp 2 lần số 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ó tính năng tự động điều chỉnh hạn mức. 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ì xảy ra khi vượt quá hạn mức

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

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 tăng hạn mức 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 của 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 của bạn
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ề danh sách 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 áp dụng hạn mức nhóm.

{
    "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 tăng hạn mức, 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 bắt buộc "Vấn đề/Câu hỏi là gì", rồi điền vào tất cả các trường bắt buộc, bao gồm cả mã truy cập 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 cho 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ư khi 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 những 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: Hãy yêu cầu tăng hạn mức nếu 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 quá trình 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, hạn mức hằng 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 hạn mức không mong muốn và sử dụng tài nguyên của Merchant Center một cách hiệu quả.

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

Phân bổ yêu cầu đồng đều: Tránh gửi một lượng lớn yêu cầu cùng lúc. Hãy 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 giới hạn tốc độ phía máy khách (điều tiết) trong ứng dụng của bạn. Đừng chỉ dựa vào 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 linh hoạt

Xử lý lỗi HTTP 429: Ứng dụng của bạn phải được 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". Độ giật 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 một lần nữa.
Tuân thủ gợi ý thử lại: Nếu phản hồi của API chứa thông tin chi tiết hoặc tiêu đề thử lại, hãy sử dụng các thông tin đó để xác định thời điểm tiếp tục lệnh gọi.

Giảm thiểu các lệnh gọi 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ả các lệnh gọi không thành công cũng sử dụng hạn mức API. Theo dõi lỗi NOT_FOUND trong phần Chẩn đoán API của Merchant Center để phát hiện hoạt động theo dõi trạng thái cũ hoặc hoạt động thăm dò 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 phản hồi đọc vào bộ nhớ đệm (ví dụ: chi tiết sản phẩm, chế độ cài đặt) trên thiết bị khi thích hợp để tránh các lệnh gọi get hoặc list lặp lại cho dữ liệu không thay đổi.

Tìm hiểu về hệ thống phân cấp hạn mức và các 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 cuộc gọi được tính vào nhóm tài nguyên 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ã tài khoản Merchant Center) 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 MCA của bạn.

Overview

Tiếp

Merchant Center limits