Ruby client for the Vend API. Access your Vend Store in Ruby.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Vending Machine

Access your Vend Store in Ruby! Vending Machine turns the Vend API into Ruby objects, including type coercion and nested objects.

# Create an instance of your store with Basic Auth
store ={:store_name => 'store_name', :username => 'user_name', :password => 'password'})
# Create an instance of your store with OAuth
store ={:store_name => 'store_name', :auth_token => 'auth_token'})

# Get all your products
store.products.order('name', 'ASC').map &:name
=> ["Coffee (Demo)", "Discount", "T-shirt (Demo)", "test"]

# Type coercion
=> Float

# Nested objects
=> Vend::RegisterSaleProduct


Add this line to your application's Gemfile:

gem 'vending-machine'

And then execute:

$ bundle

Or install it yourself as:

$ gem install vending-machine


Basic Auth and Oauth Support

Authentication defaults to Basic Auth. You can switch to Oauth by adding the following code to an initializer.

# config/vending_machine.rb
Vend.config do |config|
  config.auth_method = :oauth # defaults to :basic_auth

Get a store instance

All usage revolves around your store, as per Vend itself

# Create an instance of your store with Basic Auth
store ={:store_name => 'store_name', :username => 'user_name', :password => 'password'})
#Or Create an instance of your store with OAuth
store ={:store_name => 'store_name', :auth_token => 'auth_token'})

Once you have a store instance you can retrieve your objects


customers = store.customers

Payment Types

types = store.payment_types
=> "Cash"

Products &:name
=> ["Coffee (Demo)", "T-shirt (Demo)", "Discount", "test"]


Scopes available: active, order_by, order_direction and an order shortcut to do both order by and direction at once. Scopes are chainable. &:name
=> ["T-shirt (Demo)", "Discount", "test"]

store.products.order_by('name').map &:name
=> ["Coffee (Demo)", "Discount", "T-shirt (Demo)", "test"]

store.products.order_by('name').order_direction('desc').map &:name
=> ["test", "T-shirt (Demo)", "Discount", "Coffee (Demo)"]

store.products.order('name', 'DESC').map &:name
=> ["test", "T-shirt (Demo)", "Discount", "Coffee (Demo)"]

Creating a Product

Initialize a new product with #build, #create or #create!.

  • build create an unsaved instance
  • create create an instance, and call #save
  • create! create an instance, and call #save!
product = name: "Product Name", handle: "prod1", retail_price: 25

# Safe save
=> false

=> ["Could not Add or Update: Missing sku"]

# Explosive save!
=> Vend::ValidationFailed: Could not Add or Update: Missing sku

product.sku = 'prod1'!
=> true

Creating a Product Variant

Product variants have the same handle as another product, but a different sku. You can create a variant of a product easily with the #build_variant, #create_variant and #create_variant! methods.

Underneath the hood, it's simply copying attributes to a new instance, then changing the sku to either a provided new sku, or appending an incrementing integer to an existing sku.

product.sku = 'my-product'
product.build_variant(sku: 'my-product-alt')
=> #<Vend::Product>

product.build_variant(sku: 'my-product-alt').sku
=> 'my-product-alt'

=> 'my-product-1'

product.sku = 'my-product-3'
=> 'my-product-4'

Register Sales

sales = store.sales{|sale| sale.total_price + sale.total_tax }
=> [1337.0, 1341.95] &:name
=> ["T-shirt (Demo)", "Coffee (Demo)"]

=> "#<Vend::RegisterSaleProduct:0x007fe238720d68>"

Registers &:name
=> ["Main Register", "Back office Register"]

Open register!

Close register


Suppliers &:name
=> ["Mal Curtis", "Vend"]

Taxes &:name
=> ["NZ GST", "AU GST", "Asshole Tax"]

The default scope will provide you the first returned default tax (note, this still retrieves all taxes from the API).
=> "NZ GST"

Users &:name
=> ["A cashier", "Mal Curtis", "Joe Bloggs"]


Figuring out what attributes a resource has

Want to know what attributes are on a particular resource? Use #attributes. Vending Machine will map all returned attributes to a resource, only a portion of which are defined in the resource’s code (for validation and type coercion).

=> {:id=>"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 :name=>"NZ GST"}


  • COMPLETE: GET index resources are implemented, with the exception of Stock Control
  • IN PROGRESS: find singular resources store.products.find('some_id')
  • IN PROGRESS: create register sales products: [product1, product2]
  • COMPLETE: create products
  • COMPLETE: Create Product Variants (This seems to happen when posting a new product with a same handle, but different sku)
  • TODO: Delete resources
  • TODO: Scopes for Customer and Register Sales

Created By


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request