QuickBooks Commerce API Reference

This website documents the public API for QuickBooks Commerce

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

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/products?sku=moko/

require 'gecko-ruby'
gecko = Gecko::Client.new(<CLIENT_ID>, <CLIENT_SECRET>)
gecko.authorize_from_existing(<ACCESS_TOKEN>, nil, nil)
gecko.Product.where(sku: 'moko')

The QuickBooks Commerce API is 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.

Registering an Application

In order to use the QuickBooks Commerce API, you must have an active QuickBooks Commerce account. Once you're logged in to your account you can register a new API application at https://go.tradegecko.com/oauth/applications.

After successfully registering a new application, you will be given a set of 2 unique keys:

• APPLICATION ID
• APPLICATION SECRET

These two keys are subsequently used to obtain access tokens for making API calls.

OAuth Authentication Flows

The QuickBooks Commerce API is based on version 22 of the OAuth 2.0 specification.

If you are familiar with OAuth, then the authentication endpoints are as follows:

• Authorization: https://api.tradegecko.com/oauth/authorize
• Token Request: https://api.tradegecko.com/oauth/token

Available Authentication Flows

The QuickBooks Commerce API supports two common OAuth 2.0 flows:

• Authorization Code with Refresh Token flow
• Resource Owner Password Credentials flow

Under the majority of circumstances we recommend the Authorization Code with Refresh Token flow as it provides the highest level of security.

For prototyping, or one-off integrations you may use the Resource Owner Password Credentials flows.

If you plan on building an application that will be used by multiple QuickBooks Commerce accounts, you MUST use the Authorization Code with Refresh token flow.

Authorization Code with Refresh Token

The Authorization Code flow is a redirection-based flow, which means the application must be able to redirect the application user and receive authorization codes via a web browser.

Phase 1: Authorization Phase

To authorize, use this code:

require 'gecko-ruby'
oauth_client = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>).oauth_client
authorization_url = oauth_client.auth_code.authorize_url(redirect_uri: '<REDIRECT_URI>')
#=> "https://go.tradegecko.com/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&response_type=code"
redirect_to authorization_url

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

Make sure to replace <OAUTH_ID>, <OAUTH_SECRET> <REDIRECT_URI> with your details.

An authorization code is the key used to retrieve the access token. In order to acquire an authorization code, you need to redirect the user's browser to the authorization endpoint.

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

• https://api.tradegecko.com/oauth/authorize: indicates the API authorization endpoint.
• response_type=code: specifies that your application is requesting an authorization code grant.
• client_id=<CLIENT_ID>: the application's client ID provided when registering your application.
• redirect_uri=<REDIRECT_URI>: should be set to a URL in your application where the user will be redirected back to after the request is authorized.

Phase 2: User Authorization

