Skip to main content
En faktura er en nummereret regning for en eller flere af dine varianter, rettet til én kunde. En variant er en pris- og faktureringsopsætning, du sælger, som regel for et produkt. Dens ID starter med plan_, og fakturalinjer modtager den som plan_id. Brug en faktura, når du aftaler en pris med en kunde, før vedkommende betaler, f.eks. et tilbud, en serviceydelse eller en erhvervsordre. Du bygger en kladde, indtil den er rigtig, og udsteder den derefter for at låse beløbene og åbne den for betaling. Afsendelse gør det samme og sender den pr. e-mail i ét kald. Se Opret og send fakturaer for at sende en fra dit dashboard uden kode.
Fakturaerne på denne side kræver Api-Version-Date: 2026-10-24 eller senere på hver anmodning. Anmodninger med en tidligere version rammer det ældre faktura-API, som fungerer anderledes. Se Før du starter.

Sådan fungerer en faktura

En native faktura er en betaling. Dens ID starter med pay_ og forbliver det samme, efter kunden har betalt, så du kan også læse den med Retrieve Payment. Hver faktura får også det næste nummer i din kontos egen nummerserie, f.eks. #00000042, eller #ACME-00000042, når din konto har et fakturapræfiks.
  1. Du opretter en kladde med linjer, en kunde og faktureringsoplysninger. En kladde opkræver intet og sender ingen e-mails.
  2. Du udsteder den eller sender den. Udstedelse beregner den endelige moms og åbner fakturaen for betaling. Afsendelse udsteder den og sender den pr. e-mail, enten nu eller på et tidspunkt, du planlægger.
  3. Kunden betaler. Whop opkræver kundens gemte betalingsmetode, når du udsteder eller sender fakturaen, eller kunden betaler via Whops hostede checkout.
  4. Du leverer ordren ud fra webhooket payment.succeeded.
Fakturaer fakturerer køb nu-varianter, dvs. dem med release_method: buy_now i stedet for en venteliste. En engangsvariant faktureres én gang, og en tilbagevendende variant starter et abonnement, når fakturaen er betalt. Se Fakturer et abonnement, som også beskriver, hvordan du stopper det efter et bestemt antal betalinger.

Før du starter

Send API-versionen

/invoices betjener to forskellige API’er, og den Api-Version-Date, din anmodning resolver til, afgør, hvilket der svarer. Udstedelse, afsendelse, annullering af en planlagt afsendelse og generering af en PDF findes kun i det native API, så de rammer native fakturaer, uanset hvilken version du sender. De stier, begge API’er har, f.eks. GET /invoices og POST /invoices/{id}/void, følger versionen. Send headeren på hver anmodning i stedet for at stole på en nøgles fastlåsning, så et skift af nøgler aldrig flytter dig mellem de to. API-versioner forklarer fastlåsninger og ændringsloggen. Det native API viser eller henter ikke ældre inv_-fakturaer, og det ældre API returnerer ikke native fakturaer.

Kald API’et

Eksemplerne på denne side kalder API’et via en lille hjælpefunktion, der sender versionsheaderen på hver anmodning.
Send en Idempotency-Key på hver POST, så et genforsøg aldrig opretter en ekstra faktura eller gentager en handling. Generate Invoice PDF er undtagelsen: hvert kald laver en ny fil, så det genafspiller ikke svar.

Opret en kladde

Create Invoice gemmer en kladde med POST /invoices.
Svaret er 201 Created med kladden. Oprettelse af en kladde opkræver intet, sender ingen e-mail og sender intet webhook. Dette svar viser et udsnit af felterne:
account_id er den konto, der udsteder fakturaen, med præfikset biz_. En konto-API-nøgle kan udelade det for at bruge sin egen konto. Create Invoice viser alle felter i anmodning og svar. En kladde bruger sit nummer, når du opretter den, så en kladde, du kasserer, efterlader et hul i din nummerserie. For at kassere en kladde skal du slette den. For at beholde den på din liste skal du i stedet annullere den.

Tilføj linjer

