ruby shell
API Change log

TradeGecko API

Build tools that solve problems for millions of wholesale and retail businesses worldwide.

You can view code examples in the dark area to the right; switch the programming language of the examples with the tabs in the top right.

If anything is missing or seems incorrect, please check the GitHub issues for existing known issues or create a new issue.

Authentication

To authorize, use this code:

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Account.current
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Make sure to replace <ACCESS_TOKEN> with your API key.

TradeGecko uses API keys to allow access to the API. You can register a new TradeGecko API key at our developer portal.

TradeGecko expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <ACCESS_TOKEN>

Getting Started

Creating an Application

In order to use the TradeGecko API, you must first have a TradeGecko account, you can register a new application at https://go.tradegecko.com/oauth/applications. After successfully creating a new application, you will be given a set of 2 unique keys:

These keys are needed in order to obtain an access token to make the API calls.

TradeGecko is based on version 22 of the OAuth 2.0 specification.

If you are already familiar with OAuth, then all you really need to know about are the two authentication endpoints. The authorization endpoint and the token request endpoint.

These endpoints are:

Getting an Authorization Code

An authorization code is the key used to retrieve the access token. In order to acquire an authorization code, you need to send your user to the authorization endpoint.

https://api.tradegecko.com/oauth/authorize?response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>

CLIENT_ID should be set to your application ID. response_type should always be set to “code”. REDIRECT_URI should be set to the URL where the user will be redirected back to after the request is authorized.

Once the user has successfully authorized the application, she will be redirected to the redirect_uri with the authorization code as a query parameter.

e.g. https://my.application.com/auth/app/callback?code=12bc6909c57aaa930

Requesting for an Access Token

curl -H "Content-type: application/json" -X POST https://api.tradegecko.com/oauth/token -d '{"client_id": "d38abea2ef61c916a1e131de9fd04146579578f", "client_secret":"2kj2kd07e197f9942ca1876d759e9e9c45bdcdc", "redirect_uri": "https://my.application.com/auth/app/callback", "code": "c3d11b23992f53d748c7b25148da1ac4d838919", "grant_type": "authorization_code"}'
{
  "access_token": "57ed301af04bf35b40f255feb5ef469ab2f046aff14",
  "expires_in": 7200,
  "refresh_token": "026b343de07818b3ffebfb3001eff9a00aea43da0 ",
  "scope": "public",
  "token_type": "bearer"
}

The access token is a unique key used to make requests to the API. In order to get an access token, user must make a POST request to https://api.tradegecko.com/oauth/token with the client_id, client_secret, redirect_uri, code and grant_type as parameters. code must match the authorization code returned by the authorization endpoint and grant_type must be set to authorization_code

Refreshing Access Tokens

The refresh token is a unique key used to request for a new access token whenever the current access token becomes expired. In order to refresh an access token, user must make a POST request to https://api.tradegecko.com/oauth/token with the client_id, client_secret, redirect_uri, refresh_token and grant_type as parameters.

refresh_token must match the refresh token returned by the authorization endpoint and grant_type must be set to refresh_token.

curl -H "Content-type: application/json" -X POST https://api.tradegecko.com/oauth/token -d '{"client_id": "9eb02720054", "client_secret": "b1d41094b83", "redirect_uri": "http://my.application.com/auth/callback", "refresh_token": "9582f8a45255", "grant_type": "refresh_token"}'

{
  "access_token": "439fc57cf1525e51555",
  "expires_in": 7200,
  "refresh_token": "ecfa1a22bd612cc1d8",
  "scope": "public",
  "token_type": "bearer"
}

Note: When a token is refreshed, a new refresh token is generated and this should be the one used the next time token refresh is invoked. Using an expired refresh token would return this error.

{
  "error": "invalid_request",
  "error_description": "The request is missing a required parameter, includes an unsupported parameter value, or is otherwise malformed."
}

Making an API call

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/accounts %>/
require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Account.where()

The TradeGecko API is entirely JSON based. In order to make an authenticated call to the API, you must include your access token with the call. OAuth2 uses a BEARER token that is passed along in an Authorization header.

Testing with Oauth

Setting up the client

To test TradeGecko API, first make sure you have installed the oauth2 gem.

To setup the client, go to your terminal and fire up irb and type:

irb(main):001:0> require 'oauth2'
irb(main):002:0> client_id     = '...'
irb(main):003:0> client_secret = '...'
irb(main):004:0> redirect_uri  = '...'
irb(main):005:0> site          = "https://api.tradegecko.com"
irb(main):006:0> client = OAuth2::Client.new(client_id, client_secret, site: site)

Now that your client is ready, you can request an authorization code.

Getting an authorization code

Generate an authorization url with:

irb(main):006:0> client.auth_code.authorize_url(redirect_uri: redirect_uri)
=> https://api.tradegecko.com/oauth/authorize?response_type=code&client_id=...&redirect_uri=...

Go to this url in your browser. You’ll see the authorization endpoint. If you click on Authorize, you’ll see a page with the authorization code in it:

auth_image

Then you’ll get redirected to the redirect uri that you specified along with the code parameter in the query.

http://my.redirect.uri/callback?code=123456789

With this unique code, you will now be able to request the access token.

Getting an access token

TradeGecko API currently allows Authorization Code and Resource Owner Password Credentials authentication grant types.

For security reasons, the use of Resource Owner Password Credentials is limited only to the account who created the application.

Authorization Code flow

irb(main):008:0> code = "..." # code you got in the redirect uri
irb(main):009:0> token = client.auth_code.get_token(code, redirect_uri: redirect_uri)
=> <#OAuth2::AccessToken ...>

Resource Owner Password Credentials flow

irb(main):010:0> token = client.password.get_token('username', 'password')
=> <#OAuth2::AccessToken ...>

You now have access to the TradeGecko API.

Making your first TradeGecko API request

irb(main):011:0> response = token.get('accounts')
irb(main):012:0> JSON.parse(response.body)
=> { "accounts": [{ "name": "tradegecko", ... }] }

Congratulations! You just made your first request to the TradeGecko API.

Request with additional parameters

irb(main):013:0> response = token.post('products') do |request|
irb(main):014:0>   request.params[:product] = {
irb(main):015:0>     name: "Product1",
irb(main):016:0>     description: "My first product"
irb(main):017:0>   }
irb(main):018:0> end

irb(main):019:0> JSON.parse(response.body)
=> {"product"=>{"id"=>22, "name"=>"Product1", "description"=>"My first product", ...} }

TradeGecko OmniAuth Strategy

In order to provide our users a much better way of accessing our API, we have created a TradeGecko strategy for OmniAuth. OmniAuth is a library that standardizes multi-provider authentication for web applications.

Usage

in config/initializers/tradegecko.rb

use OmniAuth::Builder do
  provider :tradegecko, ENV['TRADEGECKO_ID'], ENV['TRADEGECKO_SECRET']
end

We’ve provided an example app in https://tradegecko-example-app.herokuapp.com/ | (source)

Privileged Access Tokens

Once you have obtained your Privileged Access Token, you can use cURL or Ruby to check if it is working.

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/accounts/
require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Account.current

You can now generate Privileged Access Tokens to be used for accessing the TradeGecko API. These keys do not have an expiry which means that you can access the API using the privileged token without the need for a refresh token. In any case that your privileged key gets compromised, you should immediately revoke them through the TradeGecko App List.

Pagination

The default limit is 100 items.

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/users?limit=20&page=1
require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.User.where(limit: 5, page: 2)

The TradeGecko API enables pagination by allowing users to include ‘limit’ and ‘page’ parameters on GET requests to index pages.

Filtering

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/products?created_at_min=2015-11-04/
require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Product.where(created_at_min: "2015-11-04")

The API also allows filtering of records by passing query parameters These are the filters currently allowed by the API (where relevant)

Index Filters

Arguments Description
ids An array of object IDs
created_at_min Return objects only created since
created_at_max Return objects only created before
updated_at_min Return objects only updated since
updated_at_max Return objects only updated before
order The order to return the collection i.e “created_at desc”
limit See the pagination docs (default is 100)
page See the pagination docs

Each object has their own specific filters; we cover those filters in their respective sections.

HTTP Request

GET https://api.tradegecko.com/products?ids=1,2,3&order=created_at+desc&limit=3

Rate Limiting

The TradeGecko API provides a rate limit of 300 requests per 300 seconds.

Your current rate limit quota is provided in the headers of every request.

Header Description
X-Rate-Limit-Limit Number of requests available for this endpoint (currently 300 for every endpoint)
X-Rate-Limit-Remaining Number of requests remaining in quota
X-Rate-Limit-Reset Integer representing the epoch time at which the quota will reset

If you go over this limit the API will return a response with a status code of 429 until the reset time.

N.B. The API limit is counted against the combination of application and account, so if your application is serving multiple accounts each account will have it’s own quota.

Guides

The Ordering flow

1 . Create the Order POST /orders

{
  "order": {
    "company_id": 123,
    "shipping_address_id": 1001,
    "billing_address_id": 1001,
    "status": "active",
    "issued_at": "21-02-2014",
    "order_line_items": [
      { "variant_id": 14, "quantity": 1 }
      { "variant_id": 15, "quantity": 2 }
    ]
  }
}

2 . Invoice the order POST /orders/[:order_id]/actions/invoice

3 . Pay the order POST /orders/[:order_id]/actions/pay

4 . Create a Package for Shipping POST /orders/[:order_id]/actions/pack

5 . Ship the package POST /orders/[:order_id]/actions/fulfil

TradeGecko will automatically manage the Order’s fulfillment, invoice, payment and packed statuses throughout the process

Errors

The TradeGecko API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is invalid
401 Unauthorized – Your API key is wrong
402 Payment Required – Your subscription has lapsed
403 Forbidden – The resource requested is hidden for administrators only
404 Not Found – The specified resource could not be found
422 Unprocessable Entity – There was an issue parsing your json
429 Too Many Requests – You are allowed 300 requests per 300 seconds.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable (Time out) – The server is overloaded or down for maintenance.

Account

This is an object representing an account.

The Account object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
contact_email String
contact_mobile String
contact_phone String
country String Needs to be a valid ISO3166-1 alpha-2 code (US, NZ, SG etc)
default_order_price_list_id String
default_purchase_order_price_list_id String
default_sales_ledger_account_on String
default_tax_treatment String
industry String
logo_url deprecated String true
name String
stock_level_warn Boolean
tax_label String
tax_number String
tax_number_label String
time_zone String
website String
primary_location_id Integer
primary_billing_location_id Integer
default_currency_id Integer
default_payment_term_id Integer
billing_contact_id Integer Account Owner, can only be transferred by existing owner
default_sales_order_tax_type_id Integer
default_purchase_order_tax_type_id Integer
default_tax_exempt_id Integer
default_tax_rate deprecated String true
default_tax_type deprecated String
default_tax_type_id Integer
default_order_price_type_id deprecated String
default_purchase_order_price_type_id deprecated String
location_ids Array true
user_ids Array true

List all accounts

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Account.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/accounts/
{
  "accounts": [
  {
    "id": 1,
    "created_at": "2015-11-02T01:22:23.803Z",
    "updated_at": "2015-11-02T01:22:24.326Z",
    "contact_email": "lcp@tradegecko.com",
    "contact_mobile": null,
    "contact_phone": null,
    "country": "NZ",
    "default_order_price_list_id": "wholesale",
    "default_purchase_order_price_list_id": "buy",
    "default_sales_ledger_account_on": "company",
    "default_tax_treatment": "exclusive",
    "default_document_theme_id": 1,
    "industry": "",
    "logo_url": null,
    "name": "Bob's Burgers",
    "stock_level_warn": true,
    "tax_label": "GST",
    "tax_number": null,
    "tax_number_label": "GST Registration Number",
    "time_zone": "Pacific/Auckland",
    "website": null,
    "primary_location_id": 1,
    "primary_billing_location_id": 1,
    "default_currency_id": 1,
    "default_payment_term_id": 3,
    "billing_contact_id": 1,
    "default_sales_order_tax_type_id": 2,
    "default_purchase_order_tax_type_id": 3,
    "default_tax_exempt_id": 1,
    "default_tax_rate": "15.0",
    "default_tax_type": "exclusive",
    "default_tax_type_id": 2,
    "default_order_price_type_id": "wholesale",
    "default_purchase_order_price_type_id": "buy",
    "location_ids": [
      1
    ],
    "user_ids": [
      1
    ]
  }
]
}

Returns a list of accounts you’ve previously created. The accounts are returned in sorted order, with the most recent accounts appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)

HTTP Request:

GET https://api.tradegecko.com/accounts

