Skip to main content
인보이스는 한 명의 고객에게 발행하는, 하나 이상의 변형에 대한 번호가 매겨진 청구서입니다. 변형은 판매하는 가격 및 청구 설정으로, 보통 상품에 속합니다. 변형의 ID는 plan_으로 시작하며, 인보이스 항목은 이를 plan_id로 받습니다. 견적, 서비스, 기업 주문처럼 고객이 결제하기 전에 가격을 합의하는 경우 인보이스를 사용하세요. 초안이 올바르게 될 때까지 작성한 다음, 발행하여 총액을 확정하고 결제를 받을 수 있도록 엽니다. 전송하면 이 작업과 이메일 발송을 한 번의 호출로 수행합니다. 코드 없이 대시보드에서 인보이스를 보내려면 인보이스 생성 및 전송을 참고하세요.
이 페이지의 인보이스는 모든 요청에 Api-Version-Date: 2026-10-24 이상이 필요합니다. 그 이전 버전으로 보낸 요청은 다르게 동작하는 레거시 인보이스 API로 전달됩니다. 시작하기 전에를 참고하세요.

인보이스의 작동 방식

네이티브 인보이스는 결제입니다. 인보이스의 ID는 pay_로 시작하며 고객이 결제한 후에도 동일하게 유지되므로, 결제 조회로도 읽을 수 있습니다. 각 인보이스는 계정 고유의 순번에서 다음 번호를 받습니다. 예를 들어 #00000042이며, 계정에 인보이스 접두사가 있으면 #ACME-00000042가 됩니다.
  1. 초안을 만듭니다. 항목, 고객, 청구 세부 정보를 포함합니다. 초안은 아무것도 청구하지 않으며 누구에게도 이메일을 보내지 않습니다.
  2. 발행하거나 전송합니다. 발행하면 최종 세금이 계산되고 인보이스가 결제를 받을 수 있도록 열립니다. 전송하면 인보이스를 발행하고 즉시 또는 예약한 시간에 이메일로 보냅니다.
  3. 고객이 결제합니다. 인보이스를 발행하거나 전송하면 Whop이 고객의 저장된 결제 수단에 청구하거나, 고객이 Whop의 호스팅 체크아웃을 통해 결제합니다.
  4. payment.succeeded 웹훅에서 주문을 처리합니다.
인보이스는 대기자 명단이 아닌 release_method: buy_now인 즉시 구매 변형을 청구합니다. 일회성 변형은 한 번 청구되며, 반복 변형은 인보이스가 결제되면 구독을 시작합니다. 정해진 결제 횟수 후 구독을 중지하는 방법도 다루는 구독 인보이스 발행을 참고하세요.

시작하기 전에

API 버전 보내기

/invoices는 서로 다른 두 API를 제공하며, 요청이 확인되는 Api-Version-Date에 따라 어느 쪽이 응답할지 결정됩니다. 발행, 전송, 예약 전송 취소, PDF 생성은 네이티브 API에만 있으므로, 어떤 버전을 보내든 네이티브 인보이스로 전달됩니다. GET /invoices와 POST /invoices/{id}/void처럼 두 API에 모두 있는 경로는 버전을 따릅니다. 키의 고정값에 의존하지 말고 모든 요청에 헤더를 보내세요. 그래야 키를 바꿔도 두 API 사이를 오가지 않습니다. 고정값과 변경 로그는 API 버전에서 설명합니다. 네이티브 API는 레거시 inv_ 인보이스를 나열하거나 조회하지 않으며, 레거시 API는 네이티브 인보이스를 반환하지 않습니다.

API 호출하기

이 페이지의 예제는 모든 요청에 버전 헤더를 보내는 작은 헬퍼를 통해 API를 호출합니다.
재시도로 인해 두 번째 인보이스가 생성되거나 작업이 반복되지 않도록 모든 POST에 Idempotency-Key를 보내세요. Generate Invoice PDF는 예외입니다. 호출할 때마다 새 파일을 만들므로 응답을 재생하지 않습니다.

초안 만들기

Create Invoice는 POST /invoices로 초안을 저장합니다.
응답은 초안과 함께 201 Created입니다. 초안을 만들면 아무것도 청구되지 않고, 이메일이나 웹훅도 전송되지 않습니다. 이 응답은 필드의 일부만 보여줍니다:
account_id는 인보이스를 발행하는 계정으로, 접두사는 biz_입니다. 계정 API 키는 이를 생략하면 자신의 계정을 사용합니다. Create Invoice에 모든 요청 및 응답 필드가 나와 있습니다. 초안은 생성 시점에 번호를 사용하므로, 폐기한 초안은 순번에 공백을 남깁니다. 초안을 폐기하려면 삭제하세요. 목록에 남겨두려면 대신 무효화하세요.