items tager 1 til 50 linjer. Hver linje tager enten plan_id for en eksisterende variant eller plan for at finde eller oprette en inline, plus en valgfri quantity. En inline plan bruger det samme find-eller-opret-input som Create Payment, f.eks. { "plan": { "product_id": "prod_xxxxxxxxxxxxx", "plan_type": "one_time", "initial_price": 250, "currency": "usd" } }. Det kræver plan:create, og et inline product kræver også produkttilladelsen, access_pass:create eller access_pass:update. Oprettelse og opdatering afviser linjer, der bryder disse regler:
  • Hver linje er en køb nu-variant fra din konto. En variant optræder én gang, så brug quantity til flere enheder.
  • Ingen variant er arkiveret, og udstedelse eller afsendelse af en kladde kontrollerer dette igen, så gendan varianten fra arkivet, eller vælg en anden.
  • quantity er mellem 1 og 999.999 og kun over 1 for en variant, der tillader flere enheder. Tilbagevendende varianter gør ikke, så en tilbagevendende linjes antal er 1.
  • En tilbagevendende variant skal tilhøre et produkt.
  • Alle linjer bruger samme valuta.
  • I en faktura med flere linjer skal hver linje, der har et produkt, være et almindeligt produkt (standardproduktypen), ikke en app. Tilbagevendende linjer deler én faktureringsperiode, længde på gratis prøveperiode og split_pay_required_payments, og alle linjer skal have kompatible indstillinger for betaling, moms og adgang. Varianter med brugerdefinerede felter eller en adgangskode kan ikke kombineres. Linjer uden et produkt, f.eks. et brugerdefineret gebyr, kan stå ved siden af resten.
Hver fakturalinje i svaret har en label, som er produktets titel, eller variantens titel for en variant uden produkt. E-mailen, PDF’en og checkouten viser den. Kladden beholder den pris, hver variant havde, da du gemte dens linjer, så en senere prisændring på varianten flytter ikke fakturaen. En engangslinje faktureres til sin pris. Fra API-version 2026-11-11 medtager oprettelse eller udskiftning af en tilbagevendende linje dens initial_price plus renewal_price i den første faktura. Tidligere versionsfastlåsninger bruger kun fornyelsesprisen. Redigeringer, der udelader items, bevarer de gemte priser.

Angiv kunde og faktureringsoplysninger

Send member_id eller email_address og billing_address eller mailing_address_id, aldrig begge i et par. En faktureringsadresse kræver en kunde. En kunde er valgfri på en kladde og påkrævet for at udstede den. Whop beregner moms, når du udsteder fakturaen, og bruger faktureringsadressen til at placere kunden. Når der skal betales moms, og Whop ikke kan afgøre, hvor kunden befinder sig, afvises udstedelsen, så tilføj en faktureringsadresse, når du opkræver moms.

Rediger en kladde

Update Invoice ændrer en kladde med PATCH /invoices/{id}. Send kun de felter, du ændrer.
  • items erstatter hele listen og læser hver variants aktuelle pris. Udelad det for at beholde de gemte linjer og priser.
  • Ændring af member_id fjerner den gemte faktureringsadresse og betalingsmetode, medmindre du sender nye. Det beholder recipient_emails, så send også en ny liste, ellers får den tidligere kunde stadig faktura-e-mailen.
  • email_address og customer_name accepteres ikke. Send et andet member_id for at fakturere en anden.
  • En kladde med en planlagt afsendelse accepterer kun en ændring af recipient_emails, indtil du annullerer afsendelsen.
  • Når fakturaen er udstedt, er den eneste ændring, du kan foretage, recipient_emails, sendt alene og kun mens fakturaen er open eller uncollectible. Enhver anden redigering afvises med en 400.

Vælg, hvordan kunden betaler

Der er to måder at få betaling for en udstedt faktura på. Vælg én, før du udsteder den, fordi den gemte betalingsmetode lægges på kladden. En udstedt faktura får et checkout_link, selv når den har en gemt betalingsmetode. Hvis den automatiske opkrævning fejler, kan kunden stadig betale via checkout.

