> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 제품 컬렉션

> 관련 제품을 함께 그룹화하여 통합 결제 경험, 계획 선택 및 고객 포털 내 원활한 업그레이드/다운그레이드 경로를 제공합니다.

<Info>
  Product Collections를 사용하면 관련 제품(예: Starter, Pro, Enterprise 요금제)을 하나의 묶음으로 그룹화할 수 있습니다. 하나의 체크아웃에 모든 옵션을 표시하고 업그레이드/다운그레이드 경로를 정의하며, 고객이 Customer Portal에서 요금제를 직접 변경할 수 있도록 유연성을 제공합니다.
</Info>

<Frame>
  <img src="https://mintcdn.com/dodopayments/2YrxTqbaYgAm54C_/images/product-collection/checkout-page.png?fit=max&auto=format&n=2YrxTqbaYgAm54C_&q=85&s=1890932384bc32c8126c7993f3581855" alt="여러 제품이 표시된 제품 컬렉션 체크아웃 페이지의 스크린샷" style={{ maxHeight: '500px', width: 'auto' }} width="1440" height="960" data-path="images/product-collection/checkout-page.png" />
</Frame>

## 주요 하이라이트

* **컬렉션 기반 구조**: 관련 제품(플랜, 계층, 가격 옵션)을 단일 컬렉션 아래 그룹화하여 조직적으로 관리합니다.
* **하나의 컬렉션, 여러 제품**: 스타터, 프로, 라이프타임 등 각기 다른 가격 모델을 가진 여러 제품을 포함합니다.
* **동적 체크아웃 경험**: 컬렉션의 모든 제품을 하나의 체크아웃 뷰에서 표시하여 고객이 선호하는 플랜을 선택할 수 있도록 합니다.
* **상인 수준 제어**: 각 컬렉션 내에서 제품을 활성화, 비활성화 및 재배치할 수 있습니다. 첫 번째 제품은 체크아웃 시 자동으로 기본 선택됩니다.
* **생애 주기 인식**: 고객이 고객 포털을 통해 동일한 컬렉션 내에서 제품 업그레이드 또는 다운그레이드할 수 있도록 합니다.

## 제품 컬렉션 생성하기

제품 컬렉션은 대시보드 또는 API를 통해 생성 및 관리됩니다. 각 컬렉션은 관련 제품의 컨테이너 역할을 합니다.

<Steps>
  <Step title="Create the collection">
    컬렉션을 이름과 선택적 설명으로 정의합니다. 체크아웃에서 컬렉션을 시각적으로 나타낼 수 있도록 이미지를 업로드하세요.

    <Frame>
      <img src="https://mintcdn.com/dodopayments/2YrxTqbaYgAm54C_/images/product-collection/collection-form.png?fit=max&auto=format&n=2YrxTqbaYgAm54C_&q=85&s=4740b9da84da8c24177a9592549222af" alt="대시보드에서 이름, 설명, 이미지 업로드 필드가 표시된 제품 컬렉션 생성 폼의 스크린샷" style={{ maxHeight: '500px', width: 'auto' }} width="1440" height="960" data-path="images/product-collection/collection-form.png" />
    </Frame>

    **컬렉션 필드:**

    * **이름** (필수): 컬렉션의 표시 이름 (예: "SaaS 플랜", "라이센스 계층")
    * **설명** (선택): 체크아웃에 표시되는 간략한 설명
    * **이미지** (선택): 컬렉션의 시각적 브랜딩
  </Step>

  <Step title="Add products to the collection">
    기존 제품을 컬렉션에 추가하세요. 제품은 더 나은 구조를 위해 그룹으로 구성할 수 있습니다.

    <Frame>
      <img src="https://mintcdn.com/dodopayments/2YrxTqbaYgAm54C_/images/product-collection/collection-form-products.png?fit=max&auto=format&n=2YrxTqbaYgAm54C_&q=85&s=41b2da4d40e8dd9a12d059f4fa3f285f" alt="제품 컬렉션 제품 페이지의 스크린샷으로, 제품 목록과 컬렉션에 추가할 수 있는 기능이 표시됨" style={{ maxHeight: '500px', width: 'auto' }} width="1440" height="960" data-path="images/product-collection/collection-form-products.png" />
    </Frame>

    **제품 조직:**

    * **그룹**: 선택적으로 제품을 이름이 있는 그룹으로 조직합니다 (예: "월간 플랜", "연간 플랜")
    * **그룹에 포함되지 않은 제품**: 그룹이 없는 제품은 컬렉션 수준에 표시됩니다.
    * **정렬**: 드래그 앤 드롭으로 표시 순서를 설정합니다.

    <Warning>
      각 제품은 하나의 컬렉션에만 속할 수 있습니다. 제품이 다른 컬렉션에 이미 포함되어 있다면 먼저 제거해야 합니다.
    </Warning>
  </Step>

  <Step title="Configure ordering and visibility">
    컬렉션 내 제품의 표시 순서와 가시성을 제어하세요.

    **구성 옵션:**

    * **제품 상태**: 컬렉션 내에서 개별 제품을 활성화 또는 비활성화합니다.
    * **표시 순서**: 드래그 앤 드롭으로 체크아웃 시 제품이 표시되는 순서를 설정합니다.

    <Info>
      컬렉션의 첫 번째 제품이 체크아웃 시 자동으로 기본 선택됩니다. 제품 순서를 변경하여 기본 선택 제품을 조정하세요.
    </Info>
  </Step>