항목 추가하기

items는 1~50개의 항목을 받습니다. 각 항목은 기존 변형을 위한 plan_id 또는 인라인으로 변형을 찾거나 생성하는 plan 중 하나와, 선택적 quantity를 받습니다. 인라인 plan은 Create Payment와 동일한 찾기 또는 생성 입력을 사용합니다. 예: { "plan": { "product_id": "prod_xxxxxxxxxxxxx", "plan_type": "one_time", "initial_price": 250, "currency": "usd" } }. 이를 위해 plan:create가 필요하며, 인라인 product에는 상품 권한인 access_pass:create 또는 access_pass:update도 필요합니다. 생성 및 업데이트는 다음 규칙을 위반하는 항목을 거부합니다:
  • 각 항목은 계정의 즉시 구매 변형이어야 합니다. 변형은 한 번만 나타날 수 있으므로, 여러 단위가 필요하면 quantity를 사용하세요.
  • 보관된 변형이 없어야 하며, 초안을 발행하거나 전송할 때 이를 다시 확인하므로 변형을 보관 해제하거나 다른 변형을 선택하세요.
  • quantity는 1에서 999,999 사이이며, 여러 수량을 허용하는 변형에서만 1보다 클 수 있습니다. 반복 변형은 이를 허용하지 않으므로 반복 항목의 수량은 1입니다.
  • 반복 변형은 상품에 속해야 합니다.
  • 모든 항목은 동일한 통화를 사용합니다.
  • 여러 항목이 있는 인보이스에서 상품이 있는 모든 항목은 앱이 아닌 일반 상품(표준 상품 유형)이어야 합니다. 반복 항목은 하나의 청구 주기, 무료 체험 기간, split_pay_required_payments를 공유하며, 모든 항목은 호환되는 결제, 세금, 액세스 설정이 필요합니다. 사용자 지정 필드나 비밀번호가 있는 변형은 결합할 수 없습니다. 사용자 지정 수수료처럼 상품이 없는 항목은 나머지 항목과 함께 둘 수 있습니다.
응답의 각 품목에는 label이 있으며, 이는 상품의 제목이거나 상품이 없는 변형의 경우 변형의 제목입니다. 이메일, PDF, 체크아웃에 이 값이 표시됩니다. 초안은 항목을 저장할 때 각 변형의 가격을 유지하므로, 나중에 변형 가격이 바뀌어도 인보이스는 변하지 않습니다. 일회성 항목은 해당 가격으로 청구됩니다. API 버전 2026-11-11부터는 반복 항목을 생성하거나 교체하면 첫 인보이스에 initial_price와 renewal_price가 함께 포함됩니다. 이전 버전 고정값은 갱신 가격만 사용합니다. items를 생략한 편집은 저장된 가격을 유지합니다.

고객 및 청구 세부 정보 설정하기

member_id 또는 email_address 중 하나, billing_address 또는 mailing_address_id 중 하나를 보내세요. 각 쌍을 둘 다 보내서는 안 됩니다. 청구 주소에는 고객이 필요합니다. 초안에서 고객은 선택 사항이지만 발행하려면 필수입니다. Whop은 인보이스를 발행할 때 청구 주소로 고객의 위치를 파악해 세금을 계산합니다. 세금이 적용되는데 Whop이 고객의 위치를 알 수 없으면 발행이 거부되므로, 세금을 징수할 때는 항상 청구 주소를 추가하세요.

초안 편집하기

Update Invoice는 PATCH /invoices/{id}로 초안을 변경합니다. 변경하는 필드만 보내세요.
  • items는 전체 목록을 교체하며 각 변형의 현재 가격을 읽습니다. 저장된 항목과 가격을 유지하려면 생략하세요.
  • member_id를 변경하면 새 값을 보내지 않는 한 저장된 청구 주소와 결제 수단이 삭제됩니다. recipient_emails는 유지되므로 새 목록도 함께 보내세요. 그렇지 않으면 이전 고객이 계속 인보이스 이메일을 받습니다.
  • email_address와 customer_name은 허용되지 않습니다. 다른 사람에게 청구하려면 다른 member_id를 보내세요.
  • 예약 전송이 있는 초안은 전송을 취소할 때까지 recipient_emails 변경만 허용합니다.
  • 인보이스가 발행된 후에는 recipient_emails만 단독으로, 그리고 인보이스가 open 또는 uncollectible인 동안에만 변경할 수 있습니다. 다른 편집은 400으로 거부됩니다.

고객의 결제 방법 선택하기