Opkræv en gemt betalingsmetode

Læg en gemt betalingsmetode på kladden med payment_method_id. Det skal være en af kundens gemte metoder. Gem betalingsmetoder viser, hvordan en kunde gemmer en, og List payment methods finder dem, et medlem har. Når du udsteder eller sender fakturaen, og dens total er over nul, gør Whop følgende:
  1. Kører de samme kontroller, som Create Payment kører på en gemt betalingsmetode.
  2. Reserverer lager til de fakturerede antal og forbereder betalingens gebyrer.
  3. Returnerer fakturaen som open og opkræver metoden uden for sessionen. Opkrævningen kører på det charge_at, du sender til Issue Invoice eller Send Invoice, ellers på due_at, mens det stadig ligger forude, ellers med det samme. scheduled_charge_at viser en opkrævning, der endnu ikke er sket.
Svaret fortæller dig ikke, om opkrævningen lykkedes. Lever ud fra webhooket payment.succeeded for fakturaens pay_-ID. En betalt faktura gennemfører medlemskabet, og dine metadata ligger på opkrævningen og medlemskabet. Betalingsregler på fakturabetalinger beskriver, hvordan dine betalingsregler screener opkrævningen.

Hvis den automatiske opkrævning afvises

En afvist opkrævning efterlader fakturaen open og frigiver det reserverede lager. Hent fakturaen som en betaling, og læs failure_message for at se, hvorfor det seneste forsøg fejlede. Når opkrævningen afvises eller kræver, at kunden handler, sender Whop fakturaens betalingslink pr. e-mail til dens modtagere, så kunden i stedet kan betale via checkout. Det er den eneste e-mail, Whop sender for en faktura, du udsteder uden at sende den. Det kræver et checkout_link og mindst én post i recipient_emails, og det tæller ikke med i afsendelsesgrænsen.
En opkrævning uden for sessionen kan ikke vise kunden en 3D Secure-udfordring. Hvis kundens bank beder om en, gennemføres den automatiske opkrævning ikke, og fakturaen forbliver ubetalt, indtil kunden godkender eller betaler på en anden måde.

Udsted fakturaen

Issue Invoice gør en kladde til en åben faktura. Whop kontrollerer fakturaen igen, beregner den endelige moms og sætter status til open og totals_status til final. Når fakturaen har en gemt betalingsmetode og en total over nul, opkræver Whop den derefter som beskrevet i Opkræv en gemt betalingsmetode.
  • Momsen bliver endelig. tax_amount er null på en kladde og sættes, når du udsteder den. total og amount_due medtager den.
  • Whop opretter kundens medlemskab, når fakturaen fakturerer et produkt. Det forbliver i kladdetilstand uden adgang, indtil fakturaen er betalt. En faktura, hvor ingen linjer har et produkt, får intet medlemskab.
  • payment.created udløses én gang for fakturaens pay_-ID.
  • Det er sikkert at udstede igen. Udstedelse af en faktura, der allerede er open, kører de samme kontroller igen og returnerer den uændret, hvis de består: dens beløb bevares, og intet opkræves igen.
  • Udstedelse sender ikke fakturaen pr. e-mail, bortset fra betalingslinket efter en afvist opkrævning. For at sende fakturaen pr. e-mail skal du i stedet sende den eller selv levere checkout-linket.
En afvist udstedelse ændrer intet og opkræver intet. Ret årsagen, og udsted fakturaen igen. Fejl ved udstedelse viser årsagerne. En udstedt, open faktura har et checkout_link, en signeret værdi i formen pay_xxxxxxxxxxxxx.<signature>. Det åbner fakturaen på Whops hostede checkout til dens faste pris.
1

Læs linket fra den udstedte faktura

checkout_link er null, medmindre fakturaen er open, så kladder og betalte, annullerede eller uerholdelige fakturaer har ikke et. Det er også null for en faktura, der er faktureret til en erhvervskøber, en faktura, hvis medlemskab er opsagt, og når din legitimation mangler payment:charge. En erhvervskøber er en kunde, der er en anden Whop-konto i stedet for en person.
2

