Call and You Shall Receive

API and EDI Documentation

API Information

About HomeRoots API

Homeroots offers APIs that allow Partners to extend the built-in features of the platform. These APIs allow Partners to read and write order data, and read inventory data.

To get started with the HomerRoots API, you need to select the type of authorization you will use. The following types of authorization are available to partners:

Personal Access Token
OAuth Client

Personal Access Tokens allow access to our data, and just like an OAuth token, it is tied to the user who requests it. The difference between Personal Access Token and OAuth is: that with OAuth, you authorize an app to talk to HomeRoots on your behalf, and might not ever see the credentials that the app uses. On the other hand, with Personal Access Tokens you are in charge of asking for the credentials to the API, and subsequently managing them.

If you want to use Personal Access Tokens or OAuth Clients, you can create them by using the menus below.

In this guide, you will find more information about OAuth Authentication.

OAuth Clients Add New

You have not created any OAuth clients.

Personal Access Tokens Add New

You have not created any personal access tokens.

Getting Started with the HomeRoots API

To get started with our API, please navigate to Authentication tab.

Authentication

The HomeRoots API uses OAuth2 to authenticate all clients over HTTPS.

Before getting started, make sure you have your Personal Access Tokens or OAuth2 Client ID & Client Secret from HomeRoots. If you do not have credentials, please contact us.

Obtaining a Personal Access Tokens

“Personal Access Tokens” is a simpler approach to issue tokens via your application’s UI.

Log in to your Account
Click the API link at the left sidebar of your profile.
Click Add new in “Personal Access Tokens” block.
Give your token a descriptive name.
Select the scopes, or permissions, you’d like to grant this token.
Click “Create“.
Copy the token to your clipboard. For security reasons, after you navigate off the page, you will not be able to see the token again.

Obtaining an OAuth Access Token

Creating an OAuth Client:

Log in to your Account
Click the API link at the left sidebar of your profile.
Click Add new in “OAuth Clients” block.
- Give your Client a descriptive name.
- Enter your application’s authorization callback URL.

Once a Client has been created, use Client ID and Secret to request an authorization code and access token from HomeRoots. Log in to your Account. After that the consuming application should make a redirect request to :

GET https://www.homeroots.co/oauth/authorize?response_type=code&client_id={YOUR_CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope={API_SCOPES}

If request is approved, you will be redirected back to the Redirect URL which includes the ?code={} query parameter that you can swap for an access token.

To obtain an access token, you will authenticate using the “Authorization Code” grant type. Please note that the request body should be x-www-form-urlencoded as shown below:

Sample Access Token Request:

POST https://www.homeroots.co/oauth/token
    Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&client_id={YOUR_CLIENT_ID}&client_secret={YOUR_CLIENT_SECRET}&redirect_uri={REDIRECT_URI}&code={CODE}

It will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires.

Sample Access Token Response:

HTTP/1.1 200 OK
{
  "token_type": "Bearer",
  "expires_in": "31536000",
  "access_token": eyJ0e...9paJ78,
  "refresh_token": "def...a5669e"
}

Refreshing OAuth Access Tokens

Sample Refresh Access Token Request:

POST https://www.homeroots.co/oauth/token
    Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token={REFRESH_TOKEN}&client_id={YOUR_CLIENT_ID}&client_secret={YOUR_CLIENT_SECRET}&scope={SCOPES}

It will return a JSON response containing access_token, refresh_token, and expires_in attributes. The expires_in attribute contains the number of seconds until the access token expires.

Sample Refresh Token Response:

HTTP/1.1 200 OK
{
  "token_type": "Bearer",
  "expires_in": "31536000",
  "access_token": eyJ0e...9paJ78,
  "refresh_token": "def...a5669e"
}

Available API Scopes

When requesting an access token using the authorization code grant, consumers should specify their desired scopes as the scope query string parameter. The scope parameter should be a space-delimited list of scopes

Scope	Description
`read_inventory`	View inventory
`read_orders`	View orders, transactions and fulfillments
`write_orders`	Manage orders, transactions and fulfillments

Including the Access Token in Requests

After you have obtained an access token, you may make requests to protected endpoints by including your access token in the “Authorization” header.

GET https://www.homeroots.co/v1/{API_URL}
Authorization: Bearer 0oW0r4m1pjIlb5UJujZA5iVuse0XSn

Warning: Treat your tokens like passwords and keep them secret. When working with the API, use tokens as environment variables instead of hardcoding them into your programs.

Orders

The HomeRoots API uses OAuth2 to authenticate all clients over HTTPS.

Before getting started, make sure you have your Personal Access Tokens or OAuth2 Client ID & Client Secret from HomeRoots. If you do not have credentials, please contact us.

Operations

Click on an Operation to view requirements, options, & examples.

