PushCart Integration

About PushCart

Push-Cart is a collection of services and APIs provided by Locally. These services allow retailers to receive real-time transactions from the Locally platform as they occur, effectively “pushing” the shopper’s cart to an external system such as a Point of Sale, Sales Order Management, or ERP for fulfillment.

Prerequisites

Inventory Integration or Inventory Feeds

Locally offers several ways to sync store inventory. If your system is already sending on-hand inventory to Locally, no action is required. Here is an example inventory feed format. The format is simple:

In order to use PushCart your system must be updating inventory feeds at least once every 24 hours. If Locally detects feed staleness beyond 72 hours, PushCart will be temporarily disabled. Inventory setup is outside of the scope of this document. Please review our documentation here or contact your Locally support representative about getting started.

Participation in “Buy It Locally” (BIL)

Locally also requires the activation of “Buy It Locally” for all retailers in order to participate in the PushCart transaction workflow. PushCart supports Reserve Online Pickup in Store (ROPIS) and Buy Online Pickup In Store (BOPIS) transactions. To be eligible, stores may accept ROPIS, BOPIS, or both.

PushCart does not currently support Same-Day Delivery or Ship to Store orders. Retailers utilizing Pushcart that wish to offer those transaction types can still fulfill those orders from the Locally order management console in their Locally dashboard.

Before proceeding with your PushCart integration, ensure you’ve completed the setup steps.

Configuring Your PushCart Profile

If you don’t already have a Locally company account, please contact your Locally representative about getting an account set up.

Once your account is set up, the following basic settings can be adjusted by contacting Locally.

Webhook URL for Order Updates

You will need to provide Locally with a webhook URL endpoint. This URL can be changed at any time via the configuration panel. Locally will send a payload containing the cart object (see below) to this endpoint whenever a new order is created or has been updated. It will be your company’s responsibility to consume this payload and act accordingly in order to fulfill the request in a timely manner. See the “Buy it Locally: Real-time Carts API” section below for more information on this topic.

Optionally, you may instead choose to poll our API at a high frequency. Please contact Locally to discuss if this option is feasible for your needs.

Manage Participating Stores

You can define which stores will have the PushCart capability. Any stores that are not enabled for PushCart fulfillment will default to the standard Buy it Locally customer order workflow (if any).

Buy It Locally: Real-time Carts API

The Real-time Carts API is your way to request up-to-the-minute information on all orders you have access to, and how to update an existing order’s status in the Locally system.

Requesting your API key

You will need an API Key to access your CartAPI endpoint. See Generate An API Key for more info.

GET /carts/{page} endpoint

Now that you have your API key, you will be able to access our Cart API endpoints.

A request is built by adding “Locally-API-Token” to the header of your request and the value of that will be the API key you generated on our platform.

To access the list of all the carts, use:

GET https://www.locally.com/api/v2/carts

You will need to pass along your API key in the header of the request. For example, in JSON:

{  
    "url": "<https://www.locally.com/api/v2/carts">,  
    "raw_url": "<https://www.locally.com/api/v2/carts">,  
    "method": "get",  
    "headers": {  
        "Locally-API-Token": "ea432b89353efxxxe46f147b3uae37fgcae2337"  
    }  
}

This will return the list of all carts your account has access to, ordered by most recent first, and broken up via 50 per page. The first page can be accessed via just /api/v2/carts or /api/v2/carts/0.

Sample payload response:

{  
    "status": true,  
    "properties": {  
        "date_time": "2022-02-03 10:52:40",  
        "current_page": 0,  
        "total_pages": 3  
    },  
    "carts": [  
        {  
            "hash": "E3GKY8",  
            "type": "HOLD",  
            "n_items": 1,  
            "source": "From locally.com",  
            "ordered_at": "2022-01-28 10:28:22",  
            "updated_at": "2022-01-28 15:34:30",  
            "delivery_status": "",  
            "pickup_window": "2022-01-29 15:00:00",
            "items": [  
                {  
                    "currency": "EUR",  
                    "total": "100.00",  
                    "status": "Canceled",  
                    "sts_status": "N/A",  
                    "qty": 1,  
                    "product_id": 967586,  
                    "order_resolution": "auto-cancelled",  
                    "upc": "601842495575",
                    "alias":[
                      "D1447020122-00003"
                      ]
                }  
            ]  
        },  
        {  
            "hash": "OK38N3",  
            "type": "ORDER",  
            "n_items": 1,  
            "source": "From locally.com",  
            "ordered_at": "2021-11-18 15:08:35",  
            "updated_at": "2021-11-18 15:09:59",  
            "delivery_status": "",
            "pickup_window": "2022-11-19 15:00:00",
            "items": [  
                {  
                    "currency": "JPY",  
                    "total": "990.00",  
                    "status": "Confirmed",  
                    "sts_status": "N/A",  
                    "qty": 1,  
                    "product_id": 936676,  
                    "order_resolution": "",  
                    "upc": "745889071559",
                     "alias": []
                }  
            ]  
        }  
    ]  
}

