Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Recurly Build Status Hex pm API Docs

Warning, this is alpha software and is not supported by Recurly. It should not be used in production yet unless you really know what you are doing. There are bugs and the API will likely change

Having said that, I would love help on making it production ready.


See the documentation to get started. This project uses inline documentation using exdoc.


  1. Add recurly to your list of dependencies in mix.exs:
def deps do
  [{:recurly, "~> 0.2.2"}]
  1. Ensure recurly is started before your application:
def application do
  [applications: [:recurly]]
  1. Add your subdomain and private key to your config file. You can use ENV vars or whatever your server uses to store configs:
config :recurly,
  private_key: System.get_env("RECURLY_DEV_KEY"),
  subdomain: System.get_env("RECURLY_DEV_SUBDOMAIN")


mix credo # code analysis
mix test  # run tests
mix coveralls # run coverage and print table
mix coveralls.html && open cover/excoveralls.html # run coverage and open html view


In writing this library from scratch, I'm trying to test some "lessons learned" in maintaining the official Recurly clients over the past year or so. I tried to take ideas from what I found worked and did not work in each library. I've also taken some inspiration from other elixir projects such as ecto. Here are some of the design principles I've tried to follow that I think will help avoid some of the problems I've encountered with the other libraries:

  1. Use metaprogramming sparingly. I've tried to only use metaprogramming for the internal APIs of the library. I wanted all public API functions to be greppable and documented.
  2. Don't abstract away the underlying XML API. The functions should be almost 1x1 with the HTTP calls. The use of changesets keeps the xml generation process transparent.
  3. Don't allow "dirty" changes to resources. If you want want to create or modify a resource, you may not modify the resource in memory. Instead, you must send a changeset to the server and get a new resource back. This eliminates the need to track changed attributes and use those changes to generate xml as well as make what you are sending to the server much more transparent. It also ensures that every resource you have is the exact represenation of what is on the server. This eliminates a whole class of annoying errors.


  • Need a good "Getting Started" in the documentation
  • Implement all fields and resources. Some resources missing as well as some fields
  • Needs work on parsing and building currency objects
  • Resource Streaming needs some work and testing
  • A few large, nested functions need to be refactored. Some have nested ifs
  • Need more examples and documentation
  • Typespecs
  • More tests


Recurly API client in Elixir







No releases published


No packages published