Once directed to the above link, the user will be asked to log in to their QuickBooks Commerce account (if they're not already logged in). They will then be asked to authorize or deny the authentication request.

Phase 3: Authorization Code response

After the user successfully authorizes the application, they will be redirected back to the provided redirect_uri with the authorization code as a query parameter named code.

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

Phase 4: Requesting an Access Token

curl -H "Content-type: application/json" -X POST https://api.tradegecko.com/oauth/token -d '{"client_id": "<CLIENT_ID>", "client_secret":"<CLIENT_SECRET>", "redirect_uri": "https://my.application.com/auth/app/callback", "code": "<CODE_FROM_PHASE_3>", "grant_type": "authorization_code"}'

{
  "access_token": "57ed301af04bf35b40f255feb5ef469ab2f046aff14",
  "expires_in": 7200,
  "refresh_token": "026b343de07818b3ffebfb3001eff9a00aea43da0a",
  "scope": "public",
  "token_type": "bearer"
}

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
oauth_client = gecko.oauth_client
access_token = oauth_client.auth_code.get_token(params[:code], redirect_uri: '<REDIRECT_URI>')
gecko.access_token = access_token
gecko.Account.current

The access token is a unique key used to make requests to the API.

In order to get an access token, the application 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.

• https://api.tradegecko.com/oauth/token: indicates the API token endpoint.
• grant_type=authorization_code: specifies that your application is requesting an authorization code.
• client_id=<CLIENT_ID>: the application's client ID provided when registering your application.
• client_secret=<CLIENT_SECRET>: the application's client secret provided when registering your application.
• redirect_uri=<REDIRECT_URI>: should be set to a URL in your application where the code will be received.
• code=<CODE> must match the authorization code returned by the authorization endpoint in Phase 3

access_token.to_hash
#=> {"token_type"=>"bearer", "scope"=>"public", "created_at"=>1500000000, :access_token=>"<ACCESS_TOKEN>", :refresh_token=>"<REFRESH_TOKEN>", :expires_at=>1500007200}

Once you have generated the access_token, this is the point where you will likely want to save off the details for future reuse without requiring user interaction. To reconstruct a refreshable access token you will need to store the access_token and refresh_token parameters returned.

Phase 5: Refreshing an Access Token

curl -H "Content-type: application/json" -X POST https://api.tradegecko.com/oauth/token -d '{"client_id": "<CLIENT_ID>", "client_secret": "<CLIENT_SECRET>", "redirect_uri": "http://my.application.com/auth/callback", "refresh_token": "<REFRESH_TOKEN>", "grant_type": "refresh_token"}'

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

# From existing access_token object
access_token.refresh!
access_token.to_hash # For storage

# From string
require 'gecko-ruby'
gecko = Gecko::Client.new("<OAUTH_ID>", "<OAUTH_SECRET>")
gecko.authorize_from_refresh_token("<REFRESH_TOKEN>")
gecko.access_token.to_hash # For storage

A refresh token is a unique token returned when creating an access token that can be used to request a new access token when the existing current access token expires.

To refresh an access token, the application 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.

• https://api.tradegecko.com/oauth/token: indicates the API token endpoint.
• grant_type=refresh_token: specifies that your application is requesting an refresh token.
• client_id=<CLIENT_ID>: the application's client ID provided when registering your application.
• client_secret=<CLIENT_SECRET>: the application's client secret provided when registering your application.
• redirect_uri=<REDIRECT_URI>: should be set to a URL in your application where the code will be received.
• refresh_token: must match the refresh token returned by the authorization endpoint in Phase 4

Resource Owner Password Credentials flow

The QuickBooks Commerce API also supports the Resource Owner Password Credentials flow through the concept of Privileged Access Tokens.

These tokens are generated through the QuickBooks Commerce UI and do not expire. This means that you can access the API using the privileged token without the need to use browser redirects or manage refresh tokens.

However you will need to manually manage key rotation yourselves if your privileged key gets compromised in any way.

Because of the inherent higher safety risks involved in storing privileged access tokens, the Resource Owner Password Credentials flow is only available on single-account Applications.

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 <PRIVILEGED_ACCESS_TOKEN>"
https://api.tradegecko.com/accounts/current

require 'gecko-ruby'
gecko = Gecko::Client.new(<OAUTH_ID>, <OAUTH_SECRET>)
gecko.authorize_from_existing(<PRIVILEGED_ACCESS_TOKEN>, nil, nil)
gecko.Account.current

Phase 1: Privileged Access Token Generation

As the application developer, after registering your application, you will see a button to "Create a Privileged Token" for the application.

If you have already registered your application, you can add a privileged token by finding your application in your QuickBooks Commerce App List.

Pagination

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/users?limit=5&page=2

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 QuickBooks Commerce API enables pagination via limit and page query parameters on GET requests to index pages.

The default page size is 50 items, with the maximum page size being 250.

Filtering Collections

The QuickBooks Commerce API allows filtering of records by passing along query parameters.
These are some of the filters currently allowed by the API (where relevant).

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")

Index Filters

Arguments	Description
ids	An array of object IDs, see Batching Requests
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 "?order=created_at desc"
limit	See Pagination (default is 50)
page	See Pagination

In addition, each record type has their own specific filters; these filters are covered in their respective sections.

Batching Requests

Requests can be batched together to get records with different IDs in a single API call.
GET https://api.tradegecko.com/products?ids[]=1&ids[]=2

Batching can also be done to return the results of multiple possible values.
For example, a single API call can return products with multiple brands:
GET https://api.tradegecko.com/products?brand[]=ABC&brand[]=XYZ

Or statuses:
GET https://api.tradegecko.com/orders?status[]=draft&status[]=active

Comma-separated support for Integer filters

For ID based filters, optionally a comma-separated collection can be used instead for brevity.
GET https://api.tradegecko.com/products?ids=1,2, or
GET https://api.tradegecko.com/variants?product_id=1,2

Combining Multiple Filters in a Single call

You can combine filters in a single API call to return tighter subsets of results.
GET https://api.tradegecko.com/companies?company_status=active&company_type=supplier&order=created_at+desc&page=2&limit=20

Response Metadata

Every response returned from the QuickBooks Commerce API returns some useful pieces of information in the response headers.

Request IDs

Every response will include an X-Request-ID parameter unique to that specific request. If you need to contact us about a specific request, please make sure to include the specific request ID in any communication with us to help speed up investigations.

Pagination Links

curl -IXGET https://api.tradegecko.com/products?page=1 -H "Content-type: application/json" -H "Authorization: Bearer <PRIVILEGED_ACCESS_TOKEN>" | grep X-Pagination

X-Pagination: {"total_records":3103,"total_pages":32,"first_page":true,"last_page":false,"out_of_bounds":false,"offset":0}

Every response that returns a collection will include pagination data in the headers. This data can be found as JSON under the X-Pagination header.

• total_records: The total number of records matching the filters (excludes page & limit params).
• total_pages: The total number of pages of records matching the filters.
• first_page: true/false based on whether this is the first page of results.
• last_page: true/false based on whether this is the last page of results.
• out_of_bounds: true/false based on whether the pagination request is out of bounds.
• offset: The offset from 0 for the start of this page

Rate Limiting

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

curl -IXGET https://api.tradegecko.com/products?page=1 -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" | grep X-Rate-Limit

X-Rate-Limit-Limit: 300
X-Rate-Limit-Remaining: 291
X-Rate-Limit-Reset: 1509339000

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

Header	Description
X-Rate-Limit-Limit	Number of requests available for this application (always 300) .
X-Rate-Limit-Remaining	Number of requests remaining in quota
X-Rate-Limit-Reset	The timestamp (as seconds since epoch) when 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.

Idempotency Tokens

curl https://api.tradegecko.com/orders/ </span>
     -X POST </span>
     -H "Idempotency-Key: ecf83ef1-0f85-4860-bbc3-70a4bd74be41" </span>
     -H "Content-type: application/json" </span>
     -H "Authorization: Bearer <ACCESS_TOKEN>" </span>
     -d '{"order": {"company_id": 101, "shipping_address_id": 1002, "billing_address_id": 1002, "status": "active", "issued_at": "21-02-2018", "order_line_items": [{"variant_id": 14, "quantity": 1}, {"variant_id": 15, "quantity": 2}]}}'

order = gecko.Order.build({
  company_id: 101,
  shipping_address_id: 1002,
  billing_address_id: 1002,
  issued_at: Time.now,
})
order.order_line_items.build(variant_id: 14, quantity: 1)
order.order_line_items.build(variant_id: 15, quantity: 2)
order.save(idempotency_token: "ecf83ef1-0f85-4860-bbc3-70a4bd74be41")

The QuickBooks Commerce API has support for idempotent requests via an optional Idempotency-Key request header. By providing a unique Idempotency key in your POST or PUT requests the API can guarantee that a specific operation is only performed once.

The keys expire after 24 hours.

Soft Deletion

QuickBooks Commerce uses soft-deletion for most of its records. In the API, a soft-deleted object will have a status of archived. These records will not be returned by default, but can be accessed using filters to specifically return records with a status of archived.

Webhooks

You can use webhooks to receive notifications fo a collection of common events, see the list here.

Once you've created a webhook via the API, any time that matching event is triggered in the customer's QuickBooks Commerce account, the endpoint will receive a POST request.

The Webhook notification

The webhook request you received will include a JSON serialized payload including the object_id, event, a timestamp and the resource_url.

  {
    "object_id": 1234567,
    "event": "fulfillments.create",
    "timestamp": 1546272000,
    "resource_url": "https://api.tradegecko.com/fulfillments/1234567.json"
  }

It will also include some specific HTTP headers.

X-Gecko-Delivery: A unique identifier for the event, if you have any issues with webhooks, please provide this value when submitting any support ticket.

X-Gecko-Signature: A signed signature for verification.

To ensure the request comes from QuickBooks Commerce itself and is not being spoofed be sure to verify the signature against the payload received.

An example implementation in Ruby is provided.

def generate_signature(body)
  digest = OpenSSL::Digest.new('sha256')
  Base64.encode64(OpenSSL::HMAC.digest(digest, application.secret, body.to_json)).strip
end

Responding to a webhook

When receiving a webhook, the request must complete within a 10-second window, we highly recommending processing the webhooks asynchronously to avoid any problems.

We use HTTP response codes to determine whether a webhook has been received successfully. If your server returns a HTTP status code between 200 and 399, we assume it has been processed successfully.

A HTTP 410 Gone response will automatically delete the webhook.

Other responses will cause the outgoing request to be retried, based on an exponential backoff strategy.

If we receive unsuccessful responses consecutively for 3 days, the webhook will be deleted. Any successful response within the 3 day period will reset the counter. Application developers will receive daily emails to notify them of webhook failure and webhook deletion.

Sideloading Resources

QuickBooks Commerce allows you retrieve associated resources as part of a single request. This can be done by adding an include parameter containing a comma-separated list of resources to load.

Here's a few examples:

Fetching a Product

GET https://api.tradegecko.com/products/1?include=variants

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.tradegecko.com/products/153172?include=variants

{
   "variants":[
      {
         "id":558277,
         "created_at":"2013-11-18T03:00:38.459Z",
         "updated_at":"2018-05-23T08:02:29.569Z",
         "product_id":153172,
         ...
      }
   ],
   "product":{
      "id":153172,
      "created_at":"2013-07-23T16:25:36.582Z",
      "updated_at":"2018-09-01T04:54:25.085Z",
      "brand":null,
      "description":"Wiggly and squiggly. Watch out for the tail falling off!\u003cbr\u003e",
      "image_url":null,
      ...
   }
}

Fetching an Order

GET https://api.tradegecko.com/orders/160?include=order_line_items,shipping_address,billing_address,company

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.tradegecko.com/orders?include=order_line_items,shipping_address,billing_address,company

{
   "order_line_items":[
      {
         "id":335,
         "created_at":"2018-02-23T07:54:43.756Z",
         "updated_at":"2018-03-22T13:50:57.564Z",
         "order_id":160,
         "variant_id":1193,
         ...
      },
      {
         "id":336,
         "created_at":"2018-02-23T07:54:43.765Z",
         "updated_at":"2018-03-22T13:50:57.507Z",
         "order_id":160,
         "variant_id":1199,
         ...
      },
      {
         "id":337,
         "created_at":"2018-02-23T07:54:43.774Z",
         "updated_at":"2018-03-22T13:50:57.475Z",
         "order_id":160,
         "variant_id":1182,
         ...
      }
   ],
   "addresses":[
      {
         "id":147,
         "created_at":"2018-02-23T07:54:42.462Z",
         "updated_at":"2018-02-23T07:54:42.462Z",
         "company_id":96,
         "address1":"1260 Billy Plaza",
         ...
      },
      {
         "id":146,
         "created_at":"2018-02-23T07:54:42.460Z",
         "updated_at":"2018-02-23T07:54:42.460Z",
         "company_id":96,
         "address1":"620 Pfannerstill Run",
         ...
      }
   ],
   "companies":[
      {
         "id":96,
         "created_at":"2018-02-23T07:54:42.457Z",
         "updated_at":"2018-03-22T13:50:30.892Z",
         ...
      }
   ],
   "order":{
      "id":160,
      "created_at":"2018-02-23T07:54:43.683Z",
      "updated_at":"2018-09-24T03:29:30.759Z",
      "assignee_id":null,
      "billing_address_id":147,
      "company_id":96,
      "contact_id":null,
      ...
   }
}

Fetching a Bundle Product Variant's Composition

Sideloading parameters for composition API work for both single and collection actions. Examples:

GET https://api.tradegecko.com/variants/composition?include=bundle

GET https://api.tradegecko.com/variants/composition/1?include=bundle,component

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.tradegecko.com/variants/composition?include=bundle,component

{
   "variants": [
      {
         "id": 1,
         "sku": "DRK-0001",
         ...
      },
      {
         "id": 2,
         "sku": "DRINK-PACK-SKU",
         ...
      },
      ...
   ],
   "composition": [
      {
         "bundle_sku": "DRINK-PACK-SKU",
         "component_sku": "DRK-0001",
         "quantity": "6.0",
         "bundle_id": 2,
         "component_id": 1
      },
      ...
   ]
}

Errors

The QuickBooks Commerce API uses the following error codes:

Error Code	Meaning
400	Bad Request -- You have passed a malformed request
401	Unauthorized -- Your API access token is invalid
402	Payment Required -- Your subscription has lapsed
403	Forbidden -- The resource requested is not available with your permissions
404	Not Found -- The specified resource could not be found
414	Request URI too long -- You have applied too many filters on a GET request
422	Unprocessable Entity -- Your request is invalid
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 was unable to finish the request in time, either the server was overloaded or if fetching large pages of data, please try using a smaller page size

Guides

Check out these guides to start integrating QuickBooks Commerce with your external sales channels, fulfillment services or warehouse management systems: 

• Ecommerce Integration Guide

• Fulfillment Service Integration Guide

• Warehouse Management Integration Guide

Creating a Sales Order

There are several ways to create a Sales Order via the QuickBooks Commerce API, depending on the number of line items, and whether the order is being made to a new or existing customer.

We're going to be POSTing a minimal JSON to the /orders endpoint.
Check out The Order Object for descriptions of all of the available fields.

As always, check the sidebar for example code.

Here's a few examples:

• Creating a Sales Order for an existing customer being shipped and billed to an existing address.
• Creating a Sales Order for an existing customer, but to a new address.
• Creating a Sales Order for a new customer.

1. Order with Existing Customer

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

order = gecko.Order.build({
  company_id: 101,
  shipping_address_id: 1002,
  billing_address_id: 1002,
  issued_at: Time.now,
})
order.order_line_items.build(variant_id: 14, quantity: 1)
order.order_line_items.build(variant_id: 15, quantity: 2)
order.save

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.tradegecko.com/orders/ \
-d '{"order": {"company_id": 101, "shipping_address_id": 1002, "billing_address_id": 1002, "status": "active", "issued_at": "21-02-2018", "order_line_items": [{"variant_id": 14, "quantity": 1}, {"variant_id": 15, "quantity": 2}]}}'

2. Order with Existing Customer but new address

We have two options here, we can either create the address in a separate request, or as in the JSON below we can embed the new address inside the Order JSON and it will get created for us.

{
  "order": {
    "company_id": 101,
    "shipping_address": {
      "address1": "123 Cross St",
      "city": "Springfield",
      "country": "United States of America",
      "label": "Head Office"
    },
    "status": "active",
    "issued_at": "21-02-2018",
    "order_line_items": [
      { "variant_id": 14, "quantity": 1 },
      { "variant_id": 15, "quantity": 2 }
    ]
  }
}

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.tradegecko.com/orders/
-d '{"order": {"company_id": 101, "shipping_address": {"address1": "123 Cross St", "city": "Springfield", "country": "United States of America", "label": "Head Office"}, "status": "active", "issued_at": "21-02-2018", "order_line_items": [{"variant_id": 14, "quantity": 1}, {"variant_id": 15, "quantity": 2}]}}'

# The rubygem does not yet support creating nested addresses,
# so this will make two API requests.
address = gecko.Address.build({
  company_id: 101,
  address1: "123 Cross St",
  city: "Springfield",
  country: "United States of America",
  label: "Head Office"
})
address.save
order = gecko.Order.build({
  company_id: 101,
  shipping_address_id: address.id,
  billing_address_id: address.id,
  issued_at: Time.now,
})
order.order_line_items.build(variant_id: 14, quantity: 1)
order.order_line_items.build(variant_id: 15, quantity: 2)
order.save

3. Order for New Customer

If the order is for a new company, the company can either be created via a separate request, or nested inside the order. If nesting inside the order, at least a shipping_address must be included as well.

{
  "order": {
    "company": {
      "name": "Bill's Boots",
      "company_code": "BB-123",
      "company_type": "business",
      "email": "billy@billsboots.com",
      "website": "https://billsboots.com"
    },
    "shipping_address": {
      "address1": "123 Cross St",
      "city": "Springfield",
      "country": "United States of America",
      "label": "Head Office"
    },
    "status": "active",
    "issued_at": "21-02-2018",
    "order_line_items": [
      { "variant_id": 14, "quantity": 1 },
      { "variant_id": 15, "quantity": 2 }
    ]
  }
}

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>" https://api.tradegecko.com/orders/ \
-d '{"order": {"company": {"name": "Bill\'s Boots", "company_code": "BB-123", "company_type": "business", "email": "billy@billsboots.com", "website": "https://billsboots.com"}, "shipping_address": {"address1": "123 Cross St", "city": "Springfield", "country": "United States of America", "label": "Head Office"}, "status": "active", "issued_at": "21-02-2018", "order_line_items": [{"variant_id": 14, "quantity": 1}, {"variant_id": 15, "quantity": 2 }]}}'

company = gecko.Company.build({
  name: "Bill's Boots",
  company_code: "BB-123",
  company_type: "business",
  email: "billy@billsboots.com",
  website: "https://billsboots.com"
})
company.save
address = gecko.Address.build({
  address1: "123 Cross St",
  city: "Springfield",
  country: "United States of America",
  label: "Head Office"
})
address.save
  company_id: company.id,
  shipping_address_id: address.id,
  billing_address_id: address.id,
  issued_at: Time.now,
})
order.order_line_items.build(variant_id: 14, quantity: 1)
order.order_line_items.build(variant_id: 15, quantity: 2)
order.save

Creating a Sales Order with > 250 items.

If you are regularly creating orders with several hundreds of items you may run into the occasional case where the server times out.

To mitigate effects of timeouts we suggest the use of two extra mechanisms.

1. Idempotency Tokens
By using an Idempotency Token header when creating the Sales Order, you can automatically recover from occasional timeout errors by simply retrying the POST request and the API will ensure only a single Sales Order is created.

2. Multi-part Creates
For an order with a significant number of line items, it may make sense to split them into multiple requests. We don't suggest unless you're running into regular issues with Sales Order size. In this case, create the Sales Order as above with a section of the line items (150 for example), and then fire an Order update request with just an array of the next set of items.

PUT /orders/12345

{
  "order": {
    "order_line_items": [
      { "variant_id": 14, "quantity": 1 },
      { "variant_id": 15, "quantity": 2 }
    ]
  }
}

