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

직접 API 호출

Merchant API와 상호작용하는 이 접근 방식에서는 일반적으로 HTTP(S)를 통해 API 엔드포인트에 직접 원시 요청을 합니다. 요청 본문 구성, 헤더 설정 (인증 포함), 응답 파싱과 같은 측면을 수동으로 처리합니다.

1단계: 개발자로 등록

Merchant API를 사용하려면 개발자 연락처 정보를 등록해야 합니다.

등록을 통해 다음을 수행할 수 있습니다.

사용자에게 API developer 역할을 할당하여 판매자 센터 계정의 기술 담당자를 만듭니다. 이를 통해 Google은 개발자가 사용하는 API 및 기능에 관한 중요한 업데이트(예: 서비스 공지사항, 새로운 기능에 관한 정보)를 개발자가 아닌 사용자에게는 관심이 없을 수 있는 정보와 함께 전송할 수 있습니다.
여러 번 등록하지 않고도 여러 판매자 계정으로 작업할 수 있습니다. 등록하면 Merchant API를 인증하는 데 사용되는 Google Cloud 프로젝트 ID가 기술 담당자 (API developer)가 있는 판매자 센터 계정과 연결됩니다. 이렇게 하면 등록된 Google Cloud 프로젝트로 인증하는 한 관리하는 모든 판매자 계정에 관한 중요한 업데이트를 받을 수 있습니다.

등록 시 등록에 자세히 설명된 기본 요건 및 제한사항을 준수하세요.

developerRegistration.registerGcp 메서드를 사용하여 등록하려면 이 예시로 시작하여 요청 본문의 {DEVELOPER_EMAIL}을(를) 적절한 이메일 주소로 바꾸세요.

POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp

{
  "developerEmail": "{DEVELOPER_EMAIL}"
}

호출이 성공하면 프로젝트와 계정 간의 연결을 확인하는 DeveloperRegistration 리소스가 반환됩니다.

{
  "name": "accounts/{ACCOUNT_ID}/developerRegistration",
  "gcpIds": [
    "123456789012345"
  ]
}

2단계: 개발자 연락처 및 권한 관리

등록 시 다음을 수행합니다.

이메일 주소가 판매자 센터 계정의 사용자에게 속한 경우 해당 사용자에게 API_DEVELOPER 역할이 부여됩니다.
이메일 주소가 기존 사용자에게 속하지 않는 경우 해당 주소로 초대장이 전송됩니다. 수신자는 API_DEVELOPER 역할이 있는 새 사용자로 추가되려면 초대를 수락해야 합니다.

초기 등록 후에는 여러 개발자를 추가하고 추가 액세스 권한을 부여하는 것이 좋습니다.

2a단계. 추가 권한 부여

API_DEVELOPER 역할은 중요한 알림을 받는 데 필요하지만 판매자 센터 내에서 최소한의 권한만 있습니다. 이 사용자가 다른 API 호출을 하거나 판매자 센터 UI에서 설정을 관리하도록 허용하려면 STANDARD 또는 ADMIN과 같은 추가 역할을 부여해야 합니다. 자세한 내용은 액세스 유형을 참고하세요.

accounts.users.patch 메서드를 사용하여 사용자의 액세스 권한을 업데이트할 수 있습니다.

다음 예시는 사용자에게 ADMIN 역할과 API_DEVELOPER 역할을 모두 부여하도록 사용자를 업데이트하는 방법을 보여줍니다. 이렇게 하면 사용자가 계정을 완전히 관리할 수 있으며 API 관련 커뮤니케이션도 수신하게 됩니다.

PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/users/{DEVELOPER_EMAIL}?update_mask=access_rights

{
  "access_rights": [
    "ADMIN",
    "API_DEVELOPER"
  ]
}

2b단계. 백업 개발자 추가

기본 개발자 연락처가 조직을 떠나는 경우 API 액세스가 중단되지 않도록 하려면 백업 개발자를 한 명 이상 추가해야 합니다.

accounts.users.create 메서드를 사용하여 사용자를 추가하거나 accounts.users.patch를 사용하여 사용자를 업데이트할 수 있습니다. 이 사용자에게 ADMIN 역할과 API_DEVELOPER 역할을 모두 부여하는 것이 좋습니다.

3단계: 기본 제품 데이터 소스 만들기

제품을 삽입하려면 기본 제품 데이터 소스가 필요합니다. 다음 요청은 계정에 제품을 삽입하는 데 사용할 수 있는 데이터 소스를 만드는 방법을 보여줍니다.

POST https://merchantapi.googleapis.com/datasources/v1/accounts/{ACCOUNT_ID}/dataSources

{
  "primaryProductDataSource": {
    "contentLanguage": "en",
    "countries": [
      "US"
    ],
    "feedLabel": "US"
  },
  "name": "primary-data-source",
  "displayName": "Primary Products Data Source"
}

{ACCOUNT_ID}를 만든 판매자 센터 계정의 ID로 바꿉니다.

이 요청을 실행하면 다음 응답이 표시됩니다.

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "Primary Products Data Source",
  "primaryProductDataSource": {
    "feedLabel": "US",
    "contentLanguage": "en",
    "countries": [
      "US"
    ],
    "defaultRule": {
      "takeFromDataSources": [
        {
          "self": true
        }
      ]
    }
  },
  "input": "API"
}

name 필드 값을 복사합니다. 제품을 삽입하는 데 필요합니다.

판매자 센터 UI에서 이 데이터 소스를 볼 수 있습니다. 자세한 내용은 다음 데이터 소스 탭을 찾는 방법을 참고하세요.

4단계: 제품 삽입

데이터 소스를 만든 후 제품을 삽입해 보세요. 올바른 ACCOUNT_ID를 제공하여 다음을 실행합니다. {DATASOURCE_NAME}을 이전에 복사한 값으로 바꿉니다.

POST https://merchantapi.googleapis.com/products/v1/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource={DATASOURCE_NAME}
{
  "contentLanguage": "en",
  "feedLabel": "US",
  "name": "Red T-shirt",
  "productAttributes": {
    "gender": "MALE",
    "brand": "New brand"
  },
  "offerId": "tshirt-123"
}