Skip to main content
네이티브 인보이스는 레거시 인보이스와 동일한 /invoices 경로를 사용하지만 요청 형식과 수명 주기가 다릅니다. 이 가이드는 통합을 마이그레이션할 때 변경해야 하는 필드와 작업을 매핑합니다.
공유 경로는 Api-Version-Date: 2026-10-24부터 네이티브 인보이스로 라우팅됩니다. 아래 네이티브 예제는 현재 변형 필드 이름과 고객 고정 규칙이 적용된 Api-Version-Date: 2026-11-02-1을 사용합니다. 각 네이티브 요청에 이 헤더를 보내세요. 레거시 호출은 2026-10-15-1과 같은 이전 릴리스 버전으로 유지하세요. 헤더가 자격 증명 고정 버전을 재정의하는 방식은 API 버전에서 설명합니다.

변경 사항

네이티브 API는 레거시 inv_ 인보이스를 나열하거나 조회하지 않습니다. 기존 레거시 인보이스는 이전 API 버전으로 계속 조회하세요. 네이티브 인보이스를 생성하면 별도의 청구서가 만들어집니다. 레거시 인보이스를 변환하거나 정산하지 않습니다.

마이그레이션 전 확인 사항

흐름을 옮기기 전에 다음 차이점을 확인하세요. 네이티브 API가 제공하지 않는 기능이 필요한 흐름은 레거시 API에 그대로 두세요.

생성 요청 매핑하기

레거시 생성은 하나의 요금제와 선택적으로 가격을 나누는 라벨을 보냅니다. 네이티브 생성은 청구되는 각 변형에 대한 항목을 보냅니다. 이 예제는 항목 가격 합계를 19.99 USD로 설정합니다. 기존 네이티브 변형은 15 USD 설정 요금을 나타냅니다. 4.99 USD 서비스 수수료는 상품이 없는 사용자 지정 일회성 요금입니다. 두 API 모두 통화 단위로 가격을 받습니다. 4.99 USD에는 4.99를 사용하세요. 499를 보내면 499 USD가 청구됩니다.
네이티브 요청은 초안을 생성합니다. 발행하고 이메일로 보내려면 POST /invoices/{id}/send로 전송하세요. member_id는 구독(mem_)이 아닌 고객(mber_)을 식별합니다. 2026-10-27-2 이전의 네이티브 버전에서는 variant_id, variant, billing_type 대신 plan_id, plan, plan_type을 사용하세요. 이러한 이전 버전에서는 응답의 라인 항목도 plan_id를 사용합니다.

발행된 금액 고정 유지하기

PATCH /invoices/{id}는 초안의 항목과 청구 세부 정보를 편집합니다. items를 보내면 변형의 현재 가격을 사용하여 전체 목록이 교체됩니다. 생략하면 저장된 항목과 가격이 유지됩니다.
  • 항목이나 청구 세부 정보를 편집하기 전에 예약된 전송을 취소하세요.
  • 2026-11-02-1부터는 초안에 지정된 고객을 교체하거나 지울 수 없습니다. 고객이 없는 초안에는 여전히 고객을 지정할 수 있습니다. 다른 사람에게 새 인보이스를 만들기 전에 초안을 무효화하세요.
  • email_address와 customer_name은 생성 시에만 입력할 수 있습니다.
  • 발행된 금액과 항목은 고정됩니다. memo 및/또는 recipient_emails만 포함한 업데이트는 예약된 초안을 포함한 draft, open, uncollectible 인보이스에서 허용됩니다.

발행, 전송 및 청구

레거시 생성은 collection_method로 수금 방식을 선택합니다. 네이티브 인보이스는 초안을 생성한 후 별도의 호출을 사용합니다:
  1. 초기 인보이스 이메일을 보내지 않고 최종 세금을 계산하여 결제를 위해 열려면 POST /invoices/{id}/issue로 발행하세요.
  2. 또는 POST /invoices/{id}/send로 전송하세요. 이렇게 하면 초안이 발행됩니다. 저장된 결제 수단으로 즉시 청구하지 않는 한 수신자에게 이메일을 보냅니다. open 인보이스를 전송하면 이메일이 다시 발송됩니다. send_at은 초안의 전송을 예약합니다. POST /invoices/{id}/unschedule은 해당 예약을 취소합니다.
  3. 초안에 payment_method_id를 설정하여 저장된 결제 수단으로 청구하세요. 합계가 양수이면 발행 또는 전송 시 미래의 charge_at에, 없으면 미래의 due_at에, 그것도 없으면 즉시 청구합니다. charge_at은 미래 시점이어야 하며 send_at보다 앞설 수 없습니다.
