Managing Warehouse Inventory Guide

    This guide explains how to manage inventory across different warehouse locations in TradeGecko.

    In this guide:

    Warehouse Resources

    Before you start working on a warehouse integration with TradeGecko, it’s helpful to understand some of the different warehouse-related resources.

    • Sales Order: Contains information about a sales order, its associated order line items and fulfillments. Order line items contain information such as variants and tax types.
      • An order in TradeGecko can have 1 of 6 statuses: draft, active, finalized, fulfilled, void or deleted.
    • Fulfillment: Represents a shipment of one or more items in a sales order.
      • A fulfillment in TradeGecko can have 1 of 4 statuses: packed, fulfilled, void or deleted.
    • Purchase Order: Contains information about a purchase order and its associated purchase order line items. Purchase order line items contain information such as variants, quantity to procure, quantity to receive, item cost, tax, and landed cost.
      • A purchase order in TradeGecko can have 1 of 5 statuses: draft, active, received, void or deleted.
      • After a purchase order is fully received, the purchase order status will be changed to received.
    • Address: Represents a physical address of a merchant's supplier or customer created and stored in the TradeGecko Relationships section.
    • Location: Represents a geographical location where a merchant can receive, store and transfer goods.
    • Product: Represents a group of variants e.g. t-shirt.
    • Variant: Represents a variation of a product, based on specific attributes e.g. t-shirt in colour red and size small, t-shirt in colour blue and size large.
      • In a sales order or purchase order, each line item always references a variant.
      • At TradeGecko, stock levels are on variants and not products.

    How Sales Order and Stock Control Affect Inventory

    • Stock Levels: There are four types of stock levels in TradeGecko: 
      • Stock on Hand:  The stock that is present in a warehouse.
      • Committed Stock:  The stock that is committed for sales orders but has not been shipped yet.
      • Incoming Stock:  The stock that has been ordered through purchase orders but has not been received yet.
      • Available Stock:  The stock that is available for sale. It is calculated using:  Stock on Hand - Committed Stock
    • When a variant is created, it has an attribute called initial_stock_levels where an array of hashes can be defined to set the initial stock level for each location. There is another attribute called initial_cost_price that will be the cost price associated with the initial stock.
    • There are 6 ways to change variant stock levels: 
      • Fulfillment of a Sales Order
      • Fulfillment Return of a Sales Order
      • Receiving a Purchase Order
      • Creating a Stock Adjustment
      • Receiving a Stock Transfer
      • Creating a Stocktake

    Receiving a Purchase Order

    • Step 1: Receive a purchase order alert from purchase_order.create webhook.
    • Step 2: Query the purchase order to see the purchase order line items.
    • Step 3: Update purchase order status to received.

    Step 1: Receive a purchase order alert from purchase_order.create webhook.

    To get started, subscribe to the purchase_order.create webhook to be notified when a new purchase order is created by a merchant.

    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=>"purchase_order.create")
    webhook.save
    
    {
      "webhook": {
        "id": 1,
        "created_at": "2018-09-24T11:12:49.244Z",
        "updated_at": "2018-09-24T11:12:49.244Z",
        "event": "purchase_order.create",
        "address": "https://mywebsite.com/webhooks",
        "oauth_application_id": 1
      }
    }
    
    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":"purchase_order.create"}}'
    
    {
      "webhook": {
        "id": 1,
        "created_at": "2018-09-24T11:12:49.244Z",
        "updated_at": "2018-09-24T11:12:49.244Z",
        "event": "purchase_order.create",
        "address": "https://mywebsite.com/webhooks",
        "oauth_application_id": 1
      }
    }
    

    Step 2: Query the purchase order to see the 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.PurchaseOrder.find(1)
    
    {
      "purchase_order": {
        "id": 1,
        "created_at": "2015-11-02T01:22:25.524Z",
        "updated_at": "2015-12-02T01:11:25.524Z",
        "stock_location_id": 1,
        "purchase_line_item_ids": [1, 2, 3]
        // more fields
      }
    }
    
    curl -X GET -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
    https://api.tradegecko.com/purchase_orders/1?include=purchase_order_line_items
    
    {
      "purchase_order_line_items": [
        {
          "id": 1,
          "created_at": "2015-11-02T01:22:25.524Z",
          "updated_at": "2015-12-02T01:11:25.524Z",
          // more fields
        }
      ],
      "purchase_order": {
        "id": 1,
        "created_at": "2015-11-02T01:22:25.524Z",
        "updated_at": "2015-12-02T01:11:25.524Z",
        "stock_location_id": 1,
        "purchase_line_item_ids": [1],
        // more fields
      }
    }
    

    Step 3: Update purchase order status to received.

    If you manage the procurement process for a merchant, once you have procured the items, you can update the original purchase order to received through an API call to POST /purchase_orders/[:purchase_order_id]/actions/receive. This will increase the Stock On Hand level of the procured 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
    purchase_order = gecko.PurchaseOrder.find(1)
    purchase_order.receive
    
    {
      "procurement": {
        "id": 1,
        // more fields
      }
    }
    
    curl -X POST -H "Content-type: application/json" -H "Authorization: Bearer <ACCESS_TOKEN>"
    https://api.tradegecko.com/purchase_orders/1/actions/receive
    
    {
      "procurement": {
        "id": 1,
        // more fields
      }
    }
    

    Note:  Partial procurements are currently not supported. If you need an endpoint for partial procurements, let us know here.

    Other Ways of Changing Stock Levels

    1. Creating a Stock Adjustment:  Used to update inventory levels when there are damaged goods, promotional goods or new products. Creating a stock adjustment would affect the account's Moving Average Cost.
    2. Receiving a Stock Transfer: Used to update inventory movements between warehouses. For example, you have 2 warehouses, one in New York and one in Chicago. When you transfer 20 items from New York to Chicago, you can create a stock transfer. Stock Transfers will not affect Moving Average Cost.
      • You can subscribe to the stock_transfer.create webhook to be notified when a merchant creates a new stock transfer.
    3. Creating a Stocktake: Used to update inventory levels without changing the account’s Moving Average Cost. For example, your TradeGecko account indicates that you have 25 medium sized, white T-shirts in stock. When you go to the warehouse to do a physical stocktake, you realise that there are only 23 in stock. To account for this discrepancy, you should create a stocktake.

    Additional Resources

    See these additional resources for more information about authorization, webhooks and order actions.

    Support

    For API feature requests, bug reports and other questions related to API guides, contact support@tradegecko.com.

    Got Feedback? We want to hear from you!

    Give Feedback