발행된 인보이스의 대금을 받는 방법은 두 가지입니다. 저장된 결제 수단은 초안에 들어가므로, 발행하기 전에 하나를 선택하세요. 발행된 인보이스는 저장된 결제 수단이 있어도 checkout_link를 받습니다. 자동 청구가 실패해도 고객은 여전히 체크아웃으로 결제할 수 있습니다.

저장된 결제 수단에 청구하기

payment_method_id로 초안에 저장된 결제 수단을 넣으세요. 이는 고객의 저장된 결제 수단 중 하나여야 합니다. 결제 수단 저장에서 고객이 결제 수단을 저장하는 방법을 보여주며, 결제 수단 목록으로 멤버가 가진 결제 수단을 찾을 수 있습니다. 인보이스를 발행하거나 전송하고 총액이 0보다 크면 Whop은 다음을 수행합니다:
  1. Create Payment가 저장된 결제 수단에 대해 실행하는 것과 동일한 검사를 실행합니다.
  2. 인보이스 수량만큼 재고를 예약하고 결제 수수료를 준비합니다.
  3. 인보이스를 open으로 반환하고 결제 수단에 오프세션으로 청구합니다. 청구는 Issue Invoice 또는 Send Invoice에 전달한 charge_at에 실행되고, 그렇지 않으면 아직 도래하지 않은 경우 due_at에, 그 외에는 즉시 실행됩니다. scheduled_charge_at은 아직 예정된 청구를 보여줍니다.
응답은 청구 성공 여부를 알려주지 않습니다. 인보이스의 pay_ ID에 대한 payment.succeeded 웹훅에서 주문을 처리하세요. 결제된 인보이스는 멤버십을 완료하며, metadata는 청구와 멤버십에 기록됩니다. 결제 규칙이 청구를 심사하는 방법은 인보이스 결제에 대한 결제 규칙에서 다룹니다.

자동 청구가 거절된 경우

청구가 거절되면 인보이스는 open 상태로 유지되고 예약된 재고가 반환됩니다. 인보이스를 결제로 조회하고 failure_message를 읽어 최근 시도가 실패한 이유를 확인하세요. 청구가 거절되거나 고객의 조치가 필요하면, Whop은 고객이 대신 체크아웃으로 결제할 수 있도록 인보이스의 결제 링크를 수신자에게 이메일로 보냅니다. 이는 전송하지 않고 발행한 인보이스에 대해 Whop이 보내는 유일한 이메일입니다. 이를 위해서는 checkout_link와 recipient_emails에 하나 이상의 항목이 필요하며, 전송 한도에 포함되지 않습니다.
오프세션 청구는 고객에게 3D Secure 인증 요청을 표시할 수 없습니다. 은행이 인증을 요구하면 자동 청구가 완료되지 않으며, 고객이 인증하거나 다른 방법으로 결제할 때까지 인보이스는 미결제 상태로 남습니다.

인보이스 발행하기

Issue Invoice는 초안을 열린 인보이스로 전환합니다. Whop은 인보이스를 다시 확인하고, 최종 세금을 계산하고, status를 open으로, totals_status를 final로 설정합니다. 인보이스에 저장된 결제 수단이 있고 총액이 0보다 크면, Whop은 저장된 결제 수단에 청구하기에 설명된 대로 청구합니다.
  • 세금이 확정됩니다. tax_amount는 초안에서는 null이며 발행하면 설정됩니다. total과 amount_due에 세금이 포함됩니다.
  • 인보이스가 상품을 청구하면 Whop이 고객의 멤버십을 만듭니다. 멤버십은 인보이스가 결제될 때까지 액세스 없이 초안 상태로 유지됩니다. 모든 항목에 상품이 없는 인보이스는 멤버십을 받지 않습니다.
  • payment.created가 인보이스의 pay_ ID에 대해 한 번 발생합니다.
  • 다시 발행해도 안전합니다. 이미 open인 인보이스를 발행하면 동일한 검사를 다시 실행하고, 통과하면 인보이스를 변경 없이 반환합니다. 총액은 그대로이며 다시 청구되지 않습니다.
  • 발행해도 인보이스가 이메일로 전송되지 않습니다. 단, 청구 거절 후 결제 링크는 예외입니다. 인보이스를 이메일로 보내려면 대신 전송하거나 체크아웃 링크를 직접 전달하세요.
거부된 발행은 아무것도 변경하거나 청구하지 않습니다. 원인을 해결하고 인보이스를 다시 발행하세요. 이유는 발행 오류에 나와 있습니다. 발행된 open 인보이스에는 pay_xxxxxxxxxxxxx.<signature> 형식의 서명된 값인 checkout_link가 있습니다. 이 링크는 고정 가격으로 Whop의 호스팅 체크아웃에서 인보이스를 엽니다.
1

발행된 인보이스에서 링크 읽기

