Using the API gem with private app credentials

Docs version 1

You want to do certain things to your products — or to your orders — that aren't so easy to accomplish in your shop admin. You want to use the haravan API for this, and you have Ruby installed on your computer. This article will show you how to use the haravan_api gem in the interactive Ruby console —irb— to 'speak' to your shop using the command line.

In this article:

Getting your URL credentials

  • Click Apps

  • Click private API key

The /admin/api page lists all the private API keys you have created. You can generate a new key, or delete existing keys if you are no longer using them.

  • Click Generate new Private App

Treat all your API keys like you'd treat the password to your shop admin. With an API key and password, anyone can access and modify the content of your shop. We're speaking ultimate control.

haravan sets you up with an Example URL that you will be able to paste in your Terminal. It contains a few things like your API key, password and shop URL:

You can select the https://apikey:password@hostname/admin part of that URL and copy it to your clipboard. Leave out the /orders.xml part. You'll need these credentials for step 4.

Opening up irb

Go into your Terminal or Ruby console and launch irb:

$ irb

Call on the power of haravan_api gem

In irb, include the haravan_api gem:

>> require 'rubygems'
=> true
>> require 'haravan_api'
=> true

Giving commands to your shop

Now's the time to take control of your shop from the Terminal. In irb, copy + paste:

>> = ""

That URL between double quotes is the one you copied to your clipboard in the 'Getting your URL slash whip ready' section. You may actually want to save the whole command somewhere well-protected.


Change a vendor name from X to Y

There's no easy way to edit a vendor name in your store. That is, unless you use the API. Let's grab the products in your shop that have the vendor name you wish to edit:

>> products = haravanAPI::Product.find(:all,:params => {:vendor => 'haravan', :limit => 50})

Replace 'haravan' with the vendor name. Also, to make sure you won't be committing a blunder, let's check how many products you have just grabbed:

>> products.size
=> 17

Does the count you get make sense? If it does, go on. Let's edit the vendor for those products:

>> products.each { |p| p.vendor = 'Whip it'; }



You can change an order’s note, note_attributes, email, and buyer_accepts_marketing. Those are the only attributes modifiable through the API. You can, of course, fulfill, open, close and accept payment for an order using the API.

Do you have many resources to update?

If you have more than 40 API calls to make, you'll need to throttle those calls. This article will show you how: Learning to Respect the API calls limit.