</Steps>

## 컬렉션 체크아웃

컬렉션은 고객이 한 곳에서 모든 사용 가능한 제품을 보고 선택할 수 있는 통합 체크아웃 경험을 제공합니다.

### 체크아웃 유형

| 유형             | 설명                | 사용 사례            |
| -------------- | ----------------- | ---------------- |
| **컬렉션 체크아웃**   | 컬렉션 내 모든 활성 제품 표시 | 구독 플랜 선택, 계층형 가격 |
| **단일 제품 체크아웃** | 특정 제품 하나만 표시      | 직접 구매, 프로모션 링크   |

### 컬렉션 체크아웃 경험

컬렉션 체크아웃을 사용할 때:

1. **모든 활성 제품이 표시됨**: 고객은 컬렉션에 있는 모든 활성 제품을 봅니다.
2. **첫 번째 제품이 기본 선택됨**: 컬렉션의 첫 번째 제품이 자동으로 선택됩니다.
3. **제품 세부정보 표시됨**: 각 제품은 이름, 설명 및 가격을 표시합니다.
4. **단일 선택**: 고객이 구매할 제품 하나를 선택합니다.
5. **표준 흐름 계속**: 선택 후 체크아웃은 선택한 제품의 가격 및 청구 설정으로 진행됩니다.

<Frame>
  <img src="https://mintcdn.com/dodopayments/2YrxTqbaYgAm54C_/images/product-collection/checkout-page.png?fit=max&auto=format&n=2YrxTqbaYgAm54C_&q=85&s=1890932384bc32c8126c7993f3581855" alt="여러 제품이 표시된 제품 컬렉션 체크아웃 페이지의 스크린샷" style={{ maxHeight: '500px', width: 'auto' }} width="1440" height="960" data-path="images/product-collection/checkout-page.png" />
</Frame>

<Tip>
  컬렉션 체크아웃은 고객이 구매 전에 요금제를 나란히 비교하길 원하는 구독 비즈니스에 이상적입니다.
</Tip>

### API 통합

컬렉션을 위해 체크아웃 세션을 생성합니다:

```typescript theme={null}
const session = await client.checkoutSessions.create({
  product_collection_id: 'pdc_abc123',
  product_cart: [], // Required: pass an empty array for collection checkout
  return_url: 'https://yoursite.com/return'
});

// Redirect customer to the checkout
window.location.href = session.checkout_url;
```

<Warning>
  `product_collection_id`를 사용 중일 때는 세션 생성 시 할인 코드를 적용할 수 없습니다. 설정이 활성화된 경우 고객은 체크아웃 중에 할인 코드를 입력할 수 있습니다.
</Warning>

## 고객 포털 통합

고객은 동일한 컬렉션 내에서 제품을 업그레이드 또는 다운그레이드할 수 있습니다.

<Tip>
  **이미 구독 제품이 있나요?** Product Collection에 추가하면 Customer Portal에서 업그레이드/다운그레이드 흐름을 활성화할 수 있습니다. 제품을 다시 만들 필요는 없습니다.
</Tip>

### 요금제 관리 작업

