Managing Warehouse Inventory Guide

Warehouse Resources

Before you start working on a warehouse integration with QuickBooks Commerce, 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 QuickBooks Commerce 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 QuickBooks Commerce 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 QuickBooks Commerce 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 QuickBooks Commerce 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 QuickBooks Commerce, 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 QuickBooks Commerce: 
• 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

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
  }
}

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
  }
}

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
  }
}

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 QuickBooks Commerce 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.

• Getting API key for Authentication
• Using Webhooks
• Order Actions
• QuickBooks Commerce API Forum

Support

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