checkout_link는 인보이스가 open이 아니면 null이므로, 초안과 결제 완료, 무효, 회수 불가 인보이스에는 링크가 없습니다. 비즈니스 구매자에게 청구된 인보이스, 멤버십이 취소된 인보이스, 자격 증명에 payment:charge가 없는 경우에도 null입니다. 비즈니스 구매자는 개인이 아닌 다른 Whop 계정인 고객입니다.
2

호스팅 체크아웃 URL 만들기

링크를 첫 번째 .에서 나누세요. 그 앞은 인보이스의 pay_ ID이고, 뒤는 토큰입니다.
3

고객에게 보내기

인보이스를 전송하여 Whop이 링크를 이메일로 보내게 하거나, URL을 자체 이메일이나 인보이스 페이지에 넣으세요. 인보이스의 고객만 이 링크로 결제할 수 있습니다. 다른 사람은 거부되며 인보이스의 고객으로 로그인하라는 요청을 받습니다. 인보이스가 결제, 무효화, 회수 불가로 표시되면 링크는 더 이상 작동하지 않습니다.
4

웹훅에서 주문 처리하기

자동 청구와 마찬가지로 인보이스의 pay_ ID에 대한 payment.succeeded를 수신하세요. 웹훅에서 핸들러 예시를 보여줍니다.
체크아웃은 항목 옆에 인보이스 번호와 기한을 표시하며, 기한이 지나면 기한이 빨간색으로 바뀝니다. 고객은 인보이스의 항목과 총액을 결제하며 프로모션 코드를 추가할 수 없습니다.

전송, 예약, 알림

Send Invoice는 POST /invoices/{id}/send로 인보이스를 이메일로 보냅니다. 초안을 전송하면 Issue Invoice와 동일하게 먼저 발행합니다. open 인보이스를 전송하면 다시 이메일로 보냅니다.
이메일에는 계정의 이름과 로고, 인보이스 번호, 총액, 기한, 각 항목, 인보이스의 체크아웃을 여는 버튼이 표시됩니다. Whop은 고객이 이메일에서 결제할 수 있는 인보이스만 이메일로 보냅니다. open 인보이스를 전송하려면 checkout_link가 필요하고, 초안에는 비즈니스 구매자가 아닌 고객이 필요합니다. 비즈니스 구매자에게 청구된 초안도 저장된 결제 수단이 있으면 대신 청구되므로 전송할 수 있습니다.

이메일을 받는 사람

각 전송은 모든 주소에 개별 이메일로 한 번씩 보내므로, 수신자는 서로의 주소를 볼 수 없습니다. 주소는 다음과 같습니다:
  • 고객의 Whop 계정 이메일. 인보이스 PDF의 Bill to 아래에 인쇄됩니다.
  • recipient_emails의 각 항목.
Whop은 recipient_emails를 소문자로 저장하고 목록의 중복을 제거하므로, 두 곳에 모두 있는 주소는 이메일을 한 통만 받습니다. recipient_emails가 비어 있으면 Whop은 고객을 포함해 아무에게도 이메일을 보내지 않습니다. Whop이 인보이스를 이메일로 보내지 않게 하려면 이를 사용하세요:
  • 저장된 결제 수단에 대신 청구하는 경우가 아니면 Send Invoice가 인보이스를 거부합니다.
  • 청구가 거절된 후 결제 링크가 발송되지 않습니다.
  • 알림이 발송되지 않습니다. open 인보이스의 recipient_emails를 비우면 남은 알림이 중지됩니다.

Whop이 이메일 대신 청구하는 경우

payment_method_id가 있고 총액이 0보다 큰 초안은 발행할 때와 마찬가지로 이메일 대신 청구됩니다. 청구가 실패하면 어떻게 되는지는 자동 청구가 거절된 경우에서 다룹니다. 이런 초안은 이메일이 필요한 사람이 없으므로 recipient_emails가 비어 있어도 전송할 수 있습니다.

전송 한도

각 인보이스는 발행 시 전송을 포함해 24시간 내에 세 번까지 이메일로 보낼 수 있습니다. 그 기간 내 네 번째 전송은 error.code가 invoice_send_limit_reached인 429로 거부됩니다. 알림, 청구 거절 후 결제 링크, 이메일 대신 청구하는 전송은 한도에 포함되지 않습니다.

전송 예약하기

