Upgrading from 1.1 to 1.7

If you pinned {:lattice_stripe, "~> 1.1"} and are moving to ~> 1.7, use this guide to answer one question first: does my existing application need a code change? It then routes you to the additive capabilities that became available in this historical interval.

Update your dependency

Bump the version in mix.exs and run mix deps.get:

{:lattice_stripe, "~> 1.7"}

Adopters pinned to ~> 1.1 resolve to 1.7. Retain your existing client and Finch setup for this historical leg.

Two-minute mandatory migration checklist

There are exactly three caller-visible behavior changes between 1.1 and 1.7. Check each affected-user predicate before exploring optional additions.

# Before (1.1):
{:ok, %PaymentIntent{customer: %{"id" => id}}} =
  PaymentIntent.retrieve(client, id, expand: ["customer"])

# After (1.7):
{:ok, %PaymentIntent{customer: %Customer{id: id}}} =
  PaymentIntent.retrieve(client, id, expand: ["customer"])

When expanded, associated resources now arrive as typed structs such as %Customer{}. See LatticeStripe.PaymentIntent.retrieve/3 for the representative retrieval call.

# Before (1.1):
if pi.status == "succeeded" do ...

# After (1.7):
if pi.status == :succeeded do ...

Affected finite-status resources include PaymentIntent, Subscription, SubscriptionSchedule, Charge, Refund, SetupIntent, Payout, BalanceTransaction, Checkout.Session, BankAccount, Billing.Meter, and Account.Capability.

# Before (1.1): tolerance: 0 always errored
{:error, :timestamp_expired} =
  LatticeStripe.Webhook.verify_signature(payload, sig_header, secret, tolerance: 0)

# After (1.7): tolerance: 0 disables the staleness check
{:ok, _event} =
  LatticeStripe.Webhook.verify_signature(payload, sig_header, secret, tolerance: 0)

If none apply

You have no code migration for this leg. Your existing integration remains compatible. Before deployment, run your application test suite so its Stripe calls, webhook handling, and any pattern matches exercise the upgraded dependency in your own configuration.

Optional additions by job

Payments and payment setup

Billing and self-service

Create a portal configuration before creating a hosted session. The configuration is the policy; the session carries its id to the customer-facing portal.

{:ok, config} =
  LatticeStripe.BillingPortal.Configuration.create(client, %{
    "features" => %{"subscription_cancel" => %{"enabled" => true}}
  })

{:ok, session} =
  LatticeStripe.BillingPortal.Session.create(client, %{
    "customer" => "cus_123",
    "configuration" => config.id,
    "return_url" => "https://example.com/account"
  })

Tax

The Tax guide owns jurisdiction, address, and reversal details; this guide only identifies the family and the first safe call.

Webhooks and operations

For thin events, verification proves the notification came from Stripe; fetch the event before treating event payload state as authoritative.

with {:ok, notification} <-
       LatticeStripe.Webhook.parse_event_notification(payload, sig_header, secret, []),
     {:ok, event} <- LatticeStripe.Webhook.fetch_event(client, notification, []) do
  process_authoritative_event(event)
end

Testing

Use the Testing guide for setup and isolation; these names are the 1.7 public testing surface, not a replacement for its full workflow.

Version-by-version appendix

Use this appendix for chronology after deciding required migration work and optional capability adoption.

For the authoritative release record, see the CHANGELOG.