@spec apply_discount(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  {:ok, Nombaone.Discount.t()} | {:error, Nombaone.Error.t()}

Apply a coupon to this subscription only. :coupon is a coupon id or its code.

@spec apply_discount!(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  Nombaone.Discount.t()

Raising variant of apply_discount/4.

@spec cancel(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  {:ok, Nombaone.Subscription.t()} | {:error, Nombaone.Error.t()}

Cancel a subscription — immediately (default), or mode: "at_period_end" to keep access until the cycle closes. Optional :comment.

Example

{:ok, subscription} = Nombaone.Subscriptions.cancel(client, id, %{mode: "at_period_end"})

@spec cancel!(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  Nombaone.Subscription.t()

Raising variant of cancel/4.

@spec change(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  {:ok, Nombaone.Subscription.t()} | {:error, Nombaone.Error.t()}

Change price or quantity mid-cycle, prorating by default (at least one of :price_id, :quantity, :interval_switch). Switching the billing interval mid-cycle is unsupported (PRORATION_INTERVAL_SWITCH_UNSUPPORTED) — queue it with Nombaone.Subscriptions.Schedule.create/4 instead.

Example

# Upgrade, prorated on the next invoice:
{:ok, subscription} = Nombaone.Subscriptions.change(client, id, %{price_id: bigger_price.id})

@spec change!(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  Nombaone.Subscription.t()

Raising variant of change/4.

@spec create(Nombaone.Client.t(), map(), keyword()) ::
  {:ok, Nombaone.Subscription.t()} | {:error, Nombaone.Error.t()}

Create a subscription. This can move money (the first charge), so the SDK sends an Idempotency-Key automatically and reuses it across its own retries.

A payment method is required for charge_automatically unless trial_days > 0 (the first charge is deferred to trial end).

Common errors: 422 CLIENT_VALIDATION_FAILED (e.g. a missing payment method without a trial), 409 SUBSCRIPTION_PAYMENT_METHOD_REQUIRED.

Example

{:ok, subscription} =
  Nombaone.Subscriptions.create(client, %{
    customer_id: customer.id,
    price_id: price.id,
    payment_method_id: method.id
  })

@spec create!(Nombaone.Client.t(), map(), keyword()) :: Nombaone.Subscription.t()

Raising variant of create/3.

@spec list(Nombaone.Client.t(), map(), keyword()) ::
  {:ok, Nombaone.Page.t()} | {:error, Nombaone.Error.t()}

List subscriptions, newest first. Optional filters: :customer_id, :status, :limit, :cursor.

@spec list!(Nombaone.Client.t(), map(), keyword()) :: Nombaone.Page.t()

Raising variant of list/3.

@spec list_events(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  {:ok, Nombaone.Page.t()} | {:error, Nombaone.Error.t()}

The subscription's audit trail of domain events, newest first.

@spec list_events!(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  Nombaone.Page.t()

Raising variant of list_events/4.

@spec pause(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  {:ok, Nombaone.Subscription.t()} | {:error, Nombaone.Error.t()}

Pause billing. The subscription keeps its place in the cycle and resumes cleanly. Optional :max_days auto-resumes after that many days.

Common errors: 409 SUBSCRIPTION_ILLEGAL_TRANSITION.

@spec pause!(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  Nombaone.Subscription.t()

Raising variant of pause/4.

@spec remove_discount(Nombaone.Client.t(), String.t(), keyword()) ::
  {:ok, Nombaone.Discount.t()} | {:error, Nombaone.Error.t()}

Remove the subscription's active discount. Returns the ended discount.

@spec remove_discount!(Nombaone.Client.t(), String.t(), keyword()) ::
  Nombaone.Discount.t()

Raising variant of remove_discount/3.

@spec resubscribe(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  {:ok, Nombaone.Subscription.t()} | {:error, Nombaone.Error.t()}

Start a fresh subscription for a canceled one's customer, reusing the old price/payment method unless overridden (:price_id, :payment_method_id). The subscription must be in a terminal state.

Common errors: 409 SUBSCRIPTION_NOT_TERMINAL.

@spec resubscribe!(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  Nombaone.Subscription.t()

Raising variant of resubscribe/4.

@spec resume(Nombaone.Client.t(), String.t(), keyword()) ::
  {:ok, Nombaone.Subscription.t()} | {:error, Nombaone.Error.t()}

Resume a paused subscription.

@spec resume!(Nombaone.Client.t(), String.t(), keyword()) :: Nombaone.Subscription.t()

Raising variant of resume/3.

@spec retrieve(Nombaone.Client.t(), String.t(), keyword()) ::
  {:ok, Nombaone.Subscription.t()} | {:error, Nombaone.Error.t()}

Retrieve a subscription by id. Common errors: 404 SUBSCRIPTION_NOT_FOUND.

@spec retrieve!(Nombaone.Client.t(), String.t(), keyword()) ::
  Nombaone.Subscription.t()

Raising variant of retrieve/3.

@spec retrieve_upcoming_invoice(Nombaone.Client.t(), String.t(), keyword()) ::
  {:ok, Nombaone.UpcomingInvoice.t()} | {:error, Nombaone.Error.t()}

Preview the next invoice without charging or storing anything.

@spec retrieve_upcoming_invoice!(Nombaone.Client.t(), String.t(), keyword()) ::
  Nombaone.UpcomingInvoice.t()

Raising variant of retrieve_upcoming_invoice/3.

@spec update(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  {:ok, Nombaone.Subscription.t()} | {:error, Nombaone.Error.t()}

Edit metadata or the default payment method (:default_payment_method_id, :metadata only). For a price/quantity/interval change (which prorates), use change/4.

@spec update!(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  Nombaone.Subscription.t()

Raising variant of update/4.

@spec update_payment_method(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  {:ok, Nombaone.PaymentMethod.t()} | {:error, Nombaone.Error.t()}

Swap the payment method that bills this subscription — the card-update path during dunning. Provide exactly one of :payment_method_reference (an already-captured method) or :checkout_token (a fresh hosted-checkout token).

Returns the attached Nombaone.PaymentMethod.

@spec update_payment_method!(Nombaone.Client.t(), String.t(), map(), keyword()) ::
  Nombaone.PaymentMethod.t()

Raising variant of update_payment_method/4.