LivePepper API

Purpose and Audience

The purpose of this document is to describe the system-to-system interface protocols and practices that are available for use between LivePepper and its partners.

This document is for business analysts, system architects, system engineers, developers, and testing organizations that need to build or test systems that programmatically access the LivePepper system.

If you have an API problem for which you can’t find a solution in this guide, then please contact LivePepper Support for assistance using any of these methods:

Telephone: +33 4 92 38 09 82
Email: support@livepepper.com

The LivePepper REST API

A REST API provides a powerful, convenient, yet simple web services API for communication with the LivePepper system. It’s easy to integrate with most other systems, and it’s an excellent technology for use with Web 2.0 projects.

To use this document, you should have a basic understanding of software development, web services, and online/remote order processing. In this guide, we show you:

The key characteristics and architecture of REST API. This will help you understand how your applications can make optimal usage of LivePepper REST resources.
How to use REST API by following a quick start that leads you step by step through a typical use case.

Accessing REST Resources

A REST resource provides an abstract for an element of information – such as a single data record, a collection of records, or dynamic real-time information. Each resource in the LivePepper REST API has a unique identity in the form of a specific URL, and you access a resource using standard HTTP methods (HEAD, GET, POST, PATCH, DELETE).

The HTTP method indicates the type of action performed on the data:

Action	HTTP Method	Description
Create	POST	Creates and persists a resource of the corresponding type.
List	GET	Returns information for all resources matching query parameters you provide. To get comprehensive information for a particular resource, first get the resource’s id with the appropriate List endpoint, then provide the id to the corresponding Retrieve endpoint.
Retrieve	GET	Provides comprehensive information for the single resource that matches the identifier you provide.
Update	PUT	Modifies the existing resource that matches the identifier you provide.
Delete	DELETE	Deletes the existing resource that matches the identifier you provide. Deleted resources cannot be retrieved or undeleted.

By means of this API, you can perform a variety of functions—including checking and modifying order status, reviewing order details, and managing customer loyalty balances.

Using cURL in the REST Examples

Some of the examples in this guide use the cURL utility to send HTTP requests for accessing, creating, and modifying LivePepper REST resources on the platform. cURL is available natively on many Linux and Mac systems. Microsoft Windows users download a version at curl.haxx.se/. When using HTTPS on Windows, you’ll need to ensure that your system meets the cURL requirements for SSL.

PostMan

As an alternative to cURL, Windows users can install Postman as a browser plugin: https://www.getpostman.com/

Example API

LivePepper users can place orders on the website and engage freely with the API—using the following links and credentials. We will use the following items for illustrating the usage of the API.

The username and password for access: john-pizza / PHAthO33
Back office: https://manager.livepepper.com
Front-end website: http://john-pizza.livepepper.com
API: https://posapi.livepepper.com/john-pizza

Authentication

Using the is Basic Authentication scheme, you need to authenticate before accessing LivePepper API resources. The form of the curl command is:

curl -u username:password https://posapi.livepepper.com/[storename]

Taking the username, password and API link from the Example API section, you would enter the following curl command to authenticate into the API:

curl -u john-pizza:PHAthO33 https://posapi.livepepper.com/john-pizza

List of Resources

You can retrieve a list of available LivePepper API resources by submitting the following request:

GET https://posapi.livepepper.com/john-pizza

The response includes all of the available API resources:

				
					<shop uri="https://posapi.livepepper.com/john-pizza">
