Class: Nombaone::Resources::Customers

Inherits:
BaseResource show all
Defined in:
lib/nombaone/resources/customers.rb,
sig/nombaone/resources.rbs

Overview

Customers — the people and businesses you bill.

Examples:

customer = nombaone.customers.create(email: "ada@example.com", name: "Ada Lovelace")
customer.id # => "nbo…cus"

Instance Method Summary collapse

Methods inherited from BaseResource

#encode, #initialize, #request, #request_page

Constructor Details

This class inherits a constructor from Nombaone::Resources::BaseResource

Instance Method Details

#apply_discount(id, coupon:, request_options: {}) ⇒ NombaObject

Apply a coupon to a customer. The resulting discount shapes every future invoice for the customer until it ends or is removed.

Examples:

nombaone.customers.apply_discount(customer.id, coupon: "LAUNCH20")

Parameters:

  • id (String) —

    nbo…cus

  • coupon (String) —

    a coupon id (nbo…cpn) or its code (e.g. "LAUNCH20").

  • request_options (Hash) (defaults to: {})

Returns:

Raises:



92
93
94
95
 
# File 'lib/nombaone/resources/customers.rb', line 92

def apply_discount(id, coupon:, request_options: {})
  request(:post, "/customers/#{encode(id)}/discount",
          body: { coupon: coupon }, options: request_options)
end

#create(email:, name:, phone: OMIT, metadata: OMIT, request_options: {}) ⇒ NombaObject

Create a customer.

Examples:

customer = nombaone.customers.create(
  email: "ada@example.com",
  name: "Ada Lovelace",
  metadata: { crm_id: "crm_812" },
)

Parameters:

  • email (String) —

    unique per organization + environment (CUSTOMER_EMAIL_TAKEN on reuse).

  • name (String)
  • phone (String, nil) (defaults to: OMIT)
  • metadata (Hash) (defaults to: OMIT) —

    free-form annotations (keys are stored verbatim).

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

    per-call overrides (:idempotency_key, :headers, :timeout, :max_retries, :cancel_when).

Returns:

Raises:



30
31
32
33
34
 
# File 'lib/nombaone/resources/customers.rb', line 30

def create(email:, name:, phone: OMIT, metadata: OMIT, request_options: {})
  request(:post, "/customers",
          body: { email: email, name: name, phone: phone, metadata: metadata },
          options: request_options)
end

#grant_credit(id, amount_in_kobo:, source: OMIT, source_reference: OMIT, metadata: OMIT, request_options: {}) ⇒ NombaObject

Grant credit to a customer. Credit is drawn down oldest-grant-first by future invoices before any payment rail is charged.

This moves money-shaped state, so the API requires an Idempotency-Key; the SDK sends one automatically. Pass request_options[:idempotency_key] to keep the grant idempotent across process restarts.

Examples:

nombaone.customers.grant_credit(customer.id, amount_in_kobo: 250_000, source: "goodwill")

Parameters:

  • id (String) —

    nbo…cus

  • amount_in_kobo (Integer) —

    amount to grant, integer kobo (₦1.00 = 100). 250_000 is ₦2,500 — not ₦250,000. Multiply naira by 100 exactly once, at the edge of your system.

  • source (String) (defaults to: OMIT) —

    "manual" or "goodwill" (defaults to manual).

  • source_reference (String) (defaults to: OMIT) —

    your own reference (ticket, promo id, …).

  • metadata (Hash) (defaults to: OMIT)
  • request_options (Hash) (defaults to: {})

Returns:



125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/nombaone/resources/customers.rb', line 125

def grant_credit(id, amount_in_kobo:, source: OMIT, source_reference: OMIT,
                 metadata: OMIT, request_options: {})
  request(:post, "/customers/#{encode(id)}/credit",
          body: {
            amount_in_kobo: amount_in_kobo,
            source: source,
            source_reference: source_reference,
            metadata: metadata,
          },
          options: request_options)
end

