class GoCardlessPro::Services::CustomersService

Service for making requests to the Customer endpoints

Public Instance Methods

all(options = {}) click to toggle source

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

@param options [Hash] parameters as a hash. If the request is a GET, these will be converted to query parameters. Otherwise they will be the body of the request.

# File lib/gocardless_pro/services/customers_service.rb, line 70
def all(options = {})
  Paginator.new(
    service: self,
    options: options
  ).enumerator
end
create(options = {}) click to toggle source

Creates a new customer object. Example URL: /customers @param options [Hash] parameters as a hash, under a params key.

# File lib/gocardless_pro/services/customers_service.rb, line 16
def create(options = {})
  path = '/customers'

  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::Customer.new(unenvelope_body(response.body), response)
end
get(identity, options = {}) click to toggle source

Retrieves the details of an existing customer. Example URL: /customers/:identity

@param identity # Unique identifier, beginning with “CU”. @param options [Hash] parameters as a hash, under a params key.

# File lib/gocardless_pro/services/customers_service.rb, line 82
def get(identity, options = {})
  path = sub_url('/customers/:identity', 'identity' => identity)

  options[:retry_failures] = true

  response = make_request(:get, path, options)

  return if response.body.nil?

  Resources::Customer.new(unenvelope_body(response.body), response)
end
list(options = {}) click to toggle source

Returns a [cursor-paginated](api-usage-cursor-pagination) list of your customers. Example URL: /customers @param options [Hash] parameters as a hash, under a params key.

# File lib/gocardless_pro/services/customers_service.rb, line 52
def list(options = {})
  path = '/customers'

  options[:retry_failures] = true

  response = make_request(:get, path, options)

  ListResponse.new(
    response: response,
    unenveloped_body: unenvelope_body(response.body),
    resource_class: Resources::Customer
  )
end
remove(identity, options = {}) click to toggle source

Removed customers will not appear in search results or lists of customers (in our API or exports), and it will not be possible to load an individually removed customer by ID.

<p class=“restricted-notice”><strong>The action of removing a customer cannot be reversed, so please use with care.</strong></p> Example URL: /customers/:identity

@param identity # Unique identifier, beginning with “CU”. @param options [Hash] parameters as a hash, under a params key.

# File lib/gocardless_pro/services/customers_service.rb, line 128
def remove(identity, options = {})
  path = sub_url('/customers/:identity', 'identity' => identity)

  options[:retry_failures] = false

  response = make_request(:delete, path, options)

  return if response.body.nil?

  Resources::Customer.new(unenvelope_body(response.body), response)
end
update(identity, options = {}) click to toggle source

Updates a customer object. Supports all of the fields supported when creating a customer. Example URL: /customers/:identity

@param identity # Unique identifier, beginning with “CU”. @param options [Hash] parameters as a hash, under a params key.

# File lib/gocardless_pro/services/customers_service.rb, line 100
def update(identity, options = {})
  path = sub_url('/customers/: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::Customer.new(unenvelope_body(response.body), response)
end

Private Instance Methods

envelope_key() click to toggle source

return the key which API responses will envelope data under

# File lib/gocardless_pro/services/customers_service.rb, line 150
def envelope_key
  'customers'
end
unenvelope_body(body) click to toggle source

Unenvelope the response of the body using the service's `envelope_key`

@param body [Hash]

# File lib/gocardless_pro/services/customers_service.rb, line 145
def unenvelope_body(body)
  body[envelope_key] || body['data']
end