Class: Pago::V2026_04::Services::Customers

Inherits:
Service
  • Object
show all
Defined in:
lib/pago/v2026_04/services/customers.rb,
sig/pago/v2026_04/generated.rbs

Defined Under Namespace

Classes: Members

Instance Attribute Summary

Attributes inherited from Service

#client

Instance Method Summary collapse

Methods inherited from Service

#initialize

Constructor Details

This class inherits a constructor from Pago::Service

Instance Method Details

#create(body: {}) ⇒ Object

Create a customer.

Scopes: customers:write

Parameters:

  • body (Hash, Object) (defaults to: {}) —

    the request body.

  • body: (Object) (defaults to: {})

Returns:

  • (Object)

Raises:



56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/pago/v2026_04/services/customers.rb', line 56

def create(body: {})
  data = client.request(
    http_method: "POST",
    path: "/v1/customers/",
    path_params: {},
    query: {},
    body: body,
    response_type: :json,
    errors: { 422 => Errors::HTTPValidationError }
  )
  Unions::Customer.from_json(data)
end

#delete(id, anonymize: false) ⇒ nil

Delete a customer.

This action cannot be undone and will immediately:

  • Cancel any active subscriptions for the customer
  • Revoke all their benefits
  • Clear any external_id

Use it only in the context of deleting a user within your own service. Otherwise, use more granular API endpoints to cancel a specific subscription or revoke certain benefits.

Note: The customers information will nonetheless be retained for historic orders and subscriptions.

Set anonymize=true to also anonymize PII for GDPR compliance.

Scopes: customers:write

Parameters:

  • id (String) —

    The customer ID.

  • anonymize (Boolean) (defaults to: false) —

    If true, also anonymize the customer's personal data for GDPR compliance. This replaces email with a hashed version, hashes name and billing name (name preserved for businesses with tax_id), clears billing address, and removes OAuth account data.

  • anonymize: (Boolean, nil) (defaults to: false)

Returns:

  • (nil)

Raises:



133
134
135
136
137
138
139
140
141
142
 
# File 'lib/pago/v2026_04/services/customers.rb', line 133

def delete(id, anonymize: false)
  client.request(
    http_method: "DELETE",
    path: "/v1/customers/{id}",
    path_params: { "id" => id },
    query: { "anonymize" => anonymize },
    response_type: :none,
    errors: { 404 => Errors::ResourceNotFound, 422 => Errors::HTTPValidationError }
  )
end

#delete_external(external_id, anonymize: false) ⇒ nil

Delete a customer by external ID.

Immediately cancels any active subscriptions and revokes any active benefits.

Set anonymize=true to also anonymize PII for GDPR compliance.

Scopes: customers:write

Parameters:

  • external_id (String) —

    The customer external ID.

  • anonymize (Boolean) (defaults to: false) —

    If true, also anonymize the customer's personal data for GDPR compliance.

  • anonymize: (Boolean, nil) (defaults to: false)

Returns:

  • (nil)

Raises:



202
203
204
205
206
207
208
209
210
211
 
# File 'lib/pago/v2026_04/services/customers.rb', line 202

def delete_external(external_id, anonymize: false)
  client.request(
    http_method: "DELETE",
    path: "/v1/customers/external/{external_id}",
    path_params: { "external_id" => external_id },
    query: { "anonymize" => anonymize },
    response_type: :none,
    errors: { 404 => Errors::ResourceNotFound, 422 => Errors::HTTPValidationError }
  )
end

#export(organization_id: nil) ⇒ String

Export customers as a CSV file.

Scopes: customers:read customers:write

Parameters:

  • organization_id (String, Array<String>, nil) (defaults to: nil) —

    Filter by organization ID.

  • organization_id: (Object) (defaults to: nil)

Returns:

  • (String)

Raises:



77
78
79
80
81
82
83
84
85
86
 
# File 'lib/pago/v2026_04/services/customers.rb', line 77

