Class: Nombaone::Resources::Subscriptions

Inherits:
BaseResource show all
Defined in:
lib/nombaone/resources/subscriptions.rb,
sig/nombaone/resources.rbs

Overview

Subscriptions — the core object. Create one against a customer and a price; the engine handles cycles, invoices, retries, and recovery.

Involuntary churn is status: "canceled" with cancellation_reason: "involuntary" (there is no separate churned status; there IS a subscription.churned event). past_due is not canceled — read #dunning and honor grace_access_until.

Examples:

subscription = nombaone.subscriptions.create(
  customer_id: customer.id, price_id: price.id, payment_method_id: method.id
)
subscription.status # => "active"

Instance Method Summary collapse

Methods inherited from BaseResource

#encode, #initialize, #request, #request_page

Constructor Details

This class inherits a constructor from Nombaone::Resources::BaseResource

Instance Method Details

#apply_discount(id, coupon:, request_options: {}) ⇒ NombaObject

Apply a coupon to this subscription only.

Parameters:

  • id (String) —

    nbo…sub

  • coupon (String) —

    a coupon id (nbo…cpn) or its code.

  • request_options (Hash) (defaults to: {})

Returns:



295
296
297
298
 
# File 'lib/nombaone/resources/subscriptions.rb', line 295

def apply_discount(id, coupon:, request_options: {})
  request(:post, "/subscriptions/#{encode(id)}/discount",
          body: { coupon: coupon }, options: request_options)
end

#cancel(id, mode: OMIT, comment: OMIT, request_options: {}) ⇒ NombaObject

Cancel a subscription — immediately (default) or at period end.

Examples:

nombaone.subscriptions.cancel(subscription.id, mode: "at_period_end")

Parameters:

  • id (String) —

    nbo…sub

  • mode (String) (defaults to: OMIT) —

    "now" (default) or "at_period_end" (keeps access until the cycle closes).

  • comment (String) (defaults to: OMIT)
  • request_options (Hash) (defaults to: {})

Returns:



214
215
216
217
 
# File 'lib/nombaone/resources/subscriptions.rb', line 214

def cancel(id, mode: OMIT, comment: OMIT, request_options: {})
  request(:post, "/subscriptions/#{encode(id)}/cancel",
          body: { mode: mode, comment: comment }, options: request_options)
end

#change(id, price_id: OMIT, quantity: OMIT, interval_switch: OMIT, proration_behavior: OMIT, request_options: {}) ⇒ NombaObject

Change price or quantity mid-cycle, prorating by default. Switching the billing interval mid-cycle is unsupported (PRORATION_INTERVAL_SWITCH_UNSUPPORTED) — queue it with #schedule instead.

Examples:

nombaone.subscriptions.change(subscription.id, price_id: bigger_price.id)

Parameters:

  • id (String) —

    nbo…sub

  • price_id (String) (defaults to: OMIT)
  • quantity (Integer) (defaults to: OMIT)
  • interval_switch (Boolean) (defaults to: OMIT)
  • proration_behavior (String) (defaults to: OMIT) —

    "create_prorations" (default) or "none".

  • request_options (Hash) (defaults to: {})

Returns:



249
250
251
252
253
254
255
256
257
258
259
 
# File 'lib/nombaone/resources/subscriptions.rb', line 249

def change(id, price_id: OMIT, quantity: OMIT, interval_switch: OMIT,
           proration_behavior: OMIT, request_options: {})
  request(:post, "/subscriptions/#{encode(id)}/change",
          body: {
            price_id: price_id,
            quantity: quantity,
            interval_switch: interval_switch,
            proration_behavior: proration_behavior,
          },
          options: request_options)
end

#create(customer_id:, price_id:, payment_method_id: OMIT, collection_method: OMIT, trial_days: OMIT, quantity: OMIT, metadata: OMIT, request_options: {}) ⇒ NombaObject

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

Parameters:

  • customer_id (String) —

    nbo…cus

  • price_id (String) —

    nbo…prc — subscriptions reference a price, not a plan.

  • payment_method_id (String) (defaults to: OMIT) —

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

  • collection_method (String) (defaults to: OMIT) —

    "charge_automatically" (default) or "send_invoice".

  • trial_days (Integer) (defaults to: OMIT)
  • quantity (Integer) (defaults to: OMIT) —

    defaults to 1 server-side.

  • metadata (Hash) (defaults to: OMIT)
  • request_options (Hash) (defaults to: {})

