Get

Retrieve a single invoice with real-time aggregates (for ACTIVE/CLOSING/CLOSED) or cached aggregates (for finalized invoices). Optionally include line items with expand=lineItems.

GET /v2/invoices/{id}

Get

cURL

curl --request GET \
  --url https://api.paygentic.io/v2/invoices/{id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.paygentic.io/v2/invoices/{id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.paygentic.io/v2/invoices/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.paygentic.io/v2/invoices/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.paygentic.io/v2/invoices/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.paygentic.io/v2/invoices/{id}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.paygentic.io/v2/invoices/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

200

{
  "id": "inv_r1s2t3u4v5w6x7y8",
  "autoApprove": true,
  "billingAnchor": "2024-02-01T00:00:00Z",
  "billingCadence": "P1M",
  "gracePeriodEnd": "2024-03-01T23:59:59Z",
  "grandTotal": "1345.61",
  "invoiceNumber": "INV-2024-02-001",
  "itemCount": 15,
  "lineItems": null,
  "nextActionAt": null,
  "paidAmount": "0.00",
  "paymentUrl": "https://checkout.paygentic.com/invoice/inv_r1s2t3u4v5w6x7y8",
  "pdfUrl": "https://quaderno.io/invoices/12345.pdf",
  "periodEnd": "2024-02-29T23:59:59Z",
  "periodStart": "2024-02-01T00:00:00Z",
  "permalink": "https://quaderno.io/invoices/12345",
  "sequenceNumber": 2,
  "status": "ISSUED",
  "subscriptionId": "sub_z9a0b1c2d3e4f5g6",
  "subtotal": "1234.50",
  "tax": {
    "actualTax": "111110000000",
    "adjustmentNeeded": true,
    "difference": "1110000000",
    "estimatedTax": "110000000000",
    "reconciled": true,
    "reconciledAt": "2024-03-01T10:00:00Z"
  },
  "totalTax": "111.11",
  "unpaidAmount": "1345.61"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

{
  "message": "The requested resource was not found",
  "error": "not_found"
}

Authorizations

Authorization · string · header · required

API key authentication

Path Parameters

id · string · required

The unique identifier of the invoice

Query Parameters

expand · string

Comma-separated list of fields to expand. Currently supports: lineItems

lineItemsLimit · integer · default: 100

Page size for line items when expand=lineItems

Required range: 1 <= x <= 1000

lineItemsPageToken · string

Pagination token for line items when expand=lineItems

Response

200

application/json

Invoice details

id · string · required

The invoice ID

object · enum<string> · required

The object type

Available options: invoice

autoApprove · boolean · required

Whether this invoice auto-approves after calculation

billingAnchor · string<date-time> · required

The billing anchor date used for period calculations

billingCadence · string · required

ISO 8601 duration string for billing frequency

createdAt · string<date-time> · required

When the invoice was created

currency · string · required

ISO 4217 currency code (e.g., USD, EUR)

gracePeriodEnd · string<date-time> · required

The end of the grace period for accepting usage events

grandTotal · string · required

Grand total (subtotal + tax) in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)

itemCount · integer · required

Number of billing items (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)

merchantId · string · required

The merchant organization ID

paidAmount · string · required

Amount already paid via wallet (account_type='main') in decimal dollars

periodEnd · string<date-time> · required

The end of the billing period

periodStart · string<date-time> · required

The start of the billing period

sequenceNumber · integer · required

The sequence number of this invoice period

status · enum<string> · required

The current status of the invoice

Available options: ACTIVE, CLOSING, CLOSED, CALCULATING, DRAFT, ISSUED, PAYMENT_FAILED, PAID, CANCELLED, WRITTEN_OFF, FAILED

subscriptionId · string · required

The subscription ID this invoice belongs to

customerId · string · required

The customer ID that owns this invoice

subtotal · string · required

Subtotal in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)

totalTax · string · required

Total tax in decimal dollars (real-time for ACTIVE/CLOSING/CLOSED, cached otherwise)

unpaidAmount · string · required

Amount accrued as liability (account_type='usage') in decimal dollars

updatedAt · string<date-time> · required

When the invoice was last updated

failureReason · string

Machine-readable reason code for the most recent failure (e.g. CALCULATION_FAILED). Present only when status is FAILED or PAYMENT_FAILED.

paymentInFlight · boolean

Whether a payment for this invoice is currently being processed (the payment session is in the 'processing' state). Clients should not offer manual 'mark as paid' while true. Only populated by GET /invoices/{id}.

invoiceNumber · string | null

The invoice number

lineItems · object | null

Line items (only present if expand=lineItems query parameter is provided)

Show child attributes

metadata · object

Additional metadata including transition history

nextActionAt · string<date-time> | null

When the next scheduled action should occur

paidAt · string<date-time> | null

When the invoice was paid (null if not yet paid)

dueAt · string<date-time> | null

Payment due date snapshotted at invoice-create time as the issue date + subscription.paymentTermDays, anchored to midnight UTC. Null only for invoices created before this feature shipped (no backfill).

paymentUrl · string<uri> | null

Payment URL for completing payment (only present when status is ISSUED and unpaidAmount > 0)

pdfUrl · string<uri> | null

Direct PDF download link for tax invoice

permalink · string<uri> | null

Public URL to view tax invoice

tax · object | null

Tax reconciliation metadata (only present when plan has taxEnabled)

Show child attributes