LatticeStripe.Builders.SubscriptionSchedule (LatticeStripe v1.7.0)

Optional fluent builder for LatticeStripe.SubscriptionSchedule creation params.

This is a companion to the raw map API — not a replacement. Developers who prefer to construct deeply-nested phase params via a pipe chain can use this builder to avoid manually typing string keys and prevent typos. The output of build/1 is a plain string-keyed map that passes directly to LatticeStripe.SubscriptionSchedule.create/3.

Usage

Mode 1: customer + phases

Build a new schedule from scratch with an explicit phase timeline.

alias LatticeStripe.Builders.SubscriptionSchedule, as: SSBuilder

params =
  SSBuilder.new()
  |> SSBuilder.customer("cus_1234567890")
  |> SSBuilder.start_date(:now)
  |> SSBuilder.end_behavior(:release)
  |> SSBuilder.add_phase(
       SSBuilder.phase_new()
       |> SSBuilder.phase_items([%{"price" => "price_1234567890", "quantity" => 1}])
       |> SSBuilder.phase_iterations(12)
       |> SSBuilder.phase_proration_behavior(:create_prorations)
       |> SSBuilder.phase_build()
     )
  |> SSBuilder.build()

# Pass to the resource layer
LatticeStripe.SubscriptionSchedule.create(client, params)

Mode 2: from_subscription

Convert an existing Subscription into a schedule whose first phase captures the subscription's current state.

params =
  SSBuilder.new()
  |> SSBuilder.from_subscription("sub_1234567890")
  |> SSBuilder.build()

LatticeStripe.SubscriptionSchedule.create(client, params)

Important: The two modes are mutually exclusive. Mixing customer/phases fields with from_subscription produces a Stripe 400 error. The builder does not client-side-validate this constraint — Stripe's error is already actionable.

Nil omission

build/1 and phase_build/1 automatically strip fields with nil values, so setting only the fields you need is safe — unused fields do not appear in the output map.

Atom values

Stripe enum fields (:release, :create_prorations, :resume, etc.) are automatically converted to their string equivalents in build/1 and phase_build/1 output.

Summary

Types

t()

Functions

add_phase(b, phase)

Append a phase to the schedule.

build(b)

Produce the final string-keyed params map.

customer(b, cus_id)

Set the customer ID (Mode 1 — customer + phases).

end_behavior(b, value)

Set the end behavior atom or string (e.g. :release, :cancel).

from_subscription(b, sub_id)

Set the source subscription ID (Mode 2 — from_subscription).

metadata(b, meta)

Set schedule-level metadata map.

new()

Create a new empty SubscriptionSchedule builder accumulator.

phase_add_invoice_items(p, items)

Set the add_invoice_items list on a phase.

phase_application_fee_percent(p, pct)

Set the application fee percent for this phase.

phase_automatic_tax(p, auto_tax)

Set the automatic_tax map for this phase.

phase_billing_cycle_anchor(p, value)

Set the billing cycle anchor behavior.

phase_billing_thresholds(p, bt)

Set the billing_thresholds map for this phase.

phase_build(p)

Produce the final string-keyed map for a phase.

phase_collection_method(p, value)

Set the collection method (e.g. :charge_automatically, :send_invoice).

phase_currency(p, currency)

Set the currency code for this phase.

phase_default_payment_method(p, pm_id)

Set the default payment method ID for this phase.

phase_default_tax_rates(p, rates)

Set the default_tax_rates list for this phase.

phase_description(p, desc)

Set the description for this phase.

phase_discounts(p, discounts)

Set the discounts list for this phase.

phase_end_date(p, date)

Set the end date for this phase. Accepts :now, a Unix timestamp integer, or a string.

phase_invoice_settings(p, settings)

Set the invoice_settings map for this phase.

phase_items(p, items)

Set the items list on a phase.

phase_iterations(p, n)

Set the number of iterations for this phase.

phase_metadata(p, meta)

Set metadata map for this phase.

phase_new()

Create a new empty Phase accumulator.

phase_on_behalf_of(p, acct_id)

Set the on_behalf_of account ID for this phase.

phase_pause_collection(p, pc)

Set the pause_collection map for this phase.

phase_prebilling(p, pb)

Set the prebilling map for this phase.

phase_proration_behavior(p, value)

Set proration behavior atom or string (e.g. :create_prorations, :none).

phase_start_date(p, date)

Set the start date for this phase. Accepts :now, a Unix timestamp integer, or a string.

phase_transfer_data(p, data)

Set the transfer_data map for this phase.

phase_trial_continuation(p, value)

Set trial_continuation behavior (e.g. :resume, :none).

phase_trial_end(p, date)

Set the trial end date (Unix timestamp) for this phase.

start_date(b, date)

Set the schedule start date. Accepts :now, a Unix timestamp integer, or a string.