초안을 나중에 보내려면 send_at을 전달하세요. 초안은 초안 상태로 유지되며 scheduled_send_at에 시간을 표시합니다. 그 시간이 되면 Whop은 그때 Send Invoice를 호출한 것처럼 초안을 전송합니다.
  • 초안만 예약할 수 있으며, send_at은 미래여야 합니다. Whop은 지금 전송할 때와 마찬가지로 예약 시점에 수신자와 결제 링크를 확인합니다.
  • 새 send_at으로 다시 전송하면 시간이 변경됩니다.
  • 전송이 이루어지거나 취소할 때까지 편집이 잠깁니다. recipient_emails만 변경하는 업데이트는 여전히 작동하지만, 청구되지 않을 초안에서 마지막 수신자를 제거할 수는 없습니다.
  • POST /invoices/{id}/unschedule로 예약 전송을 취소하세요. scheduled_send_at이 null로 돌아가고 초안을 다시 편집할 수 있습니다. 예약 전송이 없는 인보이스를 취소하면 변경 없이 반환됩니다.
  • 예약된 초안을 무효화하면 예약 전송이 중지됩니다.
Whop은 매분 전송 예정 항목을 확인하므로, 예약 전송은 send_at 후 약 1분 이내에 발송됩니다. 예를 들어 예약 이후 변형이 삭제되어 전송이 거부되면, 인보이스는 초안으로 유지되고 scheduled_send_at은 null로 돌아가며, API는 그 이유를 반환하지 않습니다. 그 외의 실패는 약 10분마다, 총 최대 12회까지 재시도됩니다. 시도가 성공하거나 Whop이 재시도를 중단할 때까지 scheduled_send_at은 null이 아닌 다음 시도 시간을 표시합니다. send_at 이후에 인보이스를 읽어 open인지 확인하세요.

알림

Send Invoice가 due_at이 있는 인보이스를 이메일로 보내면, Whop은 due_at 후 1, 3, 7, 14, 30, 60일에 알림도 예약하며, 날짜가 이미 지난 알림은 건너뜁니다. 각 알림은 인보이스와 같은 주소로 전송되며 인보이스의 연체 일수를 알려줍니다. 알림은 인보이스가 open인 동안에만 발송되므로, 결제, 무효화, 회수 불가로 표시되면 중지됩니다. 결제가 진행 중일 때 기한이 된 알림은 결제가 끝날 때까지 기다립니다. 전송하지 않고 발행한 인보이스나 이메일 대신 청구된 인보이스는 알림을 받지 않습니다.

이메일 기록

List Invoice Sends는 GET /invoices/{id}/sends로 기록된 이메일 배치를 최신순으로 반환합니다. 최초 및 반복 이메일, 예약 이메일, 알림, 저장된 결제 수단에 대한 청구 실패 후 결제 후속 이메일이 포함됩니다. 가장 최근에 기록된 전송은 첫 번째 항목을 사용하고, 이전 항목을 읽으려면 page_info.end_cursor를 after로 사용하세요. 수동 배치는 인보이스에 이전에 완료된 이메일 기록이 없으면 send를, 그렇지 않으면 resend를 사용합니다. 종류는 완료된 배치가 기록될 때 선택되므로, 함께 대기열에 들어간 요청은 완료 순서대로 분류됩니다. 이전에 기록되지 않은 이메일은 알 수 없는 상태로 남습니다. 각 항목에는 kind, sent_at, recipient_count, recipients, actor가 포함됩니다. 기록을 읽으려면 payment:basic:read가 필요합니다. 주소에는 member:email:read도 필요합니다. 이 권한이 없으면 recipients는 비어 있습니다. 발신자에는 company:authorized_user:read도 필요합니다. 그렇지 않으면 actor는 null입니다. 자동 전송과 계정 API 키도 actor가 null입니다. 워커는 전체 배치를 전달용으로 제출한 후 항목을 추가합니다. 부분 배치의 경우 재시도로 배치가 완료된 경우에만 항목을 추가합니다. 항목은 원래 수신자 목록을 유지합니다. 기록된 배치가 받은편지함 전달을 보장하지는 않습니다. 전달 전에 인보이스나 수신자가 변경되면 메일러가 메시지를 보내지 않을 수 있습니다. 기록에는 이 기능이 도입되기 전에 전송된 이메일이 포함되지 않습니다. 이메일 없이 인보이스를 발행하면 기록 항목이 추가되지 않습니다.

PDF 다운로드하기

Generate Invoice PDF는 인보이스를 PDF로 만들고 단기 링크를 반환합니다. payment:basic:read가 필요하며 모든 상태에서 작동합니다.
응답에는 url과 expires_at이 있습니다. 링크는 15분 동안 유효하며, 링크를 가진 누구나 파일을 다운로드할 수 있습니다. 만료되면 새 링크를 생성하세요. PDF는 비즈니스를 앞세웁니다. 계정 이름이 페이지 상단에 표시되고, 바닥글에는 Whop Inc가 귀하의 이름으로 귀하를 대신하여 인보이스를 발행한다고 명시됩니다. 인보이스 번호, 발행일과 기한, Bill to 세부 정보가 표시됩니다. 각 항목에는 수량, 단가, 금액이 표시되고, 그 뒤에 소계, 서비스 수수료, 세금, 청구 금액이 이어집니다. 반복 항목이 있는 인보이스는 갱신 금액과 갱신 주기도 명시합니다. 초안의 PDF는 예상 총액을 표시하며, 발행할 때까지 세금은 0입니다. 일부 콘텐츠는 자격 증명의 권한에 따라 달라집니다:

구독 인보이스 발행하기

인보이스에 반복 변형을 넣으면 고객이 결제할 때 구독이 시작됩니다. 이후 Whop은 청구 주기마다 한 번씩 구독을 갱신합니다.
  1. 인보이스는 첫 번째 주기와 선불 수수료를 청구합니다. 반복 항목은 상품에 속해야 하며 수량은 1입니다. API 버전 2026-11-11부터 첫 인보이스는 initial_price와 renewal_price를 함께 청구합니다. 변형에 무료 체험이 없으면 결제와 동시에 첫 번째 유료 청구 주기가 시작됩니다. 무료 체험이 있으면 구독은 체험으로 시작합니다. 대시보드에서 사용자 지정 반복 항목에는 선택적인 Upfront fee 필드가 있습니다. 품목의 initial_price는 unit_amount 중 일회성 부분을 나타내며, 인보이스 페이지, 이메일, PDF에서 별도의 Upfront fee 줄로 표시됩니다.
  2. 인보이스를 결제하면 구독이 시작됩니다. Whop이 발행 시 저장된 결제 수단에 청구하든, 고객이 checkout_link로 결제하든 마찬가지입니다. 첫 번째 주기는 결제 시점에 시작됩니다. 링크로 연 체크아웃에는 인보이스의 구매자 수수료를 포함한 갱신 금액과 갱신 주기가 표시됩니다.
  3. 각 갱신은 인보이스를 발행하거나 전송할 때 선택한 방식으로 수금됩니다. 갱신은 인보이스의 구매자 수수료와 함께 반복 항목만, 인보이스 발행 시점의 각 변형 갱신 가격으로 청구합니다. 항목을 저장한 후 변형 가격이 바뀌었다면 이는 초안에 저장된 가격과 다를 수 있습니다. 일회성 항목은 한 번만 청구됩니다.
Issue Invoice 또는 Send Invoice에 collection_method를 전달하여 갱신 수금 방식을 선택하세요. 예약 전송은 예약할 때 지정한 collection_method를 적용하며, 초안에는 이것이 scheduled_collection_method로 표시됩니다. send_invoice에는 최소 하나의 recipient_emails 주소가 필요하며, 비즈니스에 청구된 인보이스에는 사용할 수 없습니다. 이 방식이 적용되는 동안에는 인보이스의 마지막 수신자를 제거할 수 없습니다. 반복 항목이 없는 인보이스는 collection_method를 거부합니다. 첫 인보이스를 카드로 결제해도 send_invoice는 유지됩니다. 각 갱신은 고유한 pay_ ID와 payment.* 웹훅을 가진 별도의 결제입니다. charge_automatically 갱신은 번호가 매겨진 인보이스가 아니므로 List Invoices에 나타나지 않습니다. send_invoice 갱신은 List Invoices에 나타나는 번호가 매겨진 인보이스이며, Whop은 이를 자동으로 청구하지 않습니다. 고객이 인보이스의 checkout_link로 결제할 때까지 구독은 past_due 상태로 유지됩니다. 그동안 고객은 액세스를 유지합니다. 갱신을 중지하려면 멤버십을 취소하세요. 멤버십이 취소되면 열린 갱신 인보이스의 checkout_link는 더 이상 작동하지 않습니다. 구독을 찾으려면 인보이스를 결제로 조회하고 membership_id를 읽으세요. 이를 위해 member:basic:read가 필요합니다.

무료 체험으로 시작하기

인보이스는 체크아웃과 마찬가지로 반복 변형의 trial_period_days를 따릅니다. 첫 인보이스는 변형의 initial_price만 청구합니다. 이를 결제하면 체험이 시작되고, 체험이 끝나면 첫 번째 갱신이 renewal_price를 청구합니다. 2026-11-16 17:00 UTC 이전에 생성된 인보이스는 첫 번째 주기를 청구하고 체험을 건너뜁니다.
  • 이미 해당 변형을 구독한 적이 있는 고객은 체험을 받지 않습니다. 첫 인보이스는 initial_price와 renewal_price를 함께 청구합니다. 갱신 인보이스는 절대 체험을 시작하지 않습니다.
  • 체험은 변형에서 결정됩니다. 사용자 지정 반복 항목의 경우 variant.trial_period_days를 설정하세요. 항목 수준의 trial_period_days는 거부됩니다.
  • 인보이스의 모든 반복 항목은 체험 기간이 같아야 합니다.
  • 인보이스가 아무것도 청구하지 않을 때는 체험을 즉시 시작하는 payment_method_id와 함께, 또는 collection_method: "send_invoice"와 함께 발행하거나 전송하세요.
  • 대시보드에서 사용자 지정 반복 항목에는 Free trial days 필드가 있습니다. 상품의 청구 플랜은 자체 체험을 표시합니다.

