Integration guide | Paid

This guide covers how to manage value receipts programmatically and embed them in your application. For a conceptual overview of what value receipts are and how they work, see the overview.

Prerequisites

API key ready
Signals flowing and delivered value configured
At least one customer with signal data

Creating and managing value receipts

Sync (create or update)

The sync endpoint is the primary way to create value receipts. It finds or creates a receipt by its natural key — the combination of customer and date range — then populates it with current delivered value data. If a receipt already exists for that key, it returns the existing one. If the receipt is sealed, it’s returned as-is without re-populating.

You only need a customer and a time period — no orders or products are required.

Python

Node.js

1 from paid import Paid
2 
3 client = Paid(token="YOUR_PAID_API_KEY")
4 
5 result = client.value_receipts.sync(
6     external_customer_id="acme_123",
7     start_date="2026-01-01T00:00:00Z",
8     end_date="2026-03-31T23:59:59Z",
9 )
10 
11 print(result.id)              # value receipt ID
12 print(result.status)          # "draft" or "posted"
13 print(result.public_url)      # share URL

You can optionally scope a value receipt to a product or an order (but not both). This narrows the receipt to delivered value from that specific product or order rather than all activity for the customer.

Scoped to a product:

Python

Node.js

1 result = client.value_receipts.sync(
2     external_customer_id="acme_123",
3     start_date="2026-01-01T00:00:00Z",
4     end_date="2026-03-31T23:59:59Z",
5     product={"product_id": "prod_xyz", "currency": "USD"},
6 )

Scoped to an order:

Python

Node.js

1 result = client.value_receipts.sync(
2     external_customer_id="acme_123",
3     start_date="2026-01-01T00:00:00Z",
4     end_date="2026-03-31T23:59:59Z",
5     order_id="ord_abc123",
6 )

List value receipts

List value receipts with pagination and optional filters.

Python

Node.js

1 # List all value receipts
2 receipts = client.value_receipts.list()
3 
4 for vr in receipts.data:
5     print(f"{vr.customer_name}: {vr.total_delivered_value} ({vr.status})")
6 
7 # Filter by customer
8 receipts = client.value_receipts.list(
9     external_customer_id="acme_123",
10     limit=10,
11     offset=0,
12 )
13 
14 # Include archived receipts
15 receipts = client.value_receipts.list(archived="true")

Available filters: customerId, externalCustomerId, orderId, productId, archived.

Get by ID

Fetch a single value receipt including its publish state.

Python

Node.js

1 vr = client.value_receipts.get(id="vr_abc123")
2 
3 print(vr.status)             # "draft" or "posted"
4 print(vr.is_published)       # True or False
5 print(vr.published_at)       # timestamp or None
6 print(vr.publish_expires_at) # expiry timestamp or None

Refresh

Re-populate a draft value receipt with the latest signal and delivered value data. This is useful when new signals are still coming in and you want the receipt to reflect the most recent numbers. Sealed receipts cannot be refreshed.

Python

Node.js

1 result = client.value_receipts.refresh(id="vr_abc123")
2 print(result.status)  # "draft"

Seal

Seal a value receipt to make it immutable. This transitions it from draft to posted status. Once sealed, a receipt cannot be refreshed or re-populated — it becomes a permanent snapshot.

Python

Node.js

1 client.value_receipts.seal(id="vr_abc123")

Publish and unpublish

Publishing makes a value receipt accessible to anyone with the link. Unpublishing reverts it to private (JWT-gated) access.

Python

Node.js

1 # Publish with no expiry (permanent until unpublished)
2 vr = client.value_receipts.publish(id="vr_abc123")
3 print(vr.public_url)  # share this URL
4 
5 # Publish with an expiry
6 vr = client.value_receipts.publish(
7     id="vr_abc123",
8     publish_expires_at="2026-06-30T23:59:59Z",
9 )
10 
11 # Unpublish (revert to JWT-gated)
12 vr = client.value_receipts.unpublish(id="vr_abc123")

Archive and unarchive

Archiving soft-deletes a value receipt — it’s hidden from list results by default but can be restored.

Python

Node.js

1 # Archive
2 client.value_receipts.archive(id="vr_abc123")
3 
4 # Unarchive
5 client.value_receipts.unarchive(id="vr_abc123")