Create a new account

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Account.create({:name=>"Bobs Burgers", :country=>"NZ", :email=>"example@example.com"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/accounts/ -d '{"account":{"name":"Bobs Burgers","country":"NZ","email":"example@example.com"}'}
{
  "account": {
  "id": 1,
  "created_at": "2015-11-02T01:22:23.803Z",
  "updated_at": "2015-11-02T01:22:24.326Z",
  "contact_email": "lcp@tradegecko.com",
  "contact_mobile": null,
  "contact_phone": null,
  "country": "NZ",
  "default_order_price_list_id": "wholesale",
  "default_purchase_order_price_list_id": "buy",
  "default_sales_ledger_account_on": "company",
  "default_tax_treatment": "exclusive",
  "default_document_theme_id": 1,
  "industry": "",
  "logo_url": null,
  "name": "Bob's Burgers",
  "stock_level_warn": true,
  "tax_label": "GST",
  "tax_number": null,
  "tax_number_label": "GST Registration Number",
  "time_zone": "Pacific/Auckland",
  "website": null,
  "primary_location_id": 1,
  "primary_billing_location_id": 1,
  "default_currency_id": 1,
  "default_payment_term_id": 3,
  "billing_contact_id": 1,
  "default_sales_order_tax_type_id": 2,
  "default_purchase_order_tax_type_id": 3,
  "default_tax_exempt_id": 1,
  "default_tax_rate": "15.0",
  "default_tax_type": "exclusive",
  "default_tax_type_id": 2,
  "default_order_price_type_id": "wholesale",
  "default_purchase_order_price_type_id": "buy",
  "location_ids": [
    1
  ],
  "user_ids": [
    1
  ]
}
}

Creates a new account object.

Arguments

Attribute Type Description Required
contact_email String
contact_mobile String
contact_phone String
country String Needs to be a valid ISO3166-1 alpha-2 code (US, NZ, SG etc) true
default_order_price_list_id String
default_purchase_order_price_list_id String
default_sales_ledger_account_on String
default_tax_treatment String
industry String
logo_url deprecated String
name String true
stock_level_warn Boolean
tax_label String
tax_number String
tax_number_label String
time_zone String
website String
primary_location_id Integer
primary_billing_location_id Integer
default_currency_id Integer
default_payment_term_id Integer
billing_contact_id Integer Account Owner, can only be transferred by existing owner
default_sales_order_tax_type_id Integer
default_purchase_order_tax_type_id Integer
default_tax_exempt_id Integer
default_tax_rate deprecated String
default_tax_type deprecated String
default_tax_type_id Integer
default_order_price_type_id deprecated String
default_purchase_order_price_type_id deprecated String

HTTP Request

POST https://api.tradegecko.com/accounts/

Retrieve a particular account

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Account.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/accounts/1
{
  "account": {
  "id": 1,
  "created_at": "2015-11-02T01:22:23.803Z",
  "updated_at": "2015-11-02T01:22:24.326Z",
  "contact_email": "lcp@tradegecko.com",
  "contact_mobile": null,
  "contact_phone": null,
  "country": "NZ",
  "default_order_price_list_id": "wholesale",
  "default_purchase_order_price_list_id": "buy",
  "default_sales_ledger_account_on": "company",
  "default_tax_treatment": "exclusive",
  "default_document_theme_id": 1,
  "industry": "",
  "logo_url": null,
  "name": "Bob's Burgers",
  "stock_level_warn": true,
  "tax_label": "GST",
  "tax_number": null,
  "tax_number_label": "GST Registration Number",
  "time_zone": "Pacific/Auckland",
  "website": null,
  "primary_location_id": 1,
  "primary_billing_location_id": 1,
  "default_currency_id": 1,
  "default_payment_term_id": 3,
  "billing_contact_id": 1,
  "default_sales_order_tax_type_id": 2,
  "default_purchase_order_tax_type_id": 3,
  "default_tax_exempt_id": 1,
  "default_tax_rate": "15.0",
  "default_tax_type": "exclusive",
  "default_tax_type_id": 2,
  "default_order_price_type_id": "wholesale",
  "default_purchase_order_price_type_id": "buy",
  "location_ids": [
    1
  ],
  "user_ids": [
    1
  ]
}
}

Retrieves the details of an existing account. You need only supply the unique account identifier that was returned upon account creation.

HTTP Request

GET https://api.tradegecko.com/accounts/{RESOURCE_ID}

Update an account

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
account = gecko.Account.find(1).
account.attributes({
  rate: "12.0",
})
account.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/accounts/1 -d '{"account":{"country":"US"}}'

Response

Returns 204 status when the account gets updated successfully.

Updates the specified account by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the account creation call.

HTTP Request

PUT https://api.tradegecko.com/accounts/{RESOURCE_ID}

Get current account

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Account.current
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/accounts/current
{
  "account": {
  "id": 1,
  "created_at": "2015-11-02T01:22:23.803Z",
  "updated_at": "2015-11-02T01:22:24.326Z",
  "contact_email": "lcp@tradegecko.com",
  "contact_mobile": null,
  "contact_phone": null,
  "country": "NZ",
  "default_order_price_list_id": "wholesale",
  "default_purchase_order_price_list_id": "buy",
  "default_sales_ledger_account_on": "company",
  "default_tax_treatment": "exclusive",
  "default_document_theme_id": 1,
  "industry": "",
  "logo_url": null,
  "name": "Bob's Burgers",
  "stock_level_warn": true,
  "tax_label": "GST",
  "tax_number": null,
  "tax_number_label": "GST Registration Number",
  "time_zone": "Pacific/Auckland",
  "website": null,
  "primary_location_id": 1,
  "primary_billing_location_id": 1,
  "default_currency_id": 1,
  "default_payment_term_id": 3,
  "billing_contact_id": 1,
  "default_sales_order_tax_type_id": 2,
  "default_purchase_order_tax_type_id": 3,
  "default_tax_exempt_id": 1,
  "default_tax_rate": "15.0",
  "default_tax_type": "exclusive",
  "default_tax_type_id": 2,
  "default_order_price_type_id": "wholesale",
  "default_purchase_order_price_type_id": "buy",
  "location_ids": [
    1
  ],
  "user_ids": [
    1
  ]
}
}

Retrieves the details of the current account.

HTTP Request

GET https://api.tradegecko.com/accounts/current

Address

This is an object representing an address of a company. Companies can have multiple addresses but an address object belongs to only one Company.

The Address object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
status String true
company_id Integer The company id where the address belongs.
address1 String
address2 String
city String
company_name String Attention to field of an address
country String
email String
first_name String
last_name String
label String A (unique per company) label for the address e.g. Shipping, Billing
phone_number String
state String
suburb String
zip_code String

List all addresses

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Address.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/addresses/
{
  "addresses": [
  {
    "id": 6,
    "created_at": "2015-11-04T06:59:35.285Z",
    "updated_at": "2015-11-04T06:59:35.285Z",
    "company_id": 4,
    "address1": "Test address",
    "address2": "",
    "city": "Singapore",
    "company_name": "",
    "country": "Singapore",
    "email": "",
    "first_name": null,
    "last_name": null,
    "label": "Shipping",
    "phone_number": "",
    "state": "",
    "status": "active",
    "suburb": "",
    "zip_code": ""
  },
  {
    "id": 5,
    "created_at": "2015-11-02T01:22:24.630Z",
    "updated_at": "2015-11-02T01:22:24.630Z",
    "company_id": 3,
    "address1": "06157 Waters Road",
    "address2": "505 Frederick Flat",
    "city": "East Trudie",
    "company_name": null,
    "country": "UK",
    "email": "samara@williamwonkacandyltd.com",
    "first_name": null,
    "last_name": null,
    "label": "Warehouse (DEMO)",
    "phone_number": "952-649-4655",
    "state": null,
    "status": "active",
    "suburb": null,
    "zip_code": "98366-5837"
  }
]
}

Returns a list of addresses you’ve previously created. The addresses are returned in sorted order, with the most recent addresses appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
status
company_id Filter addresses by company

HTTP Request:

GET https://api.tradegecko.com/addresses

Create a new address

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Address.create({:company_id=>1, :label=>"Main Office", :address1=>"12 Park Ave"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/addresses/ -d '{"address":{"company_id":1,"label":"Main Office","address1":"12 Park Ave"}'}
{
  "address": {
  "id": 6,
  "created_at": "2015-11-04T06:59:35.285Z",
  "updated_at": "2015-11-04T06:59:35.285Z",
  "company_id": 4,
  "address1": "Test address",
  "address2": "",
  "city": "Singapore",
  "company_name": "",
  "country": "Singapore",
  "email": "",
  "first_name": null,
  "last_name": null,
  "label": "Shipping",
  "phone_number": "",
  "state": "",
  "status": "active",
  "suburb": "",
  "zip_code": ""
}
}

Creates a new address object.

Arguments

Attribute Type Description Required
company_id Integer The company id where the address belongs. true
address1 String true
address2 String
city String
company_name String Attention to field of an address
country String
email String
first_name String
last_name String
label String A (unique per company) label for the address e.g. Shipping, Billing
phone_number String
state String
suburb String
zip_code String

HTTP Request

POST https://api.tradegecko.com/addresses/

Retrieve a particular address

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Address.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/addresses/1
{
  "address": {
  "id": 6,
  "created_at": "2015-11-04T06:59:35.285Z",
  "updated_at": "2015-11-04T06:59:35.285Z",
  "company_id": 4,
  "address1": "Test address",
  "address2": "",
  "city": "Singapore",
  "company_name": "",
  "country": "Singapore",
  "email": "",
  "first_name": null,
  "last_name": null,
  "label": "Shipping",
  "phone_number": "",
  "state": "",
  "status": "active",
  "suburb": "",
  "zip_code": ""
}
}

Retrieves the details of an existing address. You need only supply the unique address identifier that was returned upon address creation.

HTTP Request

GET https://api.tradegecko.com/addresses/{RESOURCE_ID}

Update an address

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
address = gecko.Address.find(1).
address.attributes({
  rate: "12.0",
})
address.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/addresses/1 -d '{"address":{"address1":"12 Park Ave","city":"Singapore","label":"Main Office"}}'

Response

Returns 204 status when the address gets updated successfully.

Updates the specified address by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the address creation call.

HTTP Request

PUT https://api.tradegecko.com/addresses/{RESOURCE_ID}

Delete an address

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
address = gecko.Address.find(1).
address.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/addresses/1

Response

Returns 204 status when the address gets deleted successfully.

Permanently deletes an address. It cannot be undone. This address is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/addresses/{RESOURCE_ID}/

Company

This is an object representing a company.

The Company object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
status String Tells whether the resource is ‘active’, 'disabled’ or 'archived’
assignee_id Integer ID of the user to which new PO/SO will be assigned by default
default_ledger_account_id Integer
default_payment_term_id Integer
default_stock_location_id Integer
default_tax_type_id Integer
company_code String A unique identifier for your records
company_type String Can be 'business’, 'supplier’ or 'consumer’
default_discount_rate String
default_price_list_id String
default_tax_rate deprecated String Alias to default_tax_type#effective_rate
description String
email String
fax String
name String
phone_number String
tax_number String
website String
address_ids Array true
contact_ids Array true
note_ids Array true
default_price_type_id deprecated String

List all companies

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Company.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/companies/
{
  "companies": [
  {
    "id": 4,
    "created_at": "2015-11-02T01:44:42.417Z",
    "updated_at": "2015-11-02T01:44:42.417Z",
    "assignee_id": 1,
    "default_ledger_account_id": null,
    "default_payment_term_id": null,
    "default_stock_location_id": null,
    "default_tax_type_id": null,
    "company_code": null,
    "company_type": "business",
    "default_discount_rate": null,
    "default_price_list_id": null,
    "default_tax_rate": null,
    "default_document_theme_id": null,
    "description": "",
    "email": null,
    "fax": null,
    "name": "B2B Test Company",
    "phone_number": null,
    "status": "active",
    "tax_number": null,
    "website": null,
    "address_ids": [
      6
    ],
    "contact_ids": [
      7
    ],
    "note_ids": [

    ],
    "default_price_type_id": null
  },
  {
    "id": 3,
    "created_at": "2015-11-02T01:22:24.612Z",
    "updated_at": "2015-11-02T01:22:24.612Z",
    "assignee_id": null,
    "default_ledger_account_id": null,
    "default_payment_term_id": null,
    "default_stock_location_id": null,
    "default_tax_type_id": null,
    "company_code": null,
    "company_type": "supplier",
    "default_discount_rate": null,
    "default_price_list_id": null,
    "default_tax_rate": null,
    "default_document_theme_id": null,
    "description": "Greatest Candy-maker and chocolatier of all time and place",
    "email": "william@example.com",
    "fax": null,
    "name": "Wonka Candy (DEMO)",
    "phone_number": "123-456-789",
    "status": "active",
    "tax_number": null,
    "website": "http://williamwonkacandyltd.com",
    "address_ids": [
      4,
      5
    ],
    "contact_ids": [
      3,
      4,
      5
    ],
    "note_ids": [

    ],
    "default_price_type_id": null
  }
]
}

Returns a list of companies you’ve previously created. The companies are returned in sorted order, with the most recent companies appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
status
assignee_id
default_ledger_account_id
default_payment_term_id
default_stock_location_id
default_tax_type_id
company_code
company_type
default_price_list_id
default_document_theme_id
email
default_price_type_id

HTTP Request:

GET https://api.tradegecko.com/companies

Create a new company

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Company.create({:name=>"TradeGecko (Demo)", :company_type=>"Supplier"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/companies/ -d '{"company":{"name":"TradeGecko (Demo)","company_type":"Supplier"}'}
{
  "company": {
  "id": 4,
  "created_at": "2015-11-02T01:44:42.417Z",
  "updated_at": "2015-11-02T01:44:42.417Z",
  "assignee_id": 1,
  "default_ledger_account_id": null,
  "default_payment_term_id": null,
  "default_stock_location_id": null,
  "default_tax_type_id": null,
  "company_code": null,
  "company_type": "business",
  "default_discount_rate": null,
  "default_price_list_id": null,
  "default_tax_rate": null,
  "default_document_theme_id": null,
  "description": "",
  "email": null,
  "fax": null,
  "name": "B2B Test Company",
  "phone_number": null,
  "status": "active",
  "tax_number": null,
  "website": null,
  "address_ids": [
    6
  ],
  "contact_ids": [
    7
  ],
  "note_ids": [

], "default_price_type_id": null } }

Creates a new company object.

Arguments

Attribute Type Description Required
assignee_id Integer ID of the user to which new PO/SO will be assigned by default
default_ledger_account_id Integer
default_payment_term_id Integer
default_stock_location_id Integer
default_tax_type_id Integer
company_code String A unique identifier for your records
company_type String Can be ‘business’, 'supplier’ or 'consumer’ true
default_discount_rate String
default_price_list_id String
default_tax_rate deprecated String Alias to default_tax_type#effective_rate
description String
email String
fax String
name String true
phone_number String
tax_number String
website String
default_price_type_id deprecated String

HTTP Request

POST https://api.tradegecko.com/companies/

Retrieve a particular company

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Company.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/companies/1
{
  "company": {
  "id": 4,
  "created_at": "2015-11-02T01:44:42.417Z",
  "updated_at": "2015-11-02T01:44:42.417Z",
  "assignee_id": 1,
  "default_ledger_account_id": null,
  "default_payment_term_id": null,
  "default_stock_location_id": null,
  "default_tax_type_id": null,
  "company_code": null,
  "company_type": "business",
  "default_discount_rate": null,
  "default_price_list_id": null,
  "default_tax_rate": null,
  "default_document_theme_id": null,
  "description": "",
  "email": null,
  "fax": null,
  "name": "B2B Test Company",
  "phone_number": null,
  "status": "active",
  "tax_number": null,
  "website": null,
  "address_ids": [
    6
  ],
  "contact_ids": [
    7
  ],
  "note_ids": [

  ],
  "default_price_type_id": null
}
}

Retrieves the details of an existing company. You need only supply the unique company identifier that was returned upon company creation.

HTTP Request

GET https://api.tradegecko.com/companies/{RESOURCE_ID}

Update a company

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
company = gecko.Company.find(1).
company.attributes({
  rate: "12.0",
})
company.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/companies/1 -d '{"company":{"name":"Elephant","email":"hello@tradegecko.com","website":"http://tradegecko.com"}}'

Response

Returns 204 status when the company gets updated successfully.

Updates the specified company by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the company creation call.

HTTP Request

PUT https://api.tradegecko.com/companies/{RESOURCE_ID}

Delete a company

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
company = gecko.Company.find(1).
company.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/companies/1

Response

Returns 204 status when the company gets deleted successfully.

Permanently deletes a company. It cannot be undone. This company is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/companies/{RESOURCE_ID}/

Contact

This is an object representing a contact of a company. Companies can have multiple contacts but a contact object belongs to only one Company.

The Contact object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
status String Tells whether the resource is ‘active’ or 'archived’ true
company_id Integer The company id where the contact belongs.
email String
fax String
first_name String
last_name String
location String
mobile String
notes String
phone_number String
position Integer
online_ordering String Tells whether this contact has access to your B2B store
phone deprecated String

List all contacts

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Contact.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/contacts/
{
  "contacts": [
  {
    "id": 7,
    "created_at": "2015-11-02T01:44:42.483Z",
    "updated_at": "2015-11-02T01:45:17.085Z",
    "company_id": 4,
    "email": "lachlan@tradegecko.com",
    "fax": null,
    "first_name": "B2B Test Contact",
    "last_name": "",
    "location": null,
    "mobile": null,
    "notes": null,
    "phone_number": null,
    "position": null,
    "status": "active",
    "iguana_admin": true,
    "online_ordering": true,
    "invitation_accepted_at": "2015-11-02T01:45:17.082Z",
    "phone": null
  },
  {
    "id": 6,
    "created_at": "2015-11-02T01:22:25.821Z",
    "updated_at": "2015-11-02T01:33:35.379Z",
    "company_id": 1,
    "email": "lcp@tradegecko.com",
    "fax": null,
    "first_name": "lcp",
    "last_name": "Gecko",
    "location": null,
    "mobile": null,
    "notes": null,
    "phone_number": null,
    "position": null,
    "status": "active",
    "iguana_admin": null,
    "online_ordering": true,
    "invitation_accepted_at": "2015-11-02T01:33:35.377Z",
    "phone": null
  }
]
}

Returns a list of contacts you’ve previously created. The contacts are returned in sorted order, with the most recent contacts appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
status
company_id Filter contacts by company
online_ordering

HTTP Request:

GET https://api.tradegecko.com/contacts

Create a new contact

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Contact.create({:first_name=>"TradeGecko (Demo)", :company_id=>1})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/contacts/ -d '{"contact":{"first_name":"TradeGecko (Demo)","company_id":1}'}
{
  "contact": {
  "id": 7,
  "created_at": "2015-11-02T01:44:42.483Z",
  "updated_at": "2015-11-02T01:45:17.085Z",
  "company_id": 4,
  "email": "lachlan@tradegecko.com",
  "fax": null,
  "first_name": "B2B Test Contact",
  "last_name": "",
  "location": null,
  "mobile": null,
  "notes": null,
  "phone_number": null,
  "position": null,
  "status": "active",
  "iguana_admin": true,
  "online_ordering": true,
  "invitation_accepted_at": "2015-11-02T01:45:17.082Z",
  "phone": null
}
}

Creates a new contact object.

Arguments

Attribute Type Description Required
company_id Integer The company id where the contact belongs. true
email String
fax String
first_name String true
last_name String
location String
mobile String
notes String
phone_number String
position Integer
online_ordering String Tells whether this contact has access to your B2B store
phone deprecated String

HTTP Request

POST https://api.tradegecko.com/contacts/

Retrieve a particular contact

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Contact.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/contacts/1
{
  "contact": {
  "id": 7,
  "created_at": "2015-11-02T01:44:42.483Z",
  "updated_at": "2015-11-02T01:45:17.085Z",
  "company_id": 4,
  "email": "lachlan@tradegecko.com",
  "fax": null,
  "first_name": "B2B Test Contact",
  "last_name": "",
  "location": null,
  "mobile": null,
  "notes": null,
  "phone_number": null,
  "position": null,
  "status": "active",
  "iguana_admin": true,
  "online_ordering": true,
  "invitation_accepted_at": "2015-11-02T01:45:17.082Z",
  "phone": null
}
}

Retrieves the details of an existing contact. You need only supply the unique contact identifier that was returned upon contact creation.

HTTP Request

GET https://api.tradegecko.com/contacts/{RESOURCE_ID}

Update a contact

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
contact = gecko.Contact.find(1).
contact.attributes({
  rate: "12.0",
})
contact.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/contacts/1 -d '{"contact":{"last_name":"Rogers"}}'

Response

Returns 204 status when the contact gets updated successfully.

Updates the specified contact by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the contact creation call.

HTTP Request

PUT https://api.tradegecko.com/contacts/{RESOURCE_ID}

Delete a contact

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
contact = gecko.Contact.find(1).
contact.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/contacts/1

Response

Returns 204 status when the contact gets deleted successfully.

Permanently deletes a contact. It cannot be undone. This contact is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/contacts/{RESOURCE_ID}/

Currency

This is an object representing a currency.

The Currency object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
status String Tells whether the resource is ‘active’ or 'archived’ true
delimiter String
format String Uses %n (number) and %u (unit). e.g. (%u%n would appear as ’$12’)
iso String Three-character currency code
name String
precision String
rate String Exchange rate based on account’s base currency
separator String
symbol String

List all currencies

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Currency.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/currencies/
{
  "currencies": [
  {
    "id": 2,
    "created_at": "2015-11-02T01:22:23.947Z",
    "updated_at": "2015-11-02T01:22:23.947Z",
    "delimiter": ",",
    "format": "%u%n",
    "iso": "NZD",
    "name": "New Zealand Dollars",
    "precision": 2,
    "rate": "1.1",
    "separator": ".",
    "symbol": "$",
    "status": "active",
    "subunit": 100
  },
  {
    "id": 1,
    "created_at": "2015-11-02T01:22:23.947Z",
    "updated_at": "2015-11-02T01:22:23.947Z",
    "delimiter": ",",
    "format": "%u%n",
    "iso": "SGD",
    "name": "Singaporean Dollars",
    "precision": 2,
    "rate": "1.0",
    "separator": ".",
    "symbol": "$",
    "status": "active",
    "subunit": 100
  }
]
}

Returns a list of currencies you’ve previously created. The currencies are returned in sorted order, with the most recent currencies appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
status

HTTP Request:

GET https://api.tradegecko.com/currencies

Create a new currency

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Currency.create({:iso=>"USD", :precision=>4, :format=>"%n%u"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/currencies/ -d '{"currency":{"iso":"USD","precision":4,"format":"%n%u"}'}
{
  "currency": {
  "id": 2,
  "created_at": "2015-11-02T01:22:23.947Z",
  "updated_at": "2015-11-02T01:22:23.947Z",
  "delimiter": ",",
  "format": "%u%n",
  "iso": "NZD",
  "name": "New Zealand Dollars",
  "precision": 2,
  "rate": "1.1",
  "separator": ".",
  "symbol": "$",
  "status": "active",
  "subunit": 100
}
}

Creates a new currency object.

Arguments

Attribute Type Description Required
delimiter String
format String Uses %n (number) and %u (unit). e.g. (%u%n would appear as ’$12’)
iso String Three-character currency code true
name String
precision String
rate String Exchange rate based on account’s base currency
separator String
symbol String

HTTP Request

POST https://api.tradegecko.com/currencies/

Retrieve a particular currency

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Currency.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/currencies/1
{
  "currency": {
  "id": 2,
  "created_at": "2015-11-02T01:22:23.947Z",
  "updated_at": "2015-11-02T01:22:23.947Z",
  "delimiter": ",",
  "format": "%u%n",
  "iso": "NZD",
  "name": "New Zealand Dollars",
  "precision": 2,
  "rate": "1.1",
  "separator": ".",
  "symbol": "$",
  "status": "active",
  "subunit": 100
}
}

Retrieves the details of an existing currency. You need only supply the unique currency identifier that was returned upon currency creation.

HTTP Request

GET https://api.tradegecko.com/currencies/{RESOURCE_ID}

Update a currency

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
currency = gecko.Currency.find(1).
currency.attributes({
  rate: "12.0",
})
currency.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/currencies/1 -d '{"currency":{"separator":"."}}'

Response

Returns 204 status when the currency gets updated successfully.

Updates the specified currency by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the currency creation call.

HTTP Request

PUT https://api.tradegecko.com/currencies/{RESOURCE_ID}

Delete a currency

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
currency = gecko.Currency.find(1).
currency.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/currencies/1

Response

Returns 204 status when the currency gets deleted successfully.

Permanently deletes a currency. It cannot be undone. This currency is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/currencies/{RESOURCE_ID}/

Fulfillment

This is an object representing a fulfillment.

The Fulfillment object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
order_id Integer The order to which the fulfillment belongs.
shipping_address_id Integer The shipping address for the fulfillment
billing_address_id Integer The billing address for the fulfillment.
stock_location_id Integer The stock location where stock will be withdrawn from.
delivery_type String
exchange_rate String Currency exchange_rate at time of creation
notes String
packed_at String
received_at String
service String Dictates the service where this fulfillment was handled
shipped_at String
status String One of packed or fulfilled. Will update to deleted or void if deleted, respectively.
tracking_company String Service that is providing fulfillment
tracking_number String Tracking number provided by tracking company
tracking_url String Link to tracking info
order_number String Order Number of associated order true
company_id Integer true
fulfillment_line_item_ids Array true

List all fulfillments

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Fulfillment.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillments/
{
  "fulfillments": [
  {
    "id": 1,
    "created_at": "2015-11-02T01:22:25.524Z",
    "updated_at": "2015-11-02T01:22:25.524Z",
    "order_id": 2,
    "shipping_address_id": 1,
    "billing_address_id": 1,
    "stock_location_id": 1,
    "delivery_type": null,
    "exchange_rate": "1.0",
    "notes": null,
    "packed_at": "2015-11-02",
    "receipt": {
    },
    "received_at": "2015-11-02T00:00:00.000Z",
    "service": null,
    "shipped_at": "2015-11-02T00:00:00.000Z",
    "status": "packed",
    "tracking_company": null,
    "tracking_number": null,
    "tracking_url": null,
    "order_number": "SO0002",
    "company_id": 1,
    "fulfillment_line_item_ids": [
      3,
      2,
      1
    ]
  }
]
}

Returns a list of fulfillments you’ve previously created. The fulfillments are returned in sorted order, with the most recent fulfillments appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
order_id
shipping_address_id
billing_address_id
stock_location_id
receipt Used by Shopify
status
company_id

HTTP Request:

GET https://api.tradegecko.com/fulfillments

Create a new fulfillment

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Fulfillment.create({:order_id=>1, :packed_at=>"Time.now", :billing_address_id=>1, :shipping_address_id=>1})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillments/ -d '{"fulfillment":{"order_id":1,"packed_at":"Time.now","billing_address_id":1,"shipping_address_id":1}'}
{
  "fulfillment": {
  "id": 1,
  "created_at": "2015-11-02T01:22:25.524Z",
  "updated_at": "2015-11-02T01:22:25.524Z",
  "order_id": 2,
  "shipping_address_id": 1,
  "billing_address_id": 1,
  "stock_location_id": 1,
  "delivery_type": null,
  "exchange_rate": "1.0",
  "notes": null,
  "packed_at": "2015-11-02",
  "receipt": {
  },
  "received_at": "2015-11-02T00:00:00.000Z",
  "service": null,
  "shipped_at": "2015-11-02T00:00:00.000Z",
  "status": "packed",
  "tracking_company": null,
  "tracking_number": null,
  "tracking_url": null,
  "order_number": "SO0002",
  "company_id": 1,
  "fulfillment_line_item_ids": [
    3,
    2,
    1
  ]
}
}

Creates a new fulfillment object. This endpoint also accepts embedded fulfillment_line_items.

Arguments

Attribute Type Description Required
order_id Integer The order to which the fulfillment belongs. true
shipping_address_id Integer The shipping address for the fulfillment
billing_address_id Integer The billing address for the fulfillment.
stock_location_id Integer The stock location where stock will be withdrawn from.
delivery_type String
exchange_rate String Currency exchange_rate at time of creation
notes String
packed_at String
received_at String
service String Dictates the service where this fulfillment was handled
shipped_at String
status String One of packed or fulfilled. Will update to deleted or void if deleted, respectively.
tracking_company String Service that is providing fulfillment
tracking_number String Tracking number provided by tracking company
tracking_url String Link to tracking info

FulfillmentLineItem

Child Attribute Type Description Required
fulfillment_id Integer The fulfillment to which the fulfillment_line_item belongs. true
order_line_item_id Integer The order_line_item to which the fulfillment_line_item belongs. true
base_price String
position Integer
quantity String true

HTTP Request

POST https://api.tradegecko.com/fulfillments/

Retrieve a particular fulfillment

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Fulfillment.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillments/1
{
  "fulfillment": {
  "id": 1,
  "created_at": "2015-11-02T01:22:25.524Z",
  "updated_at": "2015-11-02T01:22:25.524Z",
  "order_id": 2,
  "shipping_address_id": 1,
  "billing_address_id": 1,
  "stock_location_id": 1,
  "delivery_type": null,
  "exchange_rate": "1.0",
  "notes": null,
  "packed_at": "2015-11-02",
  "receipt": {
  },
  "received_at": "2015-11-02T00:00:00.000Z",
  "service": null,
  "shipped_at": "2015-11-02T00:00:00.000Z",
  "status": "packed",
  "tracking_company": null,
  "tracking_number": null,
  "tracking_url": null,
  "order_number": "SO0002",
  "company_id": 1,
  "fulfillment_line_item_ids": [
    3,
    2,
    1
  ]
}
}

Retrieves the details of an existing fulfillment. You need only supply the unique fulfillment identifier that was returned upon fulfillment creation.

HTTP Request

GET https://api.tradegecko.com/fulfillments/{RESOURCE_ID}

Update a fulfillment

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
fulfillment = gecko.Fulfillment.find(1).
fulfillment.attributes({
  rate: "12.0",
})
fulfillment.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillments/1 -d '{"fulfillment":{"tracking_company":"GeckoShip","tracking_number":"123TrackMe"}}'

Response

Returns 204 status when the fulfillment gets updated successfully.

Updates the specified fulfillment by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the fulfillment creation call.

HTTP Request

PUT https://api.tradegecko.com/fulfillments/{RESOURCE_ID}

Delete a fulfillment

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
fulfillment = gecko.Fulfillment.find(1).
fulfillment.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillments/1

Response

Returns 204 status when the fulfillment gets deleted successfully.

Permanently deletes a fulfillment. It cannot be undone. This fulfillment is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/fulfillments/{RESOURCE_ID}/

FulfillmentLineItem

This is an object representing a fulfillment_line_item of a fulfillment. Fulfillments can have multiple fulfillment_line_items but a fulfillment_line_item object belongs to only one Fulfillment.

The FulfillmentLineItem object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
fulfillment_id Integer The fulfillment to which the fulfillment_line_item belongs.
order_line_item_id Integer The order_line_item to which the fulfillment_line_item belongs.
base_price String true
position Integer
quantity String

List all fulfillment_line_items

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.FulfillmentLineItem.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_line_items/
{
  "fulfillment_line_items": [
  {
    "id": 3,
    "created_at": "2015-11-02T01:22:25.535Z",
    "updated_at": "2015-11-02T01:22:25.535Z",
    "fulfillment_id": 1,
    "order_line_item_id": 4,
    "base_price": null,
    "position": 1,
    "quantity": "1.0"
  },
  {
    "id": 2,
    "created_at": "2015-11-02T01:22:25.533Z",
    "updated_at": "2015-11-02T01:22:25.533Z",
    "fulfillment_id": 1,
    "order_line_item_id": 5,
    "base_price": null,
    "position": 2,
    "quantity": "2.0"
  },
  {
    "id": 1,
    "created_at": "2015-11-02T01:22:25.531Z",
    "updated_at": "2015-11-02T01:22:25.531Z",
    "fulfillment_id": 1,
    "order_line_item_id": 6,
    "base_price": null,
    "position": 3,
    "quantity": "2.0"
  }
]
}

Returns a list of fulfillment_line_items you’ve previously created. The fulfillment_line_items are returned in sorted order, with the most recent fulfillment_line_items appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
fulfillment_id Filter fulfillment_line_items by fulfillment
order_line_item_id Filter fulfillment_line_items by order_line_item
base_price Sales value of the variant in base currency at fulfillment shipped_at date
position
quantity

HTTP Request:

GET https://api.tradegecko.com/fulfillment_line_items

Create a new fulfillment_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.FulfillmentLineItem.create({:fulfillment_id=>1, :order_line_item_id=>1, :quantity=>"10.0", :position=>1})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_line_items/ -d '{"fulfillment_line_item":{"fulfillment_id":1,"order_line_item_id":1,"quantity":"10.0","position":1}'}
{
  "fulfillment_line_item": {
  "id": 3,
  "created_at": "2015-11-02T01:22:25.535Z",
  "updated_at": "2015-11-02T01:22:25.535Z",
  "fulfillment_id": 1,
  "order_line_item_id": 4,
  "base_price": null,
  "position": 1,
  "quantity": "1.0"
}
}

Creates a new fulfillment_line_item object.

Arguments

Attribute Type Description Required
fulfillment_id Integer The fulfillment to which the fulfillment_line_item belongs. true
order_line_item_id Integer The order_line_item to which the fulfillment_line_item belongs. true
base_price String
position Integer
quantity String true

HTTP Request

POST https://api.tradegecko.com/fulfillment_line_items/

Retrieve a particular fulfillment_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.FulfillmentLineItem.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_line_items/1
{
  "fulfillment_line_item": {
  "id": 3,
  "created_at": "2015-11-02T01:22:25.535Z",
  "updated_at": "2015-11-02T01:22:25.535Z",
  "fulfillment_id": 1,
  "order_line_item_id": 4,
  "base_price": null,
  "position": 1,
  "quantity": "1.0"
}
}

Retrieves the details of an existing fulfillment_line_item. You need only supply the unique fulfillment_line_item identifier that was returned upon fulfillment_line_item creation.

HTTP Request

GET https://api.tradegecko.com/fulfillment_line_items/{RESOURCE_ID}

Update a fulfillment_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
fulfillment_line_item = gecko.FulfillmentLineItem.find(1).
fulfillment_line_item.attributes({
  rate: "12.0",
})
fulfillment_line_item.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_line_items/1 -d '{"fulfillment_line_item":{"quantity":"22.0"}}'

Response

Returns 204 status when the fulfillment_line_item gets updated successfully.

Updates the specified fulfillment_line_item by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the fulfillment_line_item creation call.

HTTP Request

PUT https://api.tradegecko.com/fulfillment_line_items/{RESOURCE_ID}

Delete a fulfillment_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
fulfillment_line_item = gecko.FulfillmentLineItem.find(1).
fulfillment_line_item.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_line_items/1

Response

Returns 204 status when the fulfillment_line_item gets deleted successfully.

Permanently deletes a fulfillment_line_item. It cannot be undone. This fulfillment_line_item is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/fulfillment_line_items/{RESOURCE_ID}/

Image

This is an object representing an image of a variant. Variants can have multiple images but an image object belongs to only one Variant.

The Image object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
variant_id Integer The variant to which the image belongs.
uploader_id Integer Identifier of the creating user or Integration (e.g. ‘Shopify’) true
name String Name of the file if changed
position Integer true
base_path String Base URL where image has been uploaded true
file_name String Parsed name of the file true
versions String An array of image sizes true
image_processing String Tells whether image sizes have been generated true
url String URL of image for fetching

List all images

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Image.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/images/
{
  "images": [
  {
    "id": 2,
    "variant_id": 1,
    "uploader_id": 1,
    "name": "",
    "position": 1,
    "base_path": "https://tradegecko-development-images.s3.amazonaws.com/uploads/variant_image/image/2231",
    "file_name": "1xUh3yT8SN6SjK6l1WXw_photo_large.png",
    "versions": [
      "thumbnail",
      "medium"
    ]
  },
  {
    "id": 1,
    "variant_id": 1,
    "uploader_id": 1,
    "name": null,
    "position": 1,
    "base_path": "https://tradegecko-development-images.s3.amazonaws.com/uploads/variant_image/image/2229",
    "file_name": "shw005a_4.jpg",
    "versions": [
      "thumbnail",
      "medium"
    ],
    "image_processing": true
  }
]
}

Returns a list of images you’ve previously created. The images are returned in sorted order, with the most recent images appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
variant_id Filter images by variant
uploader_id Filter images by uploader

HTTP Request:

GET https://api.tradegecko.com/images

Create a new image

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Image.create({:variant_id=>1, :url=>"http://www.thisismyimage.com/image.png"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/images/ -d '{"image":{"variant_id":1,"url":"http://www.thisismyimage.com/image.png"}'}
{
  "image": {
  "id": 2,
  "variant_id": 1,
  "uploader_id": 1,
  "name": "",
  "position": 1,
  "base_path": "https://tradegecko-development-images.s3.amazonaws.com/uploads/variant_image/image/2231",
  "file_name": "1xUh3yT8SN6SjK6l1WXw_photo_large.png",
  "versions": [
    "thumbnail",
    "medium"
  ]
}
}

Creates a new image object.

Arguments

Attribute Type Description Required
variant_id Integer The variant to which the image belongs. true
url String URL of image for fetching true

HTTP Request

POST https://api.tradegecko.com/images/

Retrieve a particular image

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Image.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/images/1
{
  "image": {
  "id": 2,
  "variant_id": 1,
  "uploader_id": 1,
  "name": "",
  "position": 1,
  "base_path": "https://tradegecko-development-images.s3.amazonaws.com/uploads/variant_image/image/2231",
  "file_name": "1xUh3yT8SN6SjK6l1WXw_photo_large.png",
  "versions": [
    "thumbnail",
    "medium"
  ]
}
}

Retrieves the details of an existing image. You need only supply the unique image identifier that was returned upon image creation.

HTTP Request

GET https://api.tradegecko.com/images/{RESOURCE_ID}

Delete an image

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
image = gecko.Image.find(1).
image.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/images/1

Response

Returns 204 status when the image gets deleted successfully.

Permanently deletes an image. It cannot be undone. This image is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/images/{RESOURCE_ID}/

Invoice

This is an object representing an invoice.

The Invoice object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
order_id Integer The order to which the invoice belongs.
shipping_address_id Integer The shipping address for the invoice.
billing_address_id Integer The billing address for the invoice.
payment_term_id Integer
due_at String
exchange_rate String
invoice_number String
invoiced_at String
notes String
cached_total String true
payment_status String true
order_number String true
company_id Integer true
currency_id Integer true
invoice_line_item_ids Array true
payment_ids Array true

List all invoices

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Invoice.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/invoices/
{
  "invoices": [
  {
    "id": 1,
    "created_at": "2015-11-02T01:22:25.408Z",
    "updated_at": "2015-11-02T01:22:25.408Z",
    "document_url": "http://localhost:3000/d/-34nGV_4zRUNysT7LE3mAaUN",
    "order_id": 2,
    "shipping_address_id": 1,
    "billing_address_id": 1,
    "payment_term_id": null,
    "due_at": "2015-11-02",
    "exchange_rate": "1.0",
    "invoice_number": "SO0002",
    "invoiced_at": "2015-11-02",
    "notes": null,
    "cached_total": "102.0",
    "payment_status": "unpaid",
    "order_number": "SO0002",
    "company_id": 1,
    "currency_id": 1,
    "status": "active",
    "invoice_line_item_ids": [
      3,
      2,
      1
    ],
    "payment_ids": [

    ],
    "refund_ids": [

    ]
  }
]
}

Returns a list of invoices you’ve previously created. The invoices are returned in sorted order, with the most recent invoices appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
order_id
shipping_address_id
billing_address_id
payment_term_id
invoice_number
payment_status
company_id
currency_id

HTTP Request:

GET https://api.tradegecko.com/invoices

Create a new invoice

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Invoice.create({:order_id=>1, :billing_address_id=>1, :shipping_address_id=>1, :invoice_line_items=>[]})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/invoices/ -d '{"invoice":{"order_id":1,"billing_address_id":1,"shipping_address_id":1,"invoice_line_items":[]}'}
{
  "invoice": {
  "id": 1,
  "created_at": "2015-11-02T01:22:25.408Z",
  "updated_at": "2015-11-02T01:22:25.408Z",
  "document_url": "http://localhost:3000/d/-34nGV_4zRUNysT7LE3mAaUN",
  "order_id": 2,
  "shipping_address_id": 1,
  "billing_address_id": 1,
  "payment_term_id": null,
  "due_at": "2015-11-02",
  "exchange_rate": "1.0",
  "invoice_number": "SO0002",
  "invoiced_at": "2015-11-02",
  "notes": null,
  "cached_total": "102.0",
  "payment_status": "unpaid",
  "order_number": "SO0002",
  "company_id": 1,
  "currency_id": 1,
  "status": "active",
  "invoice_line_item_ids": [
    3,
    2,
    1
  ],
  "payment_ids": [

], "refund_ids": [

] } }

Creates a new invoice object. This endpoint also accepts embedded invoice_line_items.

Arguments

Attribute Type Description Required
order_id Integer The order to which the invoice belongs. true
shipping_address_id Integer The shipping address for the invoice.
billing_address_id Integer The billing address for the invoice.
payment_term_id Integer
due_at String
exchange_rate String
invoice_number String
invoiced_at String
notes String

InvoiceLineItem

Child Attribute Type Description Required
invoice_id Integer The invoice to which the invoice_line_item belongs. true
order_line_item_id Integer The order_line_item to which the invoice_line_item belongs. true
position Integer
quantity String true

HTTP Request

POST https://api.tradegecko.com/invoices/

Retrieve a particular invoice

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Invoice.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/invoices/1
{
  "invoice": {
  "id": 1,
  "created_at": "2015-11-02T01:22:25.408Z",
  "updated_at": "2015-11-02T01:22:25.408Z",
  "document_url": "http://localhost:3000/d/-34nGV_4zRUNysT7LE3mAaUN",
  "order_id": 2,
  "shipping_address_id": 1,
  "billing_address_id": 1,
  "payment_term_id": null,
  "due_at": "2015-11-02",
  "exchange_rate": "1.0",
  "invoice_number": "SO0002",
  "invoiced_at": "2015-11-02",
  "notes": null,
  "cached_total": "102.0",
  "payment_status": "unpaid",
  "order_number": "SO0002",
  "company_id": 1,
  "currency_id": 1,
  "status": "active",
  "invoice_line_item_ids": [
    3,
    2,
    1
  ],
  "payment_ids": [

  ],
  "refund_ids": [

  ]
}
}

Retrieves the details of an existing invoice. You need only supply the unique invoice identifier that was returned upon invoice creation.

HTTP Request

GET https://api.tradegecko.com/invoices/{RESOURCE_ID}

Update an invoice

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
invoice = gecko.Invoice.find(1).
invoice.attributes({
  rate: "12.0",
})
invoice.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/invoices/1 -d '{"invoice":{"billing_address_id":2,"payment_term_id":1}}'

Response

Returns 204 status when the invoice gets updated successfully.

Updates the specified invoice by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the invoice creation call.

HTTP Request

PUT https://api.tradegecko.com/invoices/{RESOURCE_ID}

Delete an invoice

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
invoice = gecko.Invoice.find(1).
invoice.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/invoices/1

Response

Returns 204 status when the invoice gets deleted successfully.

Permanently deletes an invoice. It cannot be undone. This invoice is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/invoices/{RESOURCE_ID}/

InvoiceLineItem

This is an object representing an invoice_line_item of an invoice. Invoices can have multiple invoice_line_items but an invoice_line_item object belongs to only one Invoice.

The InvoiceLineItem object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
invoice_id Integer The invoice to which the invoice_line_item belongs.
order_line_item_id Integer The order_line_item to which the invoice_line_item belongs.
position Integer
quantity String

List all invoice_line_items

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.InvoiceLineItem.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/invoice_line_items/
{
  "invoice_line_items": [
  {
    "id": 3,
    "created_at": "2015-11-02T01:22:25.427Z",
    "updated_at": "2015-11-02T01:22:25.427Z",
    "invoice_id": 1,
    "order_line_item_id": 4,
    "ledger_account_id": null,
    "position": 1,
    "quantity": "1.0"
  },
  {
    "id": 2,
    "created_at": "2015-11-02T01:22:25.424Z",
    "updated_at": "2015-11-02T01:22:25.424Z",
    "invoice_id": 1,
    "order_line_item_id": 5,
    "ledger_account_id": null,
    "position": 2,
    "quantity": "2.0"
  },
  {
    "id": 1,
    "created_at": "2015-11-02T01:22:25.420Z",
    "updated_at": "2015-11-02T01:22:25.420Z",
    "invoice_id": 1,
    "order_line_item_id": 6,
    "ledger_account_id": null,
    "position": 3,
    "quantity": "2.0"
  }
]
}

Returns a list of invoice_line_items you’ve previously created. The invoice_line_items are returned in sorted order, with the most recent invoice_line_items appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
invoice_id Filter invoice_line_items by invoice
order_line_item_id Filter invoice_line_items by order_line_item
base_price Sales value of the variant in base currency at invoice shipped_at date
position
quantity

HTTP Request:

GET https://api.tradegecko.com/invoice_line_items

Create a new invoice_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.InvoiceLineItem.create({:invoice_id=>1, :order_line_item_id=>1, :quantity=>"10.0", :position=>1})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/invoice_line_items/ -d '{"invoice_line_item":{"invoice_id":1,"order_line_item_id":1,"quantity":"10.0","position":1}'}
{
  "invoice_line_item": {
  "id": 3,
  "created_at": "2015-11-02T01:22:25.427Z",
  "updated_at": "2015-11-02T01:22:25.427Z",
  "invoice_id": 1,
  "order_line_item_id": 4,
  "ledger_account_id": null,
  "position": 1,
  "quantity": "1.0"
}
}

