Example scope & report

# Polar: subscription state to product access

Build a billing integration with recoverable local entitlement changes

[← All services](/services)

Public reference: Polar. Independent example based on public documentation. Not commissioned by or affiliated with Polar.

[Download all 7 reports (PDF) ↓](/examples/upserto-example-reports.pdf)[Download Markdown ↓](/examples/fintech-delivery.md)

## Decision brief

Recommended next decision

| Question | Recommendation |
| --- | --- |
| Decision | Make the local entitlement decision and its delivery intent durable together. |
| Why it matters | A valid billing update can still be lost between the local commit and a downstream access change. |
| Acceptance | Duplicate, late and missed updates converge on the approved access policy with a recovery trail. |
| Scope boundary | SaaS-owned receiver, database and access adapter; billing policy and merchant responsibilities remain with the client. |

## The proposed engagement

Proposed brief: a SaaS team uses Polar for billing and needs subscriptions and granted benefits to control access inside its own product. Upserto would implement a signed webhook receiver, customer mapping, local entitlement update and recovery path. The team needs to explain why a customer has access and recover a missed update without blindly granting or removing it.

Inputs required. Polar organization/configuration; external customer ID mapping; entitlement rules; customer-owned API and database.

## System boundary and assumptions

Polar documents a Customer State object containing active subscriptions and granted benefits, available by API and through customer.state_changed. The proposed work covers the SaaS-owned receiver, database and access adapter. It does not change Polar’s billing engine, taxes or merchant responsibilities. A local outbox would be a proposed implementation choice in the SaaS, not a claim about Polar’s internal architecture.

## How Upserto would approach it

Agree access policy before coding: which subscription or benefit grants which capability, and how cancellation, expiry and revocation should appear. Use Polar’s documented signature helper for the configured SDK/secret format. Serialize processing per customer and refresh current state where needed so a late event cannot blindly overwrite a newer local decision. Keep a reconciliation path for missed notifications.

## What the team would receive

- A webhook receiver and versioned billing-to-entitlement mapping.

- A local transaction/outbox or equivalent durable handoff with idempotent access updates.

- Focused failure tests and an operator reconciliation guide.

Keep local consistency separate from external deliveryThe SaaS database commits the entitlement decision and delivery intent together. The relay and access adapter still require retry, deduplication and reconciliation.Accent frame: one local transaction · Dashed: reconciliation

Read the diagram- Validate the Polar event and resolve the current customer state under the agreed access policy.

- Commit the local entitlement decision and outbox intent in one transaction.

- Deliver by stable decision identity; reconcile provider state and product access through an owned correction path.

## Starting point and proposed change

Items to inspect in the customer integration, the proposed control and the evidence needed for acceptance.

Design comparison

| Control | Inspect first | Proposed change | Acceptance evidence |
| --- | --- | --- | --- |
| Local handoff | Review database change followed by best-effort publication. | Atomic local decision and durable delivery intent. | Crash leaves a recoverable outbox item. |
| Event handling | Review whether arrival order directly assigns access. | Current-state policy and stable decision identity. | Duplicate/late fixtures converge on the intended entitlement. |
| Recovery | Review webhook-health-only monitoring. | Customer-state-to-access reconciliation. | Missed update is found and corrected with an audit trail. |

## Decisions and approval owners

Decisions to agree before implementation

| Decision | Proposed default | Approval owner |
| --- | --- | --- |
| Entitlement policy | Agree grant, cancellation, expiry and revocation rules before implementing the mapping. | Product + billing owners |
| Recovery authority | Separate transport replay from an approved correction to customer access. | SaaS operations owner |

## Review questions and implementation risks

P1 Resolve before releasing the affected workflow, or record an explicit acceptance decision. P2 Assign an owner and an agreed follow-up milestone; do not leave the item unowned.

### FT-01 · P1 · Can a local access change lose its downstream update?

If the SaaS commits an entitlement then sends a separate message, a process exit between them can leave another service unaware. This is a design risk to check in the customer implementation.