def export(organization_id: nil)
  client.request(
    http_method: "GET",
    path: "/v1/customers/export",
    path_params: {},
    query: { "organization_id" => organization_id },
    response_type: :text,
    errors: { 422 => Errors::HTTPValidationError }
  )
end

#get(id) ⇒ Object

Get a customer by ID.

Scopes: customers:read customers:write

Parameters:

  • id (String) —

    The customer ID.

Returns:

  • (Object)

Raises:



97
98
99
100
101
102
103
104
105
106
107
 
# File 'lib/pago/v2026_04/services/customers.rb', line 97

def get(id)
  data = client.request(
    http_method: "GET",
    path: "/v1/customers/{id}",
    path_params: { "id" => id },
    query: {},
    response_type: :json,
    errors: { 404 => Errors::ResourceNotFound, 422 => Errors::HTTPValidationError }
  )
  Unions::Customer.from_json(data)
end

#get_external(external_id) ⇒ Object

Get a customer by external ID.

Scopes: customers:read customers:write

Parameters:

  • external_id (String) —

    The customer external ID.

Returns:

  • (Object)

Raises:



176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/pago/v2026_04/services/customers.rb', line 176

def get_external(external_id)
  data = client.request(
    http_method: "GET",
    path: "/v1/customers/external/{external_id}",
    path_params: { "external_id" => external_id },
    query: {},
    response_type: :json,
    errors: { 404 => Errors::ResourceNotFound, 422 => Errors::HTTPValidationError }
  )
  Unions::Customer.from_json(data)
end

#get_state(id) ⇒ Object

Get a customer state by ID.

The customer state includes information about the customer's active subscriptions and benefits.

It's the ideal endpoint to use when you need to get a full overview of a customer's status.

Scopes: customers:read customers:write

Parameters:

  • id (String) —

    The customer ID.

Returns:

  • (Object)

Raises:



251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/pago/v2026_04/services/customers.rb', line 251

def get_state(id)
  data = client.request(
    http_method: "GET",
    path: "/v1/customers/{id}/state",
    path_params: { "id" => id },
    query: {},
    response_type: :json,
    errors: { 404 => Errors::ResourceNotFound, 422 => Errors::HTTPValidationError }
  )
  Unions::CustomerState.from_json(data)
end

#get_state_external(external_id) ⇒ Object

Get a customer state by external ID.

The customer state includes information about the customer's active subscriptions and benefits.

It's the ideal endpoint to use when you need to get a full overview of a customer's status.

Scopes: customers:read customers:write

Parameters:

  • external_id (String) —

    The customer external ID.

Returns:

  • (Object)

Raises:



278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/pago/v2026_04/services/customers.rb', line 278

def get_state_external(external_id)
  data = client.request(
    http_method: "GET",
    path: "/v1/customers/external/{external_id}/state",
    path_params: { "external_id" => external_id },
    query: {},
    response_type: :json,
    errors: { 404 => Errors::ResourceNotFound, 422 => Errors::HTTPValidationError }
  )
  Unions::CustomerState.from_json(data)
end

#list(organization_id: nil, email: nil, query: nil, active: nil, page: 1, limit: 10, sorting: ["-created_at"], metadata: nil) ⇒ Models::ListResourceCustomer

List customers.

Scopes: customers:read customers:write

