Class: GoCardlessPro::Services::SubscriptionsService

Inherits:
BaseService
  • Object
show all
Defined in:
lib/gocardless_pro/services/subscriptions_service.rb

Overview

Service for making requests to the Subscription endpoints

Instance Method Summary collapse

Methods inherited from BaseService

#initialize, #make_request, #sub_url

Constructor Details

This class inherits a constructor from GoCardlessPro::Services::BaseService

Instance Method Details

#all(options = {}) ⇒ Object

Get a lazily enumerated list of all the items returned. This is similar to the ‘list` method but will paginate for you automatically.

Otherwise they will be the body of the request.

Parameters:

  • options (Hash) (defaults to: {}) —

    parameters as a hash. If the request is a GET, these will be converted to query parameters.



71
72
73
74
75
76
 
# File 'lib/gocardless_pro/services/subscriptions_service.rb', line 71

def all(options = {})
  Paginator.new(
    service: self,
    options: options
  ).enumerator
end

#cancel(identity, options = {}) ⇒ Object

Immediately cancels a subscription; no more payments will be created under it. Any metadata supplied to this endpoint will be stored on the payment cancellation event it causes.

This will fail with a cancellation_failed error if the subscription is already cancelled or finished. Example URL: /subscriptions/:identity/actions/cancel

Parameters:

  • identity —

    # Unique identifier, beginning with “SB”.

  • options (Hash) (defaults to: {}) —

    parameters as a hash, under a params key.



286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/gocardless_pro/services/subscriptions_service.rb', line 286

def cancel(identity, options = {})
  path = sub_url('/subscriptions/:identity/actions/cancel', {
                   'identity' => identity
                 })

  params = options.delete(:params) || {}
  options[:params] = {}
  options[:params]['data'] = params

  options[:retry_failures] = false

  begin
    response = make_request(:post, path, options)

    # Response doesn't raise any errors until #body is called
    response.tap(&:body)
  rescue InvalidStateError => e
    if e.idempotent_creation_conflict?
      case @api_service.on_idempotency_conflict
      when :raise
        raise IdempotencyConflict, e.error
      when :fetch
        return get(e.conflicting_resource_id)
      end
    end

    raise e
  end

  return if response.body.nil?

  Resources::Subscription.new(unenvelope_body(response.body), response)
end

#create(options = {}) ⇒ Object

Creates a new subscription object Example URL: /subscriptions

Parameters:

  • options (Hash) (defaults to: {}) —

    parameters as a hash, under a params key.



16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
 
# File 'lib/gocardless_pro/services/subscriptions_service.rb', line 16

def create(options = {})
  path = '/subscriptions'

  params = options.delete(:params) || {}
  options[:params] = {}
  options[:params][envelope_key] = params

  options[:retry_failures] = true

  begin
    response = make_request(:post, path, options)

    # Response doesn't raise any errors until #body is called
    response.tap(&:body)
  rescue InvalidStateError => e
    if e.idempotent_creation_conflict?
      case @api_service.on_idempotency_conflict
      when :raise
        raise IdempotencyConflict, e.error
      when :fetch
        return get(e.conflicting_resource_id)
      end
    end

    raise e
  end

  return if response.body.nil?

  Resources::Subscription.new(unenvelope_body(response.body), response)
end

#get(identity, options = {}) ⇒ Object

Retrieves the details of a single subscription. Example URL: /subscriptions/:identity

Parameters:

  • identity —

    # Unique identifier, beginning with “SB”.

  • options (Hash) (defaults to: {}) —

    parameters as a hash, under a params key.



83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/gocardless_pro/services/subscriptions_service.rb', line 83

def get(identity, options = {})
  path = sub_url('/subscriptions/:identity', {
                   'identity' => identity
                 })

  options[:retry_failures] = true

  response = make_request(:get, path, options)

  return if response.body.nil?

  Resources::Subscription.new(unenvelope_body(response.body), response)
end

#list(options = {}) ⇒ Object

Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your subscriptions. Please note if the subscriptions are related to customers who have been removed, they will not be shown in the response. Example URL: /subscriptions

Parameters:

  • options (Hash) (defaults to: {}) —

    parameters as a hash, under a params key.



53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/gocardless_pro/services/subscriptions_service.rb', line 53

def list(options = {})
  path = '/subscriptions'

  options[:retry_failures] = true

  response = make_request(:get, path, options)

  ListResponse.new(
    response: response,
    unenveloped_body: unenvelope_body(response.body),
    resource_class: Resources::Subscription
  )
end

#pause(identity, options = {}) ⇒ Object

Pause a subscription object. No payments will be created until it is resumed.

This can only be used when a subscription is collecting a fixed number of payments (created using ‘count`), when they continue forever (created without `count` or `end_date`) or the subscription is already paused for a number of cycles.