Returns:

Raises:



116
117
118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/nombaone/resources/subscriptions.rb', line 116

def create(customer_id:, price_id:, payment_method_id: OMIT, collection_method: OMIT,
           trial_days: OMIT, quantity: OMIT, metadata: OMIT, request_options: {})
  request(:post, "/subscriptions",
          body: {
            customer_id: customer_id,
            price_id: price_id,
            payment_method_id: payment_method_id,
            collection_method: collection_method,
            trial_days: trial_days,
            quantity: quantity,
            metadata: metadata,
          },
          options: request_options)
end

#dunning ⇒ SubscriptionDunning

Recovery/dunning state (read-only).

Returns:



95
96
97
 
# File 'lib/nombaone/resources/subscriptions.rb', line 95

def dunning
  @dunning ||= SubscriptionDunning.new(@client)
end

#list(customer_id: OMIT, status: OMIT, limit: OMIT, cursor: OMIT, request_options: {}) ⇒ Page<NombaObject>

List subscriptions, newest first.

Parameters:

  • customer_id (String) (defaults to: OMIT) —

    filter to one customer (nbo…cus).

  • status (String) (defaults to: OMIT) —

    filter by subscription status.

  • limit (Integer) (defaults to: OMIT) —

    page size, 1–100 (API default 20).

  • cursor (String) (defaults to: OMIT) —

    opaque cursor from a previous page.

  • request_options (Hash) (defaults to: {})

Returns:



163
164
165
166
167
168
 
# File 'lib/nombaone/resources/subscriptions.rb', line 163

def list(customer_id: OMIT, status: OMIT, limit: OMIT, cursor: OMIT, request_options: {})
  request_page("/subscriptions",
               query: { customer_id: customer_id, status: status, limit: limit,
                        cursor: cursor },
               options: request_options)
end

#list_events(id, limit: OMIT, cursor: OMIT, request_options: {}) ⇒ Page<NombaObject>

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

Parameters:

  • id (String) —

    nbo…sub

  • limit (Integer) (defaults to: OMIT) —

    page size, 1–100 (API default 20).

  • cursor (String) (defaults to: OMIT) —

    opaque cursor from a previous page.

  • request_options (Hash) (defaults to: {})

Returns:



177
178
179
180
 
# File 'lib/nombaone/resources/subscriptions.rb', line 177

def list_events(id, limit: OMIT, cursor: OMIT, request_options: {})
  request_page("/subscriptions/#{encode(id)}/events",
               query: { limit: limit, cursor: cursor }, options: request_options)
end

#pause(id, max_days: OMIT, request_options: {}) ⇒ NombaObject

Pause billing. The subscription keeps its place in the cycle and resumes cleanly.

Parameters:

  • id (String) —

    nbo…sub

  • max_days (Integer) (defaults to: OMIT) —

    auto-resume after this many days.

  • request_options (Hash) (defaults to: {})
  • max_days: (Integer) (defaults to: OMIT)
  • request_options: (Nombaone::request_options) (defaults to: {})

Returns:

Raises:



189
190
191
192
 
# File 'lib/nombaone/resources/subscriptions.rb', line 189

def pause(id, max_days: OMIT, request_options: {})
  request(:post, "/subscriptions/#{encode(id)}/pause",
          body: { max_days: max_days }, options: request_options)
end

#remove_discount(id, request_options: {}) ⇒ NombaObject

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

Parameters:

  • id (String) —

    nbo…sub

  • request_options (Hash) (defaults to: {})
  • request_options: (Nombaone::request_options) (defaults to: {})

Returns:



305
306
307
 
# File 'lib/nombaone/resources/subscriptions.rb', line 305

def remove_discount(id, request_options: {})
  request(:delete, "/subscriptions/#{encode(id)}/discount", options: request_options)
end

#resubscribe(id, price_id: OMIT, payment_method_id: OMIT, request_options: {}) ⇒ NombaObject

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

