Class: EasyLabs::Resources::Subscriptions

Inherits:
Base
  • Object
show all
Defined in:
lib/easylabs/resources/subscriptions.rb

Overview

The Easy-native subscription engine. Single biggest resource —~14 endpoints covering create/list/retrieve, cancel/pause/resume, item CRUD, discount application, one-time charges, metered usage, and proration preview.

Instance Method Summary collapse

Methods inherited from Base

#initialize

Constructor Details

This class inherits a constructor from EasyLabs::Resources::Base

Instance Method Details

#add_item(id, price_id:, quantity: nil) ⇒ Object

── Items ───────────────────────────────────────────────────────



80
81
82
83
 
# File 'lib/easylabs/resources/subscriptions.rb', line 80

def add_item(id, price_id:, quantity: nil)
  body = { price_id: price_id, quantity: quantity }.compact
  request(:post, "/subscriptions/#{id}/items", body: body)
end

#apply_discount(id, **body) ⇒ Object

POST /subscriptions/:id/discounts. Provide exactly one of ‘coupon_id` or `promotion_code`; optionally scope to a single subscription_item_id. The API enforces the XOR — let it reject invalid combinations rather than client-side guarding.



100
101
102
 
# File 'lib/easylabs/resources/subscriptions.rb', line 100

def apply_discount(id, **body)
  request(:post, "/subscriptions/#{id}/discounts", body: body)
end

#cancel(id, at_period_end: false) ⇒ Object

DELETE /subscriptions/:id?at_period_end=… Default at_period_end=false — cancels immediately.



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

def cancel(id, at_period_end: false)
  request(:delete, "/subscriptions/#{id}",
          query: { at_period_end: at_period_end })
end

#create(**body) ⇒ Object 



23
24
25
 
# File 'lib/easylabs/resources/subscriptions.rb', line 23

def create(**body)
  request(:post, "/subscriptions", body: body)
end

#create_one_time_charge(id, **body) ⇒ Object

── One-time charges ────────────────────────────────────────────



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

def create_one_time_charge(id, **body)
  request(:post, "/subscriptions/#{id}/one-time-charges", body: body)
end

#list(limit: nil, offset: nil, ids: nil) ⇒ Object

── Top-level CRUD ──────────────────────────────────────────────



14
15
16
17
 
# File 'lib/easylabs/resources/subscriptions.rb', line 14

def list(limit: nil, offset: nil, ids: nil)
  request(:get, "/subscriptions",
          query: pagination_query(limit: limit, offset: offset, ids: ids))
end

#list_discounts(id) ⇒ Object 



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

def list_discounts(id)
  request(:get, "/subscriptions/#{id}/discounts")
end

#pause(id, behavior:, resumes_at: nil) ⇒ Object

── Pause / resume ──────────────────────────────────────────────



40
41
42
43
 
# File 'lib/easylabs/resources/subscriptions.rb', line 40

def pause(id, behavior:, resumes_at: nil)
  body = { behavior: behavior, resumes_at: resumes_at }.compact
  request(:post, "/subscriptions/#{id}/pause", body: body)
end

#proration_preview(id, items: nil, remove_items: nil, proration_date: nil) ⇒ Object

GET /subscriptions/:id/proration-preview. Encodes ‘items` as the comma-joined `price_id:quantity` shape the API expects; pass-through `remove_items` (UUID list) and `proration_date` directly.



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/easylabs/resources/subscriptions.rb', line 55

def proration_preview(id, items: nil, remove_items: nil, proration_date: nil)
  encoded_items =
    if items.is_a?(Array) && !items.empty?
      items.map do |entry|
        if entry.is_a?(Hash) && entry[:quantity]
          "#{entry[:price_id]}:#{entry[:quantity]}"
        elsif entry.is_a?(Hash)
          entry[:price_id]
        else
          entry.to_s
        end
      end.join(",")
    end

  query = {
    items: encoded_items,
    remove_items: remove_items,
    proration_date: proration_date
  }.compact

  request(:get, "/subscriptions/#{id}/proration-preview", query: query)
end

#remove_discount(id, discount_id) ⇒ Object 



108
109
110
 
# File 'lib/easylabs/resources/subscriptions.rb', line 108

def remove_discount(id, discount_id)
  request(:delete, "/subscriptions/#{id}/discounts/#{discount_id}")
end

#remove_item(id, item_id) ⇒ Object 



90
91
92
 
# File 'lib/easylabs/resources/subscriptions.rb', line 90

def remove_item(id, item_id)
  request(:delete, "/subscriptions/#{id}/items/#{item_id}")
end

#report_usage(id, **body) ⇒ Object

── Metered usage ───────────────────────────────────────────────



120
121
122
 
# File 'lib/easylabs/resources/subscriptions.rb', line 120

def report_usage(id, **body)
  request(:post, "/subscriptions/#{id}/usage", body: body)
end

#resume(id) ⇒ Object 



45
46
47
 
# File 'lib/easylabs/resources/subscriptions.rb', line 45

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

#retrieve(id) ⇒ Object 



19
20
21
 
# File 'lib/easylabs/resources/subscriptions.rb', line 19

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

#update(id, **body) ⇒ Object 



27
28
29
 
# File 'lib/easylabs/resources/subscriptions.rb', line 27

def update(id, **body)
  request(:patch, "/subscriptions/#{id}", body: body)
end

#update_item(id, item_id, quantity:) ⇒ Object 



85
86
87
88
 
# File 'lib/easylabs/resources/subscriptions.rb', line 85

def update_item(id, item_id, quantity:)
  request(:patch, "/subscriptions/#{id}/items/#{item_id}",
          body: { quantity: quantity })
end

#usage_reconciliation(id, **query) ⇒ Object 



128
129
130
 
# File 'lib/easylabs/resources/subscriptions.rb', line 128

def usage_reconciliation(id, **query)
  request(:get, "/subscriptions/#{id}/usage/reconciliation", query: query.compact)
end

#usage_summary(id, **query) ⇒ Object 



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

def usage_summary(id, **query)
  request(:get, "/subscriptions/#{id}/usage/summary", query: query.compact)
end