Resources

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	Date and time when the account was created.	true
updated_at	String	Date and time when the account was last updated.	true
contact_email	String	Contact email used on QuickBooks Commerce documents and emails.
contact_mobile	String	Contact mobile number for your account.
contact_phone	String	Contact phone number used on QuickBooks Commerce documents and emails.
country	String	Needs to be a valid ISO3166-1 alpha-2 code (US, NZ, SG etc)
default_order_price_list_id	String	The default price list id for new Sales Orders, unless a price list is set on the company.
default_purchase_order_price_list_id	String	The default price list for new Purchase Orders, unless a price list is set on the company.
default_sales_ledger_account_on	String	Value can either be 'company', 'variant' or 'channel'. This determines how your sales total will be tracked on.
default_tax_treatment	String	Value can either be 'inclusive' or 'exclusive'. This will be the default tax treatment for orders created without assigning a tax_treatment attribute.
industry	String	The industry in which your account belongs to.
logo_url deprecated	String	Image URL for the account's logo.	true
name	String	Name of the account.
stock_level_warn	Boolean	Show a warning if attempting to ship a shipment without all the stock available
tax_label	String	Primary tax label for your business. e.g. VAT or GST.
tax_number	String	Your company's tax number. e.g. 12-345-678.
tax_number_label	String	Tax Number Label for your Organization. e.g. VAT Number.
time_zone	String	The name of the time zone in TZ format. e.g. Asia/Singapore
website	String	Your company's website URL.
primary_location_id	Integer	The default location used when dealing with stock. New variants will be added here.
primary_billing_location_id	Integer	The default billing address used on your document headers and purchase orders.
default_currency_id	Integer	The default currency for creating a new sales order.
default_payment_method_id	Integer	The default method of payment for creating a new payment.
default_payment_term_id	Integer	The default term of payment. This can also be used to push to multiple ledger accounts in your accounting integration.
billing_contact_id	Integer	Account Owner, can only be transferred by existing owner
default_sales_order_tax_type_id	Integer	The default tax type for creating a new sales order.
default_purchase_order_tax_type_id	Integer	The default tax type that is selected when you create a new purchase order.
default_tax_exempt_id	Integer	The default tax type for non-taxable products.
default_tax_rate deprecated	String		true
default_tax_type deprecated	String
default_tax_type_id	Integer	The default tax type for creating a new sales order.
default_order_price_type_id deprecated	String
default_purchase_order_price_type_id deprecated	String
location_ids	Array	An array of IDs of all the account's active locations	true
user_ids	Array	An array of IDs of all the account's active users	true

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_method_id": 2,
    "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

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 = {
  country: "US"
}
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}

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	Date and time when the address was created.	true
updated_at	String	Date and time when the address was last updated.	true
status	String	Tells whether the resource is 'active' or 'archived'.	true
company_id	Integer	The company id where the address belongs.
address1	String	First line of address.
address2	String	Second line of address.
city	String	City of an address.
company_name	String	Attention to field of an address.
country	String	Country of an address.
country_code	String	ISO3166-1 alpha2 code for the country, will be generated from country field if not provided
email	String	Email of person associated with address.
first_name	String	First name of person associated with address. Used in attention to field.
last_name	String	Last name of person associated with address. Used in attention to field.
label	String	A (unique per company) label for the address e.g. Shipping, Billing.
phone_number	String	Phone number of person associated with address.
state	String	State of an address.
suburb	String	Suburb of an address.
zip_code	String	Zip code of an address.

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",
      "country_code": "SG",
      "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": "Great Britain",
      "country_code": "GB",
      "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
ids	An array of address IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Default is active
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
address = gecko.Address.build({
  company_id: 1,
  label: "Main Office",
  address1: "12 Park Ave"
})
address.save

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",
    "country_code": "SG",
    "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	First line of address.	true
address2	String	Second line of address.
city	String	City of an address.
company_name	String	Attention to field of an address.
country	String	Country of an address.
country_code	String	ISO3166-1 alpha2 code for the country, will be generated from country field if not provided
email	String	Email of person associated with address.
first_name	String	First name of person associated with address. Used in attention to field.
last_name	String	Last name of person associated with address. Used in attention to field.
label	String	A (unique per company) label for the address e.g. Shipping, Billing.
phone_number	String	Phone number of person associated with address.
state	String	State of an address.
suburb	String	Suburb of an address.
zip_code	String	Zip code of an address.

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",
    "country_code": "SG",
    "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 = {
  address1: "12 Park Ave",
  city: "Singapore",
  label: "Main Office"
}
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 200 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 will no longer be available for future Sales Order.

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_method_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
tags	Array[String]	Company tags for easier filtering and searching
address_ids	Array		true
contact_ids	Array		true
note_ids	Array		true
default_price_type_id deprecated	String	Use default_price_list_id instead

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_method_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,
      "tags": [
        "wholesale"
      ],
      "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_method_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",
      "tags": [
        "reseller"
      ],
      "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
ids	An array of company IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Possible options are: active, disabled.
assignee_id	Possibe options: ID of any user
default_ledger_account_id
default_payment_method_id
default_payment_term_id
default_stock_location_id
default_tax_type_id
company_code
company_type	Possible options are: business, supplier, or consumer
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
company = gecko.Company.build({
  name: "TradeGecko (Demo)",
  company_type: "supplier"
})
company.save

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_method_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,
    "tags": [
      "wholesale"
    ],
    "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_method_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
tags	Array[String]	Company tags for easier filtering and searching
default_price_type_id deprecated	String	Use default_price_list_id instead

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_method_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,
    "tags": [
      "wholesale"
    ],
    "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 = {
  name: "Elephant",
  email: "hello@tradegecko.com",
  website: "http://tradegecko.com"
}
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 will no longer be available for future Sales Order.

HTTP Request

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

Composition

This is an object representing a composition.

The Composition object

Attribute	Type	Description	Readonly
bundle_id	Integer	The ID corresponding to the bundle variant. (Must be composite: true)	true
bundle_sku	String	The provided bundle variant's SKU.	true
component_id	Integer	The ID corresponding to this particular component variant of the bundle.	true
component_sku	String	The provided component variant's SKU.	true
quantity	String	The quantity of this component variant required to make up the bundle.	true

List all composition

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.Composition.where({:sku=>["B-SKU-001"]})

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/variants/composition/

{
  "composition": [
    {
      "bundle_id": 151235,
      "bundle_sku": "B-SKU-001",
      "component_id": 341234,
      "component_sku": "SKU-002",
      "quantity": "20"
    },
    {
      "bundle_id": 151235,
      "bundle_sku": "B-SKU-001",
      "component_id": 341235,
      "component_sku": "SKU-003",
      "quantity": "10"
    }
  ]
}

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

Filters

Arguments	Description
ids	An Array of Bundle IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
bundle_sku	Filter by Bundle SKU via sku parameter
component_id	An Array of Component IDs

HTTP Request:

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

Retrieve a particular composition

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.Composition.find(151235)

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/variants/composition/151235

{
  "composition": {
    "bundle_id": 151235,
    "bundle_sku": "B-SKU-001",
    "component_id": 341234,
    "component_sku": "SKU-002",
    "quantity": "20"
  }
}

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

HTTP Request

GET https://api.tradegecko.com/variants/composition/{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	Date and time when the contact was created.	true
updated_at	String	Date and time when the contact was last updated.	true
status	String	Tells whether the resource is 'active' or 'archived'.	true
company_id	Integer	The company id where the contact belongs.
email	String	Email address of the contact.
fax	String	Fax number of the contact.
first_name	String	First name of the contact.
last_name	String	Last name of the contact.
location	String	Department of the contact.
mobile	String	Mobile number of the contact.
notes	String	Notes on the contact.
phone_number	String	Phone number of the contact.
position	String	Job title of the contact.
online_ordering	Boolean	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
ids	An array of contact IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Default is active
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
contact = gecko.Contact.build({
  first_name: "TradeGecko (Demo)",
  company_id: 1
})
contact.save

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	Email address of the contact.
fax	String	Fax number of the contact.
first_name	String	First name of the contact.	true
last_name	String	Last name of the contact.
location	String	Department of the contact.
mobile	String	Mobile number of the contact.
notes	String	Notes on the contact.
phone_number	String	Phone number of the contact.
position	String	Job title of the contact.
online_ordering	Boolean	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 = {
  last_name: "Rogers"
}
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 will no longer be available for future Sales Order.

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
ids	An array of currency IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Default is active

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
currency = gecko.Currency.build({
  iso: "USD",
  precision: 4,
  format: "%n%u"
})
currency.save

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 = {
  separator: "."
}
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 will no longer be available for future Sales Order.

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	Date and time when the fulfillment was created.	true
updated_at	String	Date and time when the fulfillment was last updated.	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	Mode of delivery.
exchange_rate	String	Currency exchange_rate at time of creation.
notes	String	Additional notes.
packed_at	String	Timestamp when fulfillment is packed.
received_at	String	Timestamp when fulfillment is received.
service	String	Dictates the service where this fulfillment was handled.
shipped_at	String	Timestamp when fulfillment is shipped.
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	Company of associated order.	true
fulfillment_line_item_ids	Array	An array of IDs of the fulfillment's line items.	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
ids	An array of fulfillment IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
order_id
shipping_address_id
billing_address_id
stock_location_id
receipt	Used by Shopify
status	Possible options: packed, or fulfilled, void, deleted
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
fulfillment = gecko.Fulfillment.build({
  order_id: 1,
  packed_at: "2015-11-02T01:22:25.524Z",
  billing_address_id: 1,
  shipping_address_id: 1,
  fulfillment_line_items: [
    {
      order_line_item_id: 1,
      quantity: 1
    },
    {
      order_line_item_id: 2,
      quantity: 1
    }
  ]
})
fulfillment.save

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":"2015-11-02T01:22:25.524Z","billing_address_id":1,"shipping_address_id":1,"fulfillment_line_items":[{"order_line_item_id":1,"quantity":1},{"order_line_item_id":2,"quantity":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	Mode of delivery.
exchange_rate	String	Currency exchange_rate at time of creation.
notes	String	Additional notes.
packed_at	String	Timestamp when fulfillment is packed.
received_at	String	Timestamp when fulfillment is received.
service	String	Dictates the service where this fulfillment was handled.
shipped_at	String	Timestamp when fulfillment is shipped.
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	Sales value of the variant in base currency at fulfillment shipped_at date.
position	Integer	Display order.
quantity	String	Quantity of the variant fulfilled.	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 = {
  tracking_company: "GeckoShip",
  tracking_number: "123TrackMe"
}
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.

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	Sales value of the variant in base currency at fulfillment shipped_at date.	true
position	Integer	Display order.
quantity	String	Quantity of the variant fulfilled.
variant_id	String	The order_line_item's variant.	true
variant_sku	String	The sku of the order_line_item's variant.	true

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",
      "variant_id": 1,
      "variant_sku": "SKU1"
    },
    {
      "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",
      "variant_id": 2,
      "variant_sku": "SKU2"
    },
    {
      "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",
      "variant_id": 3,
      "variant_sku": "SKU3"
    }
  ]
}

Returns a list of fulfillment_line_items you’ve previously created. The fulfillment_line_items are returned in sorted order, based on the position attribute.

Filters

