장바구니 API 구현

이 가이드에서는 버전 2026-04-08에서 범용 커머스 프로토콜 (UCP) 장바구니 API를 통합하기 위한 기술 API 참조 및 페이로드 스키마를 제공합니다.

엔드포인트를 빌드하기 전에 장바구니 API 개요에서 상위 수준 개념과 기본 요건을 검토하세요.

장바구니 만들기

이 엔드포인트를 사용하면 새 장바구니 세션을 만들 수 있습니다. 통합하려면 CreateCart 엔드포인트 (POST /carts)를 구현하세요. 사용자가 장바구니를 전송하도록 선택하면 Google은 모든 항목 세부정보와 함께 이 엔드포인트를 호출합니다. 시스템은 사용자를 사이트에서 미리 입력된 장바구니로 안내하는 continue_url로 응답해야 합니다.

• 엔드포인트: POST /carts
• 트리거: 사용자가 장바구니를 스토어로 트랜스퍼하기 위해 트랜스퍼 버튼 (예: 판매자에서 결제)을 클릭할 때만 단일 CreateCart (POST /carts) 요청이 트리거됩니다.

장바구니 흐름

장바구니 흐름과 상태는 다음과 같이 작동합니다.

• Google에서의 누적: 사용자가 장바구니에 상품을 추가하면 Google에서 해당 상품을 로컬에 누적합니다. 상품이 추가될 때 Google에서 API 호출을 여러 번 실행하지 않습니다.
• 페이로드: 단일 POST /carts 요청에는 누적된 모든 line_items의 전체 배열이 한 번에 포함됩니다.
• 리디렉션 및 상태: 판매자의 백엔드가 웹사이트에서 미리 채워진 장바구니를 가리키는 continue_url로 응답합니다.

요청: Google에서 장바구니에 추가할 line_items 배열을 전송합니다.

요청 예:

{
  "line_items": [
    {
      "item": {
        "id": "item_123"
      },
      "quantity": 2
    }
  ]
}

응답: 항목 세부정보, 합계, continue_url를 포함한 초기화된 장바구니 세션을 반환합니다. 대답의 continue_url 필드는 사용자가 장바구니를 계속 관리할 수 있는 사이트의 페이지로 사용자를 다시 안내해야 합니다. 일반적으로 id로 식별되는 세션이 미리 로드된 장바구니 또는 결제 페이지로 연결됩니다.

응답 예시:

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.cart": [{"version": "2026-04-08"}]
    }
  },
  "id": "cart_abc123",
  "line_items": [
    {
      "id": "li_1",
      "item": {
        "id": "item_123",
        "title": "Red T-Shirt",
        "price": 2500
      },
      "quantity": 2,
      "totals": [
        {"type": "subtotal", "amount": 5000},
        {"type": "total", "amount": 5000}
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 5000
    },
    {
      "type": "total",
      "amount": 5000,
      "display_text": "Estimated total (taxes calculated at checkout)"
    }
  ],
  // Used for redirecting the user back to the merchant's cart experience from Google surfaces.
  "continue_url": "https://business.example.com/checkout?cart=cart_abc123",
  // Indicate the timestamp at which the cart session will expire and become invalid.
  "expires_at": "2026-01-16T12:00:00Z"
}

오류 처리

오류 메시지 형식 지정 방법과 프로토콜 오류와 비즈니스 로직 오류의 차이점에 관한 전체 가이드라인은 오류 코드를 참고하세요.