GET	https://callback-api.homeroots.co/api/v1/buyer/orders/status	Get an Order Status Details
GET	https://callback-api.homeroots.co/api/v1/buyer/orders/invoice	Get an Order Invoice Details
POST	https://callback-api.homeroots.co/api/v1/buyer/orders	Create a new Order

Examples

GET	https://callback-api.homeroots.co/api/v1/buyer/orders/status	Get an Order Status Details

Query String Parameters – One of this fields are required and other optional.
`po_number`	Show order status by Purchase Order Number
`invoice_number`	Show order status by Invoice Number

Response

On a successful GET, such an object will be returned:

{
    "data": [
        {
            "po_number": "1234567897",
            "invoice_number": "12-34-567890123",
            "status": "Shipped",
            "shipping_details": {
                "shipping_tracking": "00000000000000000000,
                "carrier": "FedEx",
                "shipping_method": "SmartPost"
            }
        }
    ]
}

GET	https://callback-api.homeroots.co/api/v1/buyer/orders/invoice	Get an Order Invoice Details

Query String Parameters – One of this fields are required and other optional.
`po_number`	Show orders by Purchase Order Number
`invoice_number`	Show order by Invoice Number

Response

On a successful GET, such an object will be returned.

{
    "data": [
        [
            {
                "po_number": "1234567897",
                "invoice_number": "12-34-567890123",
                "carrier_name": "",
                "carrier_account_number": "",
                "customer_name": "John Smith",
                "address_line1": "1818-1806 S Westmoreland Ave",
                "address_line2": null,
                "city": "Los Angeles",
                "state": "CA",
                "zipcode": "90006",
                "phone_number": "1234567890",
                "items": [
                    {
                        "ocid": 547961,
                        "item_name": "60\" x 90\" Multicolor Silk - Throw",
                        "quantity": 1,
                        "price": 70,
                        "shipping_price": 15.5,
                        "sub_amount": 85.5
                    }
                ],
                "total": 85.5
                }
            }
        ]
    ]
}

POST	https://callback-api.homeroots.co/api/v1/buyer/orders	Create a new Order

Input Parameters – All fields required unless otherwise marked.
po	A unique PO # from the Retailer’s OMS.
first_name	First name of the consumer
last_name	Last name of the consumer
company (optional) must be present, but may be empty	The destination company
street_address1	The destination street address.
street_address2 (optional) must be present, but may be empty	The destination street address
city	The destination city
state	The destination state
zip_code	The destination zip code
country	The destination country
telephone	The contact information of the consumer
carrier (optional) must be present, but may be empty	Shipping carrier name
carrier_account (optional) must be present, but may be empty	Shipping carrier account
items_in_order	qty – The number of items ordered ocid – HomeRoots’s identifier of product

Response

On a successful POST, such an object will be returned.

{
    "po_number": "123456789",
    "invoice_numbers": [
        "9876-54-3210987654",
        "1234-56-7890123456"
    ],
    "payment_type": "net_terms",
    "message": "Order submitted successfully.",
    "status": true
}

Sample POST request to create an order:

        POST https://callback-api.homeroots.co/api/v1/buyer/orders
        Content-type: application/json
        Authorization: Bearer 0oW0r4m1pjIlb5UJujZA5iVuse0XSn
        body: {
                "po":"11-0123456789",
                "first_name":"John",
                "last_name":"Smith",
                "company":"",
                "street_address1":"1818-1806 S Westmoreland Ave",
                "street_address2":"",
                "city":"Los Angeles",
                "state":"CA",
                "zip_code":"90006",
                "country":"US",
                "telephone":"1234567890",
                "carrier":"",
                "carrier_account":"",
                "items_in_order": {
                    "0": {
                        "qty":"2",
                         "ocid":"354787"
                    },
                    "1": {
                        "qty":"1",
                         "ocid":"317292"
                    }
                }
            }

Sample request on PHP

    <?php
        $url = "https://callback-api.homeroots.co/api/v1/buyer/orders";

        $curl = curl_init($url);
        curl_setopt($curl, CURLOPT_URL, $url);
        curl_setopt($curl, CURLOPT_POST, true);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

        $headers = array(
           "Authorization: Bearer your_token_here...",
           "Content-type: application/json",
        );
        curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);

        $data = [
            "po" => "11-0123456789",
            "first_name" => "John",
            "last_name" => "Smith",
            "company" => "",
            "street_address1" => "1818-1806 S Westmoreland Ave",
            "street_address2" => "",
            "city" => "Los Angeles",
            "state" => "CA",
            "zip_code" => "90006",
            "country" => "US",
            "telephone" => "1234567890",
            "carrier" => "",
            "carrier_account" => "",
            "items_in_order" => [
                [
                    "qty" => "2",
                    "ocid" => "354787"
                ],
                [
                    "qty" => "1",
                    "ocid" => "317292"
                ]
            ]
        ];

        curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));

        $resp = curl_exec($curl);
        curl_close($curl);
        var_dump($resp);
    ?>