Arguments	Description
ids	An array of fulfillment_line_item IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00: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
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
fulfillment_line_item = gecko.FulfillmentLineItem.build({
  fulfillment_id: 1,
  order_line_item_id: 1,
  quantity: "10.0",
  position: 1
})
fulfillment_line_item.save

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",
    "variant_id": 1,
    "variant_sku": "SKU1"
  }
}

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	Sales value of the variant in base currency at fulfillment shipped_at date.
position	Integer	Display order.
quantity	String	Quantity of the variant fulfilled.	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",
    "variant_id": 1,
    "variant_sku": "SKU1"
  }
}

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 = {
  quantity: "22.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.

HTTP Request

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

FulfillmentReturn

This is an object representing a fulfillment_return of an order. Orders can have multiple fulfillment_returns but a fulfillment_return object belongs to only one Order.

The FulfillmentReturn object

Attribute	Type	Description	Readonly
id	Integer	A unique identifier for the resource.	true
created_at	String	Date and time when the fulfillment_return was created.	true
updated_at	String	Date and time when the fulfillment_return was last updated.	true
status	String	Tells whether the resource is 'returning', 'received', 'void' or 'deleted'
order_id	Integer	The order to which the fulfillment_return belongs.
location_id	Integer	The location to which the fulfillment_return belongs.
tracking_number	String	Tracking number of fulfillment_return.
tracking_url	String	Tracking url of fulfillment_return.
tracking_company	String	Tracking company used for fulfillment_return.
delivery_type	String	Mode of delivery.
notes	String	Additional notes.
exchange_rate	String	Currency exchange_rate at time of creation.
received_at	String	Timestamp when fulfillment_return is received.
credit_note_number	String	After a fulfillment return is created, a credit note with this number is created for accounting purposes.
company_id	Integer	Company of associated order.	true

List all fulfillment_returns

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.FulfillmentReturn.where(limit: 25, status: 'active')

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_returns/

{
  "fulfillment_returns": [
    {
      "id": 1,
      "created_at": "2015-11-02T01:22:25.535Z",
      "updated_at": "2015-11-02T01:22:25.535Z",
      "order_id": 1,
      "location_id": 1,
      "delivery_type": null,
      "exchange_rate": "1.0",
      "notes": null,
      "received_at": null,
      "tracking_company": null,
      "tracking_number": null,
      "tracking_url": null,
      "status": "returning",
      "credit_note_number": "CN0001",
      "order_number": "SO0001",
      "company_id": 1
    }
  ]
}

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

Filters

Arguments	Description
ids	An array of fulfillment_return IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Default is active
order_id
location_id
company_id

HTTP Request:

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

Create a new fulfillment_return

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_return = gecko.FulfillmentReturn.build({
  order_id: 1,
  fulfillment_return_line_items: [
    {
      order_line_item_id: 1,
      quantity: 1
    },
    {
      order_line_item_id: 2,
      quantity: 1
    }
  ]
})
fulfillment_return.save

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_returns/ -d '{"fulfillment_return":{"order_id":1,"fulfillment_return_line_items":[{"order_line_item_id":1,"quantity":1},{"order_line_item_id":2,"quantity":1}]}}'

{
  "fulfillment_return": {
    "id": 1,
    "created_at": "2015-11-02T01:22:25.535Z",
    "updated_at": "2015-11-02T01:22:25.535Z",
    "order_id": 1,
    "location_id": 1,
    "delivery_type": null,
    "exchange_rate": "1.0",
    "notes": null,
    "received_at": null,
    "tracking_company": null,
    "tracking_number": null,
    "tracking_url": null,
    "status": "returning",
    "credit_note_number": "CN0001",
    "order_number": "SO0001",
    "company_id": 1
  }
}

Creates a new fulfillment_return object. This endpoint also accepts embedded fulfillment_return_line_items.

Arguments

Attribute	Type	Description	Required
order_id	Integer	The order to which the fulfillment_return belongs.	true
location_id	Integer	The location to which the fulfillment_return belongs.
tracking_number	String	Tracking number of fulfillment_return.
tracking_url	String	Tracking url of fulfillment_return.
tracking_company	String	Tracking company used for fulfillment_return.
delivery_type	String	Mode of delivery.
notes	String	Additional notes.
exchange_rate	String	Currency exchange_rate at time of creation.
received_at	String	Timestamp when fulfillment_return is received.
credit_note_number	String	After a fulfillment return is created, a credit note with this number is created for accounting purposes.

FulfillmentReturnLineItem

Child Attribute	Type	Description	Required
fulfillment_return_id	Integer	The fulfillment_return to which the fulfillment_return_line_item belongs.	true
order_line_item_id	Integer	The order_line_item to which the fulfillment_return_line_item belongs.	true
base_price	String
position	Integer
quantity	String		true
ledger_account_id	Integer

HTTP Request

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

Retrieve a particular fulfillment_return

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.FulfillmentReturn.find(1)

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_returns/1

{
  "fulfillment_return": {
    "id": 1,
    "created_at": "2015-11-02T01:22:25.535Z",
    "updated_at": "2015-11-02T01:22:25.535Z",
    "order_id": 1,
    "location_id": 1,
    "delivery_type": null,
    "exchange_rate": "1.0",
    "notes": null,
    "received_at": null,
    "tracking_company": null,
    "tracking_number": null,
    "tracking_url": null,
    "status": "returning",
    "credit_note_number": "CN0001",
    "order_number": "SO0001",
    "company_id": 1
  }
}

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

HTTP Request

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

Update a fulfillment_return

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_return = gecko.FulfillmentReturn.find(1)
fulfillment_return.attributes = {
  location_id: 2
}
fulfillment_return.save

curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_returns/1 -d '{"fulfillment_return":{"location_id":2}}'

Response

Returns 204 status when the fulfillment_return gets updated successfully.

Updates the specified fulfillment_return 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_return creation call.

HTTP Request

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

Delete a fulfillment_return

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_return = gecko.FulfillmentReturn.find(1)
fulfillment_return.destroy

curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_returns/1

Response

Returns 204 status when the fulfillment_return gets deleted successfully.

Permanently deletes a fulfillment_return. It cannot be undone.

HTTP Request

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

FulfillmentReturnLineItem

This is an object representing a fulfillment_return_line_item of a fulfillment_return. Fulfillment_returns can have multiple fulfillment_return_line_items but a fulfillment_return_line_item object belongs to only one Fulfillment_return.

The FulfillmentReturnLineItem object

Attribute	Type	Description	Readonly
id	Integer	A unique identifier for the resource.	true
created_at	String	Date and time when the fulfillment_return_line_item was created.	true
updated_at	String	Date and time when the fulfillment_return_line_item was created.	true
fulfillment_return_id	Integer	The fulfillment_return to which the fulfillment_return_line_item belongs.
order_line_item_id	Integer	The order_line_item to which the fulfillment_return_line_item belongs.
base_price	String
position	Integer
quantity	String
ledger_account_id	Integer

List all fulfillment_return_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.FulfillmentReturnLineItem.where(limit: 25, status: 'active')

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_return_line_items/

{
  "fulfillment_return_line_items": [
    {
      "id": 1,
      "created_at": "2015-11-02T01:22:25.535Z",
      "updated_at": "2015-11-02T01:22:25.535Z",
      "fulfillment_return_id": 1,
      "order_line_item_id": 1,
      "base_price": null,
      "position": 0,
      "quantity": "1.0",
      "ledger_account_id": null,
      "stock_trail_ids": [
        1
      ]
    }
  ]
}

Returns a list of fulfillment_return_line_items you’ve previously created. The fulfillment_return_line_items are returned in sorted order, based on the position attribute.

Filters

Arguments	Description
ids	An array of fulfillment_return_line_item IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
fulfillment_return_id	Filter fulfillment_return_line_items by fulfillment_return
order_line_item_id	Filter fulfillment_return_line_items by order_line_item
ledger_account_id

HTTP Request:

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

Create a new fulfillment_return_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_return_line_item = gecko.FulfillmentReturnLineItem.build({
  fulfillment_return_id: 1,
  order_line_item_id: 1,
  quantity: "10.0"
})
fulfillment_return_line_item.save

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_return_line_items/ -d '{"fulfillment_return_line_item":{"fulfillment_return_id":1,"order_line_item_id":1,"quantity":"10.0"}}'

{
  "fulfillment_return_line_item": {
    "id": 1,
    "created_at": "2015-11-02T01:22:25.535Z",
    "updated_at": "2015-11-02T01:22:25.535Z",
    "fulfillment_return_id": 1,
    "order_line_item_id": 1,
    "base_price": null,
    "position": 0,
    "quantity": "1.0",
    "ledger_account_id": null,
    "stock_trail_ids": [
      1
    ]
  }
}

Creates a new fulfillment_return_line_item object.

Arguments

Attribute	Type	Description	Required
fulfillment_return_id	Integer	The fulfillment_return to which the fulfillment_return_line_item belongs.	true
order_line_item_id	Integer	The order_line_item to which the fulfillment_return_line_item belongs.	true
base_price	String
position	Integer
quantity	String		true
ledger_account_id	Integer

HTTP Request

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

Retrieve a particular fulfillment_return_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.FulfillmentReturnLineItem.find(1)

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_return_line_items/1

{
  "fulfillment_return_line_item": {
    "id": 1,
    "created_at": "2015-11-02T01:22:25.535Z",
    "updated_at": "2015-11-02T01:22:25.535Z",
    "fulfillment_return_id": 1,
    "order_line_item_id": 1,
    "base_price": null,
    "position": 0,
    "quantity": "1.0",
    "ledger_account_id": null,
    "stock_trail_ids": [
      1
    ]
  }
}

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

HTTP Request

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

Update a fulfillment_return_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_return_line_item = gecko.FulfillmentReturnLineItem.find(1)
fulfillment_return_line_item.attributes = {
  quantity: "22.0"
}
fulfillment_return_line_item.save

curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_return_line_items/1 -d '{"fulfillment_return_line_item":{"quantity":"22.0"}}'

Response

Returns 204 status when the fulfillment_return_line_item gets updated successfully.

Updates the specified fulfillment_return_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_return_line_item creation call.

HTTP Request

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

Delete a fulfillment_return_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_return_line_item = gecko.FulfillmentReturnLineItem.find(1)
fulfillment_return_line_item.destroy

curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/fulfillment_return_line_items/1

Response

Returns 204 status when the fulfillment_return_line_item gets deleted successfully.

Permanently deletes a fulfillment_return_line_item. It cannot be undone.

HTTP Request

DELETE https://api.tradegecko.com/fulfillment_return_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
product_id	Integer	The product to which the image belongs.
variant_id deprecated	Integer	The variant to which the image belongs.
variant_ids	Array	The variants 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,
      "product_id": 1,
      "variant_id": 1,
      "variant_ids": [
        1,
        2
      ],
      "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,
      "product_id": 1,
      "variant_id": 1,
      "variant_ids": [
        1,
        2
      ],
      "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
ids	An array of image IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
product_id	Filter images by product
variant_id	Filter images by variant
variant_ids	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
image = gecko.Image.build({
  product_id: 1,
  variant_ids: [
    1,
    2
  ],
  url: "http://www.thisismyimage.com/image.png"
})
image.save

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/images/ -d '{"image":{"product_id":1,"variant_ids":[1,2],"url":"http://www.thisismyimage.com/image.png"}}'

{
  "image": {
    "id": 2,
    "product_id": 1,
    "variant_id": 1,
    "variant_ids": [
      1,
      2
    ],
    "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
product_id	Integer	The product to which the image belongs.	true
variant_id deprecated	Integer	The variant to which the image belongs.
variant_ids	Array	The variants 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,
    "product_id": 1,
    "variant_id": 1,
    "variant_ids": [
      1,
      2
    ],
    "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.

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": [
        {
          "quantity": "1.0",
          "order_line_item_id": 123
        },
        {
          "quantity": "1.0",
          "order_line_item_id": 456
        }
      ],
      "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
ids	An array of invoice IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00: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
invoice = gecko.Invoice.build({
  order_id: 1,
  billing_address_id: 1,
  shipping_address_id: 1,
  invoice_line_items: [
    {
      quantity: "1.0",
      order_line_item_id: 123
    },
    {
      quantity: "1.0",
      order_line_item_id: 456
    }
  ]
})
invoice.save

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":[{"quantity":"1.0","order_line_item_id":123},{"quantity":"1.0","order_line_item_id":456}]}}'

{
  "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": [
      {
        "quantity": "1.0",
        "order_line_item_id": 123
      },
      {
        "quantity": "1.0",
        "order_line_item_id": 456
      }
    ],
    "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": [
      {
        "quantity": "1.0",
        "order_line_item_id": 123
      },
      {
        "quantity": "1.0",
        "order_line_item_id": 456
      }
    ],
    "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 = {
  billing_address_id: 2,
  payment_term_id: 1
}
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.

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, based on the position attribute.

Filters

Arguments	Description
ids	An array of invoice_line_item IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00: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
invoice_line_item = gecko.InvoiceLineItem.build({
  invoice_id: 1,
  order_line_item_id: 1,
  quantity: "10.0",
  position: 1
})
invoice_line_item.save

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 = {
  quantity: "22.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.

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	A unique name among 'active' locations
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
ids	An array of location IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Default is active

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
location = gecko.Location.build({
  label: "Secondary office",
  address1: "887 Orchard Road",
  country: "SG"
})
location.save

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":"SG"}}'

{
  "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	A unique name among 'active' locations	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 = {
  address1: "121 Telok Ayer Street"
}
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 will no longer be available for future Sales Order.

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
ids	An array of note IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00: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
note = gecko.Note.build({
  company_id: 1,
  body: "These kittens are adorable."
})
note.save

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 = {
  body: "Cupcakes are for champions"
}
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.

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	The date and time (ISO8601 format) when the Order was created_at	true
updated_at	String	The date and time (ISO8601 format) when the Order was last updated	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[String]	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": "https://go.tradegecko.com/d/not-a-real-token-2",
      "assignee_id": null,
      "billing_address_id": 1,
      "company_id": 1,
      "contact_id": null,
      "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": null,
      "order_number": "SO0001",
      "packed_status": "unpacked",
      "payment_status": "unpaid",
      "phone_number": "+1 650-468-2904",
      "reference_number": null,
      "return_status": "unreturned",
      "returning_status": "unreturning",
      "ship_at": null,
      "source_url": null,
      "status": "draft",
      "tax_label": "GST",
      "tax_override": null,
      "tax_treatment": "inclusive",
      "total": 0,
      "tags": [
        "sales"
      ],
      "fulfillment_ids": [
        10
      ],
      "fulfillment_return_ids": [
        21
      ],
      "invoice_ids": [
        20
      ],
      "payment_ids": [
        30
      ],
      "refund_ids": [
        40
      ],
      "invoices": [
        50
      ],
      "cached_total": 0,
      "default_price_type_id": "wholesale",
      "source": null,
      "tax_type": "exclusive",
      "tracking_number": null,
      "url": null,
      "source_id": null,
      "invoice_numbers": {
        "1": "INV001"
      },
      "order_line_item_ids": [
        3,
        4
      ]
    },
    {
      "id": 1,
      "created_at": "2015-11-12T08:06:00.561Z",
      "updated_at": "2015-11-12T08:06:00.561Z",
      "document_url": "https://go.tradegecko.com/d/not-a-real-token",
      "assignee_id": null,
      "billing_address_id": 1,
      "company_id": 1,
      "contact_id": null,
      "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": null,
      "order_number": "SO0001",
      "packed_status": "unpacked",
      "payment_status": "unpaid",
      "phone_number": "+1 650-468-2904",
      "reference_number": null,
      "return_status": "unreturned",
      "returning_status": "unreturning",
      "ship_at": null,
      "source_url": null,
      "status": "draft",
      "tax_label": "GST",
      "tax_override": null,
      "tax_treatment": "exclusive",
      "total": 0,
      "tags": [
        "promotion"
      ],
      "fulfillment_ids": [
        10
      ],
      "fulfillment_return_ids": [
        11
      ],
      "invoice_ids": [
        12
      ],
      "payment_ids": [
        13
      ],
      "refund_ids": [
        14
      ],
      "invoices": [
        15
      ],
      "cached_total": 0,
      "default_price_type_id": "wholesale",
      "source": null,
      "tax_type": "exclusive",
      "tracking_number": null,
      "url": null,
      "source_id": null,
      "invoice_numbers": {
        "1": "INV001"
      },
      "order_line_item_ids": [
        1,
        2
      ]
    }
  ]
}

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
ids	An array of order IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00: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
reference_number
tags
status	Possible options are draft, deleted, active, finalized, fulfilled, void
payment_status	One or multiple of unpaid, partial and 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
order = gecko.Order.build({
  company_id: 1,
  issued_at: "2015-11-12T08:06:01.561Z",
  billing_address_id: 1,
  shipping_address_id: 1,
  order_line_items: [
    {
      variant_id: 123,
      quantity: 2,
      price: 10
    },
    {
      variant_id: 456,
      quantity: 5,
      price: 15.5
    }
  ]
})
order.save

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":"2015-11-12T08:06:01.561Z","billing_address_id":1,"shipping_address_id":1,"order_line_items":[{"variant_id":123,"quantity":2,"price":10},{"variant_id":456,"quantity":5,"price":15.5}]}}'