When ‘pause_cycles` is omitted the subscription is paused until the [resume endpoint](#subscriptions-resume-a-subscription) is called. If the subscription is collecting a fixed number of payments, `end_date` will be set to `null`. When paused indefinitely, `upcoming_payments` will be empty.

When ‘pause_cycles` is provided the subscription will be paused for the number of cycles requested. If the subscription is collecting a fixed number of payments, `end_date` will be set to a new value. When paused for a number of cycles, `upcoming_payments` will still contain the upcoming charge dates.

This fails with:

  • ‘forbidden` if the subscription was created by an app and you are not

authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app

  • ‘validation_failed` if invalid data is provided when attempting to pause a

subscription.

  • ‘subscription_paused_cannot_update_cycles` if the subscription is already

paused for a number of cycles and the request provides a value for ‘pause_cycle`.

  • ‘subscription_cannot_be_paused` if the subscription cannot be paused.

  • ‘subscription_already_ended` if the subscription has taken all payments.

  • ‘pause_cycles_must_be_greater_than_or_equal_to` if the provided value for

‘pause_cycles` cannot be satisfied. Example URL: /subscriptions/:identity/actions/pause

Parameters:

  • identity —

    # Unique identifier, beginning with “SB”.

  • options (Hash) (defaults to: {}) —

    parameters as a hash, under a params key.



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/gocardless_pro/services/subscriptions_service.rb', line 187

def pause(identity, options = {})
  path = sub_url('/subscriptions/:identity/actions/pause', {
                   'identity' => identity
                 })

  params = options.delete(:params) || {}
  options[:params] = {}
  options[:params]['data'] = params

  options[:retry_failures] = false

  begin
    response = make_request(:post, path, options)

    # Response doesn't raise any errors until #body is called
    response.tap(&:body)
  rescue InvalidStateError => e
    if e.idempotent_creation_conflict?
      case @api_service.on_idempotency_conflict
      when :raise
        raise IdempotencyConflict, e.error
      when :fetch
        return get(e.conflicting_resource_id)
      end
    end

    raise e
  end

  return if response.body.nil?

  Resources::Subscription.new(unenvelope_body(response.body), response)
end

#resume(identity, options = {}) ⇒ Object

Resume a subscription object. Payments will start to be created again based on the subscriptions recurrence rules. The ‘charge_date` on the next payment will be the same as the subscriptions `earliest_charge_date_after_resume`

This fails with:

  • ‘forbidden` if the subscription was created by an app and you are not

authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app

  • ‘validation_failed` if invalid data is provided when attempting to resume a

subscription.

  • ‘subscription_not_paused` if the subscription is not paused.

Example URL: /subscriptions/:identity/actions/resume

Parameters:

  • identity —

    # Unique identifier, beginning with “SB”.

  • options (Hash) (defaults to: {}) —

    parameters as a hash, under a params key.



242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/gocardless_pro/services/subscriptions_service.rb', line 242

def resume(identity, options = {})
  path = sub_url('/subscriptions/:identity/actions/resume', {
                   'identity' => identity
                 })

  params = options.delete(:params) || {}
  options[:params] = {}
  options[:params]['data'] = params

  options[:retry_failures] = false

  begin
    response = make_request(:post, path, options)

    # Response doesn't raise any errors until #body is called
    response.tap(&:body)
  rescue InvalidStateError => e
    if e.idempotent_creation_conflict?
      case @api_service.on_idempotency_conflict
      when :raise
        raise IdempotencyConflict, e.error
      when :fetch
        return get(e.conflicting_resource_id)
      end
    end

    raise e
  end

  return if response.body.nil?

  Resources::Subscription.new(unenvelope_body(response.body), response)
end

#update(identity, options = {}) ⇒ Object

Updates a subscription object.

This fails with:

  • ‘validation_failed` if invalid data is provided when attempting to update a

subscription.

  • ‘subscription_not_active` if the subscription is no longer active.

  • ‘subscription_already_ended` if the subscription has taken all payments.

  • ‘mandate_payments_require_approval` if the amount is being changed and the

mandate requires approval.

  • ‘number_of_subscription_amendments_exceeded` error if the subscription

amount has already been changed 10 times.

  • ‘forbidden` if the amount is being changed, and the subscription was created

by an app and you are not authenticated as that app, or if the subscription was not created by an app and you are authenticated as an app

  • ‘resource_created_by_another_app` if the app fee is being changed, and the

subscription was created by an app other than the app you are authenticated as

Example URL: /subscriptions/:identity

Parameters:

  • identity —

    # Unique identifier, beginning with “SB”.

  • options (Hash) (defaults to: {}) —

    parameters as a hash, under a params key.



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/gocardless_pro/services/subscriptions_service.rb', line 125

def update(identity, options = {})
  path = sub_url('/subscriptions/:identity', {
                   'identity' => identity
                 })

  params = options.delete(:params) || {}
  options[:params] = {}
  options[:params][envelope_key] = params

  options[:retry_failures] = true

  response = make_request(:put, path, options)

  return if response.body.nil?

  Resources::Subscription.new(unenvelope_body(response.body), response)
end