Chargebeex

Chargebeex is an Elixir implementation of Chargebee API.

This is a heavily inspired fork of the original work by Nicolas Marlier

Project status

Chargebeex is used for several months in production at Welcome to the Jungle.

Installation

The package can be installed by adding chargebeex to your list of dependencies in mix.exs:

# mix.exs
def deps do
  [
    {:chargebeex, "~> 0.6.0"}
  ]
end

Configuration

Chargebeex can be configured using Config or environment variables.

Config

config :chargebeex,
  namespace: "my-namespace",
  api_key: "my-api-key"

Environment variables

export CHARGEBEEX_API_KEY=my-api-key
export CHARGEBEEX_NAMESPACE=my-namespace

Usage

{:ok, %Chargebeex.Customer{}} = Chargebeex.Customer.retrieve("foobar")
{:ok, [%Chargebeex.Customer{}], [%Chargebeex.Customer{}]} = Chargebeex.Customer.list()
{:ok, %Chargebeex.Customer{}} = Chargebeex.Customer.update("foobar", %{name: "updated"})
{:ok, %Chargebeex.Customer{}} = Chargebeex.Customer.delete("foobar")

Custom Fields

Chargebee provides a way to add user-specific fields for resources like Customer, Subscriptions, ... called Custom Fields.

These fields are prepended with the cf_ prefix. These fields can be accessed in the special custom_fields field of the structure. Please note Custom Fields are only available for Customers, Subscriptions, Product Families, Plans, Addons and Price Points.

Example:

 iex> Chargebeex.Customer.retrieve("barbaz")
 {:ok, %Chargebeex.Customer{
     id: "barbaz",
     allow_direct_debit: false,
     custom_fields: %{
       "cf_my_custom_field" => "foobar"
     },
     [...]}
  }

Extra Resources

Some ressources can have extra infos returned along them. For example, when querying a Customer, if any card or subscription is linked to this customer, these resources will also be returned. For internal API simplification, these fields can be accessed in the resources field of the structure.

Example:

 iex> Chargebeex.Customer.retrieve("barbaz")
 {:ok, %Chargebeex.Customer{
     id: "barbaz",
     allow_direct_debit: false,
      resources: %{
        "card" => %Chargebeex.Card{
          billing_addr1: "my_address",
          billing_addr2: nil,
          billing_city: "Paris",
          ...
          }
      }
     [...]}
  }

Telemetry Integration

Chargebeex now supports :telemetry, allowing users to instrument and monitor API calls using telemetry events. This enables integration with various observability tools.

Telemetry Events

Chargebeex emits the following telemetry events for each API request:

• [:chargebeex, :request, :start]: Emitted when an API request starts.
• [:chargebeex, :request, :stop]: Emitted when an API request completes.

When making API calls, telemetry events will automatically be emitted:

Chargebeex.Client.get("/customers")

This will emit :start and :stop telemetry events with metadata such as the HTTP method, URL, and status code, which can be processed by your telemetry handler.

For more information on :telemetry, visit the official documentation.

Run tests

mix test

License

MIT