{
  "order": {
    "id": 2,
    "created_at": "2015-11-12T08:06:01.561Z",
    "updated_at": "2015-11-12T08:06:01.561Z",
    "document_url": "https://go.tradegecko.com/d/not-a-real-token-2",
    "assignee_id": null,
    "billing_address_id": 1,
    "company_id": 1,
    "contact_id": null,
    "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": null,
    "order_number": "SO0001",
    "packed_status": "unpacked",
    "payment_status": "unpaid",
    "phone_number": "+1 650-468-2904",
    "reference_number": null,
    "return_status": "unreturned",
    "returning_status": "unreturning",
    "ship_at": null,
    "source_url": null,
    "status": "draft",
    "tax_label": "GST",
    "tax_override": null,
    "tax_treatment": "inclusive",
    "total": 0,
    "tags": [
      "sales"
    ],
    "fulfillment_ids": [
      10
    ],
    "fulfillment_return_ids": [
      21
    ],
    "invoice_ids": [
      20
    ],
    "payment_ids": [
      30
    ],
    "refund_ids": [
      40
    ],
    "invoices": [
      50
    ],
    "cached_total": 0,
    "default_price_type_id": "wholesale",
    "source": null,
    "tax_type": "exclusive",
    "tracking_number": null,
    "url": null,
    "source_id": null,
    "invoice_numbers": {
      "1": "INV001"
    },
    "order_line_item_ids": [
      3,
      4
    ]
  }
}

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[String]	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	Optional field for tracking the basic type of a line item, currently used for Channel/API integrations only, blank otherwise. Supported values are: 'product', 'discount', 'shipping', 'rounding', 'fee', and 'gift_wrap'
position	Integer
price	String	Price of a single item. If not provided, we will attempt to pull the price from the parent order's default price list	true
quantity	String
tax_rate_override	String
tax_rate deprecated	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": "https://go.tradegecko.com/d/not-a-real-token-2",
    "assignee_id": null,
    "billing_address_id": 1,
    "company_id": 1,
    "contact_id": null,
    "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": null,
    "order_number": "SO0001",
    "packed_status": "unpacked",
    "payment_status": "unpaid",
    "phone_number": "+1 650-468-2904",
    "reference_number": null,
    "return_status": "unreturned",
    "returning_status": "unreturning",
    "ship_at": null,
    "source_url": null,
    "status": "draft",
    "tax_label": "GST",
    "tax_override": null,
    "tax_treatment": "inclusive",
    "total": 0,
    "tags": [
      "sales"
    ],
    "fulfillment_ids": [
      10
    ],
    "fulfillment_return_ids": [
      21
    ],
    "invoice_ids": [
      20
    ],
    "payment_ids": [
      30
    ],
    "refund_ids": [
      40
    ],
    "invoices": [
      50
    ],
    "cached_total": 0,
    "default_price_type_id": "wholesale",
    "source": null,
    "tax_type": "exclusive",
    "tracking_number": null,
    "url": null,
    "source_id": null,
    "invoice_numbers": {
      "1": "INV001"
    },
    "order_line_item_ids": [
      3,
      4
    ]
  }
}

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 = {
  status: "active",
  email: "hello@tradegecko.com",
  billing_address_id: 2
}
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}

Order actions

Use the following endpoints to manage the order's invoice, payment and fulfillment. POST /orders/[:order_id]/actions/[:action]

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/orders/[:order_id]/actions/[:order_action]

Action	Description
invoice	Invoices the whole order. If there are already existing invoices, creates another invoice with the remaining uninvoiced line items
pay	Creates payments for the entire order value. It will pay any existing unpaid or partially paid invoices and create an invoice and payment for the remaining value
pack	Create a fulfillment with status: packed for any unpacked items.
fulfil	Create a fulfillment with status: fulfilled. It will fulfill any existing fulfillments and create a new fulfillment for any remaining items
void	Voids the order

Customized actions

Some action endpoints would allow you to pass additional parameters on the body of your POST request in order for you to do more with just a single API call

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/orders/[:order_id]/actions/[:order_action]
-d {"payment":{"payment_method_name": "Credit Card", "paid_at": "2015-11-12T08:06:01.561Z"}}

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/orders/[:order_id]/actions/[:order_action]
-d {"fulfillment":{"tracking_number": "00J6E0001234", "tracking_url": "https://trackpackage.com?track=00J6E0001234", "tracking_company": "Track Package", "service": "TPackage", "notes": "Handle with care"}}

Action	Description	Allowed Attributes
pay	Set the order's payment status to paid, create an invoice and create a payment using the provided payment_method_name and paid_at in a single API call	payment_method_name, paid_at
invoice	Set the order's invoiced status to invoiced, and creates an invoice for all uninvoiced items in a single API call	due_at, invoiced_at, notes
pack	Set the order's status to packed, and create a fulfillment using any provided tracking details and notes in a single API call	tracking_number, tracking_company, tracking_url, service, notes
fulfil	Set the order's status to fulfilled, and create a fulfillment using any provided tracking details and notes in a single API call	tracking_number, tracking_company, tracking_url, service, notes

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.

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	Optional field for tracking the basic type of a line item, currently used for Channel/API integrations only, blank otherwise. Supported values are: 'product', 'discount', 'shipping', 'rounding', 'fee', and 'gift_wrap'
position	Integer
price	String	Price of a single item. If not provided, we will attempt to pull the price from the parent order's default price list
quantity	String
tax_rate_override	String
tax_rate deprecated	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": null,
      "label": null,
      "line_type": null,
      "position": 0,
      "price": "189.0",
      "quantity": "1.0",
      "tax_rate_override": null,
      "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": "product",
      "position": 0,
      "price": "189.0",
      "quantity": "1.0",
      "tax_rate_override": null,
      "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, based on the position attribute.

Filters

Arguments	Description
ids	An array of order_line_item IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00: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
order_status	Filter order_line_items by order status

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
order_line_item = gecko.OrderLineItem.build({
  quantity: "12.0",
  order_id: 1,
  tax_type_id: 1,
  price: "10.0"
})
order_line_item.save

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": null,
    "label": null,
    "line_type": null,
    "position": 0,
    "price": "189.0",
    "quantity": "1.0",
    "tax_rate_override": null,
    "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	Optional field for tracking the basic type of a line item, currently used for Channel/API integrations only, blank otherwise. Supported values are: 'product', 'discount', 'shipping', 'rounding', 'fee', and 'gift_wrap'
position	Integer
price	String	Price of a single item. If not provided, we will attempt to pull the price from the parent order's default price list	true
quantity	String
tax_rate_override	String
tax_rate deprecated	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": null,
    "label": null,
    "line_type": null,
    "position": 0,
    "price": "189.0",
    "quantity": "1.0",
    "tax_rate_override": null,
    "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 = {
  quantity: "22.0",
  price: "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.

