Pushing/Importing a Sales Order Into LOCATE

One common request by companies is to have their shopping cart or some other order source integrated with LOCATE. Here we will cover the basics of how to copy/create such an order within LOCATE.

The full documentation for the /salesorder endpoint can be found here. The one required parameter to create a sales order is a customer_id. Obtaining a customer_id is achieved in one of two ways:

  1. Search for an existing customer and use their ID
  2. Create a new customer

To search for a customer by name you would send the following request:

GET /customer?name=[insert customer name]

You can find customers by searching on many different fields (see the Core API Features page for details on ways to search via the LOCATE API) or you might store LOCATE’s customer ID in your system for instant cross-referencing.

If the customer you want to create an order for does not exist within LOCATE, you can create them. To do this you would perform the following request:

POST /customer

The full documentation for the customer POST request can be found here. You must specify a customer type (Company or Individual) and depending on the type of customer you will either specify a name or first_name and last_name. Company type customers have additional features like contacts, part pricing, advanced email configuration options, and more. Whereas Individuals are more appropriate for retail customers.

Now that we have an ID for our customer we can create our sales order. This is done with the following request:

POST /salesorder

Body: {“customer_id”: [insert customer ID here]}

LOCATE will respond with the sales order object that was created, presuming your user has permission to create sales orders. This response will contain the ID for the sales order which we will need for our next several requests.

Adding Sales Order Lines

To create a sales order line we need several pieces of data: salesorder_id, linetype_id, part_id, qty (optional), unit_price (optional). You can see the full documentation for the /salesorder/line endpoint here.

To obtain a part_id you can follow the same procedure from above for finding/creating a customer. The same principles apply, although what you search on may vary. We recommend using the “number” field or “upc” field depending on how you’re correlating parts from your system with LOCATE. Now let’s add a line to our sales order:

POST /salesorder/[insert sales order ID]/line

Body: {“linetype_id”: 1, “part_id”: [insert part ID], “qty”: 1, “unit_price”: 6.99}

Here we used linetype_id 1 which correlates with a “Sale” line type, the most common one used. For more information on the available line types see the Transaction Line Type section in the Core API Features page.

Adding Discounts/Fees

LOCATE supports order level and line level discounts/fees. To find/create a discount or fee follow the same procedure for finding/creating a customer or part from above with the /discount or /fee endpoint respectively. You will need the respective discount_id or fee_id to add it to the order.

Once you have the relevant ID you will use the corresponding request below to add the discount/fee to the order:

POST /salesorder/[insert sales order ID]/discount

Body: {“discount_id”: [insert discount ID], “amount”: [insert amount]}

POST /salesorder/[insert sales order ID]/fee

Body: {“fee_id”: [insert fee ID], “amount”: [insert amount]}

To do the same at the line level you would use:

POST /salesorder/[insert sales order ID]/line/[insert sales order line ID]/discount

Body: {“discount_id”: [insert discount ID], “amount”: [insert amount]}

POST /salesorder/[insert sales order ID]/line/[insert sales order line ID]/fee

Body: {“fee_id”: [insert fee ID], “amount”: [insert amount]}

IMPORTANT: Line level discount and fee amounts are unit based, meaning the amount will be multiplied by the qty on the line. So if you want to discount a line by $5 and it has a qty of 2 you would submit $2.50 as the amount.

Issuing a Sales Order (optional)

Once you have created your sales order in LOCATE you can leave the order to be reviewed/issued by a user, or you can issue the order via the API to begin fulfillment of the order immediately. Issuing an order starts the workflow process of completing the order. LOCATE will determine, during the issuance process, what steps are required based on how it has been configured for a given business. To issue a sales order you would make the following call:

POST /salesorder/[insert sales order ID]/issue

NOTE: This call can return 428 response when warnings that should be presented to the user are returned. To bypass these warnings make the same call with the “ignore_warnings”: 1 in the payload of the request. You can see the full documentation for the /salesorder/issue endpoint here.