Skip to content

Building a custom e commerce integration

Jump to bottom
Sophie Hernandez edited this page Dec 3, 2021 · 12 revisions

Implementing features

There are 4 key features to an e-commerce integration

  1. Import products
  2. Import orders
  3. Export tracking numbers
  4. Export inventory levels

The first 2 are required to get data from the cart to Ordoro. With orders and products in Ordoro, users can go about shipping their orders and managing their inventory.

Pro Tip! If you only care about orders and shipping, you can skip importing products entirely. We'll create products on the fly as you create an order if the product doesn't exist in Ordoro.

Understanding carts

Each of our built-in integrations is called a cart. A user can add a cart to their account at initial registration or via the settings menu. We automatically sync their data, and the user can begin managing their orders and inventory through Ordoro.

You may add a custom_integration cart to Ordoro, so users can either select from the e-commerce integrations we've developed or one of your own with this cart type. If you're developing your own shopping cart integration, you'll want to use the corresponding custom_integration cart type anytime you need a cart_id.

  • You can differentiate between actual manual orders created in the UI and the cart that you are syncing via API.

  • If you need multiple custom carts connected, you can create carts specific to them to differentiate between them as well.

  • Having this cart type versus a manual cart allows you to interact with the channel more like a Ordoro core integrated channel (mostly in the product/inventory region).

How to create a custom channel type:

POST https://api.ordoro.com/cart/

Body:

{
    "type": "custom_integration",
    "name": "Name of your cart",
    "autosync_enabled": false
}

Returns your CUSTOM_CART_ID as id.

Updates when posting an order:

Make sure to specify your cart_id when posting the order.

Example:

{

"cart": CUSTOM_CART_ID

}
Product interaction updates:

When you create a product in Ordoro that needs to come from the sales channel or just need to connect an already existing product to the sales channel, you will need to specify the cart_id in the POST request.

Example:

{
  "sku": "sku",
  "cart": CUSTOM_CART_ID,
  "name": "name"
}

Pro Tip! Fetch the custom_integration carts by querying the cart endpoint and using the cart that has vendor==custom_integration. To wit:

curl --user 'user:pass' https://api.ordoro.com/cart/ | python -m json.tool
{
    "cart": [
        {
            "_link": "/cart/1/",
            "archived_date": null,
            "autosync_activities": [],
            "autosync_enabled": true,
            "cart_download_order_statuses": {
                "order_statuses": []
            },
            "default_packing_list_id": null,
            "id": 1,
            "index": 4,
            "is_demo": false,
            "name": "Custom cart integration",
            "proxy_requests": false,
            "v3_migration_date": null,
            "vendor": "custom_integration",
            "vendor_config": {},
            "vendor_display": "Custom Integration",
            "worker_machinga": null
        }
    ],
    "count": 1,
    "limit": 10,
    "offset": 0
}

Import products

In order to manage inventory in Ordoro, you need to load products from the e-commerce platform. The minimum request needed to create a product is:

curl --user 'user:pass' --header 'Content-Type: application/json' --request POST --data '{"sku": "unique-sku", "name": "displayme"}' https://api.ordoro.com/product/

Check out the create product docs for all the params.

Pro Tip! If you need to export inventory levels, you can use original_sku and variant_sku to store extra information needed to write data back to the e-commerce platform.

Pro Tip! To figure out which products to import, we often fetch the list of products created for a particular cart sorted by the most recently created product. You can then use the created date to filter the products you fetch from the e-commerce platform. This prevents you from importing all products each time.

curl --user 'user:pass' 'https://api.ordoro.com/product/?sort=-created&cart=699&limit=1' | jq '.product[0].created'
"2015-10-28T22:13:58.639790-05:00"

Import orders

Users ship orders by creating labels, sending dropshipments, or manually entering tracking numbers. The minimum request needed to create an order is:

curl --user 'user:pass' --header 'Content-Type: application/json' --request POST --data '{"order_id": "1002", "billing_address": {"name": "Sara"}, "shipping_address": {"name": "Jenny"}, "lines": [{"product": {"sku": "goat", "name": "regular goat"}, "quantity": 2}]}' https://api.ordoro.com/v3/order/

Check out the create order docs for all the params.

Pro Tip! If you need to export tracking numbers, you can use cart_order_id, cart_order_item_id, and cart_shipment_id to store info needed to send data to the cart.

Pro Tip! Many shopping cart APIs allow you to filter by order status which allows us to filter by orders that have been paid but not shipped. This requires that you implement functionality to change order status in the shopping cart once the user has shipped the order in Ordoro (see the Export Tracking Numbers section).

Pro Tip! If filtering by order status isn't feasible, you can filter by created date, similar to filtering products.

curl --user 'user:pass' 'https://api.ordoro.com/v3/order?sort=-order_placed_date&cart=10013&limit=1' | jq '.order[0].created'
"2015-10-28T22:14:25.675931-05:00"

curl https://api.ordoro.com/v3/order?created_after=2015-10-28T22:14:25.675931-05:00

Export tracking numbers

We don't have any notifications (e.g. a webhook) when a user ships an order, so you'll need to fetch all shipped orders. As a best practice, you should remember the last time you made a call to get shipped orders so you're only getting orders that have been newly created. Otherwise, you'll get all shipped orders which would take awhile if a customer has many. You can use the order's shipping_info to get tracking numbers, carriers, and ship dates.

To fetch orders that have been shipped since Oct 1, 2015, you could use the following:

curl https://api.ordoro.com/v3/order?shipped_after=2015-10-1'

Export inventory levels

Ordoro modifies the available_on_hand value when an order is received or the physical on hand value is changed.

You can get a list of products whose available_on_hand values have changed:

curl --user 'user:pass' 'https://api.ordoro.com/product/?needs_sync=true&active=true'
{
    "count": 69,
    "limit": 10,
    "offset": 0,
    "product": [
    ...
    ]
}

Once you've updated the shopping cart with the latest available_on_hand values, you'll need to reset the inventory_changed field so the product doesn't show up in the needs_sync filter:

curl --user 'u:p' --header 'content-type:application/json' --request PUT --data '{"inventory_changed":false, "cart":699}' 'https://api.ordoro.com/product/<sku>/'
Clone this wiki locally