Proposed approach. Use one local transaction for the decision and an outbox record, or document an equivalent durable handoff. Relay only committed intent.

### FT-02 · P1 · Can a duplicate or late notification undo the right access state?

A receipt is a trigger for a decision, not proof that its arrival order is the latest business state. Repeated downstream effects also need a stable identity.

Proposed approach. Record receipt identity, serialize per customer and define a current-state refresh policy. Apply each local decision idempotently in the access adapter.

### FT-03 · P2 · Can operations reconcile a missed billing update?

Without a provider-to-local comparison, a missed update may remain invisible even when the receiver and queue look healthy.

Proposed approach. Provide a bounded customer-state reconciliation job with dry-run output and an approved correction path. Separate access-policy choices from transport recovery.

## Example technical output

Proposed local transaction boundary

```text
verified_event = validate_polar_webhook(raw_body, headers)
customer = resolve_external_customer(verified_event)
state = resolve_current_customer_state(customer)
BEGIN
  persist_receipt_if_new()
  apply_entitlement_policy(state)
  insert_outbox(stable_access_decision_id)
COMMIT
relay_with_retry_and_consumer_deduplication()
execution_result: TO_VERIFY
```

## Delivery plan and ownership

Proposed action plan

| Priority | Review item | Accountable role | Acceptance gate |
| --- | --- | --- | --- |
| P1 | FT-01 | SaaS backend + database owner | Crash after commit preserves the access decision and a recoverable delivery intent. |
| P1 | FT-02 | Billing integration owner | Repeated or reordered fixtures converge on the intended access policy without repeated grants. |
| P2 | FT-03 | SaaS operations | A seeded provider/local mismatch is detected and corrected through a recorded decision. |

## Acceptance checks

Run these checks before accepting the proposed changes.

Acceptance checks

| Scenario | Required evidence / expected behavior | Status |
| --- | --- | --- |
| Process stops just after local commit | Entitlement and delivery intent both remain durable | To verify |
| Same delivery is repeated | Access adapter applies the stable decision without a second effect | To verify |
| An older notification arrives later | Current-state policy prevents a stale access overwrite | To verify |
| A notification is missed | Bounded reconciliation detects the local/provider mismatch | To verify |

## Rollout and recovery

Use Polar’s approved sandbox and fixture customers before production. Deploy consumers before enabling a new event producer where contracts change. Start with an agreed product/customer slice, observe local decisions and downstream access together, and keep new grants independently stoppable. Preserve durable intent when pausing delivery.

## Handover and limits

Deliver the mapping, database changes, receiver, access adapter, test evidence and reconciliation procedure. Actual access-policy decisions and production acceptance belong to the product owner. No settlement or revenue result is claimed by this proposal.

## Access and evidence handling

Controls for the agreed engagement

| Area | Required control |
| --- | --- |
| Access | Use approved sandbox customers and a scoped webhook endpoint first. |
| Evidence | Persist receipt and decision references; avoid logging full customer state or webhook secrets. |
| Correction | Restrict production reconciliation and access corrections to agreed operators with an audit trail. |

## Public documentation used

The sources below establish product capabilities and API contracts. The implementation choices above are Upserto’s proposed approach for a customer integration.

- [Polar: Customer State ↗](https://polar.sh/docs/integrate/customer-state)Current subscriptions/benefits and customer.state_changed integration.

- [Polar: Handle webhook deliveries ↗](https://polar.sh/docs/integrate/webhooks/delivery)SDK signature validation, delivery inspection and redelivery.

- [Polar: Setup webhooks ↗](https://polar.sh/docs/integrate/webhooks/endpoints)Configured endpoint and secret-format considerations.

Discuss the same kind of work for your system, with an agreed scope and acceptance criteria.

[Explore Fintech and SaaS engineering ↗](/services/fintech-saas-engineering)[Discuss a similar scope ↗](/contact)

Contact: [hello@upserto.com](mailto:hello@upserto.com)