Merchant API v1beta는 2026년 2월 28일에 지원 중단되고 종료되었습니다. 안정적인 최신 버전으로 전환하는 단계는 v1beta에서 v1로 마이그레이션을 참고하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

할당량

이 문서에서는 Merchant API에 적용되는 할당량을 설명합니다.

Merchant API는 할당량을 사용하여 모든 사용자에게 안정적이고 공정한 환경을 제공합니다. 할당량은 단일 API 사용자가 시스템에 과도한 부하를 가하는 것을 방지하여 높은 성능을 보장합니다. 이러한 할당량을 이해하는 것은 제품 데이터를 관리하고 Google에서 비즈니스를 확장하는 데 중요합니다.

일반적인 개념

Merchant API 할당량은 할당량 그룹을 통해 관리됩니다.

API 메서드는 할당량 그룹에 매핑됩니다. 이 매핑의 구조는 다음과 같이 다양할 수 있습니다.

그룹당 단일 메서드: 일부 할당량 그룹은 단일 API 메서드에 적용됩니다. 예를 들어 목록 데이터 소스 메서드 accounts.dataSources.list 에는 자체 전용 할당량 그룹이 있습니다.
그룹당 여러 메서드 (번들링): 관련 메서드는 단일 할당량 그룹으로 번들링되는 경우가 많습니다. 이 그룹 내의 모든 메서드는 동일한 일일 및 분당 한도를 공유합니다. 일반적인 예시는 다음과 같습니다.
- 관련 메서드 및 리소스(예: merchant-accounts-read-methods)의 모든 읽기 작업을 그룹화합니다.
- 관련 메서드 및 리소스(예: merchant-accounts-write-methods)의 모든 쓰기 작업을 그룹화합니다.

각 메서드 호출은 유형에 관계없이 한 번씩 계산됩니다. 250개 항목의 list 요청은 250개의 get 요청이 아닌 한 번만 계산됩니다.

기본 제공 HTTP 일괄 처리 는 할당량에 영향을 미치지 않습니다. 요청 일괄 처리 내의 각 단일 요청은 할당량에 대해 하나로 계산됩니다. 예를 들어 500개의 insert 요청이 포함된 일괄 요청은 500개의 개별 insert 메서드 요청으로 청구됩니다.

전용 리전 일괄 처리 예외: 특수 리전 일괄 처리 메서드 (batchCreate, batchUpdate, batchDelete) 는 페이로드에 포함된 리전 작업 수와 관계없이 merchant_regions 할당량 그룹에 대해 단일 API 호출로 계산됩니다.

통합을 효과적으로 관리하려면 사용하려는 각 API 메서드와 연결된 특정 할당량 그룹을 검토해야 합니다. 이러한 세부정보는 할당량 목록 메서드에서 확인할 수 있습니다. 자세한 내용은 모니터링 및 가시성을 참고하세요.

정책 업데이트

Merchant API는 업데이트와 관련하여 다음 정책을 적용합니다.

기본적으로 제품을 하루에 최대 두 번 업데이트할 수 있습니다. 분당 할당량을 준수하려면 하루 종일 호출을 균등하게 분산해야 합니다.
기본적으로 하위 계정은 하루에 최대 두 번만 업데이트할 수 있습니다. 일일 하위 계정 업데이트 할당량은 허용된 총 하위 계정을 기준으로 하는 집계 한도입니다.
기본적으로 하위 계정의 데이터 소스 메서드(예: list 또는 create)는 하위 계정당 하루에 최대 두 번만 호출할 수 있습니다.

비율 할당량

각 할당량 그룹에는 두 가지 유형의 한도 (및 일일 사용량)가 있습니다.

일일 한도 (quotaLimit): 하루에 허용되는 최대 요청 수입니다. 일일 할당량 한도는 오후 12시(UTC) 에 재설정됩니다.
분당 한도 (quotaMinuteLimit): 분당 허용되는 최대 요청 수로, 요청 비율을 제어합니다. 분당 할당량 한도는 롤링 창을 사용하며, 적용 기간은 해당 메서드 및 리소스에 대한 첫 번째 API 호출이 이루어진 순간부터 시작됩니다. 예를 들어 오전 10시 1분 30초에 호출하면 해당 메서드의 분당 할당량 창은 오전 10시 2분 30초까지 실행됩니다.
일일 사용량 (quotaUsage): 이미 이루어졌으며 당일 일일 한도에 대해 계산된 요청 수입니다. 필드가 누락된 경우 이 그룹에 대해 아직 할당량이 사용되지 않은 것입니다.