Sample request on Python

    import requests
    import json
    from requests.structures import CaseInsensitiveDict

    url = "https://callback-api.homeroots.co/api/v1/buyer/orders"

    headers = CaseInsensitiveDict()
    headers[
        "Authorization"] = "Bearer your_token_here..."
    headers["Content-type"] = "application/json"

    data = {
        "po":"11-0123456789",
        "first_name":"John",
        "last_name":"Smith",
        "company":"",
        "street_address1":"1818-1806 S Westmoreland Ave",
        "street_address2":"",
        "city":"Los Angeles",
        "state":"CA",
        "zip_code":"90006",
        "country":"US",
        "telephone":"1234567890",
        "carrier":"",
        "carrier_account":"",
        "items_in_order": {
            "0":{
                "qty":"2",
                 "ocid":"354787"
            },
            "1":{
                "qty":"1",
                "ocid":"317292"
            }
        }
    }

    resp = requests.post(url, headers=headers, data=json.dumps(data))
    print(resp.content)

Sample request on Node.js

    const request = require('request');

    const headers = {
        'Authorization': 'Bearer your_token_here...',
        'Content-type': 'application/json'
    };

    const data = {
        "po":"11-0123456789",
        "first_name":"John",
        "last_name":"Smith",
        "company":"",
        "street_address1":"1818-1806 S Westmoreland Ave",
        "street_address2":"",
        "city":"Los Angeles",
        "state":"CA",
        "zip_code":"90006",
        "country":"US",
        "telephone":"1234567890",
        "carrier":"",
        "carrier_account":"",
        "items_in_order": {
            "0": {
                "qty":"2",
                 "ocid":"354787"
            },
            "1": {
                "qty":"1",
                "ocid":"317292"
            }
        }
    };

    const options = {
        url: 'https://callback-api.homeroots.co/api/v1/buyer/orders',
        method: 'POST',
        headers: headers,
        body: JSON.stringify(data)
    };

    function callback(error, response, body) {
        console.log(body)
    }

    request(options, callback);

Inventory

The HomeRoots API uses OAuth2 to authenticate all clients over HTTPS.

Before getting started, make sure you have your Personal Access Tokens or OAuth2 Client ID & Client Secret from HomeRoots. If you do not have credentials, please contact us.

Operations

Click on an Operation to view requirements, options, & examples.

GET	https://callback-api.homeroots.co/api/v2/buyer/inventory/info/{ocid}	Get an Inventory Info Details
GET	https://callback-api.homeroots.co/api/v1/buyer/inventory/info/{ocid}	Get an Inventory Info Details

Examples

GET	https://callback-api.homeroots.co/api/v2/buyer/inventory/info/{ocid}	Get an Inventory Info Details

Response

On a successful GET, such an object will be returned:

{
    "data": {
        "sales_price": 55,
        "sales_start": "2022-02-22",
        "sales_end": "2022-02-23",
        "price": 60.5,
        "shipping_cost": 15.9,
        "eta": "2022-05-05",
        "barcode": "123456789012",
        "title": "5' x 8' Ombre Gray Faux Sheepskin Rug",
        "qty_in_stock": 99,
        "warehouse_zipcodes_qty": [
            {
                "zip_code": "12345",
                "qty": 50
            },
            {
                "zip_code": "54321",
                "qty": 49
            }
        ]
    }
}

GET	https://callback-api.homeroots.co/api/v1/buyer/inventory/info/{ocid}	Get an Inventory Info Details

Response

On a successful GET, such an object will be returned:

{
    "data": {
        "sales_price": 55,
        "sales_start": "2022-02-22",
        "sales_end": "2022-02-23",
        "price": 60.5,
        "shipping_cost": 15.9,
        "eta": "2022-05-05",
        "barcode": "123456789012",
        "title": "5' x 8' Ombre Gray Faux Sheepskin Rug",
        "qty_in_stock": 99,
        "warehouse_zipcodes_qty": [
            {
                "zip_code": "12345",
                "qty": 50
            },
            {
                "zip_code": "54321",
                "qty": 49
            }
        ]
    }
}

Call and You Shall Receive

Call and You Shall Receive

API Information

About HomeRoots API

OAuth Clients Add New

Personal Access Tokens Add New

Getting Started with the HomeRoots API

Authentication

Obtaining a Personal Access Tokens

Obtaining an OAuth Access Token

Refreshing OAuth Access Tokens

Available API Scopes

Including the Access Token in Requests

Orders

Operations

Examples

Sample request on PHP

Sample request on Python

Sample request on Node.js

Inventory

Operations

Examples

By

Company

Resources

Products

Let's Talk