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

# 구독 업그레이드 문제 해결

> 업그레이드 실패 알림, 공급자 연결 문제, 비어 있는 판매 플랜 드롭다운 등 흔한 구독 업그레이드 문제에 대한 해결책이에요.

가장 흔한 구독 업그레이드 문제에 대한 해결책이에요. 이 방법들을 시도한 후에도 해결되지 않으면 [테스트 및 확인](/ko/aftersell/subscription-upgrades-testing#when-something-looks-wrong)에 나열된 세부 정보와 함께 지원팀에 문의하세요.

<div id="monitoring-upgrade-failures">
  ## 업그레이드 실패 모니터링
</div>

Aftersell은 최근 7일 기준(rolling window)으로 최종 업그레이드 실패를 모니터링해요. 실패 횟수가 알림 임계값을 넘으면, 며칠 동안 몇 건의 업그레이드가 실패했는지 설명하는 **경고 배너**가 홈페이지에 표시돼요. 같은 알림이 [홈페이지](/ko/aftersell/home/needs-attention)의 **Needs attention** 패널에도 나타나요.

알림에는 구독 업그레이드 문제로 필터링된 주문 브라우저로 바로 이동하는 **Review orders** 버튼이 포함되어 있어서, 영향을 받은 주문과 각 실패의 구체적인 원인을 확인할 수 있어요. 이동 기간 내에 실패 횟수가 임계값 아래로 떨어지면 알림이 자동으로 사라져요. 이 알림이 보이면 주문 브라우저를 열어 영향을 받은 각 주문에 표시된 원인을 확인한 다음, 아래의 관련 문제 해결 단계를 참고하세요.

<AccordionGroup>
  <Accordion title="Step 1: Connect provider를 통과할 수 없어요">
    **Subscription Upgrade** 템플릿은 절대 숨겨지지 않아요 — 공급자 설정과 관계없이 항상 **Add Funnel** 아래에 표시돼요. 막히는 것은 Step 1 연결 검사예요: **Test API key**가 초록색 체크와 함께 **API key verified**를 반환할 때까지 **Continue**는 비활성화 상태로 유지돼요.

    두 가지 서로 다른 결과가 동일한 빨간색 취소 아이콘으로 표시되므로, 옆의 메시지를 읽으세요:

    * **공급자가 키를 거부했어요.** 토큰에 필요한 스코프가 누락되었거나 취소된 경우로, 메시지에 구체적인 문제가 표시돼요. [설정 & 구성](/ko/aftersell/subscription-upgrades-setup)에 나열된 스코프로 공급자 대시보드에서 새 토큰을 발급받아 붙여넣고 다시 테스트하세요.
    * **Aftersell이 공급자에 연결할 수 없었어요** — "Could not verify the API key. Please try again." 토큰에 반드시 문제가 있는 것은 아니에요. 호출 자체가 실패한 것이에요. **Test API key**를 다시 클릭하세요.

    공급자나 토큰을 수정하면 이전 결과가 지워지므로, 변경 후에는 다시 테스트하세요.
  </Accordion>

  <Accordion title="고객이 주문에서 예상치 못한 상품을 봤어요">
    이는 정상적인 동작이에요. 이 상품은 오퍼 상품으로, 수락된 업그레이드의 기록으로 Shopify 주문에 추가된 플레이스홀더 라인 아이템이에요. 혼란을 줄이려면 오퍼 상품의 이름을 명확하게 바꾸고, Shopify Admin에서 이것이 무엇을 나타내는지 설명하는 설명을 추가하세요. [고객이 보게 되는 것](/ko/aftersell/subscription-upgrades#what-the-customer-sees)을 참고하세요.
  </Accordion>

  <Accordion title="업그레이드가 수락되었지만 구독이 수정되지 않았어요">
    Shopify 체인지셋과 공급자 API 호출은 독립적이에요. 오퍼 상품이 주문에 추가되었지만 구독이 변경되지 않았다면, 가장 흔한 원인은 다음과 같아요:

    * 공급자 API 토큰이 만료되었거나 필요한 권한이 없는 경우예요. Recharge의 경우 토큰에 `read_orders`, `read_subscriptions`, `write_subscriptions`, `read_plans`가 있어야 해요. **Step 1: Connect provider**로 이동해 키를 다시 테스트하고, 오류 메시지에서 구체적으로 누락된 스코프를 확인하세요.
    * 퍼널의 대상 상품이 고객이 실제로 구독한 것과 일치하지 않는 경우예요.
    * Loop의 경우, 구성된 주기에 해당하는 대상 판매 플랜이 Loop 대시보드에 존재하지 않는 경우예요.
    * 재시도 워크플로가 아직 일정에 따라 진행 중일 수 있어요: 호출 실패 후 +1시간, 그다음 +24시간에 다시 시도해요. 이는 모든 공급자에서 동일해요 — Loop도 포함되며, Loop의 업그레이드 호출은 동기식이라 성공하면 대시보드에 즉시 표시돼요.

    Aftersell은 실패한 공급자 호출을 백그라운드 워크플로에서 자동으로 재시도해요. 워크플로는 재실행 전에 공급자의 현재 상태를 확인하므로, 성공했지만 느린 업그레이드가 두 번 적용되지 않아요.

    재실행으로 원인을 해결할 수 없는 경우, 워크플로는 **청구 금액을 환불**하거나 — 공급자 변경이 성공하지 않았고 청구된 라인이 플레이스홀더였던 경우 — 주문을 그대로 두고 업그레이드를 **수동 조정**으로 표시해요. 완전히 새로운 구독과 박스 업그레이드는 고객이 실제 상품을 받기 때문에 자동 환불되지 않아요. [테스트 및 확인](/ko/aftersell/subscription-upgrades-testing#when-something-looks-wrong)에 나열된 세부 정보와 함께 지원팀에 문의하세요.
  </Accordion>

  <Accordion title="판매 플랜 드롭다운이 비어 있어요">
    "Use an existing selling plan" 옵션은 Recharge, Skio 또는 Loop에서 직접 플랜을 가져와요. 드롭다운이 비어 있다면:

    * 공급자 대시보드에 판매 플랜이 구성되어 있는지 확인하세요.
    * API 토큰에 Plans에 대한 읽기 권한(Recharge: `read_plans` 스코프) 또는 적절한 스코프(Skio, Loop)가 있는지 확인하세요.
    * **Step 1: Connect provider**로 돌아가 API 키를 다시 테스트하고 계속 진행하세요.
  </Accordion>

  <Accordion title="Loop를 사용 중인데 청구 주기 필드가 없어요">
    이는 정상적인 동작이에요. Loop에서는 **Billing frequency** 필드가 아예 표시되지 않아요 — "Loop syncs billing to delivery — customers are charged on each renewal"이라는 안내와 함께 **Delivery frequency**만 표시돼요. 배송 주기로 설정한 값이 곧 청구 주기가 돼요.

    선불 구독 — 배송 주기보다 긴 청구 주기 — 이 Loop에서 지원되지 않는 것도 이 때문이에요: 연동은 사용할 수 없는 필드를 제공하는 대신 이를 처음부터 거부해요. 다른 공급자들은 두 필드를 모두 표시해요.
  </Accordion>

  <Accordion title="주문 브라우저에 Subscription conflict 배지가 표시돼요">
    오퍼 상품이 구독 전용이고 — 상품 자체 또는 모든 옵션이 — 고객의 체크아웃에 이미 구독이 포함되어 있었던 경우예요. Shopify는 동일 주문에 두 번째 구독을 허용하지 않으므로 제안이 건너뛰어졌어요.

    주문 상세 패널에 어떤 경우인지 명시돼요: "The customer's checkout already has a subscription, and the offer product is subscription-only" 또는 "All variants of the offer product are subscriptions, and the customer's checkout already has one." 둘 다 같은 방법으로 해결해요 — 제안의 상품 선택을 수정해 일회성 구매 상품으로 교체하거나, **Step 4: Offer product**의 **Create new** 옵션을 사용해 플레이스홀더를 생성하세요.
  </Accordion>

  <Accordion title="업그레이드 제안이 구독자가 아닌 고객에게 표시되고 있어요">
    * **Show this funnel for all customers**가 활성화되어 있지 않은지 확인하세요. 이 옵션은 다른 모든 트리거를 무시해요.
    * **Variant on subscription** 트리거를 확인하세요. 이 트리거는 주문에 선택된 상품 중 하나가 *구독으로 구매된* 경우에만 퍼널을 표시해요. 구독 업그레이드 제안이 있는 퍼널에서는 마법사가 이 트리거를 소유하고 업그레이드 대상 상품과 동기화를 유지하므로 읽기 전용이에요 — 패널에 "Managed by this funnel's subscription upgrade offer"라고 표시돼요. 잘못된 상품을 대상으로 하고 있다면 트리거 자체가 아니라 업그레이드 제안의 트리거 상품을 수정하세요.
    * 퍼널 우선순위를 확인하세요. 더 넓은 트리거를 가진 상위 우선순위 퍼널이 먼저 실행되고 있을 수 있어요.

    <Warning>
      별도의 상품 트리거와 구독 트리거를 조합해 이를 재현하려고 하지 마세요. 그 조합이 바로 **Variant on subscription**이 대체한 방식이에요: 두 트리거가 독립적으로 매칭되어, 트리거 상품을 일회성 구매로 포함하고 *그리고* 무관한 구독 상품도 포함한 주문이 두 조건을 모두 충족해 퍼널이 실행되고, 이후 업그레이드가 다운스트림에서 실패했어요. 상품과 구독 상태를 함께 매칭하는 하나의 트리거가 지원되는 설정이에요.
    </Warning>
  </Accordion>
</AccordionGroup>