This is the official BigCommerce API client to support our Stores API. You can find more information about becoming a BigCommerce developer here: developer.bigcommerce.com.

BigCommerce is available on RubyGems.

gem install bigcommerce

You can also add it to your Gemfile.

gem 'bigcommerce', '~> 1.0.0'

• Ruby 2.0.0 or newer. Please refer to the .travis.yml to see which versions we officially support.

In order to make requests to our API, you must register as a developer and have your credentials ready.

Its also very important to note that for the OAuth authentication mechanism, the resources you have acccess to depend on the scopes which your application has been granted by the merchant. For more information about the Store API scopes, see: OAuth Scopes.

We currently have two different authentication schemes you can use depending on your use case.

OAuth apps can be submitted to BigCommerce App Store, allowing other merchants to install it in their BigCommerce store.

More Information

To develop a custom integration for one store, your app needs to use Basic Authentication.

More Information

In order to authenticate the API client, you will need to configure the client like the following.

• client_id: Obtained from the "My Apps" section on the developer portal.
• access_token: Obtained after a token exchange in the auth callback.
• store_hash: Also obtained after the token exchange.

Bigcommerce.configure do |config|
  config.store_hash = ENV['BC_STORE_HASH']
  config.client_id = ENV['BC_CLIENT_ID']
  config.access_token = ENV['BC_ACCESS_TOKEN']
end

To get all the basic auth credentials, simply visit your store admin page and navigate to the Advanced Settings > Legacy API Settings. Once there, you can create a new legacy api account to authenticate with.

Bigcommerce.configure do |config|
  config.auth = 'legacy'
  config.url = ENV['BC_API_ENDPOINT_LEGACY']
  config.username = ENV['BC_USERNAME']
  config.api_key = ENV['BC_API_KEY']
end

SSL Configuration

If you are using your own self-signed certificate, you can pass SSL options to Faraday. This is not required, but may be useful in special edge cases.

Bigcommerce.configure do |config|
  config.auth = 'legacy'
  config.url = 'https://api_path.com'
  config.username = 'username'
  config.api_key = 'api_key'
  config.ssl = {
    # Faraday options here
  }
end

For more information about configuring SSL with Faraday, please see the following:

• Faraday SSL example
• Setting up SSL certificates

For full examples on using the API client, please see the examples folder and refer to the developer documentation.

Example:

# Configure the client to talk to a given store
Bigcommerce.configure do |config|
  config.store_hash = ENV['BC_STORE_HASH']
  config.client_id = ENV['BC_CLIENT_ID']
  config.access_token = ENV['BC_ACCESS_TOKEN']
end

# Make an API request for a given resource
Bigcommerce::System.time
=> #<Bigcommerce::System time=1466801314>

The Bigcommerce.configure method is NOT thread safe. This mechanism is designed for applications or cli where thread safety is not a concern. If you need to guarantee thread safety, we support another mechanism to make threadsafe API requests.

Rather then setting up a single connection for all API requests, you will want to construct a new connection for each thread. If you can make sure that each of these connections is stored in a thread safe manner, you can pass the connection as you query the resource.

This connection is nothing more than a Faraday::Connection so if you want to write your own, or use your own adapers, you can feel free. Please refer to the connection class for more details.

connection = Bigcommerce::Connection.build(
  Bigcommerce::Config.new(
    store_hash: ENV['BC_STORE_HASH'], 
    client_id: ENV['BC_CLIENT_ID'], 
    access_token: ENV['BC_ACCESS_TOKEN']
  )
)
=> #<Faraday::Connection:0x007fbf95068978 ... >>

Bigcommerce::System.time(connection: connection)
=> #<Bigcommerce::System time=1466546702>

Bigcommerce::System.raw_request(:get, 'time', connection: connection)
=> #<Faraday::Response:0x007fd4a4063170 ... >>

connection_legacy = Bigcommerce::Connection.build(
  Bigcommerce::Config.new(
    auth: 'legacy', 
    url: ENV['BC_API_ENDPOINT_LEGACY'],
    username: ENV['BC_USERNAME'],
    api_key: ENV['BC_API_KEY']
  )
)
=> #<Faraday::Connection:0x007fbf95068978 ... >>

Bigcommerce::System.time(connection: connection_legacy)
=> #<Bigcommerce::System time=1466546702>

Bigcommerce::System.raw_request(:get, 'time', connection: connection_legacy)
=> #<Faraday::Response:0x007fd4a4063170 ... >>

See CONTRIBUTING.md