Ruby SDK

Install the Ruby gem, authenticate, and retrieve an order.

Before you start

• A Simple Key. Generate one under Configuration → Back Office → Authorized Applications. See Creating a Simple Key. For an application that multiple merchants connect to their own accounts, use OAuth 2.0 instead.

Install

Add the gem to your Gemfile:

gem 'ultracart_api'

Or install it directly:

gem install ultracart_api

The gem is published as ultracart_api and exposes the UltracartClient module. Check RubyGems for the current release if you need to pin a version.

Authenticate

Every API class has a new_using_api_key factory that builds a configured client in one call:

require 'ultracart_api'

order_api = UltracartClient::OrderApi.new_using_api_key(ENV['UC_API_KEY'])  # <- your merchant Simple Key

That factory sets the API version to 2017-03-01 along with the credential, so no further client setup is needed. It also accepts optional arguments for TLS verification and debug output. Leave TLS verification at its default of true.

warning

Read the key from the environment or a secret store rather than hardcoding it. The samples repository hardcodes a shared development key and sets VERIFY_SSL = false; neither belongs in your code.

Retrieve an order

This is the get_order sample from sdk_samples, trimmed to the call itself:

# Trimmed from sdk_samples/ruby/order/get_order.rb

expansion = "item,summary,billing,shipping,shipping.tracking_number_details"
order_id = 'DEMO-0009104390'                # <- an order ID in your account
opts = { '_expand' => expansion }

begin
  api_response = order_api.get_order(order_id, opts)

  if api_response.error
    puts "Developer Message: #{api_response.error.developer_message}"
    puts "User Message: #{api_response.error.user_message}"
    exit
  end

  puts api_response.order.inspect
rescue StandardError => e
  puts "An error occurred: #{e.message}"
end

Expansion goes in the options hash under the _expand key, not as a positional argument. It controls how much of the order comes back, and order objects are large, so request only the branches you need. Expanding objects lists the valid values.

Failures reach you two ways. Transport and HTTP failures raise, while UltraCart application errors come back on api_response.error. Handle both.

Next

• Essentials for pagination, expansion, errors, and rate limits.
• API Samples to browse a sample for every operation, or go straight to ruby/ in the samples repository.
• Error reference for the specific failures you are likely to hit, and how to handle each one.