Class: Stigg::Resources::V1::Customers

Inherits:
Object
  • Object
show all
Defined in:
lib/stigg/resources/v1/customers.rb,
lib/stigg/resources/v1/customers/integrations.rb,
lib/stigg/resources/v1/customers/payment_method.rb,
lib/stigg/resources/v1/customers/promotional_entitlements.rb,
sig/stigg/resources/v1/customers.rbs,
sig/stigg/resources/v1/customers/integrations.rbs,
sig/stigg/resources/v1/customers/payment_method.rbs,
sig/stigg/resources/v1/customers/promotional_entitlements.rbs

Defined Under Namespace

Classes: Integrations, PaymentMethod, PromotionalEntitlements

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Customers

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Customers.

Parameters:



559
560
561
562
563
564
 
# File 'lib/stigg/resources/v1/customers.rb', line 559

def initialize(client:)
  @client = client
  @payment_method = Stigg::Resources::V1::Customers::PaymentMethod.new(client: client)
  @promotional_entitlements = Stigg::Resources::V1::Customers::PromotionalEntitlements.new(client: client)
  @integrations = Stigg::Resources::V1::Customers::Integrations.new(client: client)
end

Instance Attribute Details

#integrations ⇒ Stigg::Resources::V1::Customers::Integrations (readonly)

Returns:



16
17
18
 
# File 'lib/stigg/resources/v1/customers.rb', line 16

def integrations
  @integrations
end

#payment_method ⇒ Stigg::Resources::V1::Customers::PaymentMethod (readonly)

Operations related to customers

Returns:



9
10
11
 
# File 'lib/stigg/resources/v1/customers.rb', line 9

def payment_method
  @payment_method
end

#promotional_entitlements ⇒ Stigg::Resources::V1::Customers::PromotionalEntitlements (readonly)

Operations related to promotional entitlements

Returns:



13
14
15
 
# File 'lib/stigg/resources/v1/customers.rb', line 13

def promotional_entitlements
  @promotional_entitlements
end

Instance Method Details

#archive(id, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Models::V1::CustomerResponse

Some parameter documentations has been truncated, see Models::V1::CustomerArchiveParams for more details.

Archives a customer, preventing new subscriptions. Optionally cancels existing subscriptions.

Parameters:

  • id (String) —

    The unique identifier of the entity

  • x_account_id (String) —

    Account ID — optional when authenticating with a user JWT (Bearer token); falls

  • x_environment_id (String) —

    Environment ID — required when authenticating with a user JWT (Bearer token) on

  • request_options (Stigg::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/stigg/resources/v1/customers.rb', line 168

def archive(id, params = {})
  parsed, options = Stigg::V1::CustomerArchiveParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["api/v1/customers/%1$s/archive", id],
    headers: parsed.transform_keys(
      x_account_id: "x-account-id",
      x_environment_id: "x-environment-id"
    ),
    model: Stigg::V1::CustomerResponse,
    options: options
  )
end

#check_entitlement(id, currency_id: nil, feature_id: nil, requested_usage: nil, requested_values: nil, resource_id: nil, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Models::V1::CustomerCheckEntitlementResponse

Some parameter documentations has been truncated, see Models::V1::CustomerCheckEntitlementParams for more details.

Checks a single entitlement (feature or credit) for a customer or resource. Supports requestedUsage and requestedValues to evaluate against limits or enum values.

Warning: This REST API endpoint lacks built-in client-side caching, fallback mechanisms, and low-latency guarantees. It is not recommended for hot-path entitlement checks. For production use, consider using the Stigg Node Server SDK with caching or the Sidecar for low-latency cached responses.

