/invoices-stier som ældre fakturaer, men har et andet request-format og en anden livscyklus. Denne guide kortlægger de felter og handlinger, du skal ændre, når du migrerer en integration.
De fælles stier peger på native fakturaer fra og med
Api-Version-Date: 2026-10-24.
De native eksempler nedenfor bruger Api-Version-Date: 2026-11-02-1 med de
nuværende feltnavne for varianter og reglerne for låsning af kunder. Send den header med
hver native request. Hold ældre kald på en tidligere udgivet version, f.eks.
2026-10-15-1. API-versioner forklarer, hvordan headers
tilsidesætter versionsfastlåsninger på legitimationsoplysninger.Hvad der ændrer sig
Det native API lister eller henter ikke ældre
inv_-fakturaer. Fortsæt med at læse eksisterende ældre fakturaer med den tidligere API-version. Når du opretter en native faktura, oprettes en separat regning. Den konverterer eller udligner ikke en ældre faktura.
Før du migrerer
Tjek disse forskelle, før du flytter et forløb. Behold det på det ældre API, hvis det har brug for en funktion, som det native API ikke tilbyder.Kortlæg create-requesten
En ældre oprettelse sender én plan og eventuelt labels, der opdeler dens pris. En native oprettelse sender et item for hver fakturerede variant. Disse eksempler angiver en samlet item-pris på 19,99 USD. Den eksisterende native variant repræsenterer opsætningsgebyret på 15 USD. Servicegebyret på 4,99 USD er en brugerdefineret engangsopkrævning uden et produkt. Begge API’er accepterer priser i valutaenheder. Brug4.99 for 4,99 USD. Sender du 499, faktureres 499 USD.
POST /invoices/{id}/send for at udstede og e-maile den. member_id identificerer en kunde (mber_), ikke et abonnement (mem_).
For native versioner før
2026-10-27-2 skal du bruge plan_id, plan og plan_type i stedet for variant_id, variant og billing_type. Svarets linjeposter bruger også plan_id på de ældre versioner.
Hold udstedte beløb låst
PATCH /invoices/{id} redigerer en kladdes items og faktureringsoplysninger. Sender du items, erstattes hele listen med varianternes aktuelle priser. Udelader du det, bevares de gemte items og priser.
- Annuller en planlagt afsendelse, før du redigerer items eller faktureringsoplysninger.
- Fra og med
2026-11-02-1kan du ikke erstatte eller rydde en kladdes tildelte kunde. En kladde uden kunde kan stadig få en. Annuller kladden, før du opretter en ny faktura til en anden. email_addressogcustomer_nameer input, der kun bruges ved oprettelse.- Udstedte beløb og items er låst. En opdatering, der kun indeholder
memoog/ellerrecipient_emails, er tilladt pådraft-,open- oguncollectible-fakturaer, herunder en planlagt kladde.
Udsted, send og opkræv
En ældre oprettelse vælger indkrævningsadfærd medcollection_method. Native fakturaer bruger separate kald efter oprettelsen af kladden:
- Udsted den med
POST /invoices/{id}/issuefor at beregne endelig moms og åbne den for betaling uden at sende den første faktura-e-mail. - Eller send den med
POST /invoices/{id}/send. Det udsteder kladden. Den e-mailer modtagerne, medmindre den opkræver en gemt metode med det samme. Sender du enopen-faktura, e-mailes den igen.send_atplanlægger en kladdes afsendelse.POST /invoices/{id}/unscheduleannullerer den plan. - Opkræv en gemt metode ved at angive
payment_method_idpå kladden. For en positiv total opkræver udstedelse eller afsendelse på et fremtidigtcharge_at, ellers et fremtidigtdue_at, ellers med det samme.charge_atskal ligge i fremtiden og kan ikke ligge førsend_at.
open-svar bekræfter ikke betaling. Vent på payment.succeeded, før du leverer. Brug Charge Invoice til at opkræve eller prøve en åben faktura igen. At udstede eller sende den igen starter ikke en ny opkrævning.
For en tilbagevendende variant styrer collection_method på Issue Invoice eller Send Invoice fornyelser. charge_automatically indkræver fremtidige betalinger automatisk. send_invoice opretter og e-mailer en ny faktura hver periode. Det erstatter ikke payment_method_id til indkrævning af den første faktura. Se Fakturer et abonnement.
Kortlæg svaret
For at downloade en PDF skal du kalde
POST /invoices/{id}/generate_pdf for at få et kortlivet link.
Åbn fakturaens checkout
checkout_link indeholder faktura-ID’et og et signeret token adskilt af et .. Send hele værdien som link til POST /checkout_sessions for at åbne en session for denne faktura. For en URL, der vises for kunden, skal du følge Byg den hostede checkout-URL.
Feltet er kun til stede, mens checkout er tilgængelig: fakturaen skal være open. Erhvervskøbere og annullerede medlemskaber kan ikke bruge denne checkout. Din nøgle skal have payment:charge eller invoice:create/invoice:update, når fakturaen ikke har en gemt betalingsmetode. Den er null på en kladde, betalt, annulleret eller uerholdelig faktura samt for erhvervskøbere.
Kortlæg statusser
Native fakturaer kan også returnere
authorized, pending eller unresolved. Behandl ikke alle statusser uden for den ældre enum som betalt eller mislykket. Statusser og livscyklus forklarer dem.
Kortlæg endpoints
Kortlæg webhooks
Native fakturaer sender betalings-events for derespay_-ID. invoice.*-events beskriver ældre fakturaer.
Betalings-events dækker også betalinger, der ikke har noget med fakturaer at gøre. Match eventens betalings-ID med de native faktura-ID’er, du gemmer. Webhooks viser, hvordan du leverer ud fra
payment.succeeded.
Tilladelser
member:basic:read eksponerer kundenavne og medlems-/medlemskabs-ID’er. member:email:read eksponerer email_address og recipient_emails. Felter for betalingsmetode og adresse kræver payment:basic:read.
Tjekliste til migrering
- Tjek Før du migrerer for arbejdsgange, der skal blive på det ældre API.
- Fastlås native kald til en udgivet version, der matcher deres feltnavne, f.eks.
2026-11-02-1for disse eksempler. - Byg
itemsud fra kvalificerede varianter, og tjek antal, priser, valuta og produktkrav. - Erstat den ældre oprettelse i ét kald med oprettelse efterfulgt af udstedelse eller afsendelse. Vælg opkrævning af gemte metoder for den første faktura og en indkrævningsmetode for fornyelser.
- Kortlæg forfaldsdatoer, planlagte afsendelser og købergebyrer efter deres adfærd, ikke kun efter deres feltnavne.
- Hold native
pay_- og ældreinv_-ID’er adskilt. Hold ældre læsninger på den tidligere version. - Læs beløb fra pengeobjekter, og åbn checkout med det signerede
checkout_link. - Håndter
overdueog de ekstra betalingsstatusser. - Lever ud fra
payment.succeededfor fakturaens betalings-ID. - Giv de tilladelser, dit forløb bruger, herunder tilladelser til inline varianter/produkter og læsning af kunder.
Næste trin
Guide til fakturaer
Opret, udsted, send og indkræv native fakturaer.
API-reference for fakturaer
Alle native faktura-endpoints og -felter.
Ældre faktura-API
De endpoints, din nuværende integration kalder.
API-versioner
Sådan fungerer
Api-Version-Date og versionsfastlåsninger.