Creates a new invoice_line_item object.

Arguments

Attribute Type Description Required
invoice_id Integer The invoice to which the invoice_line_item belongs. true
order_line_item_id Integer The order_line_item to which the invoice_line_item belongs. true
position Integer
quantity String true

HTTP Request

POST https://api.tradegecko.com/invoice_line_items/

Retrieve a particular invoice_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.InvoiceLineItem.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/invoice_line_items/1
{
  "invoice_line_item": {
  "id": 3,
  "created_at": "2015-11-02T01:22:25.427Z",
  "updated_at": "2015-11-02T01:22:25.427Z",
  "invoice_id": 1,
  "order_line_item_id": 4,
  "ledger_account_id": null,
  "position": 1,
  "quantity": "1.0"
}
}

Retrieves the details of an existing invoice_line_item. You need only supply the unique invoice_line_item identifier that was returned upon invoice_line_item creation.

HTTP Request

GET https://api.tradegecko.com/invoice_line_items/{RESOURCE_ID}

Update an invoice_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
invoice_line_item = gecko.InvoiceLineItem.find(1).
invoice_line_item.attributes({
  rate: "12.0",
})
invoice_line_item.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/invoice_line_items/1 -d '{"invoice_line_item":{"quantity":"22.0"}}'

Response

Returns 204 status when the invoice_line_item gets updated successfully.