Parameters:

  • id (String) —

    Path param: The unique identifier of the entity

  • currency_id (String) —

    Query param: Currency ID (refId) to check for credit entitlements. Mutually excl

  • feature_id (String) —

    Query param: Feature ID (refId) to check. Mutually exclusive with currencyId.

  • requested_usage (Integer) —

    Query param: Requested usage amount to evaluate against the entitlement limit (n

  • requested_values (Array<String>) —

    Query param: Requested values to evaluate against allowed values (enum features

  • resource_id (String) —

    Query param: Resource ID to scope the entitlement check to a specific resource

  • x_account_id (String) —

    Header param: Account ID — optional when authenticating with a user JWT (Bearer

  • x_environment_id (String) —

    Header param: Environment ID — required when authenticating with a user JWT (Bea

  • request_options (Stigg::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
 
# File 'lib/stigg/resources/v1/customers.rb', line 217

def check_entitlement(id, params = {})
  query_params = [:currency_id, :feature_id, :requested_usage, :requested_values, :resource_id]
  parsed, options = Stigg::V1::CustomerCheckEntitlementParams.dump_request(params)
  query = Stigg::Internal::Util.encode_query_params(parsed.slice(*query_params))
  @client.request(
    method: :get,
    path: ["api/v1/customers/%1$s/entitlements/check", id],
    query: query.transform_keys(
      currency_id: "currencyId",
      feature_id: "featureId",
      requested_usage: "requestedUsage",
      requested_values: "requestedValues",
      resource_id: "resourceId"
    ),
    headers: parsed.except(*query_params).transform_keys(
      x_account_id: "x-account-id",
      x_environment_id: "x-environment-id"
    ),
    model: Stigg::Models::V1::CustomerCheckEntitlementResponse,
    options: options
  )
end

#import(customers:, integration_id: nil, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Models::V1::CustomerImportResponse

Some parameter documentations has been truncated, see Models::V1::CustomerImportParams for more details.

Imports multiple customers in bulk. Used for migrating customer data from external systems.

Parameters:

  • customers (Array<Stigg::Models::V1::CustomerImportParams::Customer>) —

    Body param: List of customer objects to import

  • integration_id (String) —

    Body param: Integration details

  • x_account_id (String) —

    Header param: Account ID — optional when authenticating with a user JWT (Bearer

  • x_environment_id (String) —

    Header param: Environment ID — required when authenticating with a user JWT (Bea

  • request_options (Stigg::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



261
262
263
264
265
266
267
268
269
270
271
272
 
# File 'lib/stigg/resources/v1/customers.rb', line 261

def import(params)
  parsed, options = Stigg::V1::CustomerImportParams.dump_request(params)
  header_params = {x_account_id: "x-account-id", x_environment_id: "x-environment-id"}
  @client.request(
    method: :post,
    path: "api/v1/customers/import",
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Stigg::Models::V1::CustomerImportResponse,
    options: options
  )
end

#list(after: nil, before: nil, created_at: nil, email: nil, limit: nil, name: nil, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Internal::MyCursorIDPage<Stigg::Models::V1::CustomerListResponse>

Some parameter documentations has been truncated, see Models::V1::CustomerListParams for more details.

Retrieves a paginated list of customers in the environment.

Parameters:

  • after (String) —

    Query param: Return items that come after this cursor

  • before (String) —

    Query param: Return items that come before this cursor

  • created_at (Stigg::Models::V1::CustomerListParams::CreatedAt) —

    Query param: Filter by creation date using range operators: gt, gte, lt, lte

  • email (String) —

    Query param: Filter by exact customer email address

  • limit (Integer) —

    Query param: Maximum number of items to return

  • name (String) —

    Query param: Filter by exact customer name

  • x_account_id (String) —

    Header param: Account ID — optional when authenticating with a user JWT (Bearer

  • x_environment_id (String) —

    Header param: Environment ID — required when authenticating with a user JWT (Bea

  • request_options (Stigg::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/stigg/resources/v1/customers.rb', line 131

def list(params = {})
  query_params = [:after, :before, :created_at, :email, :limit, :name]
  parsed, options = Stigg::V1::CustomerListParams.dump_request(params)
  query = Stigg::Internal::Util.encode_query_params(parsed.slice(*query_params))
  @client.request(
    method: :get,
    path: "api/v1/customers",
    query: query.transform_keys(created_at: "createdAt"),
    headers: parsed.except(*query_params).transform_keys(
      x_account_id: "x-account-id",
      x_environment_id: "x-environment-id"
    ),
    page: Stigg::Internal::MyCursorIDPage,
    model: Stigg::Models::V1::CustomerListResponse,
    options: options
  )
end

#list_contracts(id, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Models::V1::CustomerListContractsResponse

Some parameter documentations has been truncated, see Models::V1::CustomerListContractsParams for more details.

Retrieves a customer's contracts, fetched live from the connected billing provider, each enriched with a preview of its upcoming (next) invoice when available. Returns an empty list when no billing provider is connected or the customer is not synced.

Parameters:

  • id (String) —

    The external identifier of the customer the contract belongs to

  • x_account_id (String) —

    Account ID — optional when authenticating with a user JWT (Bearer token); falls

  • x_environment_id (String) —

    Environment ID — required when authenticating with a user JWT (Bearer token) on

  • request_options (Stigg::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



295
296
297
298
299
300
301
302
303
304
305
306
307
 
# File 'lib/stigg/resources/v1/customers.rb', line 295

def list_contracts(id, params = {})
  parsed, options = Stigg::V1::CustomerListContractsParams.dump_request(params)
  @client.request(
    method: :get,
    path: ["api/v1/customers/%1$s/contracts", id],
    headers: parsed.transform_keys(
      x_account_id: "x-account-id",
      x_environment_id: "x-environment-id"
    ),
    model: Stigg::Models::V1::CustomerListContractsResponse,
    options: options
  )
end

#list_invoices(id, after: nil, before: nil, contract_external_id: nil, issued_after: nil, issued_before: nil, limit: nil, order_by: nil, order_dir: nil, state_in: nil, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Internal::MyCursorIDPage<Stigg::Models::V1::CustomerListInvoicesResponse>

Some parameter documentations has been truncated, see Models::V1::CustomerListInvoicesParams for more details.

Retrieves a cursor-paginated list of a customer's invoices, fetched live from the connected billing provider. Ordered by issue date ascending by default; override with orderBy (issueDate | dueDate | total) and orderDir (ASC | DESC). Optionally narrowed to one contract, an issue-date range, and/or a set of invoice states. Returns an empty list when no billing provider is connected or the customer is not synced.

Parameters:

  • id (String) —

    Path param: External ID of the customer the invoice belongs to: your customer re

  • after (String) —

    Query param: Return items that come after this cursor

  • before (String) —

    Query param: Return items that come before this cursor

  • contract_external_id (String) —

    Query param: Filter to invoices for this contract only (contract external ID or

  • issued_after (Time) —

    Query param: Filter to invoices issued on or after this date, inclusive (ISO 860

  • issued_before (Time) —

    Query param: Filter to invoices issued on or before this date, inclusive (ISO 86

  • limit (Integer) —

    Query param: Maximum number of items to return

  • order_by (Symbol, Stigg::Models::V1::CustomerListInvoicesParams::OrderBy) —

    Query param: Field to sort by: issueDate (default), dueDate, or total

  • order_dir (Symbol, Stigg::Models::V1::CustomerListInvoicesParams::OrderDir) —

    Query param: Sort direction: ASC (default) or DESC

  • state_in (String) —

    Query param: Filter by invoice state. Supports comma-separated values for multip

  • x_account_id (String) —

    Header param: Account ID — optional when authenticating with a user JWT (Bearer

  • x_environment_id (String) —

    Header param: Environment ID — required when authenticating with a user JWT (Bea

  • request_options (Stigg::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
 
# File 'lib/stigg/resources/v1/customers.rb', line 350

def list_invoices(id, params = {})
  query_params =
    [
      :after,
      :before,
      :contract_external_id,
      :issued_after,
      :issued_before,
      :limit,
      :order_by,
      :order_dir,
      :state_in
    ]
  parsed, options = Stigg::V1::CustomerListInvoicesParams.dump_request(params)
  query = Stigg::Internal::Util.encode_query_params(parsed.slice(*query_params))
  @client.request(
    method: :get,
    path: ["api/v1/customers/%1$s/invoices", id],
    query: query.transform_keys(
      contract_external_id: "contractExternalId",
      issued_after: "issuedAfter",
      issued_before: "issuedBefore",
      order_by: "orderBy",
      order_dir: "orderDir",
      state_in: "stateIn"
    ),
    headers: parsed.except(*query_params).transform_keys(
      x_account_id: "x-account-id",
      x_environment_id: "x-environment-id"
    ),
    page: Stigg::Internal::MyCursorIDPage,
    model: Stigg::Models::V1::CustomerListInvoicesResponse,
    options: options
  )
end

#list_resources(id, after: nil, before: nil, limit: nil, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Internal::MyCursorIDPage<Stigg::Models::V1::CustomerListResourcesResponse>

Some parameter documentations has been truncated, see Models::V1::CustomerListResourcesParams for more details.

Retrieves a paginated list of resources within the same customer.

Parameters:

  • id (String) —

    Path param: The unique identifier of the entity

  • after (String) —

    Query param: Return items that come after this cursor

  • before (String) —

    Query param: Return items that come before this cursor

  • limit (Integer) —

    Query param: Maximum number of items to return

  • x_account_id (String) —

    Header param: Account ID — optional when authenticating with a user JWT (Bearer

  • x_environment_id (String) —

    Header param: Environment ID — required when authenticating with a user JWT (Bea

  • request_options (Stigg::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
 
# File 'lib/stigg/resources/v1/customers.rb', line 410

def list_resources(id, params = {})
  query_params = [:after, :before, :limit]
  parsed, options = Stigg::V1::CustomerListResourcesParams.dump_request(params)
  query = Stigg::Internal::Util.encode_query_params(parsed.slice(*query_params))
  @client.request(
    method: :get,
    path: ["api/v1/customers/%1$s/resources", id],
    query: query,
    headers: parsed.except(*query_params).transform_keys(
      x_account_id: "x-account-id",
      x_environment_id: "x-environment-id"
    ),
    page: Stigg::Internal::MyCursorIDPage,
    model: Stigg::Models::V1::CustomerListResourcesResponse,
    options: options
  )
end

#provision(id:, billing_currency: nil, billing_id: nil, coupon_id: nil, default_payment_method: nil, email: nil, integrations: nil, language: nil, metadata: nil, name: nil, passthrough: nil, timezone: nil, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Models::V1::CustomerResponse

Some parameter documentations has been truncated, see Models::V1::CustomerProvisionParams for more details.

Creates a new customer.

Parameters:

Returns:

See Also:



468
469
470
471
472
473
474
475
476
477
478
479
 
# File 'lib/stigg/resources/v1/customers.rb', line 468

def provision(params)
  parsed, options = Stigg::V1::CustomerProvisionParams.dump_request(params)
  header_params = {x_account_id: "x-account-id", x_environment_id: "x-environment-id"}
  @client.request(
    method: :post,
    path: "api/v1/customers",
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Stigg::V1::CustomerResponse,
    options: options
  )
end

#retrieve(id, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Models::V1::CustomerResponse

Some parameter documentations has been truncated, see Models::V1::CustomerRetrieveParams for more details.

Retrieves a customer by their unique identifier, including billing information and subscription status.

Parameters:

  • id (String) —

    The unique identifier of the entity

  • x_account_id (String) —

    Account ID — optional when authenticating with a user JWT (Bearer token); falls

  • x_environment_id (String) —

    Environment ID — required when authenticating with a user JWT (Bearer token) on

  • request_options (Stigg::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/stigg/resources/v1/customers.rb', line 37

def retrieve(id, params = {})
  parsed, options = Stigg::V1::CustomerRetrieveParams.dump_request(params)
  @client.request(
    method: :get,
    path: ["api/v1/customers/%1$s", id],
    headers: parsed.transform_keys(
      x_account_id: "x-account-id",
      x_environment_id: "x-environment-id"
    ),
    model: Stigg::V1::CustomerResponse,
    options: options
  )
end

#retrieve_entitlements(id, resource_id: nil, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Models::V1::CustomerRetrieveEntitlementsResponse

Some parameter documentations has been truncated, see Models::V1::CustomerRetrieveEntitlementsParams for more details.

Retrieves the effective entitlements for a customer or resource, including feature and credit entitlements.

Warning: This REST API endpoint lacks built-in client-side caching, fallback mechanisms, and low-latency guarantees. It is not recommended for hot-path entitlement checks. For production use, consider using the Stigg Node Server SDK with caching or the Sidecar for low-latency cached responses.

Parameters:

  • id (String) —

    Path param: The unique identifier of the entity

  • resource_id (String) —

    Query param: Resource ID to scope entitlements to a specific resource

  • x_account_id (String) —

    Header param: Account ID — optional when authenticating with a user JWT (Bearer

  • x_environment_id (String) —

    Header param: Environment ID — required when authenticating with a user JWT (Bea

  • request_options (Stigg::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
 
# File 'lib/stigg/resources/v1/customers.rb', line 507

def retrieve_entitlements(id, params = {})
  query_params = [:resource_id]
  parsed, options = Stigg::V1::CustomerRetrieveEntitlementsParams.dump_request(params)
  query = Stigg::Internal::Util.encode_query_params(parsed.slice(*query_params))
  @client.request(
    method: :get,
    path: ["api/v1/customers/%1$s/entitlements", id],
    query: query.transform_keys(resource_id: "resourceId"),
    headers: parsed.except(*query_params).transform_keys(
      x_account_id: "x-account-id",
      x_environment_id: "x-environment-id"
    ),
    model: Stigg::Models::V1::CustomerRetrieveEntitlementsResponse,
    options: options
  )
end

#unarchive(id, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Models::V1::CustomerResponse

Some parameter documentations has been truncated, see Models::V1::CustomerUnarchiveParams for more details.

Restores an archived customer, allowing them to create new subscriptions again.

Parameters:

  • id (String) —

    The unique identifier of the entity

  • x_account_id (String) —

    Account ID — optional when authenticating with a user JWT (Bearer token); falls

  • x_environment_id (String) —

    Environment ID — required when authenticating with a user JWT (Bearer token) on

  • request_options (Stigg::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



542
543
544
545
546
547
548
549
550
551
552
553
554
 
# File 'lib/stigg/resources/v1/customers.rb', line 542

def unarchive(id, params = {})
  parsed, options = Stigg::V1::CustomerUnarchiveParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["api/v1/customers/%1$s/unarchive", id],
    headers: parsed.transform_keys(
      x_account_id: "x-account-id",
      x_environment_id: "x-environment-id"
    ),
    model: Stigg::V1::CustomerResponse,
    options: options
  )
end

#update(id, billing_currency: nil, billing_id: nil, coupon_id: nil, email: nil, integrations: nil, language: nil, metadata: nil, name: nil, passthrough: nil, timezone: nil, x_account_id: nil, x_environment_id: nil, request_options: {}) ⇒ Stigg::Models::V1::CustomerResponse

Some parameter documentations has been truncated, see Models::V1::CustomerUpdateParams for more details.

Updates an existing customer's properties such as name, email, and billing information.

Parameters:

  • id (String) —

    Path param: The unique identifier of the entity

  • billing_currency (Symbol, Stigg::Models::V1::CustomerUpdateParams::BillingCurrency, nil) —

    Body param: The billing currency of the customer

  • billing_id (String, nil) —

    Body param: The unique identifier for the entity in the billing provider

  • coupon_id (String, Symbol, Stigg::Models::V1::CustomerUpdateParams::CouponID, nil) —

    Body param: Customer level coupon

  • email (String, nil) —

    Body param: The email of the customer

  • integrations (Array<Stigg::Models::V1::CustomerUpdateParams::Integration>) —

    Body param: List of integrations

  • language (String, nil) —

    Body param: Language to use for this customer

  • metadata (Hash{Symbol=>String}) —

    Body param: Additional metadata

  • name (String, nil) —

    Body param: The name of the customer

  • passthrough (Stigg::Models::V1::CustomerUpdateParams::Passthrough) —

    Body param: Vendor-specific billing passthrough fields.

  • timezone (String, nil) —

    Body param: Timezone to use for this customer

  • x_account_id (String) —

    Header param: Account ID — optional when authenticating with a user JWT (Bearer

  • x_environment_id (String) —

    Header param: Environment ID — required when authenticating with a user JWT (Bea

  • request_options (Stigg::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/stigg/resources/v1/customers.rb', line 90

def update(id, params = {})
  parsed, options = Stigg::V1::CustomerUpdateParams.dump_request(params)
  header_params = {x_account_id: "x-account-id", x_environment_id: "x-environment-id"}
  @client.request(
    method: :patch,
    path: ["api/v1/customers/%1$s", id],
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Stigg::V1::CustomerResponse,
    options: options
  )
end