Parameters:

  • organization_id (String, Array<String>, nil) (defaults to: nil) —

    Filter by organization ID.

  • email (String, nil) (defaults to: nil) —

    Filter by exact email.

  • query (String, nil) (defaults to: nil) —

    Filter by name, email, or external ID.

  • active (Boolean, nil) (defaults to: nil) —

    Filter by active customers, i.e. customers with at least one trialing, active or past_due subscription.

  • page (Integer) (defaults to: 1) —

    Page number, defaults to 1.

  • limit (Integer) (defaults to: 10) —

    Size of a page, defaults to 10. Maximum is 100.

  • sorting (Array<String>, nil) (defaults to: ["-created_at"]) —

    Sorting criterion. Several criteria can be used simultaneously and will be applied in order. Add a minus sign - before the criteria name to sort by descending order.

  • metadata (Object) (defaults to: nil) —

    Filter by metadata key-value pairs. It uses the deepObject style, e.g. ?metadata[key]=value.

  • organization_id: (Object) (defaults to: nil)
  • email: (String, nil) (defaults to: nil)
  • query: (String, nil) (defaults to: nil)
  • active: (Boolean, nil) (defaults to: nil)
  • page: (Integer, nil) (defaults to: 1)
  • limit: (Integer, nil) (defaults to: 10)
  • sorting: (Array[String], nil) (defaults to: ["-created_at"])
  • metadata: (Object) (defaults to: nil)

Returns:

Raises:



25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/pago/v2026_04/services/customers.rb', line 25

def list(organization_id: nil, email: nil, query: nil, active: nil, page: 1, limit: 10, sorting: ["-created_at"], metadata: nil)
  data = client.request(
    http_method: "GET",
    path: "/v1/customers/",
    path_params: {},
    query: { "organization_id" => organization_id, "email" => email, "query" => query, "active" => active, "page" => page, "limit" => limit, "sorting" => sorting, "metadata" => metadata },
    response_type: :json,
    errors: { 422 => Errors::HTTPValidationError }
  )
  Models::ListResourceCustomer.from_json(data)
end

#list_each(organization_id: nil, email: nil, query: nil, active: nil, limit: 10, sorting: ["-created_at"], metadata: nil) {|item| ... } ⇒ Pago::Paginator

Enumerate every item of list, fetching pages on demand.

Parameters:

  • organization_id: (Object) (defaults to: nil)
  • email: (String, nil) (defaults to: nil)
  • query: (String, nil) (defaults to: nil)
  • active: (Boolean, nil) (defaults to: nil)
  • limit: (Integer, nil) (defaults to: 10)
  • sorting: (Array[String], nil) (defaults to: ["-created_at"])
  • metadata: (Object) (defaults to: nil)

Yield Parameters:

  • item (Object)

Returns:



41
42
43
44
45
46
 
# File 'lib/pago/v2026_04/services/customers.rb', line 41

def list_each(organization_id: nil, email: nil, query: nil, active: nil, limit: 10, sorting: ["-created_at"], metadata: nil, &block)
  paginator = ::Pago::Paginator.new do |page_number|
    list(organization_id: organization_id, email: email, query: query, active: active, page: page_number, limit: limit, sorting: sorting, metadata: metadata)
  end
  block ? paginator.each(&block) : paginator
end

#list_payment_methods(id, page: 1, limit: 10) ⇒ Models::ListResourcePaymentMethod

Get saved payment methods of a customer.

Scopes: customers:read customers:write

Parameters:

  • id (String) —

    The customer ID.

  • page (Integer) (defaults to: 1) —

    Page number, defaults to 1.

  • limit (Integer) (defaults to: 10) —

    Size of a page, defaults to 10. Maximum is 100.

  • page: (Integer, nil) (defaults to: 1)
  • limit: (Integer, nil) (defaults to: 10)

Returns:

Raises:



301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/pago/v2026_04/services/customers.rb', line 301

def list_payment_methods(id, page: 1, limit: 10)
  data = client.request(
    http_method: "GET",
    path: "/v1/customers/{id}/payment-methods",
    path_params: { "id" => id },
    query: { "page" => page, "limit" => limit },
    response_type: :json,
    errors: { 404 => Errors::ResourceNotFound, 422 => Errors::HTTPValidationError }
  )
  Models::ListResourcePaymentMethod.from_json(data)
end

#list_payment_methods_each(id, limit: 10) {|item| ... } ⇒ Pago::Paginator

Enumerate every item of list_payment_methods, fetching pages on demand.

Parameters:

  • id (String)
  • limit: (Integer, nil) (defaults to: 10)

Yield Parameters:

  • item (Object)