Updates the specified invoice_line_item by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the invoice_line_item creation call.

HTTP Request

PUT https://api.tradegecko.com/invoice_line_items/{RESOURCE_ID}

Delete an invoice_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
invoice_line_item = gecko.InvoiceLineItem.find(1).
invoice_line_item.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/invoice_line_items/1

Response

Returns 204 status when the invoice_line_item gets deleted successfully.

Permanently deletes an invoice_line_item. It cannot be undone. This invoice_line_item is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/invoice_line_items/{RESOURCE_ID}/

Location

This is an object representing a location.

The Location object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
status String Tells whether the resource is ‘active’ or 'archived’ true
address1 String
address2 String
city String
country String Two letter country code (e.g. SG, US)
holds_stock String Tells whether location is a warehouse
label String
state String
suburb String
zip_code String

List all locations

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Location.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/locations/
{
  "locations": [
  {
    "id": 2,
    "created_at": "2015-11-02T01:22:24.335Z",
    "updated_at": "2015-11-02T01:22:24.335Z",
    "address1": null,
    "address2": null,
    "city": null,
    "country": "NZ",
    "holds_stock": true,
    "label": "Secondary Location",
    "state": null,
    "status": "active",
    "suburb": null,
    "zip_code": null
  },
  {
    "id": 1,
    "created_at": "2015-11-02T01:22:24.335Z",
    "updated_at": "2015-11-02T01:22:24.335Z",
    "address1": null,
    "address2": null,
    "city": null,
    "country": "NZ",
    "holds_stock": true,
    "label": "Primary Location",
    "state": null,
    "status": "active",
    "suburb": null,
    "zip_code": null
  }
]
}

Returns a list of locations you’ve previously created. The locations are returned in sorted order, with the most recent locations appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
status

HTTP Request:

GET https://api.tradegecko.com/locations

Create a new location

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Location.create({:label=>"Secondary office", :address1=>"887 Orchard Road", :country=>"Singapore"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/locations/ -d '{"location":{"label":"Secondary office","address1":"887 Orchard Road","country":"Singapore"}'}
{
  "location": {
  "id": 2,
  "created_at": "2015-11-02T01:22:24.335Z",
  "updated_at": "2015-11-02T01:22:24.335Z",
  "address1": null,
  "address2": null,
  "city": null,
  "country": "NZ",
  "holds_stock": true,
  "label": "Secondary Location",
  "state": null,
  "status": "active",
  "suburb": null,
  "zip_code": null
}
}

Creates a new location object.

Arguments

Attribute Type Description Required
address1 String true
address2 String
city String
country String Two letter country code (e.g. SG, US) true
holds_stock String Tells whether location is a warehouse
label String true
state String
suburb String
zip_code String

HTTP Request

POST https://api.tradegecko.com/locations/

Retrieve a particular location

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Location.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/locations/1
{
  "location": {
  "id": 2,
  "created_at": "2015-11-02T01:22:24.335Z",
  "updated_at": "2015-11-02T01:22:24.335Z",
  "address1": null,
  "address2": null,
  "city": null,
  "country": "NZ",
  "holds_stock": true,
  "label": "Secondary Location",
  "state": null,
  "status": "active",
  "suburb": null,
  "zip_code": null
}
}

Retrieves the details of an existing location. You need only supply the unique location identifier that was returned upon location creation.

HTTP Request

GET https://api.tradegecko.com/locations/{RESOURCE_ID}

Update a location

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
location = gecko.Location.find(1).
location.attributes({
  rate: "12.0",
})
location.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/locations/1 -d '{"location":{"address1":"121 Telok Ayer Street"}}'

Response

Returns 204 status when the location gets updated successfully.

Updates the specified location by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the location creation call.

HTTP Request

PUT https://api.tradegecko.com/locations/{RESOURCE_ID}

Delete a location

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
location = gecko.Location.find(1).
location.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/locations/1

Response

Returns 204 status when the location gets deleted successfully.

Permanently deletes a location. It cannot be undone. This location is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/locations/{RESOURCE_ID}/

Note

This is an object representing a note of a company. Companies can have multiple notes but a note object belongs to only one Company.

The Note object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
company_id Integer The company id where the address belongs.
user_id Integer The user id of the author of the note. true
body String

List all notes

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Note.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/notes/
{
  "notes": [
  {
    "id": 3,
    "created_at": "2015-11-13T08:29:32.741Z",
    "updated_at": "2015-11-13T08:29:32.741Z",
    "company_id": 4,
    "user_id": 1,
    "body": "90% discount, right? They are the best."
  },
  {
    "id": 2,
    "created_at": "2015-11-13T08:29:23.837Z",
    "updated_at": "2015-11-13T08:29:23.837Z",
    "company_id": 4,
    "user_id": 1,
    "body": "Working with them has been a real pleasure."
  }
]
}

Returns a list of notes you’ve previously created. The notes are returned in sorted order, with the most recent notes appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
company_id Filter addresses by company
user_id Filter addresses by user

HTTP Request:

GET https://api.tradegecko.com/notes

Create a new note

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Note.create({:company_id=>1, :body=>"These kittens are adorable."})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/notes/ -d '{"note":{"company_id":1,"body":"These kittens are adorable."}'}
{
  "note": {
  "id": 3,
  "created_at": "2015-11-13T08:29:32.741Z",
  "updated_at": "2015-11-13T08:29:32.741Z",
  "company_id": 4,
  "user_id": 1,
  "body": "90% discount, right? They are the best."
}
}