| 작업             | 설명                     | 판매자 제어            |
| -------------- | ---------------------- | ----------------- |
| **현재 요금제 보기**  | 현재 제품 이름, 가격, 갱신 날짜 표시 | 항상 사용 가능          |
| **요금제 업그레이드**  | 동일 컬렉션 내 상위 제품으로 이동    | 구성 가능합니다(기본값: 허용) |
| **요금제 다운그레이드** | 동일 컬렉션 내 하위 제품으로 이동    | 구성 가능합니다(기본값: 허용) |
| **취소**         | 구독 전체를 취소              | 항상 사용 가능          |

<Frame>
  <img src="https://mintcdn.com/dodopayments/2YrxTqbaYgAm54C_/images/product-collection/portal.png?fit=max&auto=format&n=2YrxTqbaYgAm54C_&q=85&s=9b9d302907688238f6b84c10b85504aa" alt="계획 관리 작업이 표시된 제품 컬렉션 고객 포털 플랜 변경 인터페이스의 스크린샷" style={{ maxHeight: '500px', width: 'auto' }} width="2870" height="1654" data-path="images/product-collection/portal.png" />
</Frame>

### 업그레이드/다운그레이드 규칙

* 업그레이드 및 다운그레이드는 **같은 컬렉션 내** 제품 간에서만 가능합니다
* 과금은 구독 설정에 따라 계산됩니다
* 업그레이드, 다운그레이드, 취소 시마다 이메일 알림이 사업체에 전송됩니다

<Frame>
  <img src="https://mintcdn.com/dodopayments/2YrxTqbaYgAm54C_/images/product-collection/portal-change-plan.png?fit=max&auto=format&n=2YrxTqbaYgAm54C_&q=85&s=e4fe60146a7d8436753a36a79f902a6d" alt="계획 관리 작업이 표시된 제품 컬렉션 고객 포털 플랜 변경 인터페이스의 스크린샷" style={{ maxHeight: '500px', width: 'auto' }} width="832" height="928" data-path="images/product-collection/portal-change-plan.png" />
</Frame>

<Info>
  고객은 현재 컬렉션 외부의 제품으로 변경할 수 없습니다. 별도의 제품 라인마다 별도 컬렉션을 만드세요.
</Info>

## 구독 설정

대시보드의 **설정 → 구독**에서 비즈니스 전반에 걸쳐 구독 및 플랜 변경이 작동하는 방식을 구성합니다.

<Frame>
  <img src="https://mintcdn.com/dodopayments/2YrxTqbaYgAm54C_/images/product-collection/business-settings.png?fit=max&auto=format&n=2YrxTqbaYgAm54C_&q=85&s=9ed2f332336aab522b5238ce7218d8ae" alt="여러 구독 허용 및 구독 업데이트 허용 토글이 표시된 구독 설정 페이지의 스크린샷" style={{ maxHeight: '500px', width: 'auto' }} width="1440" height="960" data-path="images/product-collection/business-settings.png" />
</Frame>

### 사용 가능한 설정

| 설정             | 설명                                                          | 기본값   |
| -------------- | ----------------------------------------------------------- | ----- |
| **다중 구독 허용**   | 고객이 동시에 둘 이상의 활성 구독을 가질 수 있습니다                              | 활성화됨  |
| **구독 업데이트 허용** | 고객이 Customer Portal을 통해 언제든지 기존 구독을 업그레이드하거나 다운그레이드할 수 있습니다 | 비활성화됨 |

<Info>
  고객 포털을 통한 플랜 변경은 기본적으로 비활성화되어 있습니다. **설정 → 구독**에서 "구독 업데이트 허용"을 활성화하여 고객이 동일한 컬렉션 내에서 제품 간에 업그레이드하거나 다운그레이드할 수 있도록 합니다.
</Info>

<Card title="Subscription Plan Changes" icon="repeat" href="/features/subscription#subscription-plan-changes">
  과금 모드 및 요금제 변경 동작에 대해 자세히 알아보세요.
</Card>

## 컬렉션 관리

제품 컬렉션은 Dodo Payments 대시보드를 통해 또는 API를 통해 프로그래밍 방식으로 관리할 수 있습니다. API는 컬렉션 생성, 업데이트, 이미지 업로드, 아카이빙 및 중첩 그룹 및 제품 관리를 완벽하게 제어할 수 있게 합니다.

### 대시보드 작업