정해진 결제 횟수 후 중지하기

6회 월별 결제와 같은 고정 결제 플랜을 청구하려면 반복 변형에 split_pay_required_payments를 2~115 사이로 설정하세요. 인보이스는 선불 수수료를 포함한 첫 번째 결제입니다. 예를 들어 $75 선불 수수료와 $40씩 3회 할부는 $115, $40, $40을 청구합니다. Whop은 해당 횟수의 결제가 이루어지면 갱신을 중지하며 멤버십은 활성 상태로 유지됩니다. 그 전에는 고객이 직접 구독을 취소할 수 없지만 판매자는 취소할 수 있습니다. 구독이 취소될 때까지 갱신하려면 설정하지 마세요.

상태와 수명 주기

status는 결제에서 값을 가져오므로, 결제가 진행 중일 때 인보이스에 pending 같은 결제 상태가 표시될 수도 있습니다. totals_status는 금액 필드가 확정되었는지 알려줍니다. 인보이스가 초안인 동안은 estimated, 발행 후에는 final입니다. overdue는 due_at이 지난 open 또는 uncollectible 인보이스에서 true입니다.

무효화 또는 회수 불가로 표시하기

Void Invoice는 draft, open, uncollectible 인보이스를 취소합니다. 이미 무효인 인보이스를 무효화하면 변경 없이 반환되며, 결제된 인보이스는 무효화할 수 없습니다. 수금을 기대하지 않는다는 것을 기록하려면 인보이스를 회수 불가로 표시하세요. open 인보이스만 표시할 수 있으며, 회수 불가 인보이스를 다시 표시하면 변경 없이 반환됩니다. 회수 불가 인보이스에는 checkout_link가 없으며 알림을 받지 않습니다. 이 예제는 open 인보이스를 회수 불가로 표시한 다음 무효화합니다:

인보이스 삭제하기

Delete Invoice는 DELETE /invoices/{id}로 draft 또는 void 인보이스를 제거합니다. 응답은 { id, deleted: true }입니다. 삭제된 인보이스는 더 이상 List Invoices나 List Payments에 나타나지 않으며, 해당 ID는 404를 반환합니다. 삭제는 취소할 수 없습니다. open 인보이스는 삭제하기 전에 무효화하세요. 예약 전송이나 청구가 있는 초안은 먼저 Cancel Scheduled Send가 필요합니다. 초안 갱신 인보이스는 구독을 청구하는 동안 삭제할 수 없습니다. 돈을 수금했거나 아직 은행 송금을 기다리는 무효 인보이스는 삭제할 수 없으며, 결제 완료, 보류 중, 회수 불가 인보이스도 마찬가지입니다. 인보이스를 삭제할 수 있으면 deletable 필드가 true입니다. 삭제하려면 invoice:update 또는 payment:charge가 필요합니다. 삭제된 초안의 번호는 재사용되지 않습니다.

인보이스 목록 조회 및 조회

List Invoices는 자격 증명으로 읽을 수 있는 인보이스를 최신순으로 반환합니다. API 키는 자신의 계정을 보고, 사용자 토큰은 사용자가 결제를 읽을 수 있는 모든 계정을 봅니다. 다음 쿼리 매개변수로 목록을 좁히세요: 예약된 초안은 scheduled_send_at이 있는 초안입니다. open 인보이스는 절대 예약 상태가 아니며, 기한에 전송되는 초안도 마찬가지입니다. order(created_at, due_at, scheduled_send_at)와 direction(asc 또는 desc)으로 정렬하세요. due_at 또는 scheduled_send_at으로 정렬하면 해당 날짜가 없는 인보이스가 마지막에 옵니다. 응답은 { data, page_info }입니다. page_info.has_next_page가 true인 동안 page_info.end_cursor를 after로 전달하여 다음 페이지를 읽으세요.
Retrieve Invoice는 pay_ ID로 인보이스 하나를 읽습니다. List Payments는 초안을 제외합니다. 인보이스를 CSV 파일로 내보내려면 resource: "receipt_invoices"로 Create Export를 호출하세요. payment:basic:read와 payment:basic:export가 필요합니다. 고객 열은 자격 증명에 member:basic:read 또는 member:email:read도 있을 때만 표시됩니다.