Creates a new note object.

Arguments

Attribute Type Description Required
company_id Integer The company id where the address belongs. true
body String

HTTP Request

POST https://api.tradegecko.com/notes/

Retrieve a particular note

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Note.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/notes/1
{
  "note": {
  "id": 3,
  "created_at": "2015-11-13T08:29:32.741Z",
  "updated_at": "2015-11-13T08:29:32.741Z",
  "company_id": 4,
  "user_id": 1,
  "body": "90% discount, right? They are the best."
}
}

Retrieves the details of an existing note. You need only supply the unique note identifier that was returned upon note creation.

HTTP Request

GET https://api.tradegecko.com/notes/{RESOURCE_ID}

Update a note

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
note = gecko.Note.find(1).
note.attributes({
  rate: "12.0",
})
note.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/notes/1 -d '{"note":{"body":"Cupcakes are for champions"}}'

Response

Returns 204 status when the note gets updated successfully.

Updates the specified note by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the note creation call.

HTTP Request

PUT https://api.tradegecko.com/notes/{RESOURCE_ID}

Delete a note

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
note = gecko.Note.find(1).
note.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/notes/1

Response

Returns 204 status when the note gets deleted successfully.

Permanently deletes a note. It cannot be undone. This note is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/notes/{RESOURCE_ID}/

Order

This is an object representing an order.

The Order object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
assignee_id Integer The assignee to which the order belongs.
issued_at String Issue date for the order
ship_at String Ship date for the order.
billing_address_id Integer
company_id Integer
contact_id Integer
currency_id Integer
shipping_address_id Integer
stock_location_id Integer
user_id Integer true
source_id String Internal ID of the OAuth application that created the order (if not via web interface) true
default_price_list_id String
document_url String Shareable URL for resource document true
email String
notes String
order_number String
phone_number String
reference_number String A reference for the order that isn’t the order_number
source_url String
tags Array Reference tags for the order, used in filtering.
tax_treatment String One of ‘exclusive’ or 'inclusive’, if not provided defaults to account default.
total String true
status String Signifies the current state of the order, can be set as 'draft’, 'active’ or 'finalized’
payment_status String true
invoice_status String true
packed_status String true
fulfillment_status String true
return_status String true
returning_status String true
shippability_status String true
backordering_status String true
fulfillment_ids Array true
invoice_ids Array true
fulfillment_return_ids Array true
payment_ids Array true
refund_ids Array true
invoices Array true
invoice_numbers Hash true
order_line_item_ids Array true

List all orders

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Order.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/orders/
{
  "orders": [
  {
    "id": 2,
    "created_at": "2015-11-12T08:06:01.561Z",
    "updated_at": "2015-11-12T08:06:01.561Z",
    "document_url": "http://api.lvh.me:3000/d/not-a-real-token-2",
    "assignee_id": "nil",
    "billing_address_id": 1,
    "company_id": 1,
    "contact_id": "nil",
    "currency_id": 1,
    "shipping_address_id": 1,
    "stock_location_id": 1,
    "user_id": 1,
    "default_price_list_id": "retail",
    "email": "example@tradegecko.com",
    "fulfillment_status": "unshipped",
    "invoice_status": "uninvoiced",
    "issued_at": "2015-11-12",
    "notes": "nil",
    "order_number": "SO0001",
    "packed_status": "unpacked",
    "payment_status": "unpaid",
    "phone_number": "+1 650-468-2904",
    "reference_number": "nil",
    "return_status": "unreturned",
    "returning_status": "unreturning",
    "ship_at": "nil",
    "source_url": "nil",
    "status": "draft",
    "tax_label": "GST",
    "tax_override": "nil",
    "tax_treatment": "inclusive",
    "total": 0,
    "tags": [

    ],
    "fulfillment_ids": [

    ],
    "fulfillment_return_ids": [

    ],
    "invoice_ids": [

    ],
    "payment_ids": [

    ],
    "refund_ids": [

    ],
    "invoices": [

    ],
    "cached_total": 0,
    "default_price_type_id": "wholesale",
    "source": "nil",
    "tax_type": "exclusive",
    "tracking_number": "nil",
    "url": "nil",
    "source_id": "nil",
    "invoice_numbers": {
      "1": "INV001"
    },
    "order_line_item_ids": [
      1,
      2
    ]
  },
  {
    "id": 1,
    "created_at": "2015-11-12T08:06:00.561Z",
    "updated_at": "2015-11-12T08:06:00.561Z",
    "document_url": "http://api.lvh.me:3000/d/not-a-real-token",
    "assignee_id": "nil",
    "billing_address_id": 1,
    "company_id": 1,
    "contact_id": "nil",
    "currency_id": 1,
    "shipping_address_id": 1,
    "stock_location_id": 1,
    "user_id": 1,
    "default_price_list_id": "wholesale",
    "email": "example@tradegecko.com",
    "fulfillment_status": "unshipped",
    "invoice_status": "uninvoiced",
    "issued_at": "2015-11-12",
    "notes": "nil",
    "order_number": "SO0001",
    "packed_status": "unpacked",
    "payment_status": "unpaid",
    "phone_number": "+1 650-468-2904",
    "reference_number": "nil",
    "return_status": "unreturned",
    "returning_status": "unreturning",
    "ship_at": "nil",
    "source_url": "nil",
    "status": "draft",
    "tax_label": "GST",
    "tax_override": "nil",
    "tax_treatment": "exclusive",
    "total": 0,
    "tags": [

    ],
    "fulfillment_ids": [

    ],
    "fulfillment_return_ids": [

    ],
    "invoice_ids": [

    ],
    "payment_ids": [

    ],
    "refund_ids": [

    ],
    "invoices": [

    ],
    "cached_total": 0,
    "default_price_type_id": "wholesale",
    "source": "nil",
    "tax_type": "exclusive",
    "tracking_number": "nil",
    "url": "nil",
    "source_id": "nil",
    "invoice_numbers": {
      "1": "INV001"
    },
    "order_line_item_ids": [

    ]
  }
]
}

Returns a list of orders you’ve previously created. The orders are returned in sorted order, with the most recent orders appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
assignee_id Filter orders by assignee
billing_address_id
company_id
contact_id
currency_id
shipping_address_id
stock_location_id
user_id
source_id Internal ID of the OAuth application that created the order (if not via web interface)
order_number
tags
payment_status e.g. unpaid, partial or paid
invoice_status e.g. uninvoiced, partial or invoiced
packed_status e.g. unpacked, partial or packed
fulfillment_status e.g. unshipped, partial or shipped
return_status e.g. unreturned, partial or returned
returning_status e.g. unreturning, partial or returning
shippability_status e.g. not_shippable, partially_shippable or shippable
backordering_status e.g. not_backordered, partially_backordered or backordered

HTTP Request:

GET https://api.tradegecko.com/orders

Create a new order

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Order.create({:company_id=>1, :issued_at=>"Time.now", :billing_address_id=>1, :shipping_address_id=>1})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/orders/ -d '{"order":{"company_id":1,"issued_at":"Time.now","billing_address_id":1,"shipping_address_id":1}'}
{
  "order": {
  "id": 2,
  "created_at": "2015-11-12T08:06:01.561Z",
  "updated_at": "2015-11-12T08:06:01.561Z",
  "document_url": "http://api.lvh.me:3000/d/not-a-real-token-2",
  "assignee_id": "nil",
  "billing_address_id": 1,
  "company_id": 1,
  "contact_id": "nil",
  "currency_id": 1,
  "shipping_address_id": 1,
  "stock_location_id": 1,
  "user_id": 1,
  "default_price_list_id": "retail",
  "email": "example@tradegecko.com",
  "fulfillment_status": "unshipped",
  "invoice_status": "uninvoiced",
  "issued_at": "2015-11-12",
  "notes": "nil",
  "order_number": "SO0001",
  "packed_status": "unpacked",
  "payment_status": "unpaid",
  "phone_number": "+1 650-468-2904",
  "reference_number": "nil",
  "return_status": "unreturned",
  "returning_status": "unreturning",
  "ship_at": "nil",
  "source_url": "nil",
  "status": "draft",
  "tax_label": "GST",
  "tax_override": "nil",
  "tax_treatment": "inclusive",
  "total": 0,
  "tags": [

], "fulfillment_ids": [

], "fulfillment_return_ids": [

], "invoice_ids": [

], "payment_ids": [

], "refund_ids": [

], "invoices": [

], "cached_total": 0, "default_price_type_id": "wholesale", "source": "nil", "tax_type": "exclusive", "tracking_number": "nil", "url": "nil", "source_id": "nil", "invoice_numbers": { "1": "INV001" }, "order_line_item_ids": [ 1, 2 ] } }

Creates a new order object. This endpoint also accepts embedded order_line_items.

Arguments

Attribute Type Description Required
assignee_id Integer The assignee to which the order belongs.
issued_at String Issue date for the order true
ship_at String Ship date for the order.
billing_address_id Integer true
company_id Integer true
contact_id Integer
shipping_address_id Integer true
stock_location_id Integer
default_price_list_id String
email String
notes String
order_number String
phone_number String
reference_number String A reference for the order that isn’t the order_number
source_url String
tags Array Reference tags for the order, used in filtering.
tax_treatment String One of ‘exclusive’ or 'inclusive’, if not provided defaults to account default.
status String Signifies the current state of the order, can be set as 'draft’, 'active’ or 'finalized’

OrderLineItem

Child Attribute Type Description Required
order_id Integer The order to which the order_line_item belongs. true
variant_id Integer The variant to which the order_line_item belongs. true
tax_type_id Integer The tax_type to which the order_line_item belongs. true
discount String Between -100 and 100
freeform Boolean
image_url String
label String
line_type String
position Integer
price String true
quantity String
tax_rate_override String
tax_rate String

HTTP Request

POST https://api.tradegecko.com/orders/

Retrieve a particular order

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Order.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/orders/1
{
  "order": {
  "id": 2,
  "created_at": "2015-11-12T08:06:01.561Z",
  "updated_at": "2015-11-12T08:06:01.561Z",
  "document_url": "http://api.lvh.me:3000/d/not-a-real-token-2",
  "assignee_id": "nil",
  "billing_address_id": 1,
  "company_id": 1,
  "contact_id": "nil",
  "currency_id": 1,
  "shipping_address_id": 1,
  "stock_location_id": 1,
  "user_id": 1,
  "default_price_list_id": "retail",
  "email": "example@tradegecko.com",
  "fulfillment_status": "unshipped",
  "invoice_status": "uninvoiced",
  "issued_at": "2015-11-12",
  "notes": "nil",
  "order_number": "SO0001",
  "packed_status": "unpacked",
  "payment_status": "unpaid",
  "phone_number": "+1 650-468-2904",
  "reference_number": "nil",
  "return_status": "unreturned",
  "returning_status": "unreturning",
  "ship_at": "nil",
  "source_url": "nil",
  "status": "draft",
  "tax_label": "GST",
  "tax_override": "nil",
  "tax_treatment": "inclusive",
  "total": 0,
  "tags": [

  ],
  "fulfillment_ids": [

  ],
  "fulfillment_return_ids": [

  ],
  "invoice_ids": [

  ],
  "payment_ids": [

  ],
  "refund_ids": [

  ],
  "invoices": [

  ],
  "cached_total": 0,
  "default_price_type_id": "wholesale",
  "source": "nil",
  "tax_type": "exclusive",
  "tracking_number": "nil",
  "url": "nil",
  "source_id": "nil",
  "invoice_numbers": {
    "1": "INV001"
  },
  "order_line_item_ids": [
    1,
    2
  ]
}
}

Retrieves the details of an existing order. You need only supply the unique order identifier that was returned upon order creation.

HTTP Request

GET https://api.tradegecko.com/orders/{RESOURCE_ID}

Update an order

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
order = gecko.Order.find(1).
order.attributes({
  rate: "12.0",
})
order.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/orders/1 -d '{"order":{"status":"active","email":"hello@tradegecko.com","billing_address_id":2}}'

Response

Returns 204 status when the order gets updated successfully.

Updates the specified order by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the order creation call.

HTTP Request

PUT https://api.tradegecko.com/orders/{RESOURCE_ID}

Delete an order

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
order = gecko.Order.find(1).
order.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/orders/1

Response

Returns 204 status when the order gets deleted successfully.

Permanently deletes an order. It cannot be undone. This order is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/orders/{RESOURCE_ID}/

OrderLineItem

This is an object representing an order_line_item of an order. Orders can have multiple order_line_items but an order_line_item object belongs to only one Order.

The OrderLineItem object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
order_id Integer The order to which the order_line_item belongs.
variant_id Integer The variant to which the order_line_item belongs.
tax_type_id Integer The tax_type to which the order_line_item belongs.
discount String Between -100 and 100
freeform Boolean
image_url String
label String
line_type String
position Integer
price String
quantity String
tax_rate_override String
tax_rate String
fulfillment_line_item_ids Array true
fulfillment_return_line_item_ids Array true
invoice_line_item_ids Array true

List all order_line_items

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.OrderLineItem.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/order_line_items/
{
  "order_line_items": [
  {
    "id": 2,
    "created_at": "2015-11-12T06:39:53.231Z",
    "updated_at": "2015-11-12T06:39:53.231Z",
    "order_id": 1,
    "variant_id": 2,
    "tax_type_id": 1,
    "discount": "11.0",
    "freeform": false,
    "image_url": "nil",
    "label": "nil",
    "line_type": "nil",
    "position": 0,
    "price": "189.0",
    "quantity": "1.0",
    "tax_rate_override": "nil",
    "tax_rate": "nil",
    "fulfillment_line_item_ids": [

    ],
    "fulfillment_return_line_item_ids": [

    ],
    "invoice_line_item_ids": [

    ]
  },
  {
    "id": 1,
    "created_at": "2015-11-12T06:32:31.607Z",
    "updated_at": "2015-11-12T06:32:31.607Z",
    "order_id": 1,
    "variant_id": 1,
    "tax_type_id": 1,
    "discount": "11.0",
    "freeform": false,
    "image_url": "null",
    "label": "null",
    "line_type": "null",
    "position": 0,
    "price": "189.0",
    "quantity": "1.0",
    "tax_rate_override": "nil",
    "tax_rate": "nil",
    "fulfillment_line_item_ids": [

    ],
    "fulfillment_return_line_item_ids": [

    ],
    "invoice_line_item_ids": [

    ]
  }
]
}

Returns a list of order_line_items you’ve previously created. The order_line_items are returned in sorted order, with the most recent order_line_items appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
order_id Filter order_line_items by order
variant_id Filter order_line_items by variant
tax_type_id Filter order_line_items by tax_type

HTTP Request:

GET https://api.tradegecko.com/order_line_items