* **생성**: 제품 및 그룹을 사용하여 새로운 컬렉션 설정
* **업데이트**: 이름, 설명, 이미지 및 제품 구성 수정
* **재정렬**: 드래그 앤 드롭으로 제품 표시 순서 변경
* **제품 활성화/비활성화**: 결제 시 나타나는 제품 제어
* **아카이브**: 컬렉션을 영구 삭제하지 않고 숨기기 (나중에 아카이브 해제 가능)

<Frame>
  <img src="https://mintcdn.com/dodopayments/2YrxTqbaYgAm54C_/images/product-collection/collection-dashboard.png?fit=max&auto=format&n=2YrxTqbaYgAm54C_&q=85&s=0fee5cdfe68c770b7cdb1d0f8e817b5b" alt="컬렉션 관리 작업을 보여주는 제품 컬렉션 대시보드 스크린샷" style={{ maxHeight: '500px', width: 'auto' }} width="1440" height="960" data-path="images/product-collection/collection-dashboard.png" />
</Frame>

### API 관리

다음 엔드포인트를 사용하면 컬렉션 생성, 업데이트, 조회, 아카이브 및 제품 컬렉션을 프로그래밍 방식으로 구성할 수 있으며, 중첩 그룹 및 그 내의 제품도 관리할 수 있습니다.

<AccordionGroup>
  <Accordion title="Listing Product Collections">
    `GET` 요청을 `/product-collections` 엔드포인트로 보내 계정과 관련된 모든 제품 컬렉션을 가져옵니다. 페이지 매김, 브랜드별 필터링 및 아카이브된 컬렉션 포함을 지원합니다.

    <Card title="List Product Collections API" icon="code" href="/api-reference/product-collections/list-product-collections">
      목록 제품 컬렉션 API 문서에서 자세한 요청 및 응답 구조를 확인합니다.
    </Card>
  </Accordion>

  <Accordion title="Creating a Product Collection">
    새로운 제품 컬렉션을 생성하려면 이름, 설명 및 브랜드 등의 세부 정보를 포함하여 `POST` 요청을 `/product-collections` 엔드포인트로 보냅니다.

    <Card title="Create Product Collection API" icon="code" href="/api-reference/product-collections/create-product-collection">
      생성 제품 컬렉션 API 문서에서 자세한 요청 및 응답 구조를 확인합니다.
    </Card>
  </Accordion>

  <Accordion title="Retrieving a Product Collection">
    특정 제품 컬렉션에 대한 세부 정보를 얻으려면 그룹과 제품 항목을 포함하여 `GET` 요청을 `/product-collections/{id}` 엔드포인트로 보냅니다.

    <Card title="Get Product Collection API" icon="code" href="/api-reference/product-collections/get-product-collection">
      제품 컬렉션 가져오기 API 문서에서 자세한 요청 및 응답 구조를 확인합니다.
    </Card>
  </Accordion>

  <Accordion title="Updating a Product Collection">
    `PATCH` 요청을 `/product-collections/{id}` 엔드포인트로 보내 제품 컬렉션의 세부 사항(이름, 설명, 브랜드 등)을 수정합니다.

    <Card title="Update Product Collection API" icon="code" href="/api-reference/product-collections/update-product-collection">
      업데이트 제품 컬렉션 API 문서에서 자세한 요청 및 응답 구조를 확인합니다.
    </Card>
  </Accordion>

  <Accordion title="Uploading Collection Images">
    미리 서명된 URL을 통해 이미지를 업로드하여 컬렉션에 이미지를 연결합니다. `/product-collections/{id}/images` 엔드포인트에서 업로드 URL을 요청한 후 60초 이내에 반환된 URL에 이미지를 `PUT` 합니다.

    <Warning>
      미리 서명된 URL은 60초 후 만료되므로 그 시간 내에 이미지를 업로드해야 합니다.
    </Warning>

    <Card title="Update Collection Images API" icon="code" href="/api-reference/product-collections/update-product-collection-images">
      컬렉션 이미지 업데이트 API 문서에서 자세한 요청 및 응답 구조를 확인합니다.
    </Card>
  </Accordion>

  <Accordion title="Archiving a Product Collection">
    `DELETE` 요청을 `/product-collections/{id}` 엔드포인트로 보내 컬렉션을 아카이브합니다. 이는 컬렉션을 새 사용에서 숨기지만 영구적으로 제거하지는 않습니다.

    <Card title="Archive Product Collection API" icon="code" href="/api-reference/product-collections/archive-product-collection">
      아카이브 제품 컬렉션 API 문서에서 자세한 요청 및 응답 구조를 확인합니다.
    </Card>
  </Accordion>

  <Accordion title="Unarchiving a Product Collection">
    `POST` 요청을 `/product-collections/{id}/unarchive` 엔드포인트로 보내 아카이브된 컬렉션을 복원합니다.

    <Card title="Unarchive Product Collection API" icon="code" href="/api-reference/product-collections/unarchive-product-collection">
      아카이브 해제 제품 컬렉션 API 문서에서 자세한 요청 및 응답 구조를 확인합니다.
    </Card>
  </Accordion>

  <Accordion title="Managing Groups within a Collection">
    그룹을 통해 컬렉션 내에서 제품을 구성할 수 있습니다 (예: "월간 플랜" 대 "연간 플랜"). 그룹 엔드포인트를 사용하여 컬렉션 내 그룹을 추가, 업데이트 또는 제거하세요.

    * **그룹 생성**: `POST /product-collections/{id}/groups`
    * **그룹 업데이트**: `PATCH /product-collections/{id}/groups/{group_id}`
    * **그룹 삭제**: `DELETE /product-collections/{id}/groups/{group_id}`

    <CardGroup cols={3}>
      <Card title="Create Group" icon="code" href="/api-reference/product-collections/create-group">
        제품 컬렉션에 새 그룹 추가.
      </Card>

      <Card title="Update Group" icon="code" href="/api-reference/product-collections/update-group">
        그룹의 이름 또는 속성 수정.
      </Card>

      <Card title="Delete Group" icon="code" href="/api-reference/product-collections/delete-group">
        컬렉션에서 그룹 제거.
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Managing Products within a Group">
    그룹 내 개별 제품 항목을 관리 — 새 제품 추가, 기존 항목 업데이트(예: 표시 순서) 또는 완전히 제거.

    * **그룹에 제품 추가**: `POST /product-collections/{id}/groups/{group_id}/items`
    * **그룹 항목 업데이트**: `PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}`
    * **그룹 항목 삭제**: `DELETE /product-collections/{id}/groups/{group_id}/items/{item_id}`

    <CardGroup cols={3}>
      <Card title="Add Products to Group" icon="code" href="/api-reference/product-collections/add-group-items">
        컬렉션 내에서 하나 이상의 제품을 그룹에 추가합니다.
      </Card>

      <Card title="Update Group Item" icon="code" href="/api-reference/product-collections/update-group-item">
        그룹 내 제품 항목 업데이트.
      </Card>

      <Card title="Delete Group Item" icon="code" href="/api-reference/product-collections/delete-group-item">
        그룹에서 제품 항목 제거.
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>

