Skip to main content
Native fakturaer bruger de samme /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. Brug 4.99 for 4,99 USD. Sender du 499, faktureres 499 USD.
Den native request opretter en kladde. Send den med 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-1 kan 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_address og customer_name er input, der kun bruges ved oprettelse.
  • Udstedte beløb og items er låst. En opdatering, der kun indeholder memo og/eller recipient_emails, er tilladt på draft-, open- og uncollectible-fakturaer, herunder en planlagt kladde.

Udsted, send og opkræv

En ældre oprettelse vælger indkrævningsadfærd med collection_method. Native fakturaer bruger separate kald efter oprettelsen af kladden:
  1. Udsted den med POST /invoices/{id}/issue for at beregne endelig moms og åbne den for betaling uden at sende den første faktura-e-mail.
  2. 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 en open-faktura, e-mailes den igen. send_at planlægger en kladdes afsendelse. POST /invoices/{id}/unschedule annullerer den plan.
  3. Opkræv en gemt metode ved at angive payment_method_id på kladden. For en positiv total opkræver udstedelse eller afsendelse på et fremtidigt charge_at, ellers et fremtidigt due_at, ellers med det samme. charge_at skal ligge i fremtiden og kan ikke ligge før send_at.
Sender du en kladde, der opkræver med det samme, springes den første faktura-e-mail over. Sender du med en senere opkrævning, e-mailes den nu. En mislykket automatisk opkrævning kan udløse en e-mail med betalingslink, selv når du brugte Issue Invoice. Opkræv en gemt betalingsmetode forklarer forløbet. Et 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 deres pay_-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

  1. Tjek Før du migrerer for arbejdsgange, der skal blive på det ældre API.
  2. Fastlås native kald til en udgivet version, der matcher deres feltnavne, f.eks. 2026-11-02-1 for disse eksempler.
  3. Byg items ud fra kvalificerede varianter, og tjek antal, priser, valuta og produktkrav.
  4. 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.
  5. Kortlæg forfaldsdatoer, planlagte afsendelser og købergebyrer efter deres adfærd, ikke kun efter deres feltnavne.
  6. Hold native pay_- og ældre inv_-ID’er adskilt. Hold ældre læsninger på den tidligere version.
  7. Læs beløb fra pengeobjekter, og åbn checkout med det signerede checkout_link.
  8. Håndter overdue og de ekstra betalingsstatusser.
  9. Lever ud fra payment.succeeded for fakturaens betalings-ID.
  10. 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.