<short_name>john-pizza</short_name>
<name>John Pizza</name>
<phone>0102030405</phone>
<address>Colorado Avenue</address>
<city>Denver</city>
<country>US</country>
<postal_code>11111</postal_code>
<min_delivery_time>30</min_delivery_time>
<min_collection_time>20</min_collection_time>
<ordering_time_range_size>15</ordering_time_range_size>
<advanced_orders_days>0</advanced_orders_days>
<timezone>Eastern Time (US &amp; Canada)</timezone>
<currency>USD</currency>
<creation of="buyer" href="https://posapi.livepepper.com/john-pizza/buyers"/>
<creation of="menu_upload" href-template="https://posapi.livepepper.com/john-pizza/menu_upload{?pos}"/>
<creation of="area_upload" href-template="https://posapi.livepepper.com/john-pizza/area_upload{?pos}"/>
<link to="products" href="https://posapi.livepepper.com/john-pizza/products"/>
<link to="product_groups" href="https://posapi.livepepper.com/john-pizza/product_groups"/>
<link to="main_taxonomy" href="https://posapi.livepepper.com/john-pizza/taxonomy"/>
<link to="new_orders" href="https://posapi.livepepper.com/john-pizza/new_orders"/>
<link to="orders" href-template="https://posapi.livepepper.com/john-pizza/orders{?before,after,pos_code}"/>
<link to="buyers" href-template="https://posapi.livepepper.com/john-pizza/buyers{?pos_code}"/>
<link to="postal_codes" href-template="https://posapi.livepepper.com/john-pizza/postal_codes{?pos_code}"/>
<link to="streets" href-template="https://posapi.livepepper.com/john-pizza/streets{?pos_code}"/>
</shop>

Retrieving New Orders

After your customer places an order on your website, you can retrieve the order through the web API function new_orders. You’ll need to include your store name in the call, as we show in this example:

GET https://posapi.livepepper.com/john-pizza/new_orders

The response will contain a link to one or more orders, such as the following:

				
					<new_orders uri="https://posapi.livepepper.com/john-pizza/new_orders">
<link to="order" href="https://posapi.livepepper.com/john-pizza/orders/2293319"/>
</new_orders>

Order Details

In the example above, we see that order number 2293319 is in the queue. To retrieve the details for this order, you need to simply follow the link given in the response to the new_orders resource above. Of course, you need to perform a GET with the order URL immediately after you get the response from the new_orders resource.

GET https://posapi.livepepper.com/john-pizza/orders/2293319

An order will remain in the new order status until the order status changes. See the section to learn how to change the status of an order.

Is it important to note that an etag value will be returned within the response headers. Its value will need to be provided when updating the order.

Below we show the example response for this order, which contains the order details and also the list of order items.

				
					<order url="https://posapi.livepepper.com/john-pizza/orders/2293319">
<order_ref>1513/1</order_ref>
<created_at>2015-03-30T15:41:02Z</created_at>
<seen_in_peppershop>false</seen_in_peppershop>
<is_asap_delivery>false</is_asap_delivery>
<seller_comment/>
<total>21.20 USD</total>
<delivery_charge>0.00 USD</delivery_charge>
<payment_charge>0.00 USD</payment_charge>
<total_points_spent/>
<total_points_earned/>
<pos_code/>
<loyalty_discount>0.00 USD</loyalty_discount>
<expected_delivery_time>2015-03-30T12:15:00</expected_delivery_time>
<confirmed_delivery_time></confirmed_delivery_time>
<workflow_state>new_order</workflow_state>
<workflow_transitions>
<workflow_state>accepted</workflow_state>
<workflow_state>rejected</workflow_state>
</workflow_transitions>
<buyer_comment></buyer_comment>
<delivery_method>collection</delivery_method>
<payment_method>on_delivery</payment_method>
<workflow_logs>
<workflow_log time="2015-03-30T15:41:02Z">new_order</workflow_log>
</workflow_logs>
<order_items>
<order_item uri="https://posapi.livepepper.com/john-pizza/order_items/7925572">
<name>Regina ham</name>
<variant_name>8''</variant_name>
<pos_code>5-1</pos_code>
<price>6.80 USD</price>
<quantity>2</quantity>
<subtotal>13.60 USD</subtotal>
<ref_price>6.80 USD</ref_price>
<options>
<option type="Crust">
<name>Standard</name>
<pos_code>3893</pos_code>
<price>0.00 USD</price>
<ref_price>0.00 USD</ref_price>
</option>
</options>
</order_item>
<order_item uri="https://posapi.livepepper.com/john-pizza/order_items/7925573">
<name>Regina ham</name>
<variant_name>8''</variant_name>
<pos_code>5-1</pos_code>
<price>6.80 USD</price>
<quantity>1</quantity>
<subtotal>7.60 USD</subtotal>
<ref_price>6.80 USD</ref_price>
<options>
<option type="Crust">
<name>Standard</name>
<pos_code>3893</pos_code>
<price>0.00 USD</price>
<ref_price>0.00 USD</ref_price>
</option>
<option type="checkbox">
<name>Cut</name>
<pos_code>3830</pos_code>
<price>0.00 USD</price>
<ref_price>0.00 USD</ref_price>
</option>
<option type="topping">
<name>Aubergines</name>
<pos_code>158-1</pos_code>
<price>0.80 USD</price>
<ref_price>0.80 USD</ref_price>
</option>
</options>
</order_item>
</order_items>
<link to="buyer" href="https://posapi.livepepper.com/john-pizza/buyers/1054289"/>
<link to="shop" href="https://posapi.livepepper.com/john-pizza"/>
</order>