Parameters:

  • id (String) —

    nbo…sub

  • price_id (String) (defaults to: OMIT) —

    defaults to the previous price.

  • payment_method_id (String) (defaults to: OMIT) —

    defaults to the previous payment method.

  • request_options (Hash) (defaults to: {})

Returns:

Raises:



229
230
231
232
233
 
# File 'lib/nombaone/resources/subscriptions.rb', line 229

def resubscribe(id, price_id: OMIT, payment_method_id: OMIT, request_options: {})
  request(:post, "/subscriptions/#{encode(id)}/resubscribe",
          body: { price_id: price_id, payment_method_id: payment_method_id },
          options: request_options)
end

#resume(id, request_options: {}) ⇒ NombaObject

Resume a paused subscription.

Parameters:

  • id (String) —

    nbo…sub

  • request_options (Hash) (defaults to: {})
  • request_options: (Nombaone::request_options) (defaults to: {})

Returns:



199
200
201
 
# File 'lib/nombaone/resources/subscriptions.rb', line 199

def resume(id, request_options: {})
  request(:post, "/subscriptions/#{encode(id)}/resume", body: {}, options: request_options)
end

#retrieve(id, request_options: {}) ⇒ NombaObject

Retrieve a subscription by id.

Parameters:

  • id (String) —

    nbo…sub

  • request_options (Hash) (defaults to: {})
  • request_options: (Nombaone::request_options) (defaults to: {})

Returns:

Raises:



137
138
139
 
# File 'lib/nombaone/resources/subscriptions.rb', line 137

def retrieve(id, request_options: {})
  request(:get, "/subscriptions/#{encode(id)}", options: request_options)
end

#retrieve_upcoming_invoice(id, request_options: {}) ⇒ NombaObject

Preview the next invoice without charging or storing anything.

Parameters:

  • id (String) —

    nbo…sub

  • request_options (Hash) (defaults to: {})
  • request_options: (Nombaone::request_options) (defaults to: {})

Returns:



285
286
287
 
# File 'lib/nombaone/resources/subscriptions.rb', line 285

def retrieve_upcoming_invoice(id, request_options: {})
  request(:get, "/subscriptions/#{encode(id)}/upcoming-invoice", options: request_options)
end

#schedule ⇒ SubscriptionSchedules

Scheduled (next-cycle) changes.

Returns:



89
90
91
 
# File 'lib/nombaone/resources/subscriptions.rb', line 89

def schedule
  @schedule ||= SubscriptionSchedules.new(@client)
end

#update(id, default_payment_method_id: OMIT, metadata: OMIT, request_options: {}) ⇒ NombaObject

Edit metadata or the default payment method. For a price, quantity, or interval change (which prorates), use #change. At least one field is required.

Parameters:

  • id (String) —

    nbo…sub

  • default_payment_method_id (String) (defaults to: OMIT)
  • metadata (Hash) (defaults to: OMIT)
  • request_options (Hash) (defaults to: {})

Returns:



149
150
151
152
153
 
# File 'lib/nombaone/resources/subscriptions.rb', line 149

def update(id, default_payment_method_id: OMIT, metadata: OMIT, request_options: {})
  request(:patch, "/subscriptions/#{encode(id)}",
          body: { default_payment_method_id: default_payment_method_id, metadata: metadata },
          options: request_options)
end

#update_payment_method(id, payment_method_reference: OMIT, checkout_token: OMIT, request_options: {}) ⇒ NombaObject

Swap the payment method that bills this subscription — the card-update path during dunning. Provide exactly one of payment_method_reference or checkout_token.

Parameters:

  • id (String) —

    nbo…sub

  • payment_method_reference (String) (defaults to: OMIT) —

    an already-captured method (nbo…pmt).

  • checkout_token (String) (defaults to: OMIT) —

    a fresh hosted-checkout token — attaches and swaps atomically.

  • request_options (Hash) (defaults to: {})

Returns:



270
271
272
273
274
275
276
277
278
 
# File 'lib/nombaone/resources/subscriptions.rb', line 270

def update_payment_method(id, payment_method_reference: OMIT, checkout_token: OMIT,
                          request_options: {})
  request(:post, "/subscriptions/#{encode(id)}/payment-method",
          body: {
            payment_method_reference: payment_method_reference,
            checkout_token: checkout_token,
          },
          options: request_options)
end