Class: Pago::V2026_04::Services::Subscriptions

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

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: {}) ⇒ Models::Subscription

Create a subscription programmatically.

This endpoint only allows to create subscription on free products. For paid products, use the checkout flow.

No initial order will be created and no confirmation email will be sent.

Scopes: subscriptions:write

Parameters:

Returns:

Raises:



65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/pago/v2026_04/services/subscriptions.rb', line 65

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

#export(organization_id: nil) ⇒ String

Export subscriptions as a CSV file.

Scopes: subscriptions:read subscriptions:write

Parameters:

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

    Filter by organization ID.

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

Returns:

  • (String)

Raises:



86
87
88
89
90
91
92
93
94
95
 
# File 'lib/pago/v2026_04/services/subscriptions.rb', line 86

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

#get(id) ⇒ Models::Subscription

Get a subscription by ID.

Scopes: subscriptions:read subscriptions:write

Parameters:

  • id (String) —

    The subscription ID.

Returns:

Raises:



106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/pago/v2026_04/services/subscriptions.rb', line 106

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

#list(organization_id: nil, product_id: nil, customer_id: nil, external_customer_id: nil, discount_id: nil, active: nil, status: nil, cancel_at_period_end: nil, customer_cancellation_reason: nil, canceled_at_after: nil, canceled_at_before: nil, page: 1, limit: 10, sorting: ["-started_at"], metadata: nil) ⇒ Models::ListResourceSubscription

List subscriptions.

Scopes: subscriptions:read subscriptions:write