Buyer Details

The response for Order Details will also include a link to for buyer details. From the example response, we would follow this link:

Placing this into a GET:

GET https://posapi.livepepper.com/john-pizza/buyers/1054289

The response will contain the buyer details:

				
					<buyer uri="https://posapi.livepepper.com/john-pizza/buyers/1054289">
<email>joe@foocompany.com</email>
<password>$2a$07$btCpyhVE2GmXNFIH/M5qru4B5kAHDdGsDFoP5JPKQe5gdNwYrMHGi</password>
<first_name>Antoine</first_name>
<last_name>Monnier</last_name>
<phone_number>0102030405</phone_number>
<street_number/>
<street_name/>
<address_extra/>
<delivery_zone/>
<city/>
<country>US</country>
<postal_code/>
<floor/>
<door/>
<building/>
<company_name>LivePepper</company_name>
<delivery_information/>
<locale>en-US</locale>
<created_at>2015-03-30T15:40:52Z</created_at>
<emailing_authorization>false</emailing_authorization>
<sms_authorization>false</sms_authorization>
<verification>U</verification>
<pos_code/>
<points_balance>10.0</points_balance>
<timezone>America/New_York</timezone>
<updated_at>2015-03-30T15:55:48Z</updated_at>
<link to="shop" href="https://posapi.livepepper.com/john-pizza"/>
</buyer>

Changing the status of an order

To update a resource, you simply send a PUT request to the resource URL—the request must contain the updated XML representation in the message body as well as an If-None-Match header with the value provided when you first performed the GET request (note that the double quotes surrounding the “etag_value” returned during the GET must be used within that header).

Typically you’ll accept an order by sending the “accepted” value in the message. Here we continue with our examples given above for order number 2293319:

PUT https://posapi.livepepper.com/john-pizza/orders/2293319

				
					<order>
<workflow_state>accepted</workflow_state>
</order>

You can also pass other elements inside this tag, such as:

confirmed_delivery_time – should be an ISO local time.
pos_code – a string reference, which can be set to any arbitrary value for tracking the order
seller_comment – a string that you want to include in the confirmation email that will be sent to the customer

General Store Information

To retrieve general information about the store through the API, use the store function (john-pizza) as follows:

GET https://posapi.livepepper.com/john-pizza

This is the response that you will receive:

				
					<shop uri="https://posapi.livepepper.com/john-pizza">