즉시 청구하는 초안을 전송하면 초기 인보이스 이메일을 건너뜁니다. 나중에 청구하도록 전송하면 지금 이메일을 보냅니다. 자동 청구가 실패하면 Issue Invoice를 사용한 경우에도 결제 링크 이메일이 발송될 수 있습니다. 저장된 결제 수단으로 청구하기에서 흐름을 설명합니다. open 응답은 결제를 확인하지 않습니다. 주문을 처리하기 전에 payment.succeeded를 기다리세요. 열린 인보이스를 청구하거나 재시도하려면 Charge Invoice를 사용하세요. 다시 발행하거나 전송해도 새 청구가 시작되지 않습니다. 정기 변형의 경우 Issue Invoice 또는 Send Invoice의 collection_method가 갱신을 제어합니다. charge_automatically는 향후 결제를 자동으로 수금합니다. send_invoice는 매 기간 새 인보이스를 만들어 이메일로 보냅니다. 첫 번째 인보이스 수금을 위한 payment_method_id를 대체하지 않습니다. 구독 인보이스 발행하기를 참조하세요.

응답 매핑하기

PDF를 다운로드하려면 POST /invoices/{id}/generate_pdf를 호출하여 단기 링크를 받으세요.

인보이스 체크아웃 열기

checkout_link에는 .으로 구분된 인보이스 ID와 서명된 토큰이 포함되어 있습니다. 이 인보이스에 대한 세션을 열려면 전체 값을 link로 POST /checkout_sessions에 전달하세요. 고객용 URL은 호스팅 체크아웃 URL 만들기를 따르세요. 이 필드는 체크아웃이 가능한 동안에만 존재하며, 인보이스가 open 상태여야 합니다. 기업 구매자와 취소된 멤버십은 이 체크아웃을 사용할 수 없습니다. 키에는 payment:charge가 필요하며, 인보이스에 저장된 결제 수단이 없는 경우 invoice:create/invoice:update가 필요합니다. 초안, 결제 완료, 무효, 회수 불능 인보이스와 기업 구매자의 경우 null입니다.

상태 매핑하기

네이티브 인보이스는 authorized, pending, unresolved도 반환할 수 있습니다. 레거시 열거형 외의 모든 상태를 결제 완료 또는 실패로 처리하지 마세요. 상태 및 수명 주기에서 이를 설명합니다.

엔드포인트 매핑하기

웹훅 매핑하기

네이티브 인보이스는 pay_ ID에 대한 결제 이벤트를 보냅니다. invoice.* 이벤트는 레거시 인보이스를 설명합니다. 결제 이벤트는 인보이스와 관련 없는 결제도 포함합니다. 이벤트의 결제 ID를 저장한 네이티브 인보이스 ID와 대조하세요. 웹훅에서 payment.succeeded로 주문을 처리하는 방법을 보여 줍니다.

권한

member:basic:read는 고객 이름과 멤버/멤버십 ID를 노출합니다. member:email:read는 email_address와 recipient_emails를 노출합니다. 결제 수단 및 주소 필드에는 payment:basic:read가 필요합니다.

마이그레이션 체크리스트

  1. 레거시 API에 남아 있어야 하는 워크플로는 마이그레이션 전 확인 사항을 확인하세요.
  2. 네이티브 호출을 해당 필드 이름과 일치하는 릴리스 버전(이 예제의 경우 2026-11-02-1)으로 고정하세요.
  3. 수량, 가격, 통화, 상품 요구 사항을 확인하면서 적격 변형으로 items를 구성하세요.
  4. 레거시의 단일 호출 생성을 생성 후 발행 또는 전송으로 대체하세요. 첫 번째 인보이스에는 저장된 결제 수단 청구를, 갱신에는 수금 방식을 선택하세요.
  5. 기한, 예약된 전송, 구매자 수수료는 필드 이름만이 아니라 동작에 따라 매핑하세요.
  6. 네이티브 pay_ ID와 레거시 inv_ ID를 구분하세요. 레거시 조회는 이전 버전으로 유지하세요.
  7. 금액 객체에서 금액을 읽고, 서명된 checkout_link를 사용하여 체크아웃을 여세요.
  8. overdue와 추가 결제 상태를 처리하세요.
  9. 인보이스의 결제 ID에 대한 payment.succeeded로 주문을 처리하세요.
  10. 인라인 변형/상품 및 고객 조회 권한을 포함하여 흐름에서 사용하는 권한을 부여하세요.

다음 단계

인보이스 가이드

네이티브 인보이스를 생성, 발행, 전송하고 수금하세요.

인보이스 API 레퍼런스

모든 네이티브 인보이스 엔드포인트와 필드입니다.

레거시 인보이스 API

현재 통합에서 호출하는 엔드포인트입니다.

API 버전

Api-Version-Date와 버전 고정의 작동 방식입니다.