LatticeStripe

Current release:2.2.x on Hex — see CHANGELOG for what shipped since 2.1.0.

The published baseline is 2.2.0; the next planned release is the compatibility-preserving 2.2.1 quality patch. Evaluating fit? Start with User Flows & JTBD.

A production-grade, idiomatic Elixir SDK for the Stripe API.

Full documentation available on HexDocs.

If you are evaluating how this fits into a real SaaS billing architecture, start with Guide: User Flows & JTBD.

Current scope and maintenance posture

The 2.2 baseline is feature-complete for the library's intended mainstream SaaS scope: payments, billing, metering, Connect, tax on custom flows, entitlement catalog and access reconciliation, webhooks (including thin events), and production operator guides.

The 2.2 line is maintenance- and adoption-driven. The planned 2.2.1 patch concentrates on reliability, internal consistency, documentation truth, and release hygiene without changing the public API. New resource families remain driven by demonstrated adopter need.

Not in the current typed scope:

• Specialist Stripe families: Identity; Treasury; Issuing; Terminal; Financial Connections; Climate; Sigma; Reporting
• Tax narrow follow-ups: Tax Code lookup (/v1/tax_codes); Tax Transaction list (if Stripe adds the endpoint)

See Scope for boundaries, escape hatches, and how to request coverage. See API Stability for the semver contract.

Docs Ladder

Use the docs in this order:

• README for the repo-level surface map and route-by-intent overview
• Getting Started for first success with a live client and API call
• User Flows & JTBD for "which Stripe path fits my SaaS?"
• Scope for current boundaries, deliberate exclusions, and escape hatches
• Canonical guides for the surface you will actually ship
• Recipes for compact job-to-primitive bridges
• Webhooks, Production Checklist, Event Debugging, Testing, and Error Handling for runtime truth and support posture

Choose Your Route

• I want first success fast: Getting Started, Payments, Checkout
• I am evaluating recurring billing for a SaaS: User Flows & JTBD, Subscriptions, Customer Portal, Webhooks
• I need usage-based billing and reconciliation: Metering, Webhooks, Testing
• I manage product features and customer access: Entitlements, Subscriptions, Webhooks, Testing
• I calculate tax on custom payment flows (not only Checkout/Invoices): Tax, Payments, Testing
• I run a marketplace or platform: Connect, Connect Accounts, Connect Money Movement
• I am hardening ops and support paths: Production Checklist, Error Handling, Testing, Webhooks, Webhooks: Thin Events, Event Debugging

Installation

Add lattice_stripe to your dependencies in mix.exs:

def deps do
  [
    {:lattice_stripe, "~> 2.2"}
  ]
end

Quick Start

LatticeStripe uses Finch for HTTP requests. Add it to your supervision tree in application.ex:

children = [
  {Finch, name: MyApp.Finch}
]

Then create a client and make your first API call:

client = LatticeStripe.Client.new!(
  api_key: "sk_test_...",
  finch: MyApp.Finch
)

{:ok, payment_intent} = LatticeStripe.PaymentIntent.create(client, %{
  "amount" => 2000,
  "currency" => "usd",
  "payment_method" => "pm_card_visa",
  "confirm" => true,
  "automatic_payment_methods" => %{"enabled" => true, "allow_redirects" => "never"}
})

IO.puts("PaymentIntent created: #{payment_intent.id}")

Features

Payments

• Customers, PaymentIntents, SetupIntents, PaymentMethods, Refunds, Checkout Sessions (payment / subscription / setup modes)
• Charge list/search/update/capture for support, audit, and Connect reconciliation — Charge API (PI-first; no create)
• Structured, pattern-matchable errors: :card_error, :authentication_error, :rate_limit_error, :api_error, and more — Guide: Error Handling
• Auto-pagination — stream through large result sets lazily with Elixir Streams
• Guide: Payments

Billing

• Invoices — create, finalize, pay, void, send, list, search
• Credit Notes — preview, create, void, and inspect/stream line items
• Quotes — create, finalize, accept/cancel, inspect/stream line items, and download PDFs
• Subscriptions with lifecycle verbs (cancel, resume, pause_collection, trial settings)
• Subscription Schedules for phased billing with proration guards
• Billing Metering — usage-based billing with Meter, MeterEvent, and MeterEventAdjustment; two-layer idempotency and pre-flight value guards
• Entitlements — Feature catalog CRUD, Product Feature attachments, active-entitlement reads, and webhook-driven local access reconciliation
• Customer Portal — BillingPortal.Session for self-service portal URLs with 4 flow types (subscription_cancel, subscription_update, subscription_update_confirm, payment_method_update) and Inspect masking
• Guide: Subscriptions · Guide: Credit Notes · Guide: Metering · Guide: Tax · Guide: Customer Portal
• Guide: Entitlements

Operations and diagnostics

• Files and FileLinks — upload files to Stripe, manage shareable file links, and download binary content
• Disputes — retrieve/list, update metadata, stage evidence safely, submit evidence, and close disputes
• Mandates and SetupAttempts — inspect payment authorization state and SetupIntent failure history
• Operator playbooks: Production Checklist · Event Debugging
• Guide: Recipes · Guide: Webhooks · Guide: Webhooks: Thin Events · Guide: Testing
• Full ops guide ladder: Docs Ladder and User Flows & JTBD (Job 7)

Connect

• Connect accounts (Standard, Express, Custom) with onboarding AccountLinks
• Transfers, TransferReversals, Payouts, External Accounts
• Balance + BalanceTransactions for platform-fee reconciliation
• Per-client and per-request stripe_account for platform integrations
• Guide: Connect

Platform

• Pluggable Transport, Json, and RetryStrategy behaviours — bring your own HTTP client
• Automatic retry with exponential backoff, respecting Stripe's Stripe-Should-Retry header
• Automatic idempotency keys for retries within one call, plus durable operation-key guidance in Client Configuration
• Telemetry events for every request, compatible with any monitoring stack
• Phoenix-ready Webhook.Plug snapshot path + thin-event (/v2/events) helpers for fetch-after-verify integration
• Guide: Extending LatticeStripe

Compatibility

Documentation

Full documentation with guides, examples, and API reference is available on HexDocs.

Start here on HexDocs:

• Getting Started
• User Flows & JTBD
• Recipes

Canonical guide clusters:

• Payments and billing primitives: Payments, Checkout, Invoices, Credit Notes, Subscriptions, Customer Portal, Entitlements, Metering, Tax, Charge API
• Connect: Connect, Connect Accounts, Connect Money Movement
• Operations and DX: Webhooks, Webhooks: Thin Events, Production Checklist, Event Debugging, Testing, Error Handling, Client Configuration, Performance, Circuit Breaker, OpenTelemetry, Telemetry, API Stability, Extending LatticeStripe, Cheatsheet

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT — see LICENSE for details.