Byg URL'en til den hostede checkout

Del linket ved dets første .: fakturaens pay_-ID står før det, og tokenet efter det.
3

Send det til kunden

Send fakturaen for at lade Whop sende linket pr. e-mail, eller indsæt URL’en i din egen e-mail eller fakturaside. Kun fakturaens kunde kan betale via den. Alle andre afvises og bliver bedt om at logge ind som fakturaens kunde. Linket holder op med at virke, når fakturaen er betalt, annulleret eller markeret som uerholdelig.
4

Lever ud fra webhooket

Lyt efter payment.succeeded for fakturaens pay_-ID, på samme måde som for den automatiske opkrævning. Webhooks viser en handler.
Checkouten viser fakturaens nummer og forfaldsdato ved siden af dens linjer, og forfaldsdatoen bliver rød, når den er overskredet. Kunden betaler linjerne og totalen på fakturaen og kan ikke tilføje en rabatkode.

Send, planlæg og påmind

Send Invoice sender en faktura pr. e-mail med POST /invoices/{id}/send. Afsendelse af en kladde udsteder den først, på samme måde som Issue Invoice. Afsendelse af en open faktura sender den igen.
E-mailen viser din kontos navn og logo, fakturanummeret, totalen, forfaldsdatoen, hver linje og en knap, der åbner fakturaens checkout. Whop sender kun en faktura pr. e-mail, som kunden kan betale fra e-mailen. En open faktura skal have et checkout_link for at blive sendt, og en kladde skal have en kunde, der ikke er en erhvervskøber. En kladde, der er faktureret til en erhvervskøber, kan stadig sendes, når den har en gemt betalingsmetode, fordi den i stedet opkræves.

Hvem får e-mailen

Hver afsendelse sender én e-mail til hver adresse som en separat e-mail, så modtagerne aldrig ser hinandens adresser. Adresserne er:
  • E-mailen på kundens Whop-konto, som faktura-PDF’en udskriver under Bill to.
  • Hver post i recipient_emails.
Whop gemmer recipient_emails med små bogstaver og fjerner dubletter fra listen, så en adresse, der står begge steder, får én e-mail. En tom recipient_emails betyder, at Whop ikke sender e-mail til nogen, heller ikke kunden. Brug det til at forhindre Whop i at sende en faktura pr. e-mail:
  • Send Invoice afviser fakturaen, medmindre den i stedet opkræver en gemt betalingsmetode.
  • Der sendes intet betalingslink efter en afvist opkrævning.
  • Der sendes ingen påmindelser. Rydning af recipient_emails på en open faktura stopper dens resterende påmindelser.

Når Whop opkræver i stedet for at sende e-mail

En kladde med et payment_method_id og en total over nul opkræves i stedet for at blive sendt pr. e-mail, på samme måde som når du udsteder den. Hvis den automatiske opkrævning afvises beskriver, hvad der sker, når opkrævningen fejler. En sådan kladde kan sendes med en tom recipient_emails, fordi ingen har brug for e-mailen.

Afsendelsesgrænse

Hver faktura kan sendes pr. e-mail tre gange inden for 24 timer, inklusive den afsendelse, der udstedte den. En fjerde afsendelse inden for det tidsrum afvises med en 429, hvis error.code er invoice_send_limit_reached. Påmindelser, betalingslinket efter en afvist opkrævning og en afsendelse, der opkræver i stedet for at sende e-mail, tæller ikke med i grænsen.

Planlæg en afsendelse

For i stedet at sende en kladde senere skal du sende send_at. Kladden forbliver en kladde og viser tidspunktet i scheduled_send_at. På det tidspunkt sender Whop den, som om du havde kaldt Send Invoice da.
  • Kun en kladde kan planlægges, og send_at skal ligge i fremtiden. Whop kontrollerer modtagerne og betalingslinket, når du planlægger, på samme måde som ved en øjeblikkelig afsendelse.
  • Send igen med et nyt send_at for at flytte tidspunktet.
  • Redigering er låst, indtil afsendelsen sker, eller du annullerer den. En opdatering, der kun ændrer recipient_emails, virker stadig, men den kan ikke fjerne den sidste modtager fra en kladde, der ikke bliver opkrævet.
  • Cancel Scheduled Send med POST /invoices/{id}/unschedule. scheduled_send_at vender tilbage til null, og kladden kan redigeres igen. Annullering for en faktura uden planlagt afsendelse returnerer den uændret.
  • Annullering af en planlagt kladde stopper dens planlagte afsendelse.
