제품 컬렉션

Product Collections는 관련 제품(예: Starter, Pro, Enterprise 플랜)을 하나의 그룹으로 묶습니다. 모든 옵션을 단일 checkout에 표시하고, 업그레이드/다운그레이드 경로를 정의하며, 고객이 Customer Portal에서 직접 플랜을 변경하도록 할 수 있습니다.

주요 하이라이트

Product Collections를 사용하면 다음을 수행할 수 있습니다:

관련 제품(플랜, 티어, 가격 옵션)을 그룹화하여 체계적으로 관리합니다.
Starter, Pro, Lifetime 등 여러 제품을 포함하며, 각 제품은 자체 pricing model을 가질 수 있습니다.
모든 제품을 하나의 checkout 화면에 표시하여 고객이 원하는 플랜을 비교하고 선택할 수 있습니다.
Customer Portal을 통해 동일한 collection 내 제품 간 업그레이드 또는 다운그레이드를 허용합니다.
표시할 제품, 표시 순서, checkout 시 미리 선택할 제품을 제어합니다.

Product Collection 생성

dashboard 또는 API를 통해 collection을 생성하고 관리합니다.

Create the collection

이름과 선택적 설명을 사용하여 collection을 정의합니다. checkout에서 collection을 나타낼 이미지를 업로드합니다.

dashboard의 Product Collection 생성 양식에서 이름, 설명, 이미지 업로드 필드를 보여 주는 스크린샷

Collection 필드:

Name(필수): 표시 이름(예: “SaaS Plans”, “License Tiers”).
Description(선택 사항): checkout에 표시되는 간단한 설명.
Image(선택 사항): collection을 나타내는 시각적 branding.

Add products to the collection

기존 제품을 collection에 추가합니다. 더 나은 구조를 위해 제품을 그룹으로 구성합니다.

Product Collection 제품 페이지에서 제품 목록과 collection에 제품을 추가하는 기능을 보여 주는 스크린샷

제품 구성:

Groups: 선택적으로 제품을 이름이 지정된 그룹(예: “Monthly Plans”, “Annual Plans”)으로 구성합니다.
Ungrouped products: 그룹에 속하지 않은 제품은 collection 수준에 표시됩니다.
Ordering: 드래그 앤 드롭으로 표시 순서를 설정합니다.

각 제품은 하나의 collection에만 속할 수 있습니다. 제품이 이미 다른 collection에 있다면 먼저 해당 collection에서 제거합니다.

Configure ordering and visibility

collection 내 제품의 표시 순서와 공개 여부를 제어합니다.Configuration 옵션:

Product status: collection 내 개별 제품을 활성화하거나 비활성화합니다.
Display order: 드래그 앤 드롭으로 checkout에 제품이 표시되는 순서를 설정합니다.

collection의 첫 번째 제품은 checkout에서 자동으로 미리 선택됩니다. 제품 순서를 변경하여 기본 선택 제품을 바꿀 수 있습니다.

Collection Checkout

Collection은 고객이 한곳에서 사용 가능한 모든 제품을 확인하고 선택할 수 있는 통합 checkout 경험을 제공합니다.

Checkout 유형

유형	설명	사용 사례
Collection Checkout	collection 내 모든 활성 제품을 표시합니다	구독 플랜 선택, tiered pricing
Single Product Checkout	하나의 특정 제품만 표시합니다	직접 구매, 프로모션 링크

Collection Checkout 경험

collection checkout을 사용하는 경우:

collection의 모든 활성 제품이 표시됩니다.
collection 순서의 첫 번째 제품이 자동으로 미리 선택됩니다.
각 제품에 이름, 설명, 가격이 표시됩니다.
고객이 구매할 제품 하나를 선택합니다.
선택한 제품의 가격 및 billing 설정으로 checkout이 진행됩니다.

여러 제품이 표시된 Product Collection checkout 페이지의 스크린샷

Collection checkout은 고객이 구매 전에 플랜을 나란히 비교하는 구독 비즈니스에 적합합니다.

API Integration

collection용 checkout session을 생성합니다:

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'
});

window.location.href = session.checkout_url;

product_collection_id을 사용할 때는 session 생성 시 discount code를 미리 적용할 수 없습니다. 활성화되어 있다면 고객은 checkout 중에 코드를 입력할 수 있습니다.

Customer Portal Integration

고객은 Customer Portal에서 동일한 collection 내 제품 간 업그레이드 또는 다운그레이드를 직접 수행할 수 있습니다.

이미 subscription 제품을 보유하고 있나요? 해당 제품을 Product Collection에 추가하여 Customer Portal에서 업그레이드/다운그레이드 흐름을 활성화합니다. 제품을 다시 생성할 필요가 없습니다.

플랜 관리 작업