웹훅

네이티브 인보이스는 pay_ ID에 대한 결제 웹훅을 보냅니다. invoice.* 이벤트는 레거시 인보이스 API에 속하며, 네이티브 인보이스는 이를 보내지 않습니다. payment.failed 같은 다른 payment.* 이벤트도 결제 시도가 변경됨에 따라 인보이스의 pay_ ID에 대해 도착할 수 있습니다. 웹훅 가이드에서 구독하세요. 주문을 처리하려면 초안을 만들 때 인보이스의 id를 주문과 함께 저장하세요. payment.succeeded 이벤트의 data는 결제이므로 data.id가 인보이스의 pay_ ID입니다. 이벤트를 확인한 후 해당 ID로 주문을 조회하세요. 이 핸들러에서 orders는 자체 주문 저장소를 나타냅니다:
fulfilled를 확인하면 재전달된 이벤트로 인해 주문이 두 번 처리되는 것을 막을 수 있습니다. 구독 갱신은 고유한 pay_ ID를 가지므로 인보이스와 일치하지 않습니다.

인보이스 결제에 대한 결제 규칙

결제 규칙은 다른 체크아웃과 마찬가지로 Whop 자체의 사기 심사 후에 인보이스 결제에서 실행됩니다. 규칙이 할 수 있는 일은 고객이 참여하는지 여부에 따라 달라집니다.
  • 발행 시 자동 청구는 오프세션입니다. block 규칙은 이를 거절하고, allow 규칙은 다른 규칙에서 이를 면제합니다. review 및 enforce_3ds 규칙은 청구가 오프세션이므로 건너뜁니다.
  • 체크아웃 링크를 통한 결제는 온세션입니다. 사기 관리의 적격성 제한과 함께 네 가지 액션이 모두 적용됩니다.
자동 청구에서 카드 조건은 저장된 결제 수단을, 청구 조건은 인보이스의 청구 주소를 읽습니다. customer_email은 고객의 Whop 계정 이메일입니다. 결제의 payment_rule_matches에는 결정을 내린 규칙이 나열됩니다. 건너뛴 규칙은 나열되지 않습니다.

대시보드의 인보이스

Invoices 페이지에서 네이티브 인보이스를 나열하고, 생성하고, 전송합니다. 레거시 인보이스는 Legacy invoices 탭에 있으며, 인보이스 보내기에서 다룹니다.

권한

모든 쓰기 작업에는 Create Payment와 동일한 권한인 payment:charge가 필요하고, 모든 읽기 작업에는 payment:basic:read가 필요합니다. invoice:* 권한은 레거시 인보이스 API에 속하며 네이티브 인보이스는 이를 사용하지 않습니다. 인라인 plan 항목을 보내는 생성 또는 업데이트에는 plan:create도 필요합니다. 일부 필드에는 자체 권한이 필요합니다. 권한이 없으면 필드는 null로 반환되고, recipient_emails는 비어 있는 상태로 반환됩니다. POST 후 자격 증명이 이러한 읽기 권한 중 하나를 잃으면, 저장된 응답에 해당 필드가 표시되는 경우 같은 Idempotency-Key로 재생하는 요청은 error.code가 invoice_replay_permission_revoked인 403으로 거부됩니다. 대신 GET으로 인보이스를 가져오세요. 권한 가이드에서 권한을 추가하세요.

오류

거부는 { error: { type, message, code } }로 반환됩니다. 아래의 모든 코드는 별도로 명시하지 않는 한 400입니다. 알 수 없는 plan_id, member_id, mailing_address_id, payment_method_id는 404이며, Whop이 읽을 수 없는 타임스탬프는 invalid_timestamp가 포함된 400입니다. 다음 거부는 error.code가 없는 400이므로, 이유는 error.message에서 확인하세요:
  • 알 수 없는 최상위 필드.
  • 1~999,999 범위를 벗어난 quantity.
  • recipient_emails의 잘못된 주소 또는 50개 초과.
  • 청구 주기 불일치 같은 여러 항목 규칙 위반.

생성 및 업데이트 오류

발행 오류

전송 및 예약 오류

초안을 전송하면 발행되므로, 전송은 발행 오류의 어떤 이유로든 거부될 수 있습니다.

기타 오류

결제된 인보이스를 무효화하면 코드 없는 400이 반환됩니다.

다음 단계

인보이스 API 레퍼런스

모든 인보이스 엔드포인트, 매개변수, 응답 필드.

결제 수단 저장

인보이스가 발행 시 청구하는 저장된 결제 수단을 수집하세요.

사기 관리

인보이스 결제를 심사하는 결제 규칙을 작성하세요.

웹훅 수신하기

인보이스의 payment.created와 payment.succeeded를 추적하세요.