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 medpay_ 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.
- Du opretter en kladde med linjer, en kunde og faktureringsoplysninger. En kladde opkræver intet og sender ingen e-mails.
- 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.
- Kunden betaler. Whop opkræver kundens gemte betalingsmetode, når du udsteder eller sender fakturaen, eller kunden betaler via Whops hostede checkout.
- Du leverer ordren ud fra webhooket
payment.succeeded.
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.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 medPOST /invoices.
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
quantitytil 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.
quantityer 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.
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 medPATCH /invoices/{id}. Send kun de felter, du ændrer.
itemserstatter hele listen og læser hver variants aktuelle pris. Udelad det for at beholde de gemte linjer og priser.- Ændring af
member_idfjerner den gemte faktureringsadresse og betalingsmetode, medmindre du sender nye. Det beholderrecipient_emails, så send også en ny liste, ellers får den tidligere kunde stadig faktura-e-mailen. email_addressogcustomer_nameaccepteres ikke. Send et andetmember_idfor 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 eropenelleruncollectible. Enhver anden redigering afvises med en400.
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 medpayment_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:
- Kører de samme kontroller, som Create Payment kører på en gemt betalingsmetode.
- Reserverer lager til de fakturerede antal og forbereder betalingens gebyrer.
- Returnerer fakturaen som
openog opkræver metoden uden for sessionen. Opkrævningen kører på detcharge_at, du sender til Issue Invoice eller Send Invoice, ellers pådue_at, mens det stadig ligger forude, ellers med det samme.scheduled_charge_atviser en opkrævning, der endnu ikke er sket.
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 fakturaenopen 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.
Udsted fakturaen
Issue Invoice gør en kladde til en åben faktura. Whop kontrollerer fakturaen igen, beregner den endelige moms og sætterstatus 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_amounternullpå en kladde og sættes, når du udsteder den.totalogamount_duemedtager 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.createdudløses én gang for fakturaenspay_-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.
Hent checkout-linket
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.Send, planlæg og påmind
Send Invoice sender en faktura pr. e-mail medPOST /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.
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.
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_emailspå enopenfaktura stopper dens resterende påmindelser.
Når Whop opkræver i stedet for at sende e-mail
En kladde med etpayment_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 en429, 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 sendesend_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_atskal 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_atfor 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_atvender tilbage tilnull, 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.
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 endue_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 medGET /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æverpayment:basic:read og virker ved enhver status.
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.- 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-11fakturerer dens første fakturainitial_priceplusrenewal_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. Fakturalinjensinitial_priceangiver den engangsdel afunit_amount, og fakturasiden, e-mailen og PDF’en viser den på sin egen linje Upfront fee. - 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. - 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.
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 variantstrial_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_priceplusrenewal_price. Fornyelsesfakturaer starter aldrig en prøveperiode. - Prøveperioden kommer fra varianten. For en brugerdefineret tilbagevendende linje skal du angive
variant.trial_period_days. Ettrial_period_dayspå 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 medcollection_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 angivesplit_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 endraft, 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 endraft 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.
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 derespay_-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:
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 enallow-regel undtager den fra dine andre regler.review- ogenforce_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.
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
quantityuden for 1 til 999.999. - En ugyldig adresse i
recipient_emailseller 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.