HTTP Request

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

PaymentMethod

This is an object representing a payment_method.

The PaymentMethod object

Attribute	Type	Description	Readonly
id	Integer	A unique identifier for the resource.	true
created_at	String		true
updated_at	String		true
name	String	Name of the payment method.
is_default	Boolean	Is the default payment method of the account.	true

List all payment_methods

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/payment_methods/

{
  "payment_methods": [
    {
      "id": 1,
      "created_at": "2019-10-24T11:21:57.700Z",
      "updated_at": "2019-10-24T11:21:57.700Z",
      "name": "Cash",
      "is_default": true
    },
    {
      "id": 2,
      "created_at": "2019-10-24T11:21:57.710Z",
      "updated_at": "2019-10-24T11:21:57.710Z",
      "name": "Credit Card",
      "is_default": false
    },
    {
      "id": 3,
      "created_at": "2019-10-24T11:21:57.721Z",
      "updated_at": "2019-10-24T11:21:57.721Z",
      "name": "Bank Transfer",
      "is_default": false
    }
  ]
}

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

Filters

Arguments	Description
ids	An array of payment_method IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
name

HTTP Request:

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

Create a new payment_method

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/payment_methods/ -d '{"payment_method":{"name":"Wire Transfer"}}'

{
  "payment_method": {
    "id": 1,
    "created_at": "2019-10-24T11:21:57.700Z",
    "updated_at": "2019-10-24T11:21:57.700Z",
    "name": "Cash",
    "is_default": true
  }
}

Creates a new payment_method object.

Arguments

Attribute	Type	Description	Required
name	String	Name of the payment method.	true

HTTP Request

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

Retrieve a particular payment_method

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/payment_methods/

{
  "payment_method": {
    "id": 1,
    "created_at": "2019-10-24T11:21:57.700Z",
    "updated_at": "2019-10-24T11:21:57.700Z",
    "name": "Cash",
    "is_default": true
  }
}

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

HTTP Request

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

Update a payment_method

curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com//1 -d '{"payment_method":{"name":"PayPal"}}'

Response

Returns 204 status when the payment_method gets updated successfully.

Updates the specified payment_method 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_method creation call.

HTTP Request

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

Delete a payment_method

curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/payment_methods/1

Response

Returns 204 status when the payment_method gets deleted successfully.

Permanently deletes a payment_method. It cannot be undone. This payment_method will no longer be available for future Payment.

HTTP Request

DELETE https://api.tradegecko.com/payment_methods/{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
ids	An array of payment_term IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Default is active

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
payment_term = gecko.PaymentTerm.build({
  name: "NET30",
  due_in_days: "30",
  from: "eom"
})
payment_term.save

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 = {
  from: "now"
}
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 will no longer be available for future Invoice.

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 the product (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
image_ids	Array	The IDs of all the images linked to the product
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
      ],
      "image_ids": [
        1,
        2
      ],
      "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
      ],
      "image_ids": [
        1
      ],
      "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
ids	An array of product IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Possible options are: active, disabled.
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
product = gecko.Product.build({
  name: "Everlasting Gobstopper",
  opt1: "Colour"
})
product.save

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
    ],
    "image_ids": [
      1,
      2
    ],
    "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
hs_code	String	Harmonized System Code
country_of_origin	String	Two letter country code (e.g. SG, US)
initial_cost_price	String	The initial item cost price of the variant, only available when first creating the variant
initial_stock_level	String	The initial stock level of the variant, only available when first creating the variant
initial_stock_location_id	Integer	The ID of the stock location where initial stock levels should be added, only available when first creating the variant, defaults to your primary stock location
keep_selling	Boolean	Allow item to continue to be sold, even if it is no longer in stock
manage_stock	Boolean	For composite variants, the value of manage_stock will always be true
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)
purchasable	Boolean	Tells whether you can create Purchase Order with the variant
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, g, oz or lb)
wholesale_price	String	The recommended wholesale price for this product
image_ids	Array	Images assigned to the variant. The order of the Image IDs here is the position of the images on the variant.
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
    ],
    "image_ids": [
      1,
      2
    ],
    "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 = {
  opt2: "Size",
  opt3: "Weight"
}
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.

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	Defaults to 14 days from creation
email	String
notes	String
order_number	String
payment_due_at	String	Defaults to 14 days from creation
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.
issued_at	String	Date when purchase was issued.
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",
      "payment_due_at": "2015-12-07",
      "procurement_status": "unprocured",
      "reference_number": null,
      "tax_treatment": "exclusive",
      "issued_at": "2015-11-23",
      "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",
      "payment_due_at": "2015-12-07",
      "procurement_status": "unprocured",
      "reference_number": null,
      "status": "active",
      "tax_treatment": "exclusive",
      "issued_at": "2015-11-23",
      "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
ids	An array of purchase_order IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Possible options are: active, disabled.
billing_address_id
company_id
currency_id
stock_location_id
supplier_address_id
due_at
order_number
payment_due_at
issued_at
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
purchase_order = gecko.PurchaseOrder.build({
  company_id: 1,
  issued_at: "2015-11-23T11:19:07.072Z",
  billing_address_id: 1,
  shipping_address_id: 1
})
purchase_order.save

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":"2015-11-23T11:19:07.072Z","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",
    "payment_due_at": "2015-12-07",
    "procurement_status": "unprocured",
    "reference_number": null,
    "tax_treatment": "exclusive",
    "issued_at": "2015-11-23",
    "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	Defaults to 14 days from creation	true
email	String
notes	String
order_number	String
payment_due_at	String	Defaults to 14 days from creation	true
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
issued_at	String	Date when purchase was issued.	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	If it has been received, the procurement object this purchase_order_line_item belongs.
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",
    "payment_due_at": "2015-12-07",
    "procurement_status": "unprocured",
    "reference_number": null,
    "tax_treatment": "exclusive",
    "issued_at": "2015-11-23",
    "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 = {
  status: "active",
  email: "hello@tradegecko.com",
  billing_address_id: 2
}
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}

Purchase Order actions

Use the following endpoints to manage the receiving of the purchase order. POST /purchase_orders/[:purchase_order_id]/actions/[:action]

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/purchase_orders/[:purchase_order_id]/actions/[:purchase_order_action]

Action	Description
receive	Create a procurement for the purchase order

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.

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	If it has been received, the procurement object this purchase_order_line_item belongs.	true
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, based on the position attribute.

Filters

Arguments	Description
ids	An array of purchase_order_line_item IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00: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	Filter purchase_order_line_items by procurement
purchase_order_status	Filter purchase_order_line_items by purchase order status

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
purchase_order_line_item = gecko.PurchaseOrderLineItem.build({
  quantity: "12.0",
  order_id: 1,
  tax_type_id: 1,
  price: "10.0"
})
purchase_order_line_item.save

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	If it has been received, the procurement object this purchase_order_line_item belongs.
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 = {
  quantity: "22.0",
  price: "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.

HTTP Request

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

StockAdjustment

This is an object representing a stock_adjustment.

The StockAdjustment object

Attribute	Type	Description	Readonly
id	Integer	A unique identifier for the resource.	true
created_at	String		true
updated_at	String		true
adjustment_number	String
notes	String
reason	String	One of supplier (New Products), customer (Returned goods), damaged, shrinkage, promotion or production.
reason_label	String	Display label of the stock adjustment's reason (unifies the reason and stock_adjustment_reason_id fields)
stock_adjustment_reason_id	Integer	Internal ID of Custom stock adjustment reasons. See https://go.tradegecko.com/account/stock_adjustment_reasons for your accounts reasons
stock_location_id	Integer	Defaults to account primary_location.
cached_quantity	String	Cumulative quantity of all variants being adjusted	true
cached_total	String	Cumulative value of all variants being adjusted	true
stock_adjustment_line_item_ids	Array		true

List all stock_adjustments

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_adjustments/

{
  "stock_adjustments": [
    {
      "id": 1,
      "created_at": "2015-11-25T07:27:20.194Z",
      "updated_at": "2015-11-25T07:27:20.740Z",
      "adjustment_number": "SA0001",
      "notes": null,
      "reason": "promotion",
      "stock_location_id": 1,
      "cached_quantity": "1.0",
      "cached_total": "62.5",
      "stock_adjustment_line_item_ids": [
        1
      ]
    },
    {
      "id": 2,
      "created_at": "2015-11-25T07:27:39.813Z",
      "updated_at": "2015-11-25T07:27:40.176Z",
      "adjustment_number": "SA0002",
      "notes": "Reversal of Stock Adjustment #SA0001",
      "reason": "damaged",
      "stock_location_id": 1,
      "cached_quantity": "-15.0",
      "cached_total": "37.5",
      "stock_adjustment_line_item_ids": [
        3,
        4
      ]
    }
  ]
}

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

Filters

Arguments	Description
ids	An array of stock_adjustment IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
adjustment_number
stock_adjustment_reason_id
stock_location_id

HTTP Request:

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

Create a new stock_adjustment

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_adjustments/ -d '{"stock_adjustment":{"adjustment_number":"SA0001","notes":null,"reason":"promotion","stock_location_id":1,"stock_adjustment_line_items":[{"variant_id":1,"quantity":-1}]}}'

{
  "stock_adjustment": {
    "id": 1,
    "created_at": "2015-11-25T07:27:20.194Z",
    "updated_at": "2015-11-25T07:27:20.740Z",
    "adjustment_number": "SA0001",
    "notes": null,
    "reason": "promotion",
    "stock_location_id": 1,
    "cached_quantity": "1.0",
    "cached_total": "62.5",
    "stock_adjustment_line_item_ids": [
      1
    ]
  }
}

Creates a new stock_adjustment object. This endpoint also accepts embedded stock_adjustment_line_items.

Arguments

Attribute	Type	Description	Required
adjustment_number	String
notes	String
reason	String	One of supplier (New Products), customer (Returned goods), damaged, shrinkage, promotion or production.
stock_location_id	Integer	Defaults to account primary_location.	true

StockAdjustmentLineItem

Child Attribute	Type	Description	Required
stock_adjustment_id	Integer	The stock_adjustment to which the resource belongs.	true
variant_id	Integer	The variant to which the resource belongs.	true
quantity	String
position	Integer
price	String	Required only when quantity is greater than 0. For negative quantities, the current Moving Average Cost will be assigned automatically.	true

HTTP Request

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

Retrieve a particular stock_adjustment

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_adjustments/

{
  "stock_adjustment": {
    "id": 1,
    "created_at": "2015-11-25T07:27:20.194Z",
    "updated_at": "2015-11-25T07:27:20.740Z",
    "adjustment_number": "SA0001",
    "notes": null,
    "reason": "promotion",
    "stock_location_id": 1,
    "cached_quantity": "1.0",
    "cached_total": "62.5",
    "stock_adjustment_line_item_ids": [
      1
    ]
  }
}

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

HTTP Request

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

Delete a stock_adjustment

curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_adjustments/1

Response

Returns 204 status when the stock_adjustment gets deleted successfully.

Permanently deletes a stock_adjustment. It cannot be undone.

HTTP Request

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

StockAdjustmentLineItem

This is an object representing a stock_adjustment_line_item of a stock_adjustment. Stock_adjustments can have multiple stock_adjustment_line_items but a stock_adjustment_line_item object belongs to only one Stock_adjustment.

The StockAdjustmentLineItem object

Attribute	Type	Description	Readonly
id	Integer	A unique identifier for the resource.	true
created_at	String		true
updated_at	String		true
stock_adjustment_id	Integer	The stock_adjustment to which the resource belongs.
variant_id	Integer	The variant to which the resource belongs.
quantity	String
position	Integer
price	String	Required only when quantity is greater than 0. For negative quantities, the current Moving Average Cost will be assigned automatically.

List all stock_adjustment_line_items

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_adjustment_line_items/

{
  "stock_adjustment_line_items": [
    {
      "id": 3,
      "created_at": "2015-11-25T07:27:39.967Z",
      "updated_at": "2015-11-25T07:27:39.967Z",
      "stock_adjustment_id": 2,
      "variant_id": 8,
      "quantity": "-5.0",
      "position": 0,
      "price": "2.5"
    },
    {
      "id": 1,
      "created_at": "2015-11-25T07:27:20.464Z",
      "updated_at": "2015-11-25T07:27:20.464Z",
      "stock_adjustment_id": 1,
      "variant_id": 8,
      "quantity": "10.0",
      "position": 0,
      "price": "2.5"
    },
    {
      "id": 4,
      "created_at": "2015-11-25T07:27:40.136Z",
      "updated_at": "2015-11-25T07:27:40.136Z",
      "stock_adjustment_id": 2,
      "variant_id": 9,
      "quantity": "-10.0",
      "position": 1,
      "price": "2.5"
    },
    {
      "id": 2,
      "created_at": "2015-11-25T07:27:20.697Z",
      "updated_at": "2015-11-25T07:27:20.697Z",
      "stock_adjustment_id": 1,
      "variant_id": 9,
      "quantity": "15.0",
      "position": 1,
      "price": "2.5"
    }
  ]
}

Returns a list of stock_adjustment_line_items you’ve previously created. The stock_adjustment_line_items are returned in sorted order, based on the position attribute.

Filters

Arguments	Description
ids	An array of stock_adjustment_line_item IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
stock_adjustment_id	Filter resources by stock_adjustment
variant_id	Filter resources by variant

HTTP Request:

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

Create a new stock_adjustment_line_item

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_adjustment_line_items/ -d '{"stock_adjustment_line_item":{"quantity":"12.0","stock_adjustment_id":1,"variant_id":1,"price":"10.0"}}'

{
  "stock_adjustment_line_item": {
    "id": 3,
    "created_at": "2015-11-25T07:27:39.967Z",
    "updated_at": "2015-11-25T07:27:39.967Z",
    "stock_adjustment_id": 2,
    "variant_id": 8,
    "quantity": "-5.0",
    "position": 0,
    "price": "2.5"
  }
}

Creates a new stock_adjustment_line_item object.

Arguments

Attribute	Type	Description	Required
stock_adjustment_id	Integer	The stock_adjustment to which the resource belongs.	true
variant_id	Integer	The variant to which the resource belongs.	true
quantity	String
position	Integer
price	String	Required only when quantity is greater than 0. For negative quantities, the current Moving Average Cost will be assigned automatically.	true

HTTP Request

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

Retrieve a particular stock_adjustment_line_item

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_adjustment_line_items/

{
  "stock_adjustment_line_item": {
    "id": 3,
    "created_at": "2015-11-25T07:27:39.967Z",
    "updated_at": "2015-11-25T07:27:39.967Z",
    "stock_adjustment_id": 2,
    "variant_id": 8,
    "quantity": "-5.0",
    "position": 0,
    "price": "2.5"
  }
}

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

HTTP Request

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

StockLevel

This is an object representing a stock_level.

The StockLevel object

Attribute	Type	Description	Readonly
id	Integer	A unique identifier for the resource.	true
committed_stock	String	Stock committed for sale across all locations	true
locations	Array	An array of per-warehouse data about current variant.	true
stock_on_hand	String	Stock on hand across all locations	true
incoming_stock	String	Stock on order across all locations	true

List all stock_levels

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.StockLevel.where(limit: 25, status: 'active')

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_levels/

{
  "stock_levels": [
    {
      "variant_id": 60,
      "committed_stock": "5",
      "locations": [
        {
          "location_id": 3,
          "committed": "5",
          "incoming": 0,
          "stock_on_hand": "30"
        }
      ],
      "stock_on_hand": "30",
      "available_stock": "25",
      "incoming_stock": "0"
    },
    {
      "variant_id": 43,
      "committed_stock": "0",
      "locations": [
        {
          "location_id": 3,
          "committed": 0,
          "incoming": 0,
          "stock_on_hand": "75"
        }
      ],
      "stock_on_hand": "75",
      "available_stock": "75",
      "incoming_stock": "0"
    }
  ]
}

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

Filters

Arguments	Description
ids	An array of stock_level IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)