Whop tjekker for forfaldne afsendelser hvert minut, så en planlagt afsendelse går ud inden for cirka et minut efter send_at. Hvis den afvises, f.eks. fordi en variant er blevet slettet, siden du planlagde den, forbliver fakturaen en kladde, scheduled_send_at vender tilbage til null, og API’et returnerer ikke årsagen. Enhver anden fejl forsøges igen cirka hvert 10. minut, op til 12 forsøg i alt. Indtil et forsøg lykkes, eller Whop holder op med at forsøge igen, viser scheduled_send_at tidspunktet for næste forsøg i stedet for null. Læs fakturaen efter send_at for at bekræfte, at den er open.

Påmindelser

Når Send Invoice sender en faktura pr. e-mail, der har en due_at, planlægger Whop også påmindelser 1, 3, 7, 14, 30 og 60 dage efter due_at og springer dem over, hvis dato allerede er passeret. Hver påmindelse går til de samme adresser som fakturaen og angiver, hvor mange dage fakturaen er over forfald. Påmindelser sendes kun, mens fakturaen er open, så de stopper, når den er betalt, annulleret eller markeret som uerholdelig. En påmindelse, der forfalder, mens en betaling er i gang, venter, til betalingen er afsluttet. En faktura, du udsteder uden at sende, eller en, der opkræves i stedet for at blive sendt pr. e-mail, får ingen påmindelser.

E-mailhistorik

List Invoice Sends returnerer registrerede e-mailbatches med GET /invoices/{id}/sends, nyeste først. Den omfatter første og gentagne e-mails, planlagte e-mails, påmindelser og opfølgninger på betaling efter en mislykket opkrævning af en gemt betalingsmetode. Brug den første post for den senest registrerede afsendelse, og page_info.end_cursor som after for at læse ældre poster. Manuelle batches bruger send, når fakturaen ikke har nogen tidligere gennemført e-mailhistorik, og ellers resend. Typen vælges, når den gennemførte batch registreres, så anmodninger, der er sat i kø sammen, klassificeres i den rækkefølge, de gennemføres. Tidligere ikke-registrerede e-mails forbliver ukendte. Hver post indeholder kind, sent_at, recipient_count, recipients og actor. Læsning af historik kræver payment:basic:read. Adresser kræver også member:email:read. Uden den er recipients tom. Afsenderen kræver også company:authorized_user:read. Ellers er actor null. Automatiske afsendelser og konto-API-nøgler har også en null-actor. Workeren tilføjer en post efter at have indsendt hele batchen til levering. For en delvis batch tilføjer den kun en post, hvis et genforsøg gennemfører batchen. Posten beholder den oprindelige modtagerliste. En registreret batch bekræfter ikke levering til indbakken. Maileren kan undertrykke beskeder, hvis fakturaen eller modtagerne ændres før levering. Historikken udelader e-mails, der blev sendt, før denne funktion blev indført. Udstedelse af en faktura uden at sende e-mail tilføjer ingen historikpost.

Download en PDF

Generate Invoice PDF bygger fakturaen som en PDF og returnerer et kortlivet link til den. Det kræver payment:basic:read og virker ved enhver status.
Svaret har url og expires_at. Linket virker i 15 minutter, og alle, der har det, kan downloade filen. Generer et nyt, når det udløber. PDF’en sætter din virksomhed i front: din kontos navn står øverst på siden, og sidefoden angiver, at Whop Inc udsteder fakturaen i dit navn og på dine vegne. Den viser fakturanummeret, dens dato og forfaldsdato og oplysningerne under Bill to. Hver linje viser antal, enhedspris og beløb efterfulgt af subtotal, servicegebyr, moms og skyldigt beløb. En faktura med en tilbagevendende linje angiver også fornyelsesbeløbet og hvor ofte, den fornyes. En kladdes PDF viser de estimerede beløb med moms på nul, indtil du udsteder den. Noget af indholdet afhænger af din legitimations tilladelser:

Fakturer et abonnement

Læg en tilbagevendende variant på en faktura for at starte et abonnement, når kunden betaler den. Whop fornyer det derefter én gang pr. faktureringsperiode.
  1. Fakturaen fakturerer den første periode og et eventuelt startgebyr. En tilbagevendende linje skal tilhøre et produkt og har et antal på 1. Fra API-version 2026-11-11 fakturerer dens første faktura initial_price plus renewal_price. Betaling starter den første betalte faktureringsperiode med det samme, medmindre varianten har en gratis prøveperiode. Så starter abonnementet med prøveperioden. I dashboardet har en brugerdefineret tilbagevendende linje et valgfrit felt Upfront fee. Fakturalinjens initial_price angiver den engangsdel af unit_amount, og fakturasiden, e-mailen og PDF’en viser den på sin egen linje Upfront fee.
  2. Betaling af fakturaen starter abonnementet, uanset om Whop opkræver den gemte betalingsmetode ved udstedelse, eller kunden betaler via checkout_link. Den første periode starter ved betalingen. Checkouten, der åbnes fra linket, angiver fornyelsesbeløbet, inklusive fakturaens købergebyr, og hvor ofte den fornyes.
  3. Hver fornyelse opkræves på den måde, du valgte, da du udstedte eller sendte fakturaen. Den fakturerer kun de tilbagevendende linjer med fakturaens købergebyr til hver variants fornyelsespris på det tidspunkt, du udstedte fakturaen. Den kan afvige fra den pris, der er gemt på kladden, hvis variantens pris ændrede sig, efter du gemte linjerne. Engangslinjer faktureres én gang.
Send collection_method til Issue Invoice eller Send Invoice for at vælge, hvordan fornyelser opkræves. En planlagt afsendelse anvender den collection_method, du planlagde den med, som kladden viser som scheduled_collection_method. send_invoice kræver mindst én adresse i recipient_emails og er ikke tilgængelig for fakturaer, der er faktureret til en virksomhed. Mens den gælder, kan fakturaens sidste modtager ikke fjernes. En faktura uden tilbagevendende linje afviser collection_method. Betaling af den første faktura med kort bevarer send_invoice. Hver fornyelse er sin egen betaling med sit eget pay_-ID og egne payment.*-webhooks. En charge_automatically-fornyelse er ikke en nummereret faktura, så den vises ikke i List Invoices. En send_invoice-fornyelse er en nummereret faktura i List Invoices, og Whop opkræver den ikke automatisk. Abonnementet forbliver past_due, indtil kunden betaler via fakturaens checkout_link. Kunden beholder adgangen i mellemtiden. Opsig medlemskabet for at stoppe fornyelser. Når medlemskabet er opsagt, holder en åben fornyelsesfakturas checkout_link op med at virke. For at finde abonnementet skal du hente fakturaen som en betaling og læse dens membership_id, hvilket kræver member:basic:read.

Start med en gratis prøveperiode

En faktura respekterer en tilbagevendende variants trial_period_days, ligesom checkout gør. Den første faktura fakturerer kun variantens initial_price. Betaling af den starter prøveperioden, og den første fornyelse fakturerer renewal_price, når prøveperioden slutter. Fakturaer oprettet før 2026-11-16 17:00 UTC fakturerer den første periode og springer prøveperioden over.
  • En kunde, der allerede har haft et abonnement på varianten, får ingen prøveperiode. Kundens første faktura fakturerer initial_price plus renewal_price. Fornyelsesfakturaer starter aldrig en prøveperiode.
  • Prøveperioden kommer fra varianten. For en brugerdefineret tilbagevendende linje skal du angive variant.trial_period_days. Et trial_period_days på linjeniveau afvises.
  • Alle tilbagevendende linjer på fakturaen skal have samme længde på prøveperioden.
  • Når fakturaen ikke opkræver noget, skal du udstede eller sende den med et payment_method_id, som starter prøveperioden med det samme, eller med collection_method: "send_invoice".
  • I dashboardet har en brugerdefineret tilbagevendende linje feltet Free trial days. Et produkts faktureringsplan viser sin egen prøveperiode.