Create a new order_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.OrderLineItem.create({:quantity=>"12.0", :order_id=>1, :tax_type_id=>1, :price=>"10.0"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/order_line_items/ -d '{"order_line_item":{"quantity":"12.0","order_id":1,"tax_type_id":1,"price":"10.0"}'}
{
  "order_line_item": {
  "id": 2,
  "created_at": "2015-11-12T06:39:53.231Z",
  "updated_at": "2015-11-12T06:39:53.231Z",
  "order_id": 1,
  "variant_id": 2,
  "tax_type_id": 1,
  "discount": "11.0",
  "freeform": false,
  "image_url": "nil",
  "label": "nil",
  "line_type": "nil",
  "position": 0,
  "price": "189.0",
  "quantity": "1.0",
  "tax_rate_override": "nil",
  "tax_rate": "nil",
  "fulfillment_line_item_ids": [

], "fulfillment_return_line_item_ids": [

], "invoice_line_item_ids": [

] } }

Creates a new order_line_item object.

Arguments

Attribute Type Description Required
order_id Integer The order to which the order_line_item belongs. true
variant_id Integer The variant to which the order_line_item belongs. true
tax_type_id Integer The tax_type to which the order_line_item belongs. true
discount String Between -100 and 100
freeform Boolean
image_url String
label String
line_type String
position Integer
price String true
quantity String
tax_rate_override String
tax_rate String

HTTP Request

POST https://api.tradegecko.com/order_line_items/

Retrieve a particular order_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.OrderLineItem.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/order_line_items/1
{
  "order_line_item": {
  "id": 2,
  "created_at": "2015-11-12T06:39:53.231Z",
  "updated_at": "2015-11-12T06:39:53.231Z",
  "order_id": 1,
  "variant_id": 2,
  "tax_type_id": 1,
  "discount": "11.0",
  "freeform": false,
  "image_url": "nil",
  "label": "nil",
  "line_type": "nil",
  "position": 0,
  "price": "189.0",
  "quantity": "1.0",
  "tax_rate_override": "nil",
  "tax_rate": "nil",
  "fulfillment_line_item_ids": [

  ],
  "fulfillment_return_line_item_ids": [

  ],
  "invoice_line_item_ids": [

  ]
}
}

Retrieves the details of an existing order_line_item. You need only supply the unique order_line_item identifier that was returned upon order_line_item creation.

HTTP Request

GET https://api.tradegecko.com/order_line_items/{RESOURCE_ID}

Update an order_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
order_line_item = gecko.OrderLineItem.find(1).
order_line_item.attributes({
  rate: "12.0",
})
order_line_item.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/order_line_items/1 -d '{"order_line_item":{"quantity":"22.0","price":"12.0"}}'

Response

Returns 204 status when the order_line_item gets updated successfully.

Updates the specified order_line_item by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the order_line_item creation call.

HTTP Request

PUT https://api.tradegecko.com/order_line_items/{RESOURCE_ID}

Delete an order_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
order_line_item = gecko.OrderLineItem.find(1).
order_line_item.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/order_line_items/1

Response

Returns 204 status when the order_line_item gets deleted successfully.

Permanently deletes an order_line_item. It cannot be undone. This order_line_item is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/order_line_items/{RESOURCE_ID}/

PaymentTerm

This is an object representing a payment_term.

The PaymentTerm object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
status String Tells whether the resource is ‘active’ or 'archived’ true
name String
due_in_days String Number of days until payment is due
from String Dictates whether due_in_days starts from 'now’ or 'eom’ (end of month).

List all payment_terms

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.PaymentTerm.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/payment_terms/
{
  "payment_terms": [
  {
    "id": 3,
    "name": "NET30",
    "due_in_days": 30,
    "status": "active",
    "from": "now"
  },
  {
    "id": 2,
    "name": "NET10",
    "due_in_days": 10,
    "status": "active",
    "from": "now"
  },
  {
    "id": 1,
    "name": "Cash on Delivery",
    "due_in_days": 0,
    "status": "active",
    "from": "now"
  }
]
}

Returns a list of payment_terms you’ve previously created. The payment_terms are returned in sorted order, with the most recent payment_terms appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
status

HTTP Request:

GET https://api.tradegecko.com/payment_terms

Create a new payment_term

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.PaymentTerm.create({:name=>"NET30", :due_in_days=>"30", :from=>"eom"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/payment_terms/ -d '{"payment_term":{"name":"NET30","due_in_days":"30","from":"eom"}'}
{
  "payment_term": {
  "id": 3,
  "name": "NET30",
  "due_in_days": 30,
  "status": "active",
  "from": "now"
}
}

Creates a new payment_term object.

Arguments

Attribute Type Description Required
name String
due_in_days String Number of days until payment is due
from String Dictates whether due_in_days starts from ‘now’ or 'eom’ (end of month).

HTTP Request

POST https://api.tradegecko.com/payment_terms/

Retrieve a particular payment_term

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.PaymentTerm.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/payment_terms/1
{
  "payment_term": {
  "id": 3,
  "name": "NET30",
  "due_in_days": 30,
  "status": "active",
  "from": "now"
}
}

Retrieves the details of an existing payment_term. You need only supply the unique payment_term identifier that was returned upon payment_term creation.

HTTP Request

GET https://api.tradegecko.com/payment_terms/{RESOURCE_ID}

Update a payment_term

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
payment_term = gecko.PaymentTerm.find(1).
payment_term.attributes({
  rate: "12.0",
})
payment_term.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/payment_terms/1 -d '{"payment_term":{"from":"now"}}'

Response

Returns 204 status when the payment_term gets updated successfully.

Updates the specified payment_term by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the payment_term creation call.

HTTP Request

PUT https://api.tradegecko.com/payment_terms/{RESOURCE_ID}

Delete a payment_term

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
payment_term = gecko.PaymentTerm.find(1).
payment_term.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/payment_terms/1

Response

Returns 204 status when the payment_term gets deleted successfully.

Permanently deletes a payment_term. It cannot be undone. This payment_term is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/payment_terms/{RESOURCE_ID}/

Product

This is an object representing a product.

The Product object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
status String Tells whether the resource is ‘active’, 'disabled’ or 'archived’ true
brand String Name of the brand of the product
description String A brief description of the product
image_url String First image of children variants (sorted on position) true
name String
opt1 String Custom product property name eg. 'Size’, 'Color’
opt2 String Custom product property name eg. 'Size’, 'Color’
opt3 String Custom product property name eg. 'Size’, 'Color’
product_type String
quantity String Sum of the quantities of child variants true
supplier deprecated String Name of the supplier of the product
supplier_ids Array Should currently only be one ID for backwards compatibility purposes
tags Array Product tags for easier filtering and searching
variant_ids Array true
vendor deprecated String Will be removed very soon.

List all products

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Product.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/products/
{
  "products": [
  {
    "id": 2,
    "created_at": "2015-11-02T01:22:24.817Z",
    "updated_at": "2015-11-02T01:22:24.817Z",
    "brand": null,
    "description": "All ready for Easter, our giant golden chocolate eggs are just what the doctor ordered, adults and children alike",
    "image_url": null,
    "name": "Golden Egg",
    "opt1": "Size",
    "opt2": null,
    "opt3": null,
    "product_type": "Chocolate",
    "quantity": "32.5",
    "search_cache": "DEMO-EGG-L Large DEMO-EGG-XL Extra-Large DEMO-EGG-M Medium DEMO-EGG-S Small",
    "status": "active",
    "supplier": "Wonka Candy",
    "supplier_ids": [
      3
    ],
    "tags": "candy,chocolate",
    "variant_ids": [
      4,
      5,
      6,
      7
    ],
    "vendor": "Wonka Candy"
  },
  {
    "id": 1,
    "created_at": "2015-11-02T01:22:24.660Z",
    "updated_at": "2015-11-02T01:22:24.660Z",
    "brand": null,
    "description": "These everlasting gobstoppers will never run out. Just keep going forever and ever, full flavour guaranteed",
    "image_url": null,
    "name": "Everlasting Gobstopper",
    "opt1": "Flavour",
    "opt2": null,
    "opt3": null,
    "product_type": "Candy",
    "quantity": "17",
    "search_cache": "DEMO-GOBS-PEA Peach DEMO-GOBS-SNO Snozzberry",
    "status": "active",
    "supplier": "Wonka Candy",
    "supplier_ids": [
      3
    ],
    "tags": "candy,summer",
    "variant_ids": [
      2,
      3
    ],
    "vendor": "Wonka Candy"
  }
]
}

Returns a list of products you’ve previously created. The products are returned in sorted order, with the most recent products appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
status
brand
product_type
tags

HTTP Request:

GET https://api.tradegecko.com/products

Create a new product

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Product.create({:name=>"Everlasting Gobstopper", :opt1=>"Colour"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/products/ -d '{"product":{"name":"Everlasting Gobstopper","opt1":"Colour"}'}
{
  "product": {
  "id": 2,
  "created_at": "2015-11-02T01:22:24.817Z",
  "updated_at": "2015-11-02T01:22:24.817Z",
  "brand": null,
  "description": "All ready for Easter, our giant golden chocolate eggs are just what the doctor ordered, adults and children alike",
  "image_url": null,
  "name": "Golden Egg",
  "opt1": "Size",
  "opt2": null,
  "opt3": null,
  "product_type": "Chocolate",
  "quantity": "32.5",
  "search_cache": "DEMO-EGG-L Large DEMO-EGG-XL Extra-Large DEMO-EGG-M Medium DEMO-EGG-S Small",
  "status": "active",
  "supplier": "Wonka Candy",
  "supplier_ids": [
    3
  ],
  "tags": "candy,chocolate",
  "variant_ids": [
    4,
    5,
    6,
    7
  ],
  "vendor": "Wonka Candy"
}
}

Creates a new product object. This endpoint also accepts embedded variants.

Arguments

Attribute Type Description Required
brand String Name of the brand of the product
description String A brief description of the product
name String true
opt1 String Custom product property name eg. ‘Size’, 'Color’
opt2 String Custom product property name eg. 'Size’, 'Color’
opt3 String Custom product property name eg. 'Size’, 'Color’
product_type String
quantity String Sum of the quantities of child variants
supplier deprecated String Name of the supplier of the product
supplier_ids Array Should currently only be one ID for backwards compatibility purposes
tags Array Product tags for easier filtering and searching
vendor deprecated String Will be removed very soon.

Variant

Child Attribute Type Description Required
product_id Integer The product to which the variant belongs. true
default_ledger_account_id Integer Used for accounting integrations. (e.g. Revenue Ledger)
buy_price String
composite Boolean Tells whether this variant is a composite (composed of other variants)
description String
is_online deprecated Boolean
keep_selling Boolean Allow item to continue to be sold, even if it is no longer in stock
manage_stock Boolean
max_online String Integrated online store(s) should show current stock levels up to a maximum of this value
name String
online_ordering Boolean Tells whether variant is for sale on B2B platform
opt1 String
opt2 String
opt3 String
position String Default sort position of this variant (unique to product)
retail_price String The recommended retail price
sellable String Tells whether can be added to sales orders
sku String Stock Keeping Unit (should be unique)
supplier_code String
taxable Boolean Tells whether this variant can be taxed
upc String The barcode or UPC number
weight String The weight value
weight_unit String The weight unit (kg, gm, oz or lb)
wholesale_price String The recommended wholesale price for this product
variant_prices Array An array of prices with price list IDs and the price value.

HTTP Request

POST https://api.tradegecko.com/products/

Retrieve a particular product

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Product.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/products/1
{
  "product": {
  "id": 2,
  "created_at": "2015-11-02T01:22:24.817Z",
  "updated_at": "2015-11-02T01:22:24.817Z",
  "brand": null,
  "description": "All ready for Easter, our giant golden chocolate eggs are just what the doctor ordered, adults and children alike",
  "image_url": null,
  "name": "Golden Egg",
  "opt1": "Size",
  "opt2": null,
  "opt3": null,
  "product_type": "Chocolate",
  "quantity": "32.5",
  "search_cache": "DEMO-EGG-L Large DEMO-EGG-XL Extra-Large DEMO-EGG-M Medium DEMO-EGG-S Small",
  "status": "active",
  "supplier": "Wonka Candy",
  "supplier_ids": [
    3
  ],
  "tags": "candy,chocolate",
  "variant_ids": [
    4,
    5,
    6,
    7
  ],
  "vendor": "Wonka Candy"
}
}

Retrieves the details of an existing product. You need only supply the unique product identifier that was returned upon product creation.

HTTP Request

GET https://api.tradegecko.com/products/{RESOURCE_ID}

Update a product

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
product = gecko.Product.find(1).
product.attributes({
  rate: "12.0",
})
product.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/products/1 -d '{"product":{"opt2":"Size","opt3":"Weight"}}'

Response

Returns 204 status when the product gets updated successfully.

Updates the specified product by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the product creation call.

HTTP Request

PUT https://api.tradegecko.com/products/{RESOURCE_ID}

Delete a product

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
product = gecko.Product.find(1).
product.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/products/1

Response

Returns 204 status when the product gets deleted successfully.

Permanently deletes a product. It cannot be undone. This product is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/products/{RESOURCE_ID}/

PurchaseOrder

This is an object representing a purchase_order.

The PurchaseOrder object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
status String true
document_url String Shareable URL for resource document true
billing_address_id Integer The billing address for the purchase_order.
company_id Integer The company that will be supplying the purchase order
currency_id Integer The currency of the purchase_order
stock_location_id Integer The stock location where stock will be delivered
supplier_address_id Integer The supplier address for the purchase_order.
default_price_list_id String Default prices for the purchase_order_line_items (if the variant has a price on this Price List
due_at String
email String
notes String
order_number String
procurement_status String true
reference_number String A reference for the purchase order that isn’t the order_number
tax_treatment String One of ‘exclusive’ or 'inclusive’, if not provided defaults to account default.
received_at String true
total String true
tags String Reference tags for the purchase order, used in filtering.
cached_quantity String true
cached_total deprecated String true
default_price_type_id deprecated String
tax_type deprecated String
purchase_order_line_item_ids Array true
procurement_ids Array true

List all purchase_orders

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.PurchaseOrder.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/purchase_orders/
{
  "purchase_orders": [
  {
    "id": 2,
    "created_at": "2015-11-23T11:19:49.857Z",
    "updated_at": "2015-11-23T11:19:50.427Z",
    "status": "active",
    "document_url": "http://localhost:3000/d/gfPPrlS40mrZOGXXgmOIZcue",
    "billing_address_id": 1,
    "company_id": 3,
    "currency_id": 1,
    "stock_location_id": 1,
    "supplier_address_id": 4,
    "default_price_list_id": "buy",
    "due_at": "2015-12-07",
    "email": "william@example.com",
    "notes": null,
    "order_number": "PO0002",
    "procurement_status": "unprocured",
    "reference_number": null,
    "tax_treatment": "exclusive",
    "received_at": null,
    "total": "8.63",
    "tags": [

    ],
    "cached_quantity": "3.0",
    "cached_total": "8.63",
    "default_price_type_id": "buy",
    "tax_type": "exclusive",
    "purchase_order_line_item_ids": [
      3,
      2
    ],
    "procurement_ids": [

    ]
  },
  {
    "id": 1,
    "document_url": "http://localhost:3000/d/RHEDdlXiapBcsQ-CspVHn0i3",
    "created_at": "2015-11-23T11:19:07.072Z",
    "updated_at": "2015-11-23T11:19:07.483Z",
    "billing_address_id": 1,
    "company_id": 3,
    "currency_id": 1,
    "stock_location_id": 1,
    "supplier_address_id": 4,
    "default_price_list_id": "buy",
    "due_at": "2015-12-07",
    "email": "william@example.com",
    "notes": null,
    "order_number": "PO0001",
    "procurement_status": "unprocured",
    "reference_number": null,
    "status": "active",
    "tax_treatment": "exclusive",
    "received_at": null,
    "total": "2.88",
    "tags": [

    ],
    "cached_quantity": "1.0",
    "cached_total": "2.88",
    "default_price_type_id": "buy",
    "tax_type": "exclusive",
    "purchase_order_line_item_ids": [
      1
    ],
    "procurement_ids": [

    ]
  }
]
}

Returns a list of purchase_orders you’ve previously created. The purchase_orders are returned in sorted order, with the most recent purchase_orders appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
billing_address_id
company_id
currency_id
stock_location_id
supplier_address_id
order_number
tags

HTTP Request:

GET https://api.tradegecko.com/purchase_orders

Create a new purchase_order

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.PurchaseOrder.create({:company_id=>1, :issued_at=>"Time.now", :billing_address_id=>1, :shipping_address_id=>1})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/purchase_orders/ -d '{"purchase_order":{"company_id":1,"issued_at":"Time.now","billing_address_id":1,"shipping_address_id":1}'}
{
  "purchase_order": {
  "id": 2,
  "created_at": "2015-11-23T11:19:49.857Z",
  "updated_at": "2015-11-23T11:19:50.427Z",
  "status": "active",
  "document_url": "http://localhost:3000/d/gfPPrlS40mrZOGXXgmOIZcue",
  "billing_address_id": 1,
  "company_id": 3,
  "currency_id": 1,
  "stock_location_id": 1,
  "supplier_address_id": 4,
  "default_price_list_id": "buy",
  "due_at": "2015-12-07",
  "email": "william@example.com",
  "notes": null,
  "order_number": "PO0002",
  "procurement_status": "unprocured",
  "reference_number": null,
  "tax_treatment": "exclusive",
  "received_at": null,
  "total": "8.63",
  "tags": [

], "cached_quantity": "3.0", "cached_total": "8.63", "default_price_type_id": "buy", "tax_type": "exclusive", "purchase_order_line_item_ids": [ 3, 2 ], "procurement_ids": [

] } }

Creates a new purchase_order object. This endpoint also accepts embedded purchase_order_line_items.

Arguments

Attribute Type Description Required
status String
billing_address_id Integer The billing address for the purchase_order.
company_id Integer The company that will be supplying the purchase order true
currency_id Integer The currency of the purchase_order
stock_location_id Integer The stock location where stock will be delivered
supplier_address_id Integer The supplier address for the purchase_order.
default_price_list_id String Default prices for the purchase_order_line_items (if the variant has a price on this Price List
due_at String true
email String
notes String
order_number String
procurement_status String
reference_number String A reference for the purchase order that isn’t the order_number
tax_treatment String One of ‘exclusive’ or 'inclusive’, if not provided defaults to account default. true
received_at String
total String
tags String Reference tags for the purchase order, used in filtering.
cached_quantity String
cached_total deprecated String
default_price_type_id deprecated String
tax_type deprecated String

PurchaseOrderLineItem

Child Attribute Type Description Required
purchase_order_id Integer The purchase_order to which the purchase_order_line_item belongs. true
variant_id Integer The variant to which the purchase_order_line_item belongs. true
tax_type_id Integer The tax_type to which the purchase_order_line_item belongs. true
procurement_id Integer
base_price String
freeform Boolean
image_url String
label String
position Integer
price String true
quantity String
tax_rate_override String Optional tax rate override
extra_cost_value String
tax_rate deprecated String Deprecated in favour of tax_rate_override

HTTP Request

POST https://api.tradegecko.com/purchase_orders/

Retrieve a particular purchase_order

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.PurchaseOrder.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/purchase_orders/1
{
  "purchase_order": {
  "id": 2,
  "created_at": "2015-11-23T11:19:49.857Z",
  "updated_at": "2015-11-23T11:19:50.427Z",
  "status": "active",
  "document_url": "http://localhost:3000/d/gfPPrlS40mrZOGXXgmOIZcue",
  "billing_address_id": 1,
  "company_id": 3,
  "currency_id": 1,
  "stock_location_id": 1,
  "supplier_address_id": 4,
  "default_price_list_id": "buy",
  "due_at": "2015-12-07",
  "email": "william@example.com",
  "notes": null,
  "order_number": "PO0002",
  "procurement_status": "unprocured",
  "reference_number": null,
  "tax_treatment": "exclusive",
  "received_at": null,
  "total": "8.63",
  "tags": [

  ],
  "cached_quantity": "3.0",
  "cached_total": "8.63",
  "default_price_type_id": "buy",
  "tax_type": "exclusive",
  "purchase_order_line_item_ids": [
    3,
    2
  ],
  "procurement_ids": [

  ]
}
}

Retrieves the details of an existing purchase_order. You need only supply the unique purchase_order identifier that was returned upon purchase_order creation.

HTTP Request

GET https://api.tradegecko.com/purchase_orders/{RESOURCE_ID}

Update a purchase_order

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
purchase_order = gecko.PurchaseOrder.find(1).
purchase_order.attributes({
  rate: "12.0",
})
purchase_order.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/purchase_orders/1 -d '{"purchase_order":{"status":"active","email":"hello@tradegecko.com","billing_address_id":2}}'

Response

Returns 204 status when the purchase_order gets updated successfully.

Updates the specified purchase_order by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the purchase_order creation call.

HTTP Request

PUT https://api.tradegecko.com/purchase_orders/{RESOURCE_ID}

Delete a purchase_order

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
purchase_order = gecko.PurchaseOrder.find(1).
purchase_order.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/purchase_orders/1

Response

Returns 204 status when the purchase_order gets deleted successfully.

Permanently deletes a purchase_order. It cannot be undone. This purchase_order is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/purchase_orders/{RESOURCE_ID}/

PurchaseOrderLineItem

This is an object representing a purchase_order_line_item of a purchase_order. Purchase_orders can have multiple purchase_order_line_items but a purchase_order_line_item object belongs to only one Purchase_order.

The PurchaseOrderLineItem object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
purchase_order_id Integer The purchase_order to which the purchase_order_line_item belongs.
variant_id Integer The variant to which the purchase_order_line_item belongs.
tax_type_id Integer The tax_type to which the purchase_order_line_item belongs.
procurement_id Integer
base_price String true
freeform Boolean
image_url String true
label String
position Integer
price String
quantity String
tax_rate_override String Optional tax rate override
extra_cost_value String true
tax_rate deprecated String Deprecated in favour of tax_rate_override

List all purchase_order_line_items

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.PurchaseOrderLineItem.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/purchase_order_line_items/
{
  "purchase_order_line_items": [
  {
    "id": 3,
    "created_at": "2015-11-23T11:19:50.405Z",
    "updated_at": "2015-11-23T11:19:50.405Z",
    "procurement_id": null,
    "purchase_order_id": 2,
    "tax_type_id": 3,
    "variant_id": 8,
    "base_price": null,
    "freeform": false,
    "image_url": null,
    "label": null,
    "position": 0,
    "price": "2.5",
    "quantity": "2.0",
    "tax_rate_override": null,
    "extra_cost_value": "0.0",
    "tax_rate": null
  },
  {
    "id": 1,
    "created_at": "2015-11-23T11:19:07.469Z",
    "updated_at": "2015-11-23T11:19:07.469Z",
    "procurement_id": null,
    "purchase_order_id": 1,
    "tax_type_id": 3,
    "variant_id": 8,
    "base_price": null,
    "freeform": false,
    "image_url": null,
    "label": null,
    "position": 0,
    "price": "2.5",
    "quantity": "1.0",
    "tax_rate_override": null,
    "extra_cost_value": "0.0",
    "tax_rate": null
  },
  {
    "id": 2,
    "created_at": "2015-11-23T11:19:50.297Z",
    "updated_at": "2015-11-23T11:19:50.297Z",
    "procurement_id": null,
    "purchase_order_id": 2,
    "tax_type_id": 3,
    "variant_id": 9,
    "base_price": null,
    "freeform": false,
    "image_url": null,
    "label": null,
    "position": 1,
    "price": "2.5",
    "quantity": "1.0",
    "tax_rate_override": null,
    "extra_cost_value": "0.0",
    "tax_rate": null
  }
]
}

Returns a list of purchase_order_line_items you’ve previously created. The purchase_order_line_items are returned in sorted order, with the most recent purchase_order_line_items appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
purchase_order_id Filter purchase_order_line_items by order
variant_id Filter purchase_order_line_items by variant
tax_type_id Filter purchase_order_line_items by tax_type
procurement_id

HTTP Request:

GET https://api.tradegecko.com/purchase_order_line_items

Create a new purchase_order_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.PurchaseOrderLineItem.create({:quantity=>"12.0", :order_id=>1, :tax_type_id=>1, :price=>"10.0"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/purchase_order_line_items/ -d '{"purchase_order_line_item":{"quantity":"12.0","order_id":1,"tax_type_id":1,"price":"10.0"}'}
{
  "purchase_order_line_item": {
  "id": 3,
  "created_at": "2015-11-23T11:19:50.405Z",
  "updated_at": "2015-11-23T11:19:50.405Z",
  "procurement_id": null,
  "purchase_order_id": 2,
  "tax_type_id": 3,
  "variant_id": 8,
  "base_price": null,
  "freeform": false,
  "image_url": null,
  "label": null,
  "position": 0,
  "price": "2.5",
  "quantity": "2.0",
  "tax_rate_override": null,
  "extra_cost_value": "0.0",
  "tax_rate": null
}
}

Creates a new purchase_order_line_item object.

Arguments

Attribute Type Description Required
purchase_order_id Integer The purchase_order to which the purchase_order_line_item belongs. true
variant_id Integer The variant to which the purchase_order_line_item belongs. true
tax_type_id Integer The tax_type to which the purchase_order_line_item belongs. true
procurement_id Integer
base_price String
freeform Boolean
image_url String
label String
position Integer
price String true
quantity String
tax_rate_override String Optional tax rate override
extra_cost_value String
tax_rate deprecated String Deprecated in favour of tax_rate_override

HTTP Request

POST https://api.tradegecko.com/purchase_order_line_items/

Retrieve a particular purchase_order_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.PurchaseOrderLineItem.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/purchase_order_line_items/1
{
  "purchase_order_line_item": {
  "id": 3,
  "created_at": "2015-11-23T11:19:50.405Z",
  "updated_at": "2015-11-23T11:19:50.405Z",
  "procurement_id": null,
  "purchase_order_id": 2,
  "tax_type_id": 3,
  "variant_id": 8,
  "base_price": null,
  "freeform": false,
  "image_url": null,
  "label": null,
  "position": 0,
  "price": "2.5",
  "quantity": "2.0",
  "tax_rate_override": null,
  "extra_cost_value": "0.0",
  "tax_rate": null
}
}

Retrieves the details of an existing purchase_order_line_item. You need only supply the unique purchase_order_line_item identifier that was returned upon purchase_order_line_item creation.

HTTP Request

GET https://api.tradegecko.com/purchase_order_line_items/{RESOURCE_ID}

Update a purchase_order_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
purchase_order_line_item = gecko.PurchaseOrderLineItem.find(1).
purchase_order_line_item.attributes({
  rate: "12.0",
})
purchase_order_line_item.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/purchase_order_line_items/1 -d '{"purchase_order_line_item":{"quantity":"22.0","price":"12.0"}}'

Response

Returns 204 status when the purchase_order_line_item gets updated successfully.

Updates the specified purchase_order_line_item by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the purchase_order_line_item creation call.

HTTP Request

PUT https://api.tradegecko.com/purchase_order_line_items/{RESOURCE_ID}

Delete a purchase_order_line_item

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
purchase_order_line_item = gecko.PurchaseOrderLineItem.find(1).
purchase_order_line_item.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/purchase_order_line_items/1

Response

Returns 204 status when the purchase_order_line_item gets deleted successfully.

Permanently deletes a purchase_order_line_item. It cannot be undone. This purchase_order_line_item is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/purchase_order_line_items/{RESOURCE_ID}/

TaxType

This is an object representing a tax_type.

The TaxType object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
status String Tells whether the resource is ‘active’ or 'archived’ true
code String
imported_from String Source location (e.g. Quickbooks) true
name String Display name
effective_rate String Computed rate of child tax_components true
tax_component_ids Array true

List all tax_types

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.TaxType.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/tax_types/
{
  "tax_types": [
  {
    "id": 3,
    "code": "PURCHASES",
    "imported_from": null,
    "name": "Purchases Tax",
    "status": "active",
    "quickbooks_online_id": null,
    "xero_online_id": null,
    "effective_rate": "15.0",
    "tax_component_ids": [
      3
    ]
  },
  {
    "id": 2,
    "code": "SALES",
    "imported_from": null,
    "name": "Sales Tax",
    "status": "active",
    "quickbooks_online_id": null,
    "xero_online_id": null,
    "effective_rate": "15.0",
    "tax_component_ids": [
      2
    ]
  },
  {
    "id": 1,
    "code": "TAX EXEMPT",
    "imported_from": null,
    "name": "Tax Exempt",
    "status": "active",
    "quickbooks_online_id": null,
    "xero_online_id": null,
    "effective_rate": "0.0",
    "tax_component_ids": [
      1
    ]
  }
]
}

Returns a list of tax_types you’ve previously created. The tax_types are returned in sorted order, with the most recent tax_types appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
status

HTTP Request:

GET https://api.tradegecko.com/tax_types

Create a new tax_type

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.TaxType.create({:name=>"Retail", :code=>"RETAIL"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/tax_types/ -d '{"tax_type":{"name":"Retail","code":"RETAIL"}'}
{
  "tax_type": {
  "id": 3,
  "code": "PURCHASES",
  "imported_from": null,
  "name": "Purchases Tax",
  "status": "active",
  "quickbooks_online_id": null,
  "xero_online_id": null,
  "effective_rate": "15.0",
  "tax_component_ids": [
    3
  ]
}
}

Creates a new tax_type object.

Arguments

Attribute Type Description Required
code String
name String Display name true

HTTP Request

POST https://api.tradegecko.com/tax_types/

Retrieve a particular tax_type

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.TaxType.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/tax_types/1
{
  "tax_type": {
  "id": 3,
  "code": "PURCHASES",
  "imported_from": null,
  "name": "Purchases Tax",
  "status": "active",
  "quickbooks_online_id": null,
  "xero_online_id": null,
  "effective_rate": "15.0",
  "tax_component_ids": [
    3
  ]
}
}

Retrieves the details of an existing tax_type. You need only supply the unique tax_type identifier that was returned upon tax_type creation.

HTTP Request

GET https://api.tradegecko.com/tax_types/{RESOURCE_ID}

Update a tax_type

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
tax_type = gecko.TaxType.find(1).
tax_type.attributes({
  rate: "12.0",
})
tax_type.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/tax_types/1 -d '{"tax_type":{"name":"Wholesale","code":"WHOLESALE"}}'

Response

Returns 204 status when the tax_type gets updated successfully.

Updates the specified tax_type by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the tax_type creation call.

HTTP Request

PUT https://api.tradegecko.com/tax_types/{RESOURCE_ID}

Delete a tax_type

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
tax_type = gecko.TaxType.find(1).
tax_type.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/tax_types/1

Response

Returns 204 status when the tax_type gets deleted successfully.

Permanently deletes a tax_type. It cannot be undone. This tax_type is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/tax_types/{RESOURCE_ID}/

User

This is an object representing a user.

The User object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
status String Tells whether the resource is ‘active’ or 'archived’ true
action_items_email String Frequency of action items email [off, daily, weekly]
avatar_url String This image is not processed (so it accepts gifs!)
billing_contact Boolean Tells whether user is billing_contact for the current account
email String
first_name String
last_name String
last_sign_in_at String
location String
login_id Integer The current login identifier. true
mobile String
notification_email Boolean
permissions Array Permissions available to user.
phone_number String
position String Role in the company
sales_report_email Boolean
account_id String The current account identifier. true

List all users

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.User.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/users/
{
  "users": [
  {
    "id": 1,
    "created_at": "2015-11-02T01:22:23.877Z",
    "updated_at": "2015-11-02T01:22:23.920Z",
    "action_items_email": "weekly",
    "avatar_url": "assets/avatars/avatar1-70fa2b37c7341a16d9ef72fc6b0f961c253965e9c395fc063ad0165bc65b7167.png",
    "billing_contact": true,
    "email": "example@tradegecko.com",
    "first_name": "Gordon",
    "last_name": "Gecko",
    "last_sign_in_at": "2015-11-17T06:35:25.521Z",
    "location": null,
    "login_id": 1,
    "mobile": null,
    "notification_email": true,
    "permissions": [
      "read_reports",
      "write_stocks",
      "write_orders",
      "write_products",
      "write_settings",
      "write_companies",
      "read_buy_prices"
    ],
    "phone_number": null,
    "position": null,
    "sales_report_email": true,
    "status": "active",
    "account_id": 1
  }
]
}

Returns a list of users you’ve previously created. The users are returned in sorted order, with the most recent users appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
status
login_id
account_id

HTTP Request:

GET https://api.tradegecko.com/users

Retrieve a particular user

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.User.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/users/1
{
  "user": {
  "id": 1,
  "created_at": "2015-11-02T01:22:23.877Z",
  "updated_at": "2015-11-02T01:22:23.920Z",
  "action_items_email": "weekly",
  "avatar_url": "assets/avatars/avatar1-70fa2b37c7341a16d9ef72fc6b0f961c253965e9c395fc063ad0165bc65b7167.png",
  "billing_contact": true,
  "email": "example@tradegecko.com",
  "first_name": "Gordon",
  "last_name": "Gecko",
  "last_sign_in_at": "2015-11-17T06:35:25.521Z",
  "location": null,
  "login_id": 1,
  "mobile": null,
  "notification_email": true,
  "permissions": [
    "read_reports",
    "write_stocks",
    "write_orders",
    "write_products",
    "write_settings",
    "write_companies",
    "read_buy_prices"
  ],
  "phone_number": null,
  "position": null,
  "sales_report_email": true,
  "status": "active",
  "account_id": 1
}
}

Retrieves the details of an existing user. You need only supply the unique user identifier that was returned upon user creation.

HTTP Request

GET https://api.tradegecko.com/users/{RESOURCE_ID}

Update a user

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
user = gecko.User.find(1).
user.attributes({
  rate: "12.0",
})
user.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/users/1 -d '{"user":{"first_name":"Gordon"}}'

Response

Returns 204 status when the user gets updated successfully.

Updates the specified user by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the user creation call.

HTTP Request

PUT https://api.tradegecko.com/users/{RESOURCE_ID}

Delete a user

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
user = gecko.User.find(1).
user.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/users/1

Response

Returns 204 status when the user gets deleted successfully.

Permanently deletes a user. It cannot be undone. This user is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/users/{RESOURCE_ID}/

Get current user

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.User.current
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/users/current
{
  "user": {
  "id": 1,
  "created_at": "2015-11-02T01:22:23.877Z",
  "updated_at": "2015-11-02T01:22:23.920Z",
  "action_items_email": "weekly",
  "avatar_url": "/assets/avatars/avatar1-70fa2b37c7341a16d9ef72fc6b0f961c253965e9c395fc063ad0165bc65b7167.png",
  "billing_contact": true,
  "email": "example@tradegecko.com",
  "first_name": "Gordon",
  "last_name": "Gecko",
  "last_sign_in_at": "2015-11-17T06:35:25.521Z",
  "location": null,
  "login_id": 1,
  "mobile": null,
  "notification_email": true,
  "permissions": [
    "read_reports",
    "write_stocks",
    "write_orders",
    "write_products",
    "write_settings",
    "write_companies",
    "read_buy_prices"
  ],
  "phone_number": null,
  "position": null,
  "sales_report_email": true,
  "status": "active",
  "account_id": 1
}
}

Retrieves the details of the current user.

HTTP Request

GET https://api.tradegecko.com/users/current

Variant

This is an object representing a variant of a product. Products can have multiple variants but a variant object belongs to only one Product.

The Variant object

Attribute Type Description Readonly
id Integer A unique identifier for the resource. true
created_at String true
updated_at String true
status String Tells whether the resource is ‘active’ or 'archived’ true
product_id Integer The product to which the variant belongs.
default_ledger_account_id Integer Used for accounting integrations. (e.g. Revenue Ledger)
buy_price String
committed_stock String Stock committed for sale across all locations true
incoming_stock String Stock on order across all locations true
composite Boolean Tells whether this variant is a composite (composed of other variants)
description String
is_online deprecated Boolean
keep_selling Boolean Allow item to continue to be sold, even if it is no longer in stock
last_cost_price String Last purchase price paid for this variant true
manage_stock Boolean
max_online String Integrated online store(s) should show current stock levels up to a maximum of this value
moving_average_cost String Average cost price paid for this variant true
name String
online_ordering Boolean Tells whether variant is for sale on B2B platform
opt1 String
opt2 String
opt3 String
position String Default sort position of this variant (unique to product)
product_name String provided by the product to which the variant belongs true
product_status String provided by the product to which the variant belongs true
product_type String provided by the product to which the variant belongs true
retail_price String The recommended retail price
sellable String Tells whether can be added to sales orders
sku String Stock Keeping Unit (should be unique)
stock_on_hand String Stock on hand across all locations true
supplier_code String
taxable Boolean Tells whether this variant can be taxed
upc String The barcode or UPC number
weight String The weight value
weight_unit String The weight unit (kg, gm, oz or lb)
wholesale_price String The recommended wholesale price for this product
image_ids Array true
variant_prices Array An array of prices with price list IDs and the price value.
locations Array An array of per-warehouse data about current variant. true
prices deprecated Hash true
stock_levels deprecated Hash true
committed_stock_levels deprecated Hash true

List all variants

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token

gecko.Variant.where(limit: 25, status: 'active')
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/variants/
{
  "variants": [
  {
    "id": 3,
    "created_at": "2015-11-02T01:22:24.772Z",
    "updated_at": "2015-11-02T01:34:04.502Z",
    "product_id": 1,
    "default_ledger_account_id": null,
    "buy_price": "4.5",
    "committed_stock": "3",
    "incoming_stock": "0",
    "composite": null,
    "description": null,
    "is_online": false,
    "keep_selling": false,
    "last_cost_price": "5.0",
    "manage_stock": true,
    "max_online": null,
    "moving_average_cost": "5",
    "name": "Peach",
    "online_ordering": true,
    "opt1": "Peach",
    "opt2": null,
    "opt3": null,
    "position": 2,
    "product_name": "Everlasting Gobstopper",
    "product_status": "active",
    "product_type": "Candy",
    "retail_price": "22.0",
    "sellable": true,
    "sku": "DEMO-GOBS-PEA",
    "status": "active",
    "stock_on_hand": "10",
    "supplier_code": null,
    "taxable": true,
    "upc": null,
    "weight": null,
    "weight_unit": null,
    "weight_value": null,
    "wholesale_price": "12.0",
    "image_ids": [

    ],
    "variant_prices": [
      {
        "price_list_id": "retail",
        "value": "22.0"
      },
      {
        "price_list_id": "wholesale",
        "value": "12.0"
      },
      {
        "price_list_id": "buy",
        "value": "4.5"
      }
    ],
    "locations": [
      {
        "location_id": 1,
        "stock_on_hand": "10",
        "committed": "3",
        "incoming": null,
        "bin_location": null,
        "reorder_point": null
      }
    ],
    "channels": [

    ],
    "prices": {
      "retail": "22.0",
      "wholesale": "12.0",
      "buy": "4.5"
    },
    "stock_levels": {
      "1": "10.0"
    },
    "committed_stock_levels": {
      "1": "3.0"
    }
  },
  {
    "id": 2,
    "created_at": "2015-11-02T01:22:24.796Z",
    "updated_at": "2015-11-02T01:34:04.474Z",
    "product_id": 1,
    "default_ledger_account_id": null,
    "buy_price": "4.5",
    "committed_stock": "0",
    "incoming_stock": "0",
    "composite": null,
    "description": null,
    "is_online": false,
    "keep_selling": false,
    "last_cost_price": "6.0",
    "manage_stock": true,
    "max_online": null,
    "moving_average_cost": "6",
    "name": "Snozzberry",
    "online_ordering": true,
    "opt1": "Snozzberry",
    "opt2": null,
    "opt3": null,
    "position": 3,
    "product_name": "Everlasting Gobstopper",
    "product_status": "active",
    "product_type": "Candy",
    "retail_price": "24.0",
    "sellable": true,
    "sku": "DEMO-GOBS-SNO",
    "status": "active",
    "stock_on_hand": "10",
    "supplier_code": null,
    "taxable": true,
    "upc": null,
    "weight": null,
    "weight_unit": null,
    "weight_value": null,
    "wholesale_price": "12.0",
    "image_ids": [

    ],
    "variant_prices": [
      {
        "price_list_id": "retail",
        "value": "24.0"
      },
      {
        "price_list_id": "wholesale",
        "value": "12.0"
      },
      {
        "price_list_id": "buy",
        "value": "4.5"
      }
    ],
    "locations": [
      {
        "location_id": 1,
        "stock_on_hand": "10",
        "committed": null,
        "incoming": null,
        "bin_location": null,
        "reorder_point": null
      }
    ],
    "channels": [

    ],
    "prices": {
      "retail": "24.0",
      "wholesale": "12.0",
      "buy": "4.5"
    },
    "stock_levels": {
      "1": 10
    },
    "committed_stock_levels": {
    }
  }
]
}

Returns a list of variants you’ve previously created. The variants are returned in sorted order, with the most recent variants appearing first.

Filters

Arguments Description
limit used for pagination (default is 100)
page used for pagination (default is 1)
created_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
created_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_min ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
updated_at_max ISO 8601 format (e.g. 2015-11-04T00:00:00.00Z)
status possible options are ‘active’ and 'disabled’, default is 'active’
product_id
sku find product variant by SKU

HTTP Request:

GET https://api.tradegecko.com/variants

Create a new variant

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Variant.create({:product_id=>1, :initial_cost_price=>25, :initial_stock_level=>100, :initial_stock_location_id=>1, :retail_price=>"10.0", :name=>"Sample Variant", :sku=>"SV1234"})
curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/variants/ -d '{"variant":{"product_id":1,"initial_cost_price":25,"initial_stock_level":100,"initial_stock_location_id":1,"retail_price":"10.0","name":"Sample Variant","sku":"SV1234"}'}
{
  "variant": {
  "id": 3,
  "created_at": "2015-11-02T01:22:24.772Z",
  "updated_at": "2015-11-02T01:34:04.502Z",
  "product_id": 1,
  "default_ledger_account_id": null,
  "buy_price": "4.5",
  "committed_stock": "3",
  "incoming_stock": "0",
  "composite": null,
  "description": null,
  "is_online": false,
  "keep_selling": false,
  "last_cost_price": "5.0",
  "manage_stock": true,
  "max_online": null,
  "moving_average_cost": "5",
  "name": "Peach",
  "online_ordering": true,
  "opt1": "Peach",
  "opt2": null,
  "opt3": null,
  "position": 2,
  "product_name": "Everlasting Gobstopper",
  "product_status": "active",
  "product_type": "Candy",
  "retail_price": "22.0",
  "sellable": true,
  "sku": "DEMO-GOBS-PEA",
  "status": "active",
  "stock_on_hand": "10",
  "supplier_code": null,
  "taxable": true,
  "upc": null,
  "weight": null,
  "weight_unit": null,
  "weight_value": null,
  "wholesale_price": "12.0",
  "image_ids": [

], "variant_prices": [ { "price_list_id": "retail", "value": "22.0" }, { "price_list_id": "wholesale", "value": "12.0" }, { "price_list_id": "buy", "value": "4.5" } ], "locations": [ { "location_id": 1, "stock_on_hand": "10", "committed": "3", "incoming": null, "bin_location": null, "reorder_point": null } ], "channels": [

], "prices": { "retail": "22.0", "wholesale": "12.0", "buy": "4.5" }, "stock_levels": { "1": "10.0" }, "committed_stock_levels": { "1": "3.0" } } }

Creates a new variant object.

Arguments

Attribute Type Description Required
product_id Integer The product to which the variant belongs. true
default_ledger_account_id Integer Used for accounting integrations. (e.g. Revenue Ledger)
buy_price String
composite Boolean Tells whether this variant is a composite (composed of other variants)
description String
is_online deprecated Boolean
keep_selling Boolean Allow item to continue to be sold, even if it is no longer in stock
manage_stock Boolean
max_online String Integrated online store(s) should show current stock levels up to a maximum of this value
name String
online_ordering Boolean Tells whether variant is for sale on B2B platform
opt1 String
opt2 String
opt3 String
position String Default sort position of this variant (unique to product)
retail_price String The recommended retail price
sellable String Tells whether can be added to sales orders
sku String Stock Keeping Unit (should be unique)
supplier_code String
taxable Boolean Tells whether this variant can be taxed
upc String The barcode or UPC number
weight String The weight value
weight_unit String The weight unit (kg, gm, oz or lb)
wholesale_price String The recommended wholesale price for this product
variant_prices Array An array of prices with price list IDs and the price value.

HTTP Request

POST https://api.tradegecko.com/variants/

Retrieve a particular variant

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
gecko.Variant.find(1)
curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/variants/1
{
  "variant": {
  "id": 3,
  "created_at": "2015-11-02T01:22:24.772Z",
  "updated_at": "2015-11-02T01:34:04.502Z",
  "product_id": 1,
  "default_ledger_account_id": null,
  "buy_price": "4.5",
  "committed_stock": "3",
  "incoming_stock": "0",
  "composite": null,
  "description": null,
  "is_online": false,
  "keep_selling": false,
  "last_cost_price": "5.0",
  "manage_stock": true,
  "max_online": null,
  "moving_average_cost": "5",
  "name": "Peach",
  "online_ordering": true,
  "opt1": "Peach",
  "opt2": null,
  "opt3": null,
  "position": 2,
  "product_name": "Everlasting Gobstopper",
  "product_status": "active",
  "product_type": "Candy",
  "retail_price": "22.0",
  "sellable": true,
  "sku": "DEMO-GOBS-PEA",
  "status": "active",
  "stock_on_hand": "10",
  "supplier_code": null,
  "taxable": true,
  "upc": null,
  "weight": null,
  "weight_unit": null,
  "weight_value": null,
  "wholesale_price": "12.0",
  "image_ids": [

  ],
  "variant_prices": [
    {
      "price_list_id": "retail",
      "value": "22.0"
    },
    {
      "price_list_id": "wholesale",
      "value": "12.0"
    },
    {
      "price_list_id": "buy",
      "value": "4.5"
    }
  ],
  "locations": [
    {
      "location_id": 1,
      "stock_on_hand": "10",
      "committed": "3",
      "incoming": null,
      "bin_location": null,
      "reorder_point": null
    }
  ],
  "channels": [

  ],
  "prices": {
    "retail": "22.0",
    "wholesale": "12.0",
    "buy": "4.5"
  },
  "stock_levels": {
    "1": "10.0"
  },
  "committed_stock_levels": {
    "1": "3.0"
  }
}
}

Retrieves the details of an existing variant. You need only supply the unique variant identifier that was returned upon variant creation.

HTTP Request

GET https://api.tradegecko.com/variants/{RESOURCE_ID}

Update a variant

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
variant = gecko.Variant.find(1).
variant.attributes({
  rate: "12.0",
})
variant.save
curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/variants/1 -d '{"variant":{"retail_price":"12.0","name":"Sample Variant","sku":"SV1234"}}'

Response

Returns 204 status when the variant gets updated successfully.

Updates the specified variant by setting the values of the parameters passed.

Any parameters not provided will be left unchanged. This request accepts the same arguments as the variant creation call.

HTTP Request

PUT https://api.tradegecko.com/variants/{RESOURCE_ID}

Delete a variant

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
access_token = OAuth2::AccessToken.new(gecko.oauth_client, <ACCESS_TOKEN>)
gecko.access_token = access_token
variant = gecko.Variant.find(1).
variant.destroy
curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/variants/1

Response

Returns 204 status when the variant gets deleted successfully.

Permanently deletes a variant. It cannot be undone. This variant is no longer available for future Sales Orders.

HTTP Request

DELETE https://api.tradegecko.com/variants/{RESOURCE_ID}/