We're approached constantly by larger chain retailers who want to accept transactions from the Locally network, but who can't support multiple curbside and same-day delivery systems.

Our newest tool allows retailers who already have robust sales order management systems (and processes) to accept entire carts from second and third party sites. We call this tool PushCart and the discussion that follows is mostly meant for web developers.

But, before we dig into the details of how it works and how to set it up, let's run through a shopping scenario: Shopper is having a party this weekend and realizes his grill no longer works. He not only doesn't have time to have one shipped, but he prefers the support a nearby store provides. He does his research before ultimately visiting a grill manufacturer's website where he sees that the model he wants is in-stock at a local hardware chain. He even sees that he can have the item delivered right there on the manufacturer's product page.

Once he's entered delivery and payment details, Locally passes the sale directly to the hardware chain's BOPIS system so they can fulfill the order and become the primary point-of-contact. For the shopper, the experience is seamless, but behind the scenes, an elaborate handoff of data and proceeds are occurring. Here's how:

1. About PushCart

PushCart 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 per 24 hours. If Locally detects feed staleness beyond 24 hours, PushCart will be temporarily disabled. Inventory setup is outside of the scope of this document. Please contact your Locally support representative about getting started.

Participation in “Buy it Locally” (BIL)

Locally also requires the activation of a BIL profile for all retailers in order to participate in the PushCart transaction workflow. Enabling BIL involves the following actions:

• Defining and managing the local sales tax rate for each participating store
• Connecting a Stripe account to Locally’s Stripe account for transmission of funds
• Adding a credit card or other payment method to your Locally company account

If Buy It Locally (BIL) becomes disconnected at any time, PushCart will automatically cease to function.

2. 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 you can manage basic settings for your PushCart profile here.

The following fields are editable in this configuration panel:

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 API documentation 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.

Manage Participating Stores

In this panel 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).

3. 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 that resides within the Locally system. This is a broad overview of what development for PushCart will entail.

Requesting your API key

Start by logging into the Locally platform, navigate over to the “Credentials” area at https://www.locally.com/station/panel/credentials . Follow the instructions for creating a new API key.

You will be able to give it a name, we recommend something that will help you remember what specifically this is for. If needed you can always revoke an API key and create a new one.

You’ll see your new key in the API Credentials page now.

When you click on “Show” you will see the API Key: GET /api/v2/carts/{page} endpoint.

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

The way a request is built is 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, access:

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 cURL:

curl -X GET https://www.locally.com/api/v2/carts -H 'Locally-API-Token: ea432b8a353ef459be46f147b33ae37f0cae2337'

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. First page can be accessed via just /api/v2/carts or /api/v2/carts/0

Sample, abbreviated payload:

Definition of the response payload

GET /api/v2/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 cURL: curl -X GET https://www.locally.com/api/v2/cart/O3V36 -H 'Locally-API-Token: ea432b8a353ef459be46f147b33ae37f0cae2337'

Sample, abbreviated payload:

Definition of the response payload

POST /api/v2/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 cURL:

4. Lifecycle of a PushCart Transaction

The products in your inventory feeds combined along with your activated retailer list will determine which stores display the “Buy Online, Pick up in Store” labels on product display pages and other product locator technology throughout the Locally platform.

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

1. PENDING STORE. WINDOW FOR CONFIRMATION

Customer submits the order. Their credit card is authorized for the full MSRP amount but Locally does not charge the card yet. The order is pending retailer rejection. The retailer has a 2 hour window, during store hours, to reject the order and supply a reason for the rejection via the Cart API.

If the 2 hour indow expires, the customer will be notified via email and SMS. Locally will also PUT an API request to your webhook endpoint about this order, indicating that it was automatically rejected.

During this 2 hour window, you may optionally POST to Locally’s cart API with the status received and include a fulfillment_url as part of your response. If we receive a fulfillment_url we assume that the order (while not yet “confirmed” is in your system and that Locally will redirect all subsequent shopper requests to the URL you specified.

2. RETAILER APPROVED OR REJECTED

You must POST to Locally’s cart API with the status confirmed in order to approve the customer order. To reject the order, you must submit the status rejected and supply a reason.

If you reject the customer’s request, we will notify the customer and the store about the rejection. If you did not supply a fulfillment_url in your response, you can still communicate with the customer about this order through the Buy it Locally messaging window after an order has been rejected.

If you did supply a fulfillment_url in your response. Locally will no longer be involved in any direct communications with the customer. The customer will be redirected to the URL you submitted and all other communications should come directly from your company.

If you approve the 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.

3. PROCESSING THROUGH FULFILLMENT

From this point forward, your system is responsible for handling the shopper’s experience. Locally requires that you POST to Locally’s cart API with a final status update of fulfilled as each item is picked up.

4. HANDLING RETURNS AND CHARGEBACKS

Because Locally originally captured the shopper’s card details, we can only accept refund requests via when you POST to Locally’s cart API with a final status update of refund as well as a companion refund_amount per item in the shopper’s cart. Refunds will be processed immediately.