Module: PaymentKit::Resources::Subscriptions

Included in:
Client
Defined in:
lib/payment_kit/resources/subscriptions.rb

Overview

Subscription lifecycle, scheduling and change requests.

Instance Method Summary collapse

Instance Method Details

#active_change_request(subscription_id) ⇒ Object

Returns null when the subscription has no active change request.



97
98
99
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 97

def active_change_request(subscription_id)
  get("/subscriptions/#{subscription_id}/change-requests/active")
end

#add_change_request_changes(subscription_id, request_id, params = nil) ⇒ Object

Appends item_changes, coupon_changes, balance_changes and trial_behavior to a draft. Callable repeatedly; each call appends. Adding changes to a ready request reverts it to draft.



104
105
106
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 104

def add_change_request_changes(subscription_id, request_id, params = nil, **)
  patch("/subscriptions/#{subscription_id}/change-requests/#{request_id}", params, **)
end

#apply_change_request(subscription_id, request_id) ⇒ Object

Charge-first execution: pass a stable idempotency_key.



114
115
116
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 114

def apply_change_request(subscription_id, request_id, **)
  post("/subscriptions/#{subscription_id}/change-requests/#{request_id}/apply", {}, **)
end

#apply_subscription_changes(subscription_id, params = nil) ⇒ Object

One-step shortcut: create, add changes, preview and apply in a single call.



124
125
126
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 124

def apply_subscription_changes(subscription_id, params = nil, **)
  post("/subscriptions/#{subscription_id}/change-requests/apply", params, **)
end

#cancel_change_request(subscription_id, request_id) ⇒ Object

Discards a change request without applying it.



119
120
121
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 119

def cancel_change_request(subscription_id, request_id)
  delete("/subscriptions/#{subscription_id}/change-requests/#{request_id}")
end

#cancel_pending_change(id) ⇒ Object

Cancels a scheduled (period-end) plan change before it executes.



79
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 79

def cancel_pending_change(id) = delete("/subscriptions/#{id}/pending-change")

#cancel_scheduled_cancellation(id) ⇒ Object

Clears a cancellation previously scheduled by #schedule_cancellation.



44
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 44

def cancel_scheduled_cancellation(id) = delete("/subscriptions/#{id}/scheduled-cancellation")

#cancel_scheduled_pause(id) ⇒ Object

Removes a pending pause_at_end before it activates.



52
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 52

def cancel_scheduled_pause(id) = delete("/subscriptions/#{id}/scheduled-pause")

#cancel_subscription(id, params = nil) ⇒ Object

Immediate, irreversible cancellation. Accepts refund_option (+none+, full, prorated, cancel_unpaid) and is_preview.



34
35
36
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 34

def cancel_subscription(id, params = nil, **)
  post("/subscriptions/#{id}/cancel", params, **)
end

#change_plan(subscription_id, params = nil) ⇒ Object

Deprecated. PaymentKit documents change-plan as the legacy single-call endpoint, planned for deprecation. Prefer the change-request workflow (#create_change_request, #add_change_request_changes, #preview_change_request, #apply_change_request) or the one-step #apply_subscription_changes.



74
75
76
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 74

def change_plan(subscription_id, params = nil, **)
  post("/subscriptions/#{subscription_id}/change-plan", params, **)
end

#create_change_request(subscription_id, params = nil) ⇒ Object

Opens a draft change request. Accepts reason and expires_in_hours.

Only one active (draft/ready) change request may exist per subscription; creating a second raises ConflictError (HTTP 409).



87
88
89
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 87

def create_change_request(subscription_id, params = nil, **)
  post("/subscriptions/#{subscription_id}/change-requests", params, **)
end

#create_subscription(params = nil) ⇒ Object

POST /subscriptions — customer_id, currency, billing_interval, billing_interval_count, period_start and collection_method are required; items is an Array of +price_id+/+quantity+ pairs.



10
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 10

def create_subscription(params = nil, **) = post("/subscriptions", params, **)

#list_subscriptions(params = {}) ⇒ Object

GET /subscriptions — auto-paginated Array of subscriptions.



16
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 16

def list_subscriptions(params = {}) = list("/subscriptions", params)

#pause_subscription(id, params = nil) ⇒ Object

pause_behavior (+pause_immediately+/+pause_at_end+) is required.



47
48
49
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 47

def pause_subscription(id, params = nil, **)
  post("/subscriptions/#{id}/pause", params, **)
end

#preview_change_request(subscription_id, request_id) ⇒ Object

Computes proration and moves the request to ready.



109
110
111
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 109

def preview_change_request(subscription_id, request_id)
  post("/subscriptions/#{subscription_id}/change-requests/#{request_id}/preview", {})
end

#renew_subscription(id) ⇒ Object

Forces a renewal cycle immediately.



67
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 67

def renew_subscription(id, **) = post("/subscriptions/#{id}/renew", {}, **)

#reschedule_billing(id, params = nil) ⇒ Object

Moves the next invoice date. Accepts next_billing_date, create_proration and is_preview.



62
63
64
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 62

def reschedule_billing(id, params = nil, **)
  post("/subscriptions/#{id}/reschedule-billing", params, **)
end

#resume_subscription(id, params = nil) ⇒ Object

Resumes a paused subscription. Whether billing re-anchors or catches up is governed by the account's resume_billing_behavior setting.



56
57
58
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 56

def resume_subscription(id, params = nil, **)
  post("/subscriptions/#{id}/resume", params, **)
end

#retrieve_change_request(subscription_id, request_id) ⇒ Object

GET /subscriptions/id/change-requests/request_id



92
93
94
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 92

def retrieve_change_request(subscription_id, request_id)
  get("/subscriptions/#{subscription_id}/change-requests/#{request_id}")
end

#retrieve_subscription(id) ⇒ Object

GET /subscriptions/id



13
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 13

def retrieve_subscription(id) = get("/subscriptions/#{id}")

#schedule_cancellation(id, params = nil) ⇒ Object

Cancel on a specific date instead of immediately.



39
40
41
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 39

def schedule_cancellation(id, params = nil, **)
  post("/subscriptions/#{id}/schedule-cancellation", params, **)
end

#update_subscription(id, params = nil) ⇒ Object

PATCH /subscriptions/id — subscription-level fields such as cancel_at_period_end and metadata. Line items are not accepted here; use #update_subscription_items.



21
22
23
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 21

def update_subscription(id, params = nil, **)
  patch("/subscriptions/#{id}", params, **)
end

#update_subscription_items(id, params = nil) ⇒ Object

Add/update/remove items within the current billing interval. Charge-first: payment is collected before the change applies, so pass a stable idempotency_key. proration_behavior is required by the API.



28
29
30
 
# File 'lib/payment_kit/resources/subscriptions.rb', line 28

def update_subscription_items(id, params = nil, **)
  patch("/subscriptions/#{id}/items", params, **)
end