Definition of the response payload:

Reference Doc: GET /carts

GET /cart/{cart_hash} endpoint

This will give you all the data for this specific cart. Your company must have access to this cart in order to retrieve its data.

To access this single cart’s information, use this endpoint:

GET https://www.locally.com/api/v2/cart/{cart_hash}

You will need to pass along your API Key in the header of the request. For example, in JSON:

{  
    "url": "<https://www.locally.com/api/v2/cart/QE3QL6">,  
    "raw_url": "<https://www.locally.com/api/v2/cart/PDQE89">,  
    "method": "get",  
    "headers": {  
        "Locally-API-Token": "ea432b8935xxx459be4gf147b33ae3uf0cae2337"  
    }  
}

Sample payload response:

{  
    "status": true,  
    "properties": {  
        "date_time": "2022-02-03 11:11:18",  
        "type": "HOLD",  
        "hash": "QE3QL6",
        "pickup_window": "2022-02-04 11:00:00",
        "ordered_at": "2022-02-03 11:07:42",  
        "updated_at": "2022-02-03 11:09:43",  
        "delivery_status": "",  
        "invoice": "https://www.locally.com/order/QE3QL6/S615W9CDQK7M?print=1"  
    },  
    "customer": {  
        "first_name": "John",  
        "last_name": "Doe",  
        "address_1": "509 N Carrollton Ave",  
        "address_2": "",  
        "city": "New Orleans",  
        "state": "LA",  
        "zip": "21541",  
        "country": "US",  
        "email": "retailers@locally.com",  
        "phone": "",  
        "marketing_active_consent": "answer_yes"  
    },  
    "store": {  
        "name": "Locally Test Store Netherlands",  
        "phone": "",  
        "address": "1012 KN",  
        "address_2": "",  
        "city": "Amsterdam",  
        "state": "",  
        "zip": "9V9R+RV",  
        "country": "NL",  
        "store_id": 245728,  
        "vendor_id": 0  
    },  
    "items": [  
        {  
            "status": "Ordered",  
            "sts_status": false,  
            "product_id": 967586,  
            "qty": 1,  
            "brand": "Trek",  
            "upc": "601842495575",  
             "alias": [
                  "D1447020122-00003"
                  ],
            "name": "Bontrager Circuit Road Cycling Shoe",  
            "attrib_1": "US Men 4/Women 5.5/EU 37",  
            "attrib_2": "",  
            "currency": "EUR",  
            "msrp": "100.00",  
            "product_price": "100.00",  
            "product_price_less_vat": "100.00",  
            "subtotal": "100.00",  
            "tax": "0.00",  
            "tax_rate": "0.00",			  
            "tax_is_vat": true,  
            "tax_remitted": false,  
            "commission": "3.50",  
            "stripe_fee": "3.20",  
            "total": "100.00",  
            "disbursement": "96.80",  
            "order_resolution": "",  
            "resolution_notes": "",  
            "messages": [  
                {  
                    "sender": "retailer",  
                    "description": "test message to customer",  
                    "created_at": "2022-02-03 11:09:41"  
                },  
                 {  
                    "sender": "customer",  
                    "description": "test message to store",  
                    "created_at": "2022-02-03 11:58:21"  
                }

        		]
    		}
		]
}

Definition of the response payload:

Reference Doc: /cart/{cart_hash}

POST /cart/{cart_hash}/{upc} endpoint

Use this endpoint to make updates to existing orders. See “Lifecycle of a PushCart Transaction” for details on the timing of these requests.

You will need to pass along your API Key in the header of the request. For example, in JSON:

{  
    "url": "<https://www.locally.com/api/v2/cart/QE3QL6/190340561726">,  
    "raw_url": "<https://www.locally.com/api/v2/cart/QE3QL6/190340561726">,  
    "method": "post",  
    "headers": {  
        "Locally-API-Token": "ea432b8axxxef459be46f147577e37fgcae2u37"  
    },  
    "data": {  
        {
          "status" : "confirm"
        }  
    }  
}

Payloads:

Confirm the BOPIS or ROPIS order:

{  
	"status" : "confirm"  
}

Reject the BOPIS or ROPIS order:

{  
	"status" : "reject"  
}

Send a message to the shopper via SMS and email:

{  
	"message" : "Message goes here that will be sent to the customer via SMS and email"  
}

Update the order status and include a message in the same payload:

{  
	"status" : "confirm",
	"message" : "Looking forward to seeing you!"  
}

Refund a previously confirmed BOPIS order

{  
	"refund":true  
}

Sample response:

{  
	"status": true,  
  "debug": "Inputs: array ('status' => 'reject')",  
  "code": 102  
}

Definition of the response payload:

Lifecycle of a PushCart Transaction

What follows is a description of the workflow, starting with the initial customer engagement in the “Buy It Locally” system through to fulfillment (pickup) of the product from the local retailer:

Payment, Communications, and Order Handoff

This section requires the use of webhooks. Read more about Locally's webhook configuration here.

1. PENDING STORE ACTION. WINDOW FOR CONFIRMATION:

Customer submits the order. If this is for a BOPIS order, their credit card is authorized for the full MSRP amount but Locally does not charge their card yet.

Locally pushes information for the new order by sending a PUT request to the webhook address you provided. The payload is as follows:

{
  "upc":"601842495575",
  "order_id":"QE3QL6",
  "status":"ordered",
  "order_url":"https://www.locally.com/api/v2/cart/QE3QL6"
}

The retailer has a 4 hour window, during store operating hours, to respond to the order via the Cart API or via the Locally notification link. If the order is placed when the store is closed, the 4 hour window begins when the store next opens.

If the 4 hour window expires, the customer will be notified via email and SMS that it has expired and that the order is canceled. Locally will also PUT an API request to your webhook endpoint about this order, indicating that it was automatically rejected. The payload is as follows:

{
  "upc":"601842495575",
  "order_id":"E3GKY8",
  "status":"canceled",
  "order_url":"https://www.locally.com/api/v2/cart/QE3QL6"
}

2. RETAILER APPROVED OR REJECTED:

You must POST to Locally’s cart API with the status confirm in order to approve the customer order. To reject the order, you must submit the status reject. If the order was approved on the Locally platform, we will notify you via a PUT request to the webhook address you provided. The payload is as follows:

{
  "upc":"601842495575",
  "order_id":"QE3QL6",
  "status":"confirmed",
  "order_url":"https://www.locally.com/api/v2/cart/QE3QL6"
}

If you reject the customer’s request, we will notify the customer about the rejection.

After a BOPIS or ROPIS order has been confirmed or rejected, you can still communicate with the customer about this order through the messaging system.

If you approve a BOPIS request, the customer’s credit card will be charged immediately for the full amount and the funds will be transferred directly to your Stripe account.

Other API Functionality

SEND MESSAGE:

You can pass along any message through the POST API endpoint. For example:

{  
    "message":"Message goes here that will be sent to the customer via SMS and email"  
}

ORDER RESOLUTION:

If not supplied, it will be assumed that the order was successful. These can be set to provide information on what happened with the order. Order resolution statuses affect your billing, so it’s important for the store to be accurate in reporting what happened.

Here are the possible order resolutions you can change a line item to:

{  
    "1": {  
        "id": 1,  
        "name": "The shopper purchased this item (and this item only)",  
        "brief_name": "purchased"  
    },  
    "2": {  
        "id": 2,  
        "name": "The shopper purchased this item and additional products",  
        "brief_name": "purchased +"  
    },  
    "3": {  
        "id": 3,  
        "name": "The shopper showed up, but purchased a different product than this.",  
        "brief_name": "purchased other"  
    },  
    "4": {  
        "id": 4,  
        "name": "The shopper showed up but did not purchase anything",  
        "brief_name": "no purchase"  
    },  
    "5": {  
        "id": 5,  
        "name": "No sale/the shopper did not show up to the store",  
        "brief_name": "no show"  
    }  
}

