Nombaone.
View Source
Customers — the people and businesses you bill.
Every function takes the client first and returns {:ok, result} or
{:error, %Nombaone.Error{}}. Each also has a raising ! variant (for
example create!/3) that returns the value directly and raises on error.
client = Nombaone.new()
{:ok, customer} =
Nombaone.Customers.create(client, %{email: "ada@example.com", name: "Ada Lovelace"})Summary
Functions
Apply a coupon to a customer. The resulting discount shapes every future
invoice for the customer until it ends or is removed. :coupon is a coupon
id (nbo…cpn) or its code (e.g. "LAUNCH20").
Raising variant of apply_discount/4.
Create a customer.
Raising variant of create/3.
Grant credit to a customer. Credit is drawn down oldest-grant-first by future invoices before any payment rail is charged.
Raising variant of grant_credit/4.
List customers, newest first. Optional filters: :email (exact match),
:limit (1–100, default 20), :cursor.
Raising variant of list/3.
Remove the customer's active discount. Returns the ended discount.
Raising variant of remove_discount/3.
Retrieve a customer by id.
Raising variant of retrieve/3.
Retrieve the customer's credit balance and the grants behind it.
Raising variant of retrieve_credit_balance/3.
Update a customer's mutable fields. At least one field is required. Pass
phone: nil to clear the phone number.
Raising variant of update/4.
Void a credit grant — its remaining balance becomes unusable. Consumed credit is untouched.
Raising variant of void_credit/4.
Functions
@spec apply_discount(Nombaone.Client.t(), String.t(), map(), keyword()) :: {:ok, Nombaone.Discount.t()} | {:error, Nombaone.Error.t()}
Apply a coupon to a customer. The resulting discount shapes every future
invoice for the customer until it ends or is removed. :coupon is a coupon
id (nbo…cpn) or its code (e.g. "LAUNCH20").
Common errors: 404 COUPON_NOT_FOUND, 409 COUPON_ALREADY_APPLIED.
Example
{:ok, discount} = Nombaone.Customers.apply_discount(client, id, %{coupon: "LAUNCH20"})@spec apply_discount!(Nombaone.Client.t(), String.t(), map(), keyword()) :: Nombaone.Discount.t()
Raising variant of apply_discount/4.
@spec create(Nombaone.Client.t(), map(), keyword()) :: {:ok, Nombaone.Customer.t()} | {:error, Nombaone.Error.t()}
Create a customer.
Common errors: 422 CLIENT_VALIDATION_FAILED (see error.fields),
409 CUSTOMER_EMAIL_TAKEN (reuse the existing customer instead).
Example
{:ok, customer} =
Nombaone.Customers.create(client, %{
email: "ada@example.com",
name: "Ada Lovelace",
metadata: %{crm_id: "crm_812"}
})
customer.id # => "nbo…cus"@spec create!(Nombaone.Client.t(), map(), keyword()) :: Nombaone.Customer.t()
Raising variant of create/3.
@spec grant_credit(Nombaone.Client.t(), String.t(), map(), keyword()) :: {:ok, Nombaone.CreditGrant.t()} | {:error, Nombaone.Error.t()}
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 SDK sends an Idempotency-Key
automatically. Pass idempotency_key: in opts to control it across process
restarts.
Money is integer kobo
amount_in_kobo is integer kobo — 250_000 is ₦2,500.00, not ₦250,000.
Multiply naira by 100 exactly once, at the edge of your system.
Example
{:ok, grant} =
Nombaone.Customers.grant_credit(client, id, %{
amount_in_kobo: 250_000,
source: "goodwill"
})@spec grant_credit!(Nombaone.Client.t(), String.t(), map(), keyword()) :: Nombaone.CreditGrant.t()
Raising variant of grant_credit/4.
@spec list(Nombaone.Client.t(), map(), keyword()) :: {:ok, Nombaone.Page.t()} | {:error, Nombaone.Error.t()}
List customers, newest first. Optional filters: :email (exact match),
:limit (1–100, default 20), :cursor.
The returned Nombaone.Page iterates every customer across every page:
{:ok, page} = Nombaone.Customers.list(client, %{limit: 50})
for customer <- page do
IO.puts(customer.email) # pages fetched for you
end@spec list!(Nombaone.Client.t(), map(), keyword()) :: Nombaone.Page.t()
Raising variant of list/3.
@spec remove_discount(Nombaone.Client.t(), String.t(), keyword()) :: {:ok, Nombaone.Discount.t()} | {:error, Nombaone.Error.t()}
Remove the customer's active discount. Returns the ended discount.
@spec remove_discount!(Nombaone.Client.t(), String.t(), keyword()) :: Nombaone.Discount.t()
Raising variant of remove_discount/3.
@spec retrieve(Nombaone.Client.t(), String.t(), keyword()) :: {:ok, Nombaone.Customer.t()} | {:error, Nombaone.Error.t()}
Retrieve a customer by id.
Common errors: 404 CUSTOMER_NOT_FOUND — check the id, and that your key
matches the environment the customer was created in.
Example
{:ok, customer} = Nombaone.Customers.retrieve(client, "nbo123456789012cus")@spec retrieve!(Nombaone.Client.t(), String.t(), keyword()) :: Nombaone.Customer.t()
Raising variant of retrieve/3.
@spec retrieve_credit_balance(Nombaone.Client.t(), String.t(), keyword()) :: {:ok, Nombaone.CreditBalance.t()} | {:error, Nombaone.Error.t()}
Retrieve the customer's credit balance and the grants behind it.
@spec retrieve_credit_balance!(Nombaone.Client.t(), String.t(), keyword()) :: Nombaone.CreditBalance.t()
Raising variant of retrieve_credit_balance/3.
@spec update(Nombaone.Client.t(), String.t(), map(), keyword()) :: {:ok, Nombaone.Customer.t()} | {:error, Nombaone.Error.t()}
Update a customer's mutable fields. At least one field is required. Pass
phone: nil to clear the phone number.
Example
{:ok, customer} = Nombaone.Customers.update(client, id, %{phone: "+2348012345678"})@spec update!(Nombaone.Client.t(), String.t(), map(), keyword()) :: Nombaone.Customer.t()
Raising variant of update/4.
@spec void_credit(Nombaone.Client.t(), String.t(), String.t(), keyword()) :: {:ok, Nombaone.CreditGrant.t()} | {:error, Nombaone.Error.t()}
Void a credit grant — its remaining balance becomes unusable. Consumed credit is untouched.
Common errors: 409 CREDIT_GRANT_ALREADY_VOIDED.
@spec void_credit!(Nombaone.Client.t(), String.t(), String.t(), keyword()) :: Nombaone.CreditGrant.t()
Raising variant of void_credit/4.