Returns:



317
318
319
320
321
322
 
# File 'lib/pago/v2026_04/services/customers.rb', line 317

def list_payment_methods_each(id, limit: 10, &block)
  paginator = ::Pago::Paginator.new do |page_number|
    list_payment_methods(id, page: page_number, limit: limit)
  end
  block ? paginator.each(&block) : paginator
end

#list_payment_methods_external(external_id, page: 1, limit: 10) ⇒ Models::ListResourcePaymentMethod

Get saved payment methods of a customer by external ID.

Scopes: customers:read customers:write

Parameters:

  • external_id (String) —

    The customer external ID.

  • page (Integer) (defaults to: 1) —

    Page number, defaults to 1.

  • limit (Integer) (defaults to: 10) —

    Size of a page, defaults to 10. Maximum is 100.

  • page: (Integer, nil) (defaults to: 1)
  • limit: (Integer, nil) (defaults to: 10)

Returns:

Raises:



335
336
337
338
339
340
341
342
343
344
345
 
# File 'lib/pago/v2026_04/services/customers.rb', line 335

def list_payment_methods_external(external_id, page: 1, limit: 10)
  data = client.request(
    http_method: "GET",
    path: "/v1/customers/external/{external_id}/payment-methods",
    path_params: { "external_id" => external_id },
    query: { "page" => page, "limit" => limit },
    response_type: :json,
    errors: { 404 => Errors::ResourceNotFound, 422 => Errors::HTTPValidationError }
  )
  Models::ListResourcePaymentMethod.from_json(data)
end

#list_payment_methods_external_each(external_id, limit: 10) {|item| ... } ⇒ Pago::Paginator

Enumerate every item of list_payment_methods_external, fetching pages on demand.

Parameters:

  • external_id (String)
  • limit: (Integer, nil) (defaults to: 10)

Yield Parameters:

  • item (Object)

Returns:



351
352
353
354
355
356
 
# File 'lib/pago/v2026_04/services/customers.rb', line 351

def list_payment_methods_external_each(external_id, limit: 10, &block)
  paginator = ::Pago::Paginator.new do |page_number|
    list_payment_methods_external(external_id, page: page_number, limit: limit)
  end
  block ? paginator.each(&block) : paginator
end

#members ⇒ Members

Returns:



8
 
# File 'lib/pago/v2026_04/services/customers.rb', line 8

def members = @members ||= Members.new(client)

#update(id, body: {}) ⇒ Object

Update a customer.

Scopes: customers:write

Parameters:

  • id (String) —

    The customer ID.

  • body (Hash, Models::CustomerUpdate) (defaults to: {}) —

    the request body.

  • body: (Object) (defaults to: {})

Returns:

  • (Object)

Raises:



154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/pago/v2026_04/services/customers.rb', line 154

def update(id, body: {})
  data = client.request(
    http_method: "PATCH",
    path: "/v1/customers/{id}",
    path_params: { "id" => id },
    query: {},
    body: body,
    response_type: :json,
    errors: { 404 => Errors::ResourceNotFound, 422 => Errors::HTTPValidationError }
  )
  Unions::Customer.from_json(data)
end

#update_external(external_id, body: {}) ⇒ Object

Update a customer by external ID.

Scopes: customers:write

Parameters:

  • external_id (String) —

    The customer external ID.

  • body (Hash, Models::CustomerUpdateExternalID) (defaults to: {}) —

    the request body.

  • body: (Object) (defaults to: {})

Returns:

  • (Object)

Raises:



223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/pago/v2026_04/services/customers.rb', line 223

def update_external(external_id, body: {})
  data = client.request(
    http_method: "PATCH",
    path: "/v1/customers/external/{external_id}",
    path_params: { "external_id" => external_id },
    query: {},
    body: body,
    response_type: :json,
    errors: { 404 => Errors::ResourceNotFound, 422 => Errors::HTTPValidationError }
  )
  Unions::Customer.from_json(data)
end