Parameters:

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

    Filter by organization ID.

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

    Filter by product ID.

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

    Filter by customer ID.

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

    Filter by customer external ID.

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

    Filter by discount ID.

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

    Filter by active or inactive subscription.

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

    Filter by subscription status.

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

    Filter by subscriptions that are set to cancel at period end.

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

    Filter by customer cancellation reason.

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

    Filter by cancellation date (after or equal to).

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

    Filter by cancellation date (before or equal to).

  • 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: ["-started_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)
  • product_id: (Object) (defaults to: nil)
  • customer_id: (Object) (defaults to: nil)
  • external_customer_id: (Object) (defaults to: nil)
  • discount_id: (Object) (defaults to: nil)
  • active: (Boolean, nil) (defaults to: nil)
  • status: (Object) (defaults to: nil)
  • cancel_at_period_end: (Boolean, nil) (defaults to: nil)
  • customer_cancellation_reason: (Object) (defaults to: nil)
  • canceled_at_after: (String, nil) (defaults to: nil)
  • canceled_at_before: (String, nil) (defaults to: nil)
  • page: (Integer, nil) (defaults to: 1)
  • limit: (Integer, nil) (defaults to: 10)
  • sorting: (Array[String], nil) (defaults to: ["-started_at"])
  • metadata: (Object) (defaults to: nil)

Returns:

Raises:



29
30
31
32
33
34
35
36
37
38
39
 
# File 'lib/pago/v2026_04/services/subscriptions.rb', line 29

def list(organization_id: nil, product_id: nil, customer_id: nil, external_customer_id: nil, discount_id: nil, active: nil, status: nil, cancel_at_period_end: nil, customer_cancellation_reason: nil, canceled_at_after: nil, canceled_at_before: nil, page: 1, limit: 10, sorting: ["-started_at"], metadata: nil)
  data = client.request(
    http_method: "GET",
    path: "/v1/subscriptions/",
    path_params: {},
    query: { "organization_id" => organization_id, "product_id" => product_id, "customer_id" => customer_id, "external_customer_id" => external_customer_id, "discount_id" => discount_id, "active" => active, "status" => status, "cancel_at_period_end" => cancel_at_period_end, "customer_cancellation_reason" => customer_cancellation_reason, "canceled_at_after" => canceled_at_after, "canceled_at_before" => canceled_at_before, "page" => page, "limit" => limit, "sorting" => sorting, "metadata" => metadata },
    response_type: :json,
    errors: { 422 => Errors::HTTPValidationError }
  )
  Models::ListResourceSubscription.from_json(data)
end

#list_each(organization_id: nil, product_id: nil, customer_id: nil, external_customer_id: nil, discount_id: nil, active: nil, status: nil, cancel_at_period_end: nil, customer_cancellation_reason: nil, canceled_at_after: nil, canceled_at_before: nil, limit: 10, sorting: ["-started_at"], metadata: nil) {|item| ... } ⇒ Pago::Paginator

Enumerate every item of list, fetching pages on demand.

Parameters:

  • organization_id: (Object) (defaults to: nil)
  • product_id: (Object) (defaults to: nil)
  • customer_id: (Object) (defaults to: nil)
  • external_customer_id: (Object) (defaults to: nil)
  • discount_id: (Object) (defaults to: nil)
  • active: (Boolean, nil) (defaults to: nil)
  • status: (Object) (defaults to: nil)
  • cancel_at_period_end: (Boolean, nil) (defaults to: nil)
  • customer_cancellation_reason: (Object) (defaults to: nil)
  • canceled_at_after: (String, nil) (defaults to: nil)
  • canceled_at_before: (String, nil) (defaults to: nil)
  • limit: (Integer, nil) (defaults to: 10)
  • sorting: (Array[String], nil) (defaults to: ["-started_at"])
  • metadata: (Object) (defaults to: nil)

Yield Parameters:

Returns:



45
46
47
48
49
50
 
# File 'lib/pago/v2026_04/services/subscriptions.rb', line 45

def list_each(organization_id: nil, product_id: nil, customer_id: nil, external_customer_id: nil, discount_id: nil, active: nil, status: nil, cancel_at_period_end: nil, customer_cancellation_reason: nil, canceled_at_after: nil, canceled_at_before: nil, limit: 10, sorting: ["-started_at"], metadata: nil, &block)
  paginator = ::Pago::Paginator.new do |page_number|
    list(organization_id: organization_id, product_id: product_id, customer_id: customer_id, external_customer_id: external_customer_id, discount_id: discount_id, active: active, status: status, cancel_at_period_end: cancel_at_period_end, customer_cancellation_reason: customer_cancellation_reason, canceled_at_after: canceled_at_after, canceled_at_before: canceled_at_before, page: page_number, limit: limit, sorting: sorting, metadata: metadata)
  end
  block ? paginator.each(&block) : paginator
end

#revoke(id) ⇒ Models::Subscription

Revoke a subscription, i.e cancel immediately.

Scopes: subscriptions:write

Parameters:

  • id (String) —

    The subscription ID.

Returns:

Raises:



129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/pago/v2026_04/services/subscriptions.rb', line 129

def revoke(id)
  data = client.request(
    http_method: "DELETE",
    path: "/v1/subscriptions/{id}",
    path_params: { "id" => id },
    query: {},
    response_type: :json,
    errors: { 403 => Errors::AlreadyCanceledSubscription, 404 => Errors::ResourceNotFound, 409 => Errors::SubscriptionLocked, 422 => Errors::HTTPValidationError }
  )
  Models::Subscription.from_json(data)
end

#update(id, body: {}) ⇒ Models::Subscription

Update a subscription.

Scopes: subscriptions:write

Parameters:

  • id (String) —

    The subscription ID.

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

    the request body.

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

Returns:

Raises:



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

def update(id, body: {})
  data = client.request(
    http_method: "PATCH",
    path: "/v1/subscriptions/{id}",
    path_params: { "id" => id },
    query: {},
    body: body,
    response_type: :json,
    errors: { 402 => Errors::PaymentFailed, 403 => Errors::AlreadyCanceledSubscription, 404 => Errors::ResourceNotFound, 409 => Errors::SubscriptionLocked, 422 => Errors::HTTPValidationError }
  )
  Models::Subscription.from_json(data)
end