작업	설명	Merchant 제어
View Current Plan	현재 제품 이름, 가격, 갱신 날짜를 표시합니다.	항상 사용 가능.
Upgrade Plan	동일한 collection 내 더 높은 티어의 제품으로 이동합니다.	구성 가능(기본값: 비활성화).
Downgrade Plan	동일한 collection 내 더 낮은 티어의 제품으로 이동합니다.	구성 가능(기본값: 비활성화).
Cancel	subscription을 완전히 취소합니다.	항상 사용 가능.

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

업그레이드와 다운그레이드는 동일한 collection 내 제품 간에만 사용할 수 있습니다.
Customer Portal 플랜 변경의 Proration은 Settings → Subscriptions의 기본 업그레이드 및 다운그레이드 동작을 따르며, 각 collection에서 이러한 기본값을 재정의할 수 있습니다. Change Plan API를 통해 변경한 플랜은 요청과 함께 전송된 proration_billing_mode을 사용합니다.
업그레이드, 다운그레이드 또는 취소가 발생할 때마다 business에 email notification이 전송됩니다.

고객은 현재 collection 외부의 제품으로 변경할 수 없습니다. 서로 다른 제품 라인에는 별도의 collection을 생성합니다.

Subscription Settings

dashboard의 Settings → Subscriptions에서 business 전체의 subscription 및 플랜 변경 작동 방식을 구성합니다.

사용 가능한 Settings

Setting	설명	기본값
Allow Multiple Subscriptions	고객이 동시에 하나 이상의 활성 subscription을 보유할 수 있습니다.	활성화됨
Allow Subscription Updates	고객이 Customer Portal을 통해 언제든 기존 subscription을 업그레이드하거나 다운그레이드할 수 있습니다.	비활성화됨
Allow Immediate Cancellation	고객이 subscription을 종료하고 즉시 access 권한을 잃을 수 있습니다.	활성화됨
Allow Cancellation at Next Billing Date	고객이 이미 결제한 기간이 끝날 때 subscription을 취소할 수 있습니다.	활성화됨
Allow Subscription Pause	고객이 Customer Portal에서 직접 subscription을 일시 중지하고 재개할 수 있습니다.	비활성화됨
Bill Usage at Pause	사용량 기반 subscription을 일시 중지하는 순간 미지급 사용량이 invoice로 청구되며, 다음 정기 invoice로 이월되지 않습니다.	활성화됨
Prevent Trial Misuse	이미 trial을 사용한 고객은 새 trial을 받는 대신 유료 및 trial 없는 구매로 전환됩니다.	비활성화됨
Payment Method Reminder	Card-Optional at Zero Price subscription의 고객에게 payment method 추가를 요청하는 email을 billing 시작 며칠 전에 보낼지 설정합니다(1~30일).	3일

Customer Portal을 통한 플랜 변경은 기본적으로 비활성화되어 있습니다. 고객이 동일한 collection 내 제품 간에 업그레이드 또는 다운그레이드할 수 있도록 Settings → Subscriptions에서 “Allow Subscription Updates”를 활성화합니다.

두 cancellation setting은 서로 독립적이므로, 고객이 이미 결제한 기간을 끝까지 사용하도록 허용하면서 즉시 취소는 직접 처리하도록 하거나 그 반대로 설정할 수 있습니다. 하나를 끄면 Customer Portal에서 해당 옵션이 숨겨지고 Customer Portal API를 통한 해당 요청이 거부됩니다. 자체 merchant 측 취소에는 영향을 주지 않습니다. Cancelling a Subscription을 참조하세요.

“Allow Subscription Pause”는 Customer Portal에만 적용됩니다. 설정과 관계없이 dashboard 또는 API에서 subscription을 일시 중지하고 재개할 수 있습니다. “Bill Usage at Pause”는 사용량 기반 subscription에만 적용되며 billing cycle별로 기록되므로, cycle 중간에 설정을 변경해도 진행 중인 cycle의 정산 방식은 바뀌지 않습니다. Pausing and Resuming Subscriptions을 참조하세요.

trial 사용이 어떻게 매칭되고 기록되는지에 대한 자세한 내용은 Preventing Trial Misuse을 참조하세요.

“Payment Method Reminder”는 Card-Optional at Zero Price가 활성화된 subscription에만 적용됩니다. 이미 card가 필요한 subscription에는 영향을 주지 않습니다. reminder를 무시한 경우를 포함한 전체 순서는 What Happens Without a Card을 참조하세요.

Subscription Plan Changes

Proration mode와 플랜 변경 동작에 대해 자세히 알아보세요.

Collection 관리

dashboard 또는 API를 통해 programmatically collection을 관리합니다.

Dashboard 작업

Create: 제품 및 그룹을 포함한 새 collection을 설정합니다.
Update: 이름, 설명, 이미지 및 제품 구성을 수정합니다.
Reorder: 드래그 앤 드롭으로 제품 표시 순서를 변경합니다.
Enable/Disable products: checkout에 표시할 제품을 제어합니다.
Archive: collection을 영구 삭제하지 않고 숨깁니다(나중에 archive를 해제할 수 있음).

collection 관리 작업을 보여 주는 Product Collection dashboard의 스크린샷

API Management