앞서 설명한 세 가지 필드 (quotaLimit, quotaMinuteLimit, 및 quotaUsage)는 quotas.list 메서드의 응답에서 확인할 수 있습니다.

특정 일일 및 분당 한도는 할당량 그룹마다 크게 다릅니다. 제품 데이터 읽기와 같이 예상되는 볼륨이 높거나 시스템 비용이 낮은 작업에는 일반적으로 더 높은 한도가 적용됩니다. 반대로 계정 수정과 같이 더 집약적이거나 민감한 작업에는 더 낮은 한도가 적용될 수 있습니다.

할당량 할당 및 계층 구조

이 섹션에서는 Merchant API가 할당량 사용량을 추적하고 적용하는 주체를 설명합니다.

일반적으로 할당량은 API 요청을 하는 사용자를 기준으로 청구됩니다.

단독 계정: API 호출을 인증하는 단독 계정의 경우 해당 요청은 해당 계정의 할당량에 대해 계산됩니다.
- 예: 판매자 신발 매장 A (계정 ID: 12345)는 자체 서비스 계정을 사용하여 자체 계정 (accounts/12345)을 타겟팅하는 products.insert를 호출합니다. 할당량은 신발 매장 A의 할당량 풀에서 사용됩니다.
고급 계정: 고급 계정 으로 인증하면 하위 계정을 타겟팅하는 경우에도 고급 계정의 풀에서 할당량이 사용됩니다.
- 예: 대행사 소매 관리 계정 (고급 계정 ID: 12345)은 하위 계정 의류 매장 B (계정 ID: 11111)를 관리합니다. 대행사는 자체 사용자 인증 정보를 사용하여 인증하고 의류 매장 B (accounts/11111)를 타겟팅하는 products.insert를 호출합니다. 할당량은 하위 계정의 풀이 아닌 상위 대행사의 풀 (고급 계정 ID: 12345)에서 사용됩니다.
하위 계정: API 호출이 하위 계정의 사용자 인증 정보를 사용하여 인증되면 할당량은 해당 하위 계정의 개별 풀에 청구됩니다. 상위 고급 계정에서 관리하지만 단독 계정과 동일한 방식으로 작동합니다.
- 예: 이전과 동일한 설정을 사용하여 의류 매장 B (계정 ID: 11111)가 하위 계정에 맞게 설정된 사용자 인증 정보를 사용하여 자체 계정 (accounts/11111)을 타겟팅하는 products.insert를 호출하기 위해 인증하는 경우 할당량은 의류 매장 B의 개별 할당량 풀에서 사용되며 상위 대행사의 풀은 그대로 유지됩니다.

일반 규칙의 예외

할당량 할당 일반 규칙에 적용되는 몇 가지 예외가 있습니다.

Accounts.list: 이 메서드의 할당량은 판매자 센터 계정 ID가 아닌 호출을 하는 인증된 사용자 또는 서비스 계정에 대해 청구됩니다. 할당량 사용량은 표준 판매자 센터 API 진단 페이지에 표시되지 않습니다. 고급 계정이 있는 경우 고급 계정 할당량에 포함되는 accounts.listSubaccounts 메서드를 사용하는 것이 좋습니다.
Issueresolution 메서드: 이러한 메서드는 요청을 인증하는 계정이 다르더라도 문제가 요청되는 계정의 할당량에 대해 항상 계산됩니다.

할당 계층 구조

비교 쇼핑 서비스 (CSS): CSS는 제품 오퍼를 집계하고 사용자를 판매자의 웹사이트로 안내하여 구매를 유도하는 웹사이트입니다. API 호출을 할 때 할당량은 인증하는 특정 CSS 그룹, CSS 도메인, 계정 또는 하위 계정에 적용됩니다.