Stop efter et bestemt antal betalinger

For at fakturere en fast betalingsplan, f.eks. seks månedlige betalinger, skal du angive split_pay_required_payments på den tilbagevendende variant, fra 2 til 115. Fakturaen er den første betaling, inklusive et eventuelt startgebyr. For eksempel fakturerer et startgebyr på $75 med tre rater på $40 først $115, derefter $40 og så $40. Whop holder op med at forny, når så mange betalinger er foretaget, og medlemskabet forbliver aktivt. Kunden kan ikke selv opsige abonnementet før da, men det kan du. Lad det være tomt for at forny, indtil abonnementet opsiges.

Statusser og livscyklus

status tager sine værdier fra betalinger, så en faktura kan også vise en betalingstilstand som pending, mens en betaling er i gang. totals_status fortæller dig, om beløbsfelterne er endelige: estimated, mens fakturaen er en kladde, og final, efter du har udstedt den. overdue er true for en open eller uncollectible faktura, hvis due_at er passeret.

Annuller eller marker som uerholdelig

Void Invoice annullerer en draft, open eller uncollectible faktura. Annullering af en faktura, der allerede er annulleret, returnerer den uændret, og en betalt faktura kan ikke annulleres. Marker en faktura som uerholdelig for at registrere, at du ikke forventer at inddrive den. Kun en open faktura kan markeres, og en ny markering af en uerholdelig faktura returnerer den uændret. En uerholdelig faktura har intet checkout_link og får ingen påmindelser. Dette eksempel markerer en open faktura som uerholdelig og annullerer den derefter:

Slet en faktura

Delete Invoice fjerner en draft eller void faktura med DELETE /invoices/{id}. Svaret er { id, deleted: true }. En slettet faktura vises ikke længere i List Invoices eller List Payments, og dens ID returnerer en 404. Du kan ikke fortryde en sletning. Annuller en open faktura, før du sletter den. En kladde med en planlagt afsendelse eller opkrævning kræver først Cancel Scheduled Send. En fornyelsesfaktura i kladdetilstand kan ikke slettes, mens den fakturerer et abonnement. En annulleret faktura, der har inddrevet penge eller stadig venter på en bankoverførsel, kan ikke slettes, og det kan en betalt, afventende eller uerholdelig faktura heller ikke. En fakturas felt deletable er true, når den kan slettes. Sletning kræver invoice:update eller payment:charge. Nummeret på en slettet kladde genbruges ikke.

Vis og hent fakturaer

List Invoices returnerer de fakturaer, din legitimation kan læse, nyeste først. En API-nøgle ser sin egen konto, og et brugertoken ser alle konti, som brugeren kan læse betalinger for. Indsnævr listen med disse forespørgselsparametre: En planlagt kladde er en med et scheduled_send_at. En open faktura er aldrig planlagt, og det er en kladde, der sendes på sin forfaldsdato, heller ikke. Sorter med order (created_at, due_at eller scheduled_send_at) og direction (asc eller desc). Sortering efter due_at eller scheduled_send_at placerer fakturaer uden den dato sidst. Svaret er { data, page_info }. Så længe page_info.has_next_page er true, skal du sende page_info.end_cursor som after for at læse næste side.
Retrieve Invoice læser én faktura ud fra dens pay_-ID. List Payments udelader kladder. For at eksportere fakturaer som en CSV-fil skal du kalde Create Export med resource: "receipt_invoices". Det kræver payment:basic:read og payment:basic:export. Kundekolonnerne vises kun, når din legitimation også har member:basic:read eller member:email:read.

Webhooks

