Receipt APIs

PacSpace currently supports two receipt surfaces:

1. Customer-scoped receipt generation by customerId (balance.receipt()).
2. Headless receipt documents by receiptId (balance.receipts.*).

Use headless receipt documents for rendering public pages, tenant-branded embeds, or PDF exports.

For invoice templates, prefer the persistent Shared Record link when the invoicing bundle includes one. The Shared Record is stable for the customer across periods and can show live records during the current cycle. Receipt links are still useful for period-specific statements.

1. Customer-Scoped Receipt Generation (balance.receipt())#

GET https://app.pacspace.io/api/v1/balance/receipt/:customerId

This route creates a scoped receipt response from customerId + time scope.

Scope Parameters#

SDK example:

const scoped = await pac.balance.receipt('cust_12345', { period: '2026-04' });
console.log(scoped.proofRoot);
console.log(scoped.verifyUrl); // Human invoice link
console.log(scoped.verificationApiUrl); // Machine verification endpoint

Use verifyUrl on invoices and customer emails. Use verificationApiUrl when a tool, agent, or auditor needs the machine verification endpoint.

2. Headless Receipt Document APIs (balance.receipts.*)#

Tenant-Authenticated JSON#

GET https://app.pacspace.io/api/v1/balance/receipts/:receiptId

Optional query parameters:

• customerDisplayName=true|false
• locale (for example en-US)
• timezone (for example UTC or America/Los_Angeles)
• unit (credits)

Tenant-Authenticated Receipt Listing#

GET https://app.pacspace.io/api/v1/balance/customers/:customerId/receipts?limit=25

Tenant-Authenticated Preview#

GET https://app.pacspace.io/api/v1/balance/receipts/preview

3. Public Receipt APIs (No Auth)#

Public JSON#

GET https://app.pacspace.io/api/v1/receipt/:receiptId

Public PDF#

GET https://app.pacspace.io/api/v1/receipt/:receiptId.pdf

SDK Example (balance.receipts.*)#

import { PacSpace } from '@pacspace-io/sdk';

const pac = new PacSpace({ apiKey: process.env.PACSPACE_API_KEY! });

// Customer-scoped receipt generation (customerId + scope)
const scoped = await pac.balance.receipt('cust_12345', { period: '2026-04' });

// Headless list/get by receiptId
const receipts = await pac.balance.receipts.list('cust_12345', { limit: 10 });
const receipt = await pac.balance.receipts.get(receipts[0].receiptId, {
  customerDisplayName: true,
  timezone: 'UTC',
});

// Parse receiptId from a URL
const parsedReceiptId = pac.balance.receipts.fromUrl(receipt.links.permalink);

// Build email copy
const emailBody = pac.balance.receipts.emailBody(receipt);

// Download public PDF bytes
const pdfBytes = await pac.balance.receipts.downloadPdf(parsedReceiptId);
console.log(emailBody, pdfBytes.byteLength);

receiptId Identity Rules#

• Public receipt identifiers use chk_ + 32 hex chars.
• Receipt links should use receiptUrl fields returned by API responses.
• Shared Record links use /c/{customerHandle} and may appear in verifyUrl when a customer handle exists. Treat URL fields as opaque strings; use explicit receiptId or checkpoint fields when code needs a period identifier.
• Machine verification uses verificationApiUrl, which points at /api/v1/verify/:proofRoot.

Response Highlights (Headless Document)#

A headless receipt document includes:

• receiptId, checkpointId, status
• summary (openingBalance, netDelta, closingBalance, deltaCount)
• statementRows[] (chronological rows with running balance)
• dailyTotals[]
• tenant branding metadata
• verification metadata
• links (permalink, pdf)

Related#

• Checkpoint
• Receipts and Verification
• Verify