HTTP Request:

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

Retrieve a particular stock_level

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.StockLevel.find(1)

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_levels/1

{
  "stock_level": {
    "variant_id": 60,
    "committed_stock": "5",
    "locations": [
      {
        "location_id": 3,
        "committed": "5",
        "incoming": 0,
        "stock_on_hand": "30"
      }
    ],
    "stock_on_hand": "30",
    "available_stock": "25",
    "incoming_stock": "0"
  }
}

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

HTTP Request

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

StockTransfer

This is an object representing a stock_transfer.

The StockTransfer 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 'received'
adjustment_number	String
received_at	String	Automatically set when stock transfer status is set to received
notes	String
source_location_id	Integer	Origin of stock being tranferred
destination_location_id	Integer	Destination of stock being transferred
cached_quantity	String	Cumulative quantity of all variants being transferred	true
transacted_at	String
stock_transfer_line_item_ids	Array		true

List all stock_transfers

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_transfers/

{
  "stock_transfers": [
    {
      "id": 2,
      "created_at": "2015-11-26T04:14:45.572Z",
      "updated_at": "2015-11-26T04:14:45.606Z",
      "adjustment_number": "ST0002",
      "status": "active",
      "received_at": null,
      "notes": "Reversal of Stock Transfer #ST0001",
      "source_location_id": 3,
      "destination_location_id": 1,
      "cached_quantity": "8.0",
      "transacted_at": null,
      "stock_transfer_line_item_ids": [
        3,
        4
      ]
    },
    {
      "id": 1,
      "created_at": "2015-11-26T03:53:17.729Z",
      "updated_at": "2015-11-26T03:53:21.760Z",
      "adjustment_number": "ST0001",
      "status": "received",
      "received_at": "2015-11-26T03:52:51.000Z",
      "notes": null,
      "source_location_id": 1,
      "destination_location_id": 3,
      "cached_quantity": "17.0",
      "transacted_at": "2015-11-26T03:52:51.000Z",
      "stock_transfer_line_item_ids": [
        1,
        2
      ]
    }
  ]
}

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

Filters

Arguments	Description
ids	An array of stock_transfer IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Default is active
status
adjustment_number
received_at
notes
source_location_id
destination_location_id
cached_quantity
transacted_at
stock_transfer_line_item_ids

HTTP Request:

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

Create a new stock_transfer

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_transfers/ -d '{"stock_transfer":{"company_id":1,"issued_at":"2015-11-26T03:53:17.729Z","billing_address_id":1,"shipping_address_id":1}}'

{
  "stock_transfer": {
    "id": 2,
    "created_at": "2015-11-26T04:14:45.572Z",
    "updated_at": "2015-11-26T04:14:45.606Z",
    "adjustment_number": "ST0002",
    "status": "active",
    "received_at": null,
    "notes": "Reversal of Stock Transfer #ST0001",
    "source_location_id": 3,
    "destination_location_id": 1,
    "cached_quantity": "8.0",
    "transacted_at": null,
    "stock_transfer_line_item_ids": [
      3,
      4
    ]
  }
}

Creates a new stock_transfer object. This endpoint also accepts embedded stock_transfer_line_items.

Arguments

Attribute	Type	Description	Required
status	String	Tells whether the resource is 'active' or 'received'
adjustment_number	String
received_at	String	Automatically set when stock transfer status is set to received
notes	String
source_location_id	Integer	Origin of stock being tranferred	true
destination_location_id	Integer	Destination of stock being transferred	true
transacted_at	String
stock_transfer_line_item_ids	Array

StockTransferLineItem

Child Attribute	Type	Description	Required
stock_transfer_id	Integer	The stock_transfer to which the resource belongs.	true
variant_id	Integer	The variant to which the resource belongs.	true
quantity	String
position	Integer
image_url	String

HTTP Request

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

Retrieve a particular stock_transfer

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_transfers/

{
  "stock_transfer": {
    "id": 2,
    "created_at": "2015-11-26T04:14:45.572Z",
    "updated_at": "2015-11-26T04:14:45.606Z",
    "adjustment_number": "ST0002",
    "status": "active",
    "received_at": null,
    "notes": "Reversal of Stock Transfer #ST0001",
    "source_location_id": 3,
    "destination_location_id": 1,
    "cached_quantity": "8.0",
    "transacted_at": null,
    "stock_transfer_line_item_ids": [
      3,
      4
    ]
  }
}

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

HTTP Request

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

Stock Transfer actions

Use the following endpoints to manage the receiving or reverting of the stock transfer. POST /stock_transfers/[:stock_transfer_id]/actions/[:action]

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_transfers/[:stock_transfer_id]/actions/[:stock_transfer_action]

Action	Description
receive	Receive the stock transfer
revert	Revert the stock transfer

Delete a stock_transfer

curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_transfers/1

Response

Returns 204 status when the stock_transfer gets deleted successfully.

Permanently deletes a stock_transfer. It cannot be undone.

HTTP Request

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

StockTransferLineItem

This is an object representing a stock_transfer_line_item of a stock_transfer. Stock_transfers can have multiple stock_transfer_line_items but a stock_transfer_line_item object belongs to only one Stock_transfer.

The StockTransferLineItem object

Attribute	Type	Description	Readonly
id	Integer	A unique identifier for the resource.	true
created_at	String		true
updated_at	String		true
stock_transfer_id	Integer	The stock_transfer to which the resource belongs.
variant_id	Integer	The variant to which the resource belongs.
quantity	String
position	Integer
image_url	String		true

List all stock_transfer_line_items

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_transfer_line_items/

{
  "stock_transfer_line_items": [
    {
      "id": 1,
      "created_at": "2015-11-26T03:53:17.761Z",
      "updated_at": "2015-11-26T03:53:17.761Z",
      "stock_transfer_id": 1,
      "variant_id": 8,
      "quantity": "8.0",
      "position": 0,
      "image_url": null
    },
    {
      "id": 2,
      "created_at": "2015-11-26T03:53:17.775Z",
      "updated_at": "2015-11-26T03:53:17.775Z",
      "stock_transfer_id": 1,
      "variant_id": 9,
      "quantity": "9.0",
      "position": 1,
      "image_url": null
    }
  ]
}

Returns a list of stock_transfer_line_items you’ve previously created. The stock_transfer_line_items are returned in sorted order, based on the position attribute.

Filters

Arguments	Description
ids	An array of stock_transfer_line_item IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
stock_transfer_id	Filter resources by stock_transfer
variant_id	Filter resources by variant

HTTP Request:

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

Create a new stock_transfer_line_item

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_transfer_line_items/ -d '{"stock_transfer_line_item":{"quantity":"12.0","stock_transfer_id":1,"variant_id":1,"price":"10.0"}}'

{
  "stock_transfer_line_item": {
    "id": 1,
    "created_at": "2015-11-26T03:53:17.761Z",
    "updated_at": "2015-11-26T03:53:17.761Z",
    "stock_transfer_id": 1,
    "variant_id": 8,
    "quantity": "8.0",
    "position": 0,
    "image_url": null
  }
}

Creates a new stock_transfer_line_item object.

Arguments

Attribute	Type	Description	Required
stock_transfer_id	Integer	The stock_transfer to which the resource belongs.	true
variant_id	Integer	The variant to which the resource belongs.	true
quantity	String
position	Integer
image_url	String

HTTP Request

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

