Using the API console

If you'll be writing your app in Rails, or want to troubleshoot issues in your app, the Shopify API console will allow you to easily interact with the API without running a full Rails app or making HTTP requests via curl.

This tutorial will get you started using the Shopify API console in development.

Prerequisites

Before you begin using the console, you will need a few things:

Setup your development store and get the required gems

To become a Shopify Partner register here for your free Shopify Partner account. As a Shopify Partner, you gain access to the Partners dashboard where you can create development stores. To create a development store, navigate to the "Development stores" tab and click Create a new development store.

Create test shop

Open up your development store and populate it with Orders, Customers, Products, etc. — whatever you may need to properly develop your app.

You can generate your API key one of two ways:

  • Create a private API key: In your development store, click on the Apps tab. At the bottom of the screen, click on the Private API key link.
  • Create a public API key: In your Partners dashboard, click on the Apps tab. Click the Create app button and complete the required form. Once you complete the form, you will be given an API key.

Once you have your API key get the shopify_api and shopify_cli gems. Once you're done, we can get going with the console.

Use the console

Open up your terminal, and type 'shopify-cli'

Bobs-MacBook:~ Bob$ 'shopify-cli'
Commands:
  shopify-cli add CONNECTION        # create a config file for a connection named...
  shopify-cli console [CONNECTION]  # start an API console for CONNECTION
  shopify-cli default [CONNECTION]  # show the default connection, or make CONNEC...
  shopify-cli edit [CONNECTION]     # open the config file for CONNECTION with yo...
  shopify-cli help [COMMAND]        # Describe available commands or one specific...
  shopify-cli list                  # list available connections
  shopify-cli remove CONNECTION     # remove the config file for CONNECTION
  shopify-cli show [CONNECTION]     # output the location and contents of the CON...

You're presented with options for setting up and managing connection configuration. Nothing is set up yet, so add a connection. Name it whatever you like, but make sure that the URL matches up with that of your development store. You'll be prompted to enter in your API key and password, which you can find in your shop admin. Be sure to enter the API password, not secret.

Bobs-MacBook:~ Bob$ shopify-cli add ferryorncarroll
Domain? (leave blank for ferryorncarroll.myshopify.com) ferry-orn-and-carroll7638.myshopify.com
open https://ferry-orn-and-carroll7638.myshopify.com/admin/api in your browser to get API credentials
API key? [REDACTED]
Password? [REDACTED]
create  .shopify/shops/ferryorncarroll.yml
remove  .shopify/shops/default
Default connection is ferryorncarroll

That wasn't difficult! Now let's start the console. Type 'shopify-cli console'

Bobs-MacBook:~ Bob$ shopify-cli console using ferryorncarroll.myshopify.com

To make things easier, we'll include the ShopifyAPI module provided by the shopify_api gem right away. This is optional, but if you leave it off, you'll need to prefix API calls with 'ShopifyAPI::'.

Bobs-MacBook:~ Bob$ shopify-cli console
using ferryorncarroll.myshopify.com
1.9.3p125 :001 > include ShopifyAPI
 => Object
1.9.3p125 :002 >

Now you can start to look at the data. Check out the API docs to see what is queryable and mutable.

Let's start out with something simple. To look at your products, type 'Product.all'

1.9.3p125 :002 > Product.all

Let's try something more advanced. We're going to add a customer with the following values:

 {
    'first_name'=>'Steve',
    'last_name'=>'Lastnameson',
    'email'=>'steve@email.com',
    'addresses'=>[
        {
            'address1'=>'123 Oak St',
            'city'=>'Ottawa',
            'province'=>'ON',
            'phone'=>'555-1212',
            'zip'=>'123ABC',
            'last_name'=>'Lastnameson',
            'first_name'=>'Mother',
            'country'=>'CA'
        }
    ],
    'send_email_invite'=>true
}
1.9.3p125 :036 > i = ShopifyAPI::Customer.new({'first_name' => 'Steve','last_name' => 'Lastnameson','email' => 'steve@email.com','addresses' => [{'address1' => '123 Oak St','city' =>'Ottawa', 'province'=>'ON', 'phone'=>'555-1212', 'zip'=>'123ABC', 'last_name'=>'Lastnameson', 'first_name'=>'Mother', 'country'=>'CA' } ], 'send_email_invite'=>true})

Don't forget to save the entry!

1.9.3p125 :037 > i.save
 => true

Troubleshoot errors

You've now successfully added a customer to our shop, and sent them an email invitation. Let's use this example to see how we can troubleshoot errors. Change the entry slightly to set a password instead of sending an email invite, and then save the entry.

 {
    'first_name'=>'Steve',
    'last_name'=>'Lastnameson',
    'email'=>'steve@email.com',
    'addresses'=>[
        {
            'address1'=>'123 Oak St',
            'city'=>'Ottawa',
            'province'=>'ON',
            'phone'=>'555-1212',
            'zip'=>'123ABC',
            'last_name'=>'Lastnameson',
            'first_name'=>'Mother',
            'country'=>'CA'
        }
    ],
    'password' => '1234',
    'password_confirmation' => '1234'
}

If we use this data, we'll see that it fails when we try to save.

 1.9.3p125 :035 > i.save
 => false

So, why did it fail? Type 'i.errors' to find out. We'll get some information back on what we tried to post, and some information on the error, which we see is the following.

 @remote_errors=#<ActiveResource::ResourceInvalid: Failed.  Response code = 422.  Response message = Unprocessable Entity.>, @validation_context=nil, @errors=#<ActiveResource::Errors:0x007fc814173b60 ...>>, @messages={:password=>["is too short (minimum is 5 characters)"], :email=>["has already been taken"]

It didn't work because the password is too short, and the email address is already registered to the first customer we created. We've just quickly and easily troubleshooted why an API call wasn't working. Success!

Make complex calls

Let's take a look at how to string together a couple more complex calls.

Get a list of something using query parameters

Here we'll find all products, using the limit parameter to limit the results to just three products.

 1.9.3p125 :002 > Product.find(:all, :params => {:limit => 3})

Update something

Add a description to an existing collection.

 1.9.3p125 :028 >   i = CustomCollection.find(7724148)
 => #<ShopifyAPI::CustomCollection:0x007fd47c57acf8 @attributes={"body_html"=>nil, "handle"=>"frontpage", "id"=>7724148, "published_at"=>2012-07-06 17:57:28 UTC, "sort_order"=>"alpha-asc", "template_suffix"=>nil, "title"=>"Frontpage", "updated_at"=>2013-01-31 21:55:21 UTC}, @prefix_options={}>
1.9.3p125 :029 > i.body_html = 'Give the collection a new description'
 => "Give the collection a new description"
1.9.3p125 :030 > i.save
 => true
1.9.3p125 :031 > CustomCollection.find(7724148)
 => #<ShopifyAPI::CustomCollection:0x007fd47c5f1ba0 @attributes={"body_html"=>"Give the collection a new description", "handle"=>"frontpage", "id"=>7724148, "published_at"=>2012-07-06 17:57:28 UTC, "sort_order"=>"alpha-asc", "template_suffix"=>nil, "title"=>"Frontpage", "updated_at"=>2013-02-26 04:21:41 UTC}, @prefix_options={}>