Native fakturaer sender betalingswebhooks for deres pay_-ID. invoice.*-events hører til det ældre faktura-API, og native fakturaer sender dem ikke. Andre payment.*-events, f.eks. payment.failed, kan også ankomme for fakturaens pay_-ID, efterhånden som dens betalingsforsøg ændrer sig. Abonner på dem med guiden om webhooks. For at levere en ordre skal du gemme fakturaens id sammen med ordren, når du opretter kladden. data i en payment.succeeded-event er betalingen, så data.id er fakturaens pay_-ID. Når du har verificeret eventen, skal du slå ordren op ud fra det ID. I denne handler står orders for dit eget ordrelager:
Tjekket af fulfilled forhindrer, at en genleveret event leverer ordren to gange. Abonnementsfornyelser har deres egne pay_-ID’er, så de matcher ikke en faktura.

Betalingsregler på fakturabetalinger

Dine betalingsregler kører på fakturabetalinger efter Whops egen svindelscreening, ligesom de gør på enhver checkout. Hvad de kan gøre, afhænger af, om kunden er til stede.
  • Den automatiske opkrævning ved udstedelse sker uden for sessionen. En block-regel afviser den, og en allow-regel undtager den fra dine andre regler. review- og enforce_3ds-regler springes over, fordi opkrævningen sker uden for sessionen.
  • En betaling via checkout-linket sker i sessionen. Alle fire handlinger gælder med begrænsningerne for berettigelse i Håndter svindel.
Ved den automatiske opkrævning læser kortbetingelser den gemte betalingsmetode, og faktureringsbetingelser læser fakturaens faktureringsadresse. customer_email er e-mailen på kundens Whop-konto. Betalingens payment_rule_matches viser den regel, der afgjorde den. En regel, der er sprunget over, vises ikke.

Fakturaer i dashboardet

Siden Invoices viser, opretter og sender native fakturaer. Ældre fakturaer ligger på dens fane Legacy invoices, som Send en faktura beskriver.

Tilladelser

Hver skrivning kræver payment:charge, den samme tilladelse som Create Payment, og hver læsning kræver payment:basic:read. invoice:*-tilladelserne hører til det ældre faktura-API, og native fakturaer bruger dem ikke. En oprettelse eller opdatering, der sender en inline plan-linje, kræver også plan:create. Nogle felter kræver deres egen tilladelse. Uden den returneres feltet som null, og recipient_emails returneres tom. Hvis din legitimation mister en af disse læsetilladelser efter en POST, afvises en genafspilning med samme Idempotency-Key med en 403, hvis error.code er invoice_replay_permission_revoked, når det gemte svar viser de felter. Hent i stedet fakturaen med GET. Tilføj tilladelser fra guiden om tilladelser.

Fejl

Afvisninger returneres som { error: { type, message, code } }. Hver kode nedenfor er en 400, medmindre andet er angivet. Et ukendt plan_id, member_id, mailing_address_id eller payment_method_id er en 404, og et tidsstempel, som Whop ikke kan læse, er en 400 med invalid_timestamp. Disse afvisninger er en 400 uden error.code, så læs error.message for at se årsagen:
  • Et ukendt felt på øverste niveau.
  • En quantity uden for 1 til 999.999.
  • En ugyldig adresse i recipient_emails eller flere end 50 af dem.
  • En brudt regel for flere linjer, f.eks. uoverensstemmende faktureringsperioder.

Fejl ved oprettelse og opdatering

Fejl ved udstedelse

Fejl ved afsendelse og planlægning

Afsendelse af en kladde udsteder den, så en afsendelse kan også afvises af enhver årsag i Fejl ved udstedelse.

Andre fejl

Annullering af en betalt faktura er en 400 uden kode.

Næste trin

API-reference for fakturaer

Alle faktura-endpoints, parametre og svarfelter.

Gem betalingsmetoder

Indsaml den gemte betalingsmetode, som en faktura opkræver ved udstedelse.

Håndter svindel

Skriv de betalingsregler, der screener fakturabetalinger.

Lyt til webhooks

Følg payment.created og payment.succeeded for dine fakturaer.