Library OpenApi Overview About these APIs Architecture Authentication Error Responses Locating a Server Sessions Design Guides Guides and Hints Examples Pricing for Websites Accepting Vouchers PreAuth Payment Replication Common Apis The most used APIs Create New Sale Payment Completion Multiple Locations Delivery Addresses Customers Locations Products Staff WebHooks eCommerce Apis These APIs are often used with eCommerce website integrations Get Pricing Card Inquiry Report & Analysis Grouped or analysed report data. Typically used to build reports and dashboards Today Login Access Pinboard ReportRequest Advanced Information More indepth information Caller Handling HTTP Protocol Bulk Data Downloads Document Uploading RetailConfig Under Development Details of APIs that will be available shortly. Documentation provided is for early adopters Get Receipt

Multiple Locations on Create New Sale API

Technical Definitions

Sale.Location The location (store) that this sale is to be recorded against for reporting purposes. This value is typically always supplied, although the server can apply defaults in some cases.

Sale.StockLocation The location (store / warehouse) where stock will be drawn from. This value is rarely provided by API callers as they cannot be certain where the stock will actually be taken from. Sometimes eCommerce sites do know, so can provide this value

Delivery.CollectLocation This is the location the item will be collected from by the shopper.

Single Store Retailers

If the retailer has a single store (location) and an assocated website, then the "location" will typically be the website, and stock location is managed server side to be the store. Most of the rest of this document doesn't apply as you do not need to specify the extra location information. However, this page also delves into maintaining precise stock levels which is still relevant if needed

Selling the Mona Lisa

The concepts being explained here are easier when presented using an example, so we will consider the case of a chain of Art stores selling Art works.

The Store has 3 physical locations and the only original Mona Lisa available for sale, currently on display in the Lerwick store.

StoreQty On Hand
Head Office0
Lerwick1
York0
Websiten/a

If the sale is a "normal" web sale, and all web sales should reported as "website". Then sale sent would be as below. This sale will report as "website", and retailer will handle the stock transfer to head office for dispatch

{
    "ExternalId": "Sale.000001",
    "Location": "Website",
    "CompletedDt": "2019-07-01T10:35",
    "Phase": 200,
    "LINE": [{
            "Pid": 12345,
            "Qty": 1,
            "TotalPrice": 29.95
        }]
}

If the customer indicated they wished to click+collect this item from Lerwick, then the sale includes that additional detail. The revenue will still be recorded as website, but the physical delivery will go to Lerwick.

{
    "ExternalId": "Sale.000001",
    "Location": "Website",
    "CompletedDt": "2019-07-01T10:35",
    "Phase": 200,
    "LINE": [{
            "Pid": 12345,
            "Qty": 1,
            "TotalPrice": 29.95
        }],
    "Delivery": {
        "CollectLocation": "Lerwick"
    }
}

If the customer indicated they wished to click+collect this item from York, which does not have the Mona Lisa in stock, then the API still simply sends that information. The revenue will still be recorded as website, but the physical delivery will go to York. The website does not send stock location information. While stock location is clear in this example, in reality it isn't quite so easy.

{
    "ExternalId": "Sale.000001",
    "Location": "Website",
    "CompletedDt": "2019-07-01T10:35",
    "Phase": 200,
    "LINE": [{
            "Pid": 12345,
            "Qty": 1,
            "TotalPrice": 29.95
        }],
    "Delivery": {
        "CollectLocation": "York"
    }
}

Stock Levels

Selling the Mona Lisa for 29.95 is a bargain, so you could easily have multiple customers purchasing this item at the same moment, but there is only one original, so we need to restrict sales

Fieldpine reduces the stock level when it receives the sale advice via the API

Tip. When stock levels are low, consider always putting a warning on the sale saying 'availability subject to confirmation at dispatch time'. Potentially the item could be sold in store at the same moment it is sold online

When showing stock levels for items, remember that the available level is Current Fieldpine Level minus Open Shopping carts. So for the Mona Lisa, as soon as the first shopper places this item in their shopping cart, you should be showing zero availability. When the sale is sent to Fieldpine, then Fieldpine will reflect that with lower stock levels, however, that may take some time depending on how fulfillment is being handled at the retailer. You might like to display stock levels as Current Fieldpine Level minus Open Shopping carts minus Carts finished in last ( N minutes/hours )

The logic used by Fieldpine to determine stock locations is as follows
  1. If the sale has specified StockLocation, use that.
  2. If the sale has delivery.CollectLocation AND that store has stock, use that.
  3. Otherwise, use the Sale.location

Additionally, if "AutoStock" is enabled and the sale is a "picking" sale, then the stock level in the selected StockLocation immediately reduces. If AutoStock is not enabled then the stock level reduces when the item is picked.