#list(email: OMIT, limit: OMIT, cursor: OMIT, request_options: {}) ⇒ Page<NombaObject>

List customers, newest first.

Examples:

nombaone.customers.list.each { |customer| puts customer.email }

Parameters:

  • email (String) (defaults to: OMIT) —

    exact-match filter on email.

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

    page size, 1–100 (API default 20).

  • cursor (String) (defaults to: OMIT) —

    opaque cursor from a previous page's next_cursor.

  • request_options (Hash) (defaults to: {})

Returns:



74
75
76
77
78
 
# File 'lib/nombaone/resources/customers.rb', line 74

def list(email: OMIT, limit: OMIT, cursor: OMIT, request_options: {})
  request_page("/customers",
               query: { email: email, limit: limit, cursor: cursor },
               options: request_options)
end

#remove_discount(id, request_options: {}) ⇒ NombaObject

Remove the customer's active discount. Returns the ended discount.

Parameters:

  • id (String) —

    nbo…cus

  • request_options (Hash) (defaults to: {})

Returns:



102
103
104
 
# File 'lib/nombaone/resources/customers.rb', line 102

def remove_discount(id, request_options: {})
  request(:delete, "/customers/#{encode(id)}/discount", options: request_options)
end

#retrieve(id, request_options: {}) ⇒ NombaObject

Retrieve a customer by id.

Parameters:

  • id (String) —

    nbo…cus

  • request_options (Hash) (defaults to: {})
  • request_options: (Nombaone::request_options) (defaults to: {})

Returns:

Raises:

  • (Nombaone::NotFoundError) —

    404 CUSTOMER_NOT_FOUND — check the id and that your key matches the environment the customer was created in.



43
44
45
 
# File 'lib/nombaone/resources/customers.rb', line 43

def retrieve(id, request_options: {})
  request(:get, "/customers/#{encode(id)}", options: request_options)
end

#retrieve_credit_balance(id, request_options: {}) ⇒ NombaObject

Retrieve the customer's credit balance and the grants behind it.

Parameters:

  • id (String) —

    nbo…cus

  • request_options (Hash) (defaults to: {})
  • request_options: (Nombaone::request_options) (defaults to: {})

Returns:



142
143
144
 
# File 'lib/nombaone/resources/customers.rb', line 142

def retrieve_credit_balance(id, request_options: {})
  request(:get, "/customers/#{encode(id)}/credit", options: request_options)
end

#update(id, name: OMIT, phone: OMIT, metadata: OMIT, request_options: {}) ⇒ NombaObject

Update a customer's mutable fields. At least one field is required.

Examples:

nombaone.customers.update(customer.id, phone: "+2348012345678")

Parameters:

  • id (String) —

    nbo…cus

  • name (String) (defaults to: OMIT)
  • phone (String, nil) (defaults to: OMIT) —

    pass nil to clear the phone number.

  • metadata (Hash) (defaults to: OMIT)
  • request_options (Hash) (defaults to: {})

Returns:



58
59
60
61
62
 
# File 'lib/nombaone/resources/customers.rb', line 58

def update(id, name: OMIT, phone: OMIT, metadata: OMIT, request_options: {})
  request(:patch, "/customers/#{encode(id)}",
          body: { name: name, phone: phone, metadata: metadata },
          options: request_options)
end

#void_credit(id, grant_id, request_options: {}) ⇒ NombaObject

Void a credit grant — its remaining balance becomes unusable. Consumed credit is untouched.

Parameters:

  • id (String) —

    nbo…cus

  • grant_id (String) —

    nbo…crg

  • request_options (Hash) (defaults to: {})
  • request_options: (Nombaone::request_options) (defaults to: {})

Returns:

Raises:



154
155
156
157
 
# File 'lib/nombaone/resources/customers.rb', line 154

def void_credit(id, grant_id, request_options: {})
  request(:delete, "/customers/#{encode(id)}/credit/#{encode(grant_id)}",
          options: request_options)
end