## 모범 사례

* **논리적으로 그룹화**: 청구 주기(월간/연간) 또는 기능 계층(스타터/프로/엔터프라이즈)별로 조직
* **전략적으로 주문**: 가장 인기 있거나 추천된 플랜을 가장 먼저 배치하여 결제 시 사전 선택되도록 합니다
* **명확한 이름 사용**: 제품 이름은 가치 차이를 명확하게 전달해야 합니다
* **양방향 활성화**: 고객이 업그레이드 및 다운그레이드할 수 있도록 유연성을 제공합니다
* **비례 배려**: 비즈니스 모델에 맞는 비례 배분 모드를 선택하세요
* **철저히 테스트**: 라이브 전에 테스트 모드에서 결제 및 플랜 변경 흐름을 확인하세요

<Check>
  이제 제품 컬렉션을 생성하고 고객에게 통합된 플랜 선택 경험을 제공할 준비가 되었습니다.
</Check>

<CardGroup cols={2}>
  <Card title="Products" icon="box" href="/features/products">
    컬렉션에 추가할 일회성, 구독 또는 사용 기반 제품 생성.
  </Card>

  <Card title="Checkout" icon="cart-shopping" href="/features/checkout">
    통합 결제 경험에서 컬렉션 제품 표시.
  </Card>

  <Card title="Customer Portal" icon="id-card" href="/features/customer-portal">
    고객이 같은 컬렉션 내에서 업그레이드 또는 다운그레이드할 수 있게 합니다.
  </Card>

  <Card title="Subscriptions" icon="repeat" href="/features/subscription">
    비례 배분 및 플랜 변경으로 반복적인 플랜 관리.
  </Card>
</CardGroup>