<short_name>john-pizza</short_name>
<name>John Pizza</name>
<phone>0102030405</phone>
<address>Colorado Avenue</address>
<city>Denver</city>
<country>US</country>
<postal_code>11111</postal_code>
<min_delivery_time>30</min_delivery_time>
<min_collection_time>20</min_collection_time>
<ordering_time_range_size>15</ordering_time_range_size>
<advanced_orders_days>0</advanced_orders_days>
<timezone>Eastern Time (US & Canada)</timezone>
<currency>USD</currency>
<creation of="buyer" href="https://posapi.livepepper.com/john-pizza/buyers"/>
<creation of="menu_upload" href-template="https://posapi.livepepper.com/john-pizza/menu_upload{?pos}"/>
<creation of="area_upload" href-template="https://posapi.livepepper.com/john-pizza/area_upload{?pos}"/>
<link to="products" href="https://posapi.livepepper.com/john-pizza/products"/>
<link to="product_groups" href="https://posapi.livepepper.com/john-pizza/product_groups"/>
<link to="main_taxonomy" href="https://posapi.livepepper.com/john-pizza/taxonomy"/>
<link to="new_orders" href="https://posapi.livepepper.com/john-pizza/new_orders"/>
<link to="orders" href-template="https://posapi.livepepper.com/john-pizza/orders{?before,after,pos_code}"/>
<link to="buyers" href-template="https://posapi.livepepper.com/john-pizza/buyers{?pos_code}"/>
<link to="postal_codes" href-template="https://posapi.livepepper.com/john-pizza/postal_codes{?pos_code}"/>
<link to="streets" href-template="https://posapi.livepepper.com/john-pizza/streets{?pos_code}"/>
</shop>

Update a Buyer Loyalty Balance

To update the loyalty balance for a buyer, send a PUT request to /store/buyers, including the new balance and an optional reason should be passed in the URL. In this example, the new balance is 10 and the reason given is “bonus”.

PUT https://posapi.livepepper.com/john-pizza/buyers/1054289/points_balance?new_balance=10&reason=bonus

The response will return the updated representation of the buyer.

Retrieve Product/Category Information

To retrieve the entire list of store product offerings, use the products function as follows:

GET https://posapi.livepepper.com/john-pizza/products

You’ll receive a response listing similar to the one below. This list will contain individual products—each of which you can retrieve individually with a GET.

				
					<products uri="https://posapi.livepepper.com/john-pizza/products">
<link to="product" href="https://posapi.livepepper.com/john-pizza/products/1522410"/>
<link to="product" href="https://posapi.livepepper.com/john-pizza/products/1522411"/>
</products>

Retrieving Postal Codes

If you have setup some postal codes in your administrative website, you can retrieve the entire list of postal codes by accessing the postal_codes resource:

GET https://posapi.livepepper.com/john-pizza/postal_codes

You’ll receive a response message similar to the one below. Then you need to follow each URL to retrieve the geographic data that corresponds to that postal code.

				
					<postal_codes uri="https://posapi.livepepper.com/john-pizza/postal_codes">
<link to="postal_code" href="https://posapi.livepepper.com/john-pizza/postal_codes/31932"/>
<link to="postal_code" href="https://posapi.livepepper.com/john-pizza/postal_codes/31933"/>
<link to="postal_code" href="https://posapi.livepepper.com/john-pizza/postal_codes/31934"/>
<link to="postal_code"
</postal_codes>

Retrieve Orders Matching a Condition

You can send query parameters to the orders resource to retrieve a filtered orders list.

To retrieve orders that match a specific POS code, access the orders resource as follows:

GET https://posapi.livepepper.com/john-pizza/orders?pos_code=xxx

It will retrieve a list of orders, and you can follow the link for each order to get those details (as we explain in Order Details).

To retrieve a list of orders placed between 13th Feb 2014 10am and 13th Feb 2014 8pm (UTC times), you could perform this request:

GET https://posapi.livepepper.com/john-pizza/orders after=20140213_10&before=20140213_20

Buyer Lookup

To lookup a buyer with an email address, use the buyers resource as we show in the example below. If there is a match, the list will contain a link to a single buyer; otherwise the list will be empty.

GET https://posapi.livepepper.com/john-pizza/buyers?email= joe@foocompany.com

Request Demo