Returns an action on a resource given the action name

Parameters

• resource Recurly.Resource struct
• action_name Atom of the action name

Examples

Recurly.Resource.action(subscription, :cancel)
#=> [:put, "https://your-subsdomain.recurly.com/v2/subscriptions/36d81d1e79995b0b4c7df3419aa1c2f5/cancel"]

Returns an map of actions keyed by action name

Parameters

• resource Recurly.Resource struct

Gives us the attributes of a resource without all the metadata.

Parameters

• resource Resource struct with some attributes

Gives the count of records returned given a path and options

Parameters

• path the url path
• options the request options. See options in the pagination section of the docs.

Examples

# suppose we want to count all subscriptions
case Recurly.Resource.count("/subscriptions", []) do
  {:ok, count} ->
    # count => 176 (or some integer)
  {:error, err} ->
    # error occurred
end

# or maybe we wan to count just active subscriptions
case Recurly.Resource.count("/subscriptions", state: :active) do
  {:ok, count} ->
    # count => 83 (or some integer)
  {:error, err} ->
    # error occurred
end

Creates a resource on the server and returns a resource struct.

Parameters

• resource empty resource struct with the type of the expected return resource
• changset Keyword list changeset representing the creation data
• path String path to the creation endpoint

Examples

  changeset = [
    account_code: "myaccountcode"
  ]

  case Recurly.Resource.create(%Recurly.Account{}, changeset, "/accounts/") do
    {:ok, account} ->
      # successfully created
    {:error, error} ->
      # There was an error
  end

Finds and parses a resource given an association

Parameters

• association Recurly.Association struct where paginate == false

Examples

{:ok, account} = Recurly.Account.find("myaccountcode")

# Suppose we have an account and want to fetch the billing info association
case Recurly.Resource.find(account.billing_info) do
  {:ok, billing_info} ->
    # successfully found the billing_info
  {:error, error} ->
    # There was an error
end

# It will explode if we try to use a pageable association
Recurly.Resource.find(account.transactions)
#=> crashes with argument error because paginate == true

Finds and parses a resource given a path

Parameters

Recurly.Resource.find/2 takes a resource and a path:

• resource Recurly.Resource struct to parse result into
• path String path to the resource

Recurly.Resource.find/1 takes an association:

• association Recurly.Association struct with paginate: false

Examples

case Recurly.Resource.find(%Recurly.Account{}, "/accounts/account123") do
  {:ok, account} ->
    # successfully found account
  {:error, error} ->
    # There was an error
end

Gives the first resource returned given a path and options

Parameters

• resource resource to parse into
• path the url path
• options the request options. See options in the pagination section of the docs.

Examples

alias Recurly.{Resource,Subscription}

# suppose we want the latest, active subscription
case Resource.first(%Subscription{}, "/subscriptions", state: :active) do
  {:ok, subscription} ->
    # subscription => the newest active subscription
  {:error, err} ->
    # error occurred
end

# or maybe want the oldest, active subscription
case Resource.first(%Subscription{}, "/subscriptions", state: :active, order: :asc) do
  {:ok, subscription} ->
    # subscription => the oldest active subscription
  {:error, err} ->
    # error occurred
end

Returns a Recurly.Page at the given endpoint. You will probably not want to use this directly and instead use Recurly.Resource.stream/3.

Parameters

• resource Recurly.Resource struct to parse result into
• path String path to the resource
• options the request options. See options in the pagination section of the docs for possible values.

Examples

case Recurly.Resource.list(%Recurly.Account{}, "/accounts", state: "subscriber") do
  {:ok, page} ->
    # a recurly page
  {:error, error} ->
    # There was an error
end

Gives us fully qualified location of the persisted resource.

Parameters

• resource Resource struct representing a persisted resource

Performs and action on a resource. Actions can be found in the <a> tags of the xml. It follows the same response pattern as Recurly.API.make_request/5

Parameters

• resource Resource struct representing a persisted resource
• action_name Atom of the action name

Examples

case Recurly.Resource.perform_action(subscription, :cancel) do
  {:ok, subscription} ->
    # sucessfully canceled the subscription
  {:error, error} ->
    # error happened
end

Creates a stream from a Recurly.Association. See Recurly.Resource.stream/3.

Creates a stream of resources given a type, an endpoint, and request options.

A resource stream behaves the way any elixir Stream would behave. Streams are composable and lazy. We’ll try to create some trivial examples here but what you can accomplish with streams is pretty limitless.

TODO - need more examples, need error handling

Parameters

• resource_type the resource type to parse
• endpoint the list path for this stream of pages
• options the request options. See options in the pagination section of the docs.

Examples

You should use the shortcut on the module of the resource you are streaming such as Recurly.Subscription.stream/1 to create the stream. This function is mostly for internal use, but these examples will show Resource’s stream function.

alias Recurly.{Resource,Subscription,Account}

# Suppose we want the uuids of the first 70 active subscriptions
# in order of creation (newest to oldest)
options = [state: :active, order: :desc, sort: :created_at]

stream = Resource.stream(Subscription, "/subscriptions", options)
# stream = Subscription.stream(options) # use this shortcut instead

uuids =
  stream
  |> Stream.map(&(Map.get(&1, :uuid)))
  |> Enum.take(70)

# uuids => ["376e7209ee28de6b611f7b49df847539", "376e71e42b254873f550a749789dbaaa", ...] # 68 more

# Since the default page size is 50, we had to fetch 2 pages.
# This, however, was abstracted away from you.

# You can also turn associations into streams as long as their `paginate` attribute
# is true. Consider the example of getting the uuids of each transaction on an account

{:ok, account} = Account.find("myaccountcode")

uuids =
  account
  |> Map.get(:transactions)
  |> Resource.stream
  |> Enum.map(fn tr -> tr.uuid end)

# uuids => ["37f6aa1eae4657c0d8b430455fb6dcb6", "6bcd6bf554034b8d0c7564eae1aa6f73", ...]