Payload needed to push to us is:

{  
    "order_resolution":1  
}

REFUND ITEM:

This can be done through the same POST API endpoint. Our system will do a full refund for the line item you are altering. Refunds will be processed immediately, though the shopper’s financial institution will generally take 5-10 business days to process the returned funds. Payload example:

{  
    "refund":true  
}

Testing endpoints and integrations

Our current process is to flag a company as being in “test mode.” What that does is make it so if an order is placed that would normally collect money, it would use our test payment credentials. This means orders can be placed on production with a test CC (acct: 4242 4242 4242 4242 exp: 02/26, csv: 111) and it will work the same as a live order. We could create a test store that could be used as well. Please reach out to us when ready for testing.

Important Considerations

SALES TAX COLLECTION IN THE US AND CANADA:

As a Marketplace Facilitator, Locally is required to collect and remit sales tax on BOPIS orders in the US and Canada. The sales tax amount on BOPIS sales is not remitted to retailers; Locally collects the tax amount during the transaction and remits it to state and local jurisdictions. A log of the sales tax Locally has collected and remitted is available in a retailer’s Locally dashboard.

Locally uses Avalara/Avatax to calculate sales tax amount based on the item being purchased and the location of the store.

The opposite is true outside of the US and Canada. In Asia and Europe, Locally passes the tax (VAT) amount to the retailer, and it is the retailer’s responsibility to remit.

CHARGE FAILED:

While very rare, there can be cases where a BOPIS order is able to be placed, but the credit card charge fails when the retailer confirms the item. This is more common in Europe where varying authentication requirements by different banks can lead to complications, however users in the US and Canada should take this into account as well.

In this case, the item status changes to Charge_Failed. At this point, both the shopper and the retailer are emailed informing them that the order was confirmed but the credit card charge failed and the order must be paid in-store, and the Locally order screen UI is also updated with this messaging. Pushcart users must take this into account; our recommendation is to change the type to a ROPIS order to indicate payment was not captured.

Here is a sample payload response for a failed charge:

{  
    "status": true,  
    "properties": {  
        "date_time": "2022-04-29 11:46:25",  
        "type": "ORDER",  
        "hash": "00001",
        "pickup_window": "2022-04-29 18:00:00",
        "ordered_at": "2022-04-28 11:20:48",  
        "updated_at": "2022-04-28 11:20:49",  
        "delivery_status": "",  
        "invoice": "https://www.locally.com/order/00001/SGZ48JH1WNOK?print=1"  
    },  
    "customer": {  
        "first_name": "John",  
        "last_name": "Smith",  
        "address_1": "123 Fake St",  
        "address_2": "",  
        "city": "New Orleans",  
        "state": "LA",  
        "zip": "70179",  
        "country": "US",  
        "email": "sampleshopper@gmail.com",  
        "phone": "+11234567890",  
        "marketing_active_consent": "answer_yes"  
    },  
    "store": {  
        "name": "Sample Store",  
        "phone": "+11234567890",  
        "address": "789 Fake St",  
        "address_2": "",  
        "city": "New Orleans",  
        "state": "LA",  
        "zip": "70471",  
        "country": "US",  
        "store_id": 12345,  
        "vendor_id": 0  
    },  
    "items": [  
        {  
            "status": "Charge_Failed",  
            "sts_status": false,  
            "product_id": 653104,  
            "qty": 1,  
            "brand": "Arc'teryx",  
            "upc": "686487512122",  
            "name": "Mantis 26 Backpack",  
            "attrib_1": "",  
            "attrib_2": "",  
            "currency": "GBP",  
            "msrp": "90.00",  
            "product_price": "90.00",  
            "product_price_less_vat": "75.00",  
            "subtotal": "90.00",  
            "tax": "15.00",  
            "tax_rate": "20.00",  
            "tax_is_vat": true,  
            "tax_remitted": false,  
            "shipping_cost": "0.00",  
            "commission": "2.63",  
            "stripe_fee": "0.00",  
            "total": "90.00",  
            "order_resolution": "",  
            "resolution_notes": "",  
            "messages": \[],  
            "disbursement": "90.00"  
        }  
    ]  
}