다음 endpoint를 사용하여 중첩된 그룹과 제품 관리를 포함한 product collection의 생성, 수정, 조회, archive 및 구성을 programmatically 수행합니다.

Listing Product Collections

GET request를 사용하여 계정과 연결된 모든 product collection을 조회합니다. pagination, brand별 filtering 및 archived collection 포함을 지원합니다.

List Product Collections API

List Product Collections API documentation에서 자세한 request 및 response 구조를 확인하세요.

Creating a Product Collection

이름, 설명, brand 등의 세부 정보와 함께 POST request를 /product-collections endpoint로 전송하여 새 product collection을 생성합니다.

Create Product Collection API

Create Product Collection API documentation에서 자세한 request 및 response 구조를 확인하세요.

Retrieving a Product Collection

GET request를 /product-collections/{id} endpoint로 전송하여 특정 product collection의 그룹 및 product item을 포함한 자세한 정보를 조회합니다.

Get Product Collection API

Get Product Collection API documentation에서 자세한 request 및 response 구조를 확인하세요.

Updating a Product Collection

PATCH request를 /product-collections/{id} endpoint로 전송하여 product collection의 세부 정보(이름, 설명, brand 등)를 수정합니다.

Update Product Collection API

Update Product Collection API documentation에서 자세한 request 및 response 구조를 확인하세요.

Uploading Collection Images

pre-signed URL을 통해 이미지를 업로드하여 collection에 연결합니다. /product-collections/{id}/images endpoint에서 upload URL을 요청한 다음 60초 이내에 반환된 URL로 이미지를 PUT합니다.

pre-signed URL은 60초 후 만료되므로 해당 시간 내에 이미지를 업로드해야 합니다.

Update Collection Images API

Update Collection Images API documentation에서 자세한 request 및 response 구조를 확인하세요.

Archiving a Product Collection

DELETE request를 /product-collections/{id} endpoint로 전송하여 collection을 archive합니다. 이렇게 하면 collection이 새 사용처에서 숨겨지지만 영구적으로 삭제되지는 않습니다.

Archive Product Collection API

Archive Product Collection API documentation에서 자세한 request 및 response 구조를 확인하세요.

Unarchiving a Product Collection

POST request를 /product-collections/{id}/unarchive endpoint로 전송하여 archived collection을 복원합니다.

Unarchive Product Collection API

Unarchive Product Collection API documentation에서 자세한 request 및 response 구조를 확인하세요.

Managing Groups within a Collection

그룹을 사용하면 collection 내 제품을 구성할 수 있습니다(예: “Monthly Plans”와 “Annual Plans”). groups endpoint를 사용하여 collection 내 그룹을 추가, 수정 또는 제거합니다.

Create a group: POST /product-collections/{id}/groups
Update a group: PATCH /product-collections/{id}/groups/{group_id}
Delete a group: DELETE /product-collections/{id}/groups/{group_id}

Create Group

product collection에 새 그룹을 추가합니다.

Update Group

그룹의 이름 또는 attribute를 수정합니다.

Delete Group

collection에서 그룹을 제거합니다.

Managing Products within a Group

그룹 내부의 개별 product item을 관리합니다. 새 제품을 추가하고, 기존 item(예: 표시 순서)을 수정하거나, 완전히 제거할 수 있습니다.

Add products to a group: POST /product-collections/{id}/groups/{group_id}/items
Update a group item: PATCH /product-collections/{id}/groups/{group_id}/items/{item_id}
Delete a group item: DELETE /product-collections/{id}/groups/{group_id}/items/{item_id}

Add Products to Group

collection 내 그룹에 하나 이상의 제품을 추가합니다.

Update Group Item

그룹 내 product item을 업데이트합니다.

Delete Group Item

그룹에서 product item을 제거합니다.

Best Practices

논리적으로 그룹화: billing interval(월간/연간) 또는 feature tier(starter/pro/enterprise)를 기준으로 제품을 구성합니다.
전략적으로 정렬: 가장 인기 있거나 추천하는 플랜을 첫 번째에 배치합니다. checkout에서 해당 플랜이 미리 선택되기 때문입니다.
명확한 이름 사용: 제품 이름만으로도 가치의 차이를 명확히 전달해야 합니다.
양방향 활성화: 고객에게 유연성을 제공하도록 업그레이드와 다운그레이드를 모두 허용합니다.
Proration 고려: business model에 적합한 proration mode를 선택합니다.
철저히 테스트: live 환경으로 전환하기 전에 test mode에서 checkout 및 플랜 변경 흐름을 확인합니다.

Products

컬렉션에 추가할 일회성, 구독 또는 사용량 기반 제품을 생성합니다.

Checkout

통합된 Checkout 환경에서 컬렉션 제품을 표시합니다.

Customer Portal

고객이 동일한 컬렉션 내에서 업그레이드하거나 다운그레이드할 수 있도록 합니다.

Subscriptions

proration 및 플랜 변경을 사용하여 반복 결제 플랜을 관리합니다.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

주요 하이라이트

Product Collection 생성