Added checkout example

docs/source/usage/communicate_with_the_api.rst

@@ -83,8 +83,8 @@ You can fetch the detail of each product by following it's url:
 .. code-block:: python
 
     products = response.json()
-    # get the details of the first product
-    response = session.get(products[0]['url'])
+    # get the details of the second product
+    response = session.get(products[1]['url'])
     print(response.content)
     {
         "attributes": [
@@ -116,12 +116,11 @@ Ok, now we want to add this to our basket:
 .. code-block:: python
 
     data = {
-        "url": products[0]['url'],
+        "url": products[1]['url'],
         "quantity": 1
     }
 
-    response = session.post(
-        'http://localhost:8000/api/basket/add-product/', json=data)
+    response = session.post('http://localhost:8000/api/basket/add-product/', json=data)
 
 And we can see that it has been added:
 
@@ -145,10 +144,122 @@ And we can see that it has been added:
             "product": "http://localhost:8000/api/products/1/",
             "quantity": 1,
             "stockrecord": "http://localhost:8000/api/stockrecords/1/",
-            "url": "http://localhost:8000/api/lines/2/",
+            "url": "http://localhost:8000/api/lines/1/",
             "warning": null
         }
     ]
 
-.. attention::
-    Add a checkout example here
+
+Place an order (checkout)
+-------------------------
+
+When your basket is filled an you want to proceed to checkout you can do a single call with all information needed. Note that we are doing an anonymous checkout here, so we need to set the `guest_email` field. (Make sure that ``OSCAR_ALLOW_ANON_CHECKOUT`` is set to ``True`` in your ``settings.py``). If you don't support anonymous checkouts you will have to login the user first (see login example below).
+
+.. code-block:: python
+
+    guest_email = "foo@example.com"
+
+    # get our basket information
+    response = session.get('http://localhost:8000/api/basket/')
+    basket_data = response.json()
+
+    # oscar needs a country for the shipping address. You can get a list of
+    # the available countries with the api
+    response = session.get('http://localhost:8000/api/countries/')
+    countries = response.json()
+    print(countries)
+    [
+        {
+            "display_order": 0,
+            "is_shipping_country": true,
+            "iso_3166_1_a3": "NLD",
+            "iso_3166_1_numeric": "528",
+            "name": "Kingdom of the Netherlands",
+            "printable_name": "Netherlands",
+            "url": "http://127.0.0.1:8000/api/countries/NL/"
+        }
+    ]    
+
+    # we need the country url in the shipping address
+    country_url = countries[0]['url']
+
+    # let's fill out the request data
+    data = {
+        "basket": basket_data['url'],
+        "guest_email": guest_email,
+        "total": basket_data['total_incl_tax'],
+        "shipping_method_code": "no-shipping-required",
+        # the shipping charge is optional, but we leave it here for example purposes
+        "shipping_charge": {
+            "currency": basket_data['currency'],
+            "excl_tax": "0.0",
+            "tax": "0.0"
+        },
+        "shipping_address": {
+            "country": country_url,
+            "first_name": "Henk",
+            "last_name": "Van den Heuvel",
+            "line1": "Roemerlaan 44",
+            "line2": "",
+            "line3": "",
+            "line4": "Kroekingen",
+            "notes": "",
+            "phone_number": "+31 26 370 4887",
+            "postcode": "7777KK",
+            "state": "Gerendrecht",
+            "title": "Mr"
+        }
+    }
+
+    # now we can place the order
+    response = session.post('http://localhost:8000/api/checkout/', json=data)
+
+    # and the api should give us a response with all info needed
+    print (response.content)
+    {
+        "basket": "http://localhost:8000/api/baskets/1/",
+        "billing_address": null,
+        "currency": "EUR",
+        "date_placed": "2016-01-02T23:18:01.089796Z",
+        "guest_email": "foo@example.com",
+        "lines": "http://localhost:8000/api/orders/1/lines/",
+        # this is the order number generated in oscar
+        "number": "10001",
+        "offer_discounts": [],
+        "owner": null,
+        # the payment view is something you will have to implement yourself, 
+        # see the note below
+        "payment_url": "You need to implement a view named 'api-payment' which redirects to the payment provider and sets up the callbacks.",
+        "shipping_address": {
+            "country": "http://localhost:8000/api/countries/NL/",
+            "first_name": "Henk",
+            "id": 3,
+            "last_name": "Van den Heuvel",
+            "line1": "Roemerlaan 44",
+            "line2": "",
+            "line3": "",
+            "line4": "Kroekingen",
+            "notes": "",
+            "phone_number": "+31 26 370 4887",
+            "postcode": "7777KK",
+            "search_text": "Henk Van den Heuvel Roemerlaan 44 Kroekingen Gerendrecht 7777KK Kingdom of the Netherlands",
+            "state": "Gerendrecht",
+            "title": "Mr"
+        },
+        "shipping_code": "free-shipping",
+        "shipping_excl_tax": "0.00",
+        "shipping_incl_tax": "0.00",
+        "shipping_method": "Free shipping",
+        "status": "new",
+        "total_excl_tax": "10.00",
+        "total_incl_tax": "10.00",
+        # you can fetch the order details by getting this url
+        "url": "http://localhost:8000/api/orders/1/",
+        "voucher_discounts": []
+    }    
+
+.. note::
+    After you placed an order with the api, the basket is frozen. Oscar API has checks for this in the checkout view and won't let you checkout the same (or any frozen) basket again. At this stage an order is submitted in Oscar and you will have to implement the following steps regarding payment yourself. See also the ``payment_url`` field above in the response.
+
+.. caution::
+    Explain the payment_url a bit more and add a login example.