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

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 simmilar 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.



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

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.



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'lib/gocardless_pro/services/subscriptions_service.rb', line 151

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)
      else
        raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
      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.



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
47
48
49
 
# File 'lib/gocardless_pro/services/subscriptions_service.rb', line 17

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)
      else
        raise ArgumentError, 'Unknown mode for :on_idempotency_conflict'
      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.



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

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. Example URL: /subscriptions

Parameters:

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

    parameters as a hash, under a params key.



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

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

#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
 
# 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