장바구니 API 구현

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

엔드포인트를 빌드하기 전에 장바구니 API 개요에서 대략적인 개념과 기본 요건을 검토했는지 확인하세요.

장바구니 만들기

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

• 엔드포인트: POST /carts
• 트리거: 사용자가 제품에서 '장바구니에 추가'를 클릭하고 판매자의 장바구니에 첫 번째 항목을 추가합니다.

요청: 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"
}

오류 처리

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