Retrieve a particular stock_transfer_line_item

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_transfer_line_items/

{
  "stock_transfer_line_item": {
    "id": 1,
    "created_at": "2015-11-26T03:53:17.761Z",
    "updated_at": "2015-11-26T03:53:17.761Z",
    "stock_transfer_id": 1,
    "variant_id": 8,
    "quantity": "8.0",
    "position": 0,
    "image_url": null
  }
}

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

HTTP Request

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

Delete a stock_transfer_line_item

curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/stock_transfer_line_items/1

Response

Returns 204 status when the stock_transfer_line_item gets deleted successfully.

Permanently deletes a stock_transfer_line_item. It cannot be undone.

HTTP Request

DELETE https://api.tradegecko.com/stock_transfer_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_components	Array	An array of Tax Components that the tax rate is composed of

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": "RETAIL",
      "imported_from": null,
      "name": "Retail",
      "status": "active",
      "quickbooks_online_id": null,
      "xero_online_id": null,
      "effective_rate": "10.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
ids	An array of tax_type IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Default is active

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
tax_type = gecko.TaxType.build({
  name: "Retail",
  code: "RETAIL",
  tax_components: [
    {
      position: 0,
      label: "Retail GST",
      rate: 10,
      compound: false
    }
  ]
})
tax_type.save

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_components":[{"position":0,"label":"Retail GST","rate":10,"compound":false}]}}'

{
  "tax_type": {
    "id": 3,
    "code": "RETAIL",
    "imported_from": null,
    "name": "Retail",
    "status": "active",
    "quickbooks_online_id": null,
    "xero_online_id": null,
    "effective_rate": "10.0",
    "tax_component_ids": [
      3
    ]
  }
}

Creates a new tax_type object.

Arguments

Attribute	Type	Description	Required
code	String
name	String	Display name	true
tax_components	Array	An array of Tax Components that the tax rate is composed of

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": "RETAIL",
    "imported_from": null,
    "name": "Retail",
    "status": "active",
    "quickbooks_online_id": null,
    "xero_online_id": null,
    "effective_rate": "10.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 = {
  name: "Wholesale",
  code: "WHOLESALE"
}
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 will no longer be available for future Sales Order.

HTTP Request

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

TaxComponent

This is an object representing a tax_component of a tax_type. Tax_types can have multiple tax_components but a tax_component object belongs to only one Tax_type.

The TaxComponent object

Attribute	Type	Description	Readonly
id	Integer	A unique identifier for the resource.	true
tax_type_id	Integer	The tax_type to which the tax_component belongs.
position	Integer
label	String	Display name
rate	String	Tax Rate
compound	String

List all tax_components

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/tax_components/

{
  "tax_components": [
    {
      "id": 3,
      "tax_type_id": 3,
      "position": 1,
      "label": "GST",
      "rate": "15.0"
    },
    {
      "id": 2,
      "tax_type_id": 2,
      "position": 1,
      "label": "GST",
      "rate": "15.0"
    },
    {
      "id": 1,
      "tax_type_id": 1,
      "position": 1,
      "label": "GST",
      "rate": "0.0"
    }
  ]
}

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

Filters

Arguments	Description
ids	An array of tax_component IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
tax_type_id
position
label
rate
compound

HTTP Request:

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

Create a new tax_component

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/tax_components/ -d '{"tax_component":{"quantity":"12.0","order_id":1,"tax_type_id":1,"price":"10.0"}}'

{
  "tax_component": {
    "id": 3,
    "tax_type_id": 3,
    "position": 1,
    "label": "GST",
    "rate": "15.0"
  }
}

Creates a new tax_component object.

Arguments

Attribute	Type	Description	Required
tax_type_id	Integer	The tax_type to which the tax_component belongs.	true
position	Integer
label	String	Display name
rate	String	Tax Rate
compound	String

HTTP Request

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

Retrieve a particular tax_component

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/tax_components/

{
  "tax_component": {
    "id": 3,
    "tax_type_id": 3,
    "position": 1,
    "label": "GST",
    "rate": "15.0"
  }
}

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

HTTP Request

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

Update a tax_component

curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com//1 -d '{"tax_component":{"quantity":"22.0","price":"12.0"}}'

Response

Returns 204 status when the tax_component gets updated successfully.

Updates the specified tax_component 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_component creation call.

HTTP Request

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

Delete a tax_component

curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/tax_components/1

Response

Returns 204 status when the tax_component gets deleted successfully.

Permanently deletes a tax_component. It cannot be undone.

HTTP Request

DELETE https://api.tradegecko.com/tax_components/{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
ids	An array of user IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	Default is active
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}

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

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 = {
  first_name: "Gordon"
}
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 will no longer be available for future Sales Order.

HTTP Request

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

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
hs_code	String	Harmonized System Code
country_of_origin	String	Two letter country code (e.g. SG, US)
initial_cost_price	String	The initial item cost price of the variant, only available when first creating the variant
initial_stock_level	String	The initial stock level of the variant, only available when first creating the variant
initial_stock_location_id	Integer	The ID of the stock location where initial stock levels should be added, only available when first creating the variant, defaults to your primary stock location
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	For composite variants, the value of manage_stock will always be true
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
purchasable	Boolean	Tells whether you can create Purchase Order with the variant
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, g, oz or lb)
wholesale_price	String	The recommended wholesale price for this product
image_ids	Array	Images assigned to the variant. The order of the Image IDs here is the position of the images on the variant.
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",
      "available_stock": "7",
      "incoming_stock": "0",
      "hs_code": "110100",
      "country_of_origin": "SG",
      "composite": null,
      "description": null,
      "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,
          "production_committed": "0",
          "production_incoming": "0",
          "available": "7"
        }
      ],
      "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",
      "hs_code": "110100",
      "country_of_origin": "SG",
      "composite": null,
      "description": null,
      "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,
          "production_committed": "0",
          "production_incoming": "0",
          "available": "10"
        }
      ],
      "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
ids	An array of variant IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
status	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
variant = gecko.Variant.build({
  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.save

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",
    "available_stock": "7",
    "incoming_stock": "0",
    "hs_code": "110100",
    "country_of_origin": "SG",
    "composite": null,
    "description": null,
    "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,
        "production_committed": "0",
        "production_incoming": "0",
        "available": "7"
      }
    ],
    "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
hs_code	String	Harmonized System Code
country_of_origin	String	Two letter country code (e.g. SG, US)
initial_cost_price	String	The initial item cost price of the variant, only available when first creating the variant
initial_stock_level	String	The initial stock level of the variant, only available when first creating the variant
initial_stock_location_id	Integer	The ID of the stock location where initial stock levels should be added, only available when first creating the variant, defaults to your primary stock location
keep_selling	Boolean	Allow item to continue to be sold, even if it is no longer in stock
manage_stock	Boolean	For composite variants, the value of manage_stock will always be true
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)
purchasable	Boolean	Tells whether you can create Purchase Order with the variant
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, g, oz or lb)
wholesale_price	String	The recommended wholesale price for this product
image_ids	Array	Images assigned to the variant. The order of the Image IDs here is the position of the images on the variant.
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",
    "available_stock": "7",
    "incoming_stock": "0",
    "hs_code": "110100",
    "country_of_origin": "SG",
    "composite": null,
    "description": null,
    "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,
        "production_committed": "0",
        "production_incoming": "0",
        "available": "7"
      }
    ],
    "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 = {
  retail_price: "12.0",
  name: "Sample Variant",
  sku: "SV1234"
}
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 will no longer be available for future Sales Order.

HTTP Request

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

Webhook

This is an object representing a webhook.

The Webhook object

Attribute	Type	Description	Readonly
id	Integer	A unique identifier for the resource.	true
created_at	String	Date and Time when the webhook was created.	true
updated_at	String	Date and Time when the webhook was last updated.	true
event	String	Event which fires the webhook from QuickBooks Commerce to the specified address.
address	String	URI where a POST request will be sent everytime an event occurs in QuickBooks Commerce

List all webhooks

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.Webhook.where(limit: 25, status: 'active')

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/webhooks/

{
  "webhooks": [
    {
      "id": 1,
      "created_at": "2018-09-24T11:12:49.244Z",
      "updated_at": "2018-09-24T11:12:49.244Z",
      "event": "product.create",
      "address": "https://mywebsite.com/webhooks",
      "oauth_application_id": 1
    },
    {
      "id": 2,
      "created_at": "2018-09-24T11:12:49.244Z",
      "updated_at": "2018-09-24T11:12:49.244Z",
      "event": "product.update",
      "address": "https://mywebsite.com/webhooks",
      "oauth_application_id": 1
    }
  ]
}

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

Filters

Arguments	Description
ids	An array of webhook IDs. See Getting Started for examples.
limit	used for pagination (default is 50)
page	used for pagination (default is 1)
created_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
created_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_min	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)
updated_at_max	ISO 8601 format (e.g. 2020-01-08T00:00:00.00Z)

HTTP Request:

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

Create a new webhook

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
webhook = gecko.Webhook.build({
  address: "https://mywebsite.com/webhooks",
  event: "product.create"
})
webhook.save

curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/webhooks/ -d '{"webhook":{"address":"https://mywebsite.com/webhooks","event":"product.create"}}'

{
  "webhook": {
    "id": 1,
    "created_at": "2018-09-24T11:12:49.244Z",
    "updated_at": "2018-09-24T11:12:49.244Z",
    "event": "product.create",
    "address": "https://mywebsite.com/webhooks",
    "oauth_application_id": 1
  }
}

Creates a new webhook object.

Arguments

Attribute	Type	Description	Required
event	String	Event which fires the webhook from QuickBooks Commerce to the specified address.	true
address	String	URI where a POST request will be sent everytime an event occurs in QuickBooks Commerce	true

List of Available Events

Resource	Event
account	account.update
addresss	address.create, address.update
channel	channel.destroy
company	company.create, company.update, company.destroy
contact	contact.create, contact.update
document_theme	document_theme.update
fulfillment	fulfillment.create, fulfillment.fulfilled
fulfillment_return	fulfillment_return.create, fulfillment_return.received
invoice	invoice.create, invoice.destroy
location	location.create, location.update
order	order.create, order.finalized, order.fulfilled
payment	payment.create
product	product.create, product.destroy
procurement	procurement.create
purchase_order	purchase_order.create, purchase_order.received
stock_adjustment	stock_adjustment.create
stock_transfer	stock_transfer.create
variant	variant.create, variant.stock_level_update
image	image.create

HTTP Request

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

Retrieve a particular webhook

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.Webhook.find(1)

curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/webhooks/1

{
  "webhook": {
    "id": 1,
    "created_at": "2018-09-24T11:12:49.244Z",
    "updated_at": "2018-09-24T11:12:49.244Z",
    "event": "product.create",
    "address": "https://mywebsite.com/webhooks",
    "oauth_application_id": 1
  }
}

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

HTTP Request

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

Update a webhook

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
webhook = gecko.Webhook.find(1)
webhook.attributes = {
  address: "https://mynewwebsite.com/webhooks",
  event: "product.create"
}
webhook.save

curl -X PUT -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/webhooks/1 -d '{"webhook":{"address":"https://mynewwebsite.com/webhooks","event":"product.create"}}'

Response

Returns 204 status when the webhook gets updated successfully.

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

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

HTTP Request

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

Delete a webhook

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
webhook = gecko.Webhook.find(1)
webhook.destroy

curl -X DELETE -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
https://api.tradegecko.com/webhooks/1

Response

Returns 204 status when the webhook gets deleted successfully.

Permanently deletes a webhook. It cannot be undone.

HTTP Request

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

Libraries

• Official Rubygem
• Official Omniauth strategy
• Example Rails App w/ Omniauth