예:
- 유럽 쇼핑 그룹 (계정 ID: 10001)이라는 CSS 그룹이 연결된 CSS 도메인을 나열하려고 합니다. 자체 사용자 인증 정보를 사용하여 이 API 호출을 인증하면 할당량이 유럽 쇼핑 그룹 할당량 풀에서 직접 사용됩니다.
- CSS 도메인 TopDeals CSS (계정 ID: 20002)는 연결된 판매자 계정 중 하나(accounts/30003)를 타겟팅하는 메서드를 호출하여 라벨을 할당하기 위해 인증합니다. 할당량은 판매자 계정의 풀이 아닌 TopDeals CSS 할당량 풀에서 사용됩니다.
마켓: 마켓은 여러 개별 판매자를 호스팅하는 온라인 플랫폼입니다. 판매자별로 개별 하위 계정을 만들 수 있는 특수 고급 계정으로 작동합니다.

다음 다이어그램은 CSS 그룹, CSS, 마켓, 고급 계정, 단독 계정, 하위 계정의 계층 구조를 보여줍니다.

CSS 그룹은 전반적인 인증 수준이며, 그 안에 개별 CSS, 해당 CSS 내의 계정, 가장 개별적인 수준인 하위 계정이 있을 수 있습니다.

자동 할당량 조정

Merchant API에는 특정 서비스에 대한 자동 할당량 관리 시스템이 있으며, 이 시스템은 사용량, 오퍼, 계정 크기를 기준으로 성장하는 판매자의 할당량 한도를 조정합니다. Merchant API는 이러한 할당량을 매일 다시 계산합니다.

자동 할당량 조정에 포함된 할당량 그룹은 다음과 같습니다.

제품 서비스

products 및 productInputs 리소스와 관련된 메서드의 모든 할당량 그룹입니다.
일일 호출 할당량은 일반적으로 판매자가 보유한 오퍼 할당량 수의 2배로 설정됩니다. 이는 판매자가 제품을 하루에 최대 두 번 업데이트해야 할 수 있다고 가정합니다.
개별 제품은 두 번 이상 업데이트할 수 있지만 전체 일일 API 호출은 집계 일일 호출 할당량을 초과할 수 없습니다.

계정 서비스

Merchant API의 다양한 세분화된 계정 관련 리소스와 관련된 메서드의 모든 할당량 그룹입니다.
일일 호출 할당량은 해당 계정에 허용되는 최대 하위 계정 수로 설정됩니다. 이를 통해 하위 계정당 하루에 최대 두 번의 읽기 호출이 가능합니다.

데이터 소스 서비스

고급 계정이 하위 계정에서 실행하는 list 또는 create와 같은 Merchant API의 데이터 소스 관련 리소스와 관련된 메서드의 모든 할당량 그룹입니다.
일일 호출 할당량은 일반적으로 고급 계정이 보유한 하위 계정 수의 2배로 설정됩니다. 이는 판매자가 하위 계정의 데이터 소스를 하루에 최대 두 번 업데이트할 수 있다고 가정합니다.

앞서 설명한 서비스에만 자동 할당량 조정이 적용됩니다. 다른 서비스에는 기본 할당량이 있으며, 증가는 수동으로 요청해야 합니다. 자세한 내용은 할당량 증가 프로세스 섹션을 참고하세요.

할당량을 초과하면 어떻게 되나요?

할당량을 초과하면 API 응답과 판매자 센터 계정의 진단 페이지에 오류가 표시됩니다.

분당: 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"
                }
            }
        ]
    }
}

일일: 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"
                }
            }
        ]
    }
}

다음 오류는 판매자 센터 한도이며 Merchant API 할당량과 관련이 없습니다. 상품, 피드 또는 하위 계정의 추가 할당량을 요청해 볼 수 있습니다.

too_many_items: 판매자 할당량 초과
too_many_subaccounts: 최대 하위 계정 수 도달

모니터링 및 가시성

계정의 현재 호출 할당량과 사용량을 확인하려면 계정 이름으로 quotas.list with 를 호출합니다.

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

다음을 바꿉니다.

ACCOUNT_ID: 판매자 센터 ID
ACCESS_TOKEN: API 호출을 하기 위한 승인 토큰

요청이 성공하면 API는 할당량 그룹의 리소스 name, 다양한 할당량, 그룹 할당량이 적용되는 메서드가 포함된 quotaGroups 리소스 목록을 반환합니다.

{
    "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"
        }
    ]
}

할당량 증가 프로세스

추가 할당량을 요청하려면 지원팀에 문의 양식을 열고 필수 '문제/질문' 필드에 할당량 증가 요청을 선택한 후 판매자 센터 ID, 타겟 메서드, 비즈니스 근거를 비롯한 모든 필수 필드를 작성합니다.

자동 할당량이 있는 리소스 (고급 계정의 products, accounts, datasources): 새 시장에서 출시하거나 트래픽이 많은 쇼핑 시즌과 같은 특별한 시나리오에 대해서만 일시적인 증가를 요청할 수 있습니다. 이러한 유형의 리소스에 대해서는 영구적인 할당량 증가를 허용하지 않습니다.
자동 할당량이 없는 기타 모든 리소스: 필요에 따라 할당량 증가를 요청합니다.

구현에 충분한 할당량이 있는지 확인하고 할당량이 자동으로 조정되는 방식을 확인하려면 할당량을 주기적으로 확인하는 것이 좋습니다. quotas.list 메서드를 사용하여 각 API 메서드 그룹의 현재 일일 할당량 한도, 분당 한도, 현재 일일 사용량을 확인합니다.

권장사항

이러한 권장사항을 구현하면 통합이 원활하게 실행되고, 예기치 않은 할당량 오류를 방지하며, 판매자 센터 리소스를 효율적으로 활용할 수 있습니다.

요청 배포 최적화

요청을 균등하게 분산: 대량의 요청을 한 번에 보내지 마세요. 일일 API 호출을 하루 종일 균등하게 분산하여 분당 할당량 한도 (quotaMinuteLimit)를 초과하지 않도록 합니다.
사전 제한: 애플리케이션에서 클라이언트 측 비율 제한 (제한)을 구현합니다. Google 서버에만 과도한 트래픽을 거부하도록 의존하지 마세요. 소스에서 요청 비율을 제어합니다.

정상적인 오류 처리

HTTP 429 처리: 애플리케이션은 429 요청이 너무 많음 오류 (quota/request_rate_too_high)를 처리할 수 있도록 준비되어야 합니다.
지터가 있는 지수 백오프: 실패한 요청을 재시도할 때는(특히 429 이후) 지수 백오프 (대기 시간 증가)를 사용하고 '지터'(임의 지연)를 추가합니다. 지터는 여러 클라이언트 인스턴스가 정확히 동시에 재시도하여 서버에 다시 과부하가 걸리는 '재시도 폭풍'을 방지합니다.
재시도 힌트 준수: API 응답에 재시도 세부정보 또는 헤더가 포함되어 있으면 이를 사용하여 호출을 재개할 시점을 결정합니다.

중복 호출 최소화

오래된 호출 방지 (404 NOT_FOUND): 더 이상 존재하지 않는 리소스를 요청하거나 삭제하지 마세요. 실패한 호출도 API 할당량을 사용합니다. 판매자 센터 API 진단에서 NOT_FOUND 오류를 모니터링하여 오래된 상태 추적 또는 불필요한 폴링을 감지합니다.
업데이트 전 확인: 업데이트 요청을 보내기 전에 데이터가 실제로 변경되었는지 확인합니다. 동일한 값을 쓰는 업데이트는 보내지 마세요.
캐싱 사용: 변경되지 않은 데이터에 대한 반복적인 get 또는 list 호출을 방지하기 위해 적절한 경우 읽기 응답 (예: 제품 세부정보, 설정)을 로컬에 캐시합니다.

할당량 계층 구조 및 예외 탐색

고급 계정 및 하위 계정: 고급 계정인 경우 호출이 고급 계정 공유 풀에 대해 계산되도록 하려면 고급 계정 수준에서 인증합니다.
listSubaccounts 사용: 고급 계정의 경우 accounts.list 대신 accounts.listSubaccounts를 사용합니다. accounts.list 할당량은 호출 사용자 (MC ID가 아님)에게 청구되며 표준 진단에 표시되지 않습니다. listSubaccounts는 MCA 할당량에 대해 계산됩니다.

Overview

Merchant Center limits