From 0fd9c4557eb84428606f814d4b0910411c0488ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz?= Date: Wed, 25 Jan 2017 11:47:46 +0100 Subject: [PATCH] [API] [Documentation] Cart api --- docs/api/carts.rst | 809 ++++++++++++++++++++++++++++++++++++++ docs/api/index.rst | 1 + docs/api/map.rst.inc | 1 + docs/api/orders.rst | 911 ++++++++++++++++++++----------------------- 4 files changed, 1238 insertions(+), 484 deletions(-) create mode 100644 docs/api/carts.rst diff --git a/docs/api/carts.rst b/docs/api/carts.rst new file mode 100644 index 00000000000..c5b772a9bc2 --- /dev/null +++ b/docs/api/carts.rst @@ -0,0 +1,809 @@ +Carts API +========= + +These endpoints will allow you to easily manage cart and cart items. Base URI is `/api/v1/carts/`. + +.. note:: + + If you still don't know the difference between Cart and Order concepts in Sylius, please read :doc:`this article ` carefully. + +Cart structure +-------------- + +Cart API response structure +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you request a cart, you will receive an object with the following fields: + ++-------------------+-------------------------------------------------------------------+ +| Field | Description | ++===================+===================================================================+ +| id | Id of cart | ++-------------------+-------------------------------------------------------------------+ +| items | List of items related to cart | ++-------------------+-------------------------------------------------------------------+ +| items_total | Sum of all items prices | ++-------------------+-------------------------------------------------------------------+ +| adjustments | List of adjustments related to cart | ++-------------------+-------------------------------------------------------------------+ +| adjustments_total | Sum of all order adjustments | ++-------------------+-------------------------------------------------------------------+ +| total | Sum of items total and adjustments total | ++-------------------+-------------------------------------------------------------------+ +| customer | :doc:`Customer detailed serialization ` for order | ++-------------------+-------------------------------------------------------------------+ +| channel | :doc:`Default channel serialization ` | ++-------------------+-------------------------------------------------------------------+ +| currency_code | Currency of the cart | ++-------------------+-------------------------------------------------------------------+ +| checkout_state | State of checkout process | ++-------------------+-------------------------------------------------------------------+ + +CartItem API response structure +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each cart item will be build as follows: + ++-------------------+------------------------------------------+ +| Field | Description | ++===================+==========================================+ +| id | Id of cart item | ++-------------------+------------------------------------------+ +| quantity | Quantity of item units | ++-------------------+------------------------------------------+ +| unit_price | Price of each item unit | ++-------------------+------------------------------------------+ +| total | Sum of units total and adjustments total | ++-------------------+------------------------------------------+ +| units | List of units related to cart | ++-------------------+------------------------------------------+ +| units_total | Sum of all units prices | ++-------------------+------------------------------------------+ +| adjustments | List of adjustments related to item | ++-------------------+------------------------------------------+ +| adjustments_total | Sum of all item adjustments | ++-------------------+------------------------------------------+ +| variant | Default variant serialization | ++-------------------+------------------------------------------+ + +CartItemUnit API response structure +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Each cart item unit will be build as follows: + ++-------------------+-------------------------------------+ +| Field | Description | ++===================+=====================================+ +| id | Id of cart item unit | ++-------------------+-------------------------------------+ +| adjustments | List of adjustments related to unit | ++-------------------+-------------------------------------+ +| adjustments_total | Sum of all units adjustments | ++-------------------+-------------------------------------+ + +Adjustment API response structure +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +And each adjustment will be build as follows: + ++--------+---------------------------------------------------------+ +| Field | Description | ++========+=========================================================+ +| id | Id of cart item unit | ++--------+---------------------------------------------------------+ +| type | Type of an adjustment (E.g. *order_promotion* or *tax*) | ++--------+---------------------------------------------------------+ +| label | Label of adjustment | ++--------+---------------------------------------------------------+ +| amount | Amount of adjustment | ++--------+---------------------------------------------------------+ + +.. note:: + + If it is still confusing to you, learn more about :doc:`Carts (Orders) ` and :doc:`Adjustments `. + +Creating a Cart +--------------- + +To create a new cart you will need to call the ``/api/v1/carts/`` endpoint with ``POST`` method. + +Definition +^^^^^^^^^^ + +.. code-block:: text + + POST /api/v1/carts/ + ++--------------------+----------------+----------------------------------------------------+ +| Parameter | Parameter type | Description | ++====================+================+====================================================+ +| Authorization | header | Token received during authentication | ++--------------------+----------------+----------------------------------------------------+ +| customer | request | Email of related customer | ++--------------------+----------------+----------------------------------------------------+ +| channel | request | Code of related channel | ++--------------------+----------------+----------------------------------------------------+ +| locale_code | request | Code of locale in which the cart should be created | ++--------------------+----------------+----------------------------------------------------+ +| criteria[customer] | query | Code of locale in which the cart should be created | ++--------------------+----------------+----------------------------------------------------+ + +Example +^^^^^^^ + +To create a new cart for the ``shop@example.com`` user in the ``US_WEB`` channel in the ``en_US`` locale use the below method. + +.. warning:: + + Remember, that it doesn't replicate the environment of shop usage. It is more like an admin part of cart creation, which will allow you to manage + cart from admin perspective. ShopAPI is still an experimental concept. + +.. code-block:: bash + + $ curl http://demo.sylius.org/api/v1/carts/ \ + -H "Authorization: Bearer SampleToken" \ + -H "Content-Type: application/json" \ + -X POST \ + --data ' + { + "customer": "shop@example.com", + "channel": "US_WEB", + "locale_code": "en_US" + } + ' + +Example Response +^^^^^^^^^^^^^^^^ + +.. code-block:: text + + STATUS: 201 Created + +.. code-block:: json + + { + "id":21, + "items":[ + + ], + "items_total":0, + "adjustments":[ + + ], + "adjustments_total":0, + "total":0, + "customer":{ + "id":1, + "email":"shop@example.com", + "first_name":"John", + "last_name":"Doe", + "user":{ + "id":1, + "username":"shop@example.com", + "username_canonical":"shop@example.com" + } + }, + "channel":{ + "code":"US_WEB", + "_links":{ + "self":{ + "href":"\/api\/v1\/channels\/1" + } + } + }, + "currency_code":"USD", + "checkout_state":"cart" + } + +.. note:: + + A currency code will be added automatically based on a channel settings. :doc:`Read more about channels ` + +.. warning:: + + If you try to create a resource without name or code, you will receive a 400 Bad Request error. + +Example +^^^^^^^ + +.. code-block:: bash + + $ curl http://demo.sylius.org/api/v1/carts/ \ + -H "Authorization: Bearer SampleToken" \ + -H "Accept: application/json" \ + -X POST + +Example Response +^^^^^^^^^^^^^^^^ + +.. code-block:: text + + STATUS: 400 Bad Request + +.. code-block:: json + + { + "code":400, + "message":"Validation Failed", + "errors":{ + "children":{ + "customer":{ + "errors":[ + "This value should not be blank." + ] + }, + "localeCode":{ + "errors":[ + "This value should not be blank." + ] + }, + "channel":{ + "errors":[ + "This value should not be blank." + ] + } + } + } + } + +Collection of Carts +------------------- + +To retrieve the paginated list of carts you will need to call the ``/api/v1/carts/`` endpoint with ``GET`` method. + +Definition +^^^^^^^^^^ + +.. code-block:: text + + GET /api/v1/carts/ + ++---------------+----------------+------------------------------------------------------------------+ +| Parameter | Parameter type | Description | ++===============+================+==================================================================+ +| Authorization | header | Token received during authentication | ++---------------+----------------+------------------------------------------------------------------+ +| page | query | *(optional)* Number of the page, by default = 1 | ++---------------+----------------+------------------------------------------------------------------+ +| limit | query | *(optional)* Number of carts displayed per page, by default = 10 | ++---------------+----------------+------------------------------------------------------------------+ + +Example +^^^^^^^ + +To see the first page of all carts use the method below. + +.. code-block:: bash + + $ curl http://demo.sylius.org/api/v1/carts/ \ + -H "Authorization: Bearer SampleToken" \ + -H "Accept: application/json" + +Example Response +^^^^^^^^^^^^^^^^ + +.. code-block:: text + + STATUS: 200 OK + +.. code-block:: json + + { + "page":1, + "limit":10, + "pages":1, + "total":1, + "_links":{ + "self":{ + "href":"\/api\/v1\/carts\/?page=1&limit=10" + }, + "first":{ + "href":"\/api\/v1\/carts\/?page=1&limit=10" + }, + "last":{ + "href":"\/api\/v1\/carts\/?page=1&limit=10" + } + }, + "_embedded":{ + "items":[ + { + "id":21, + "items":[ + + ], + "items_total":0, + "adjustments":[ + + ], + "adjustments_total":0, + "total":0, + "customer":{ + "id":1, + "email":"shop@example.com", + "first_name":"John", + "last_name":"Doe", + "user":{ + "id":1, + "username":"shop@example.com", + "enabled":true + } + }, + "channel":{ + "code":"US_WEB", + "_links":{ + "self":{ + "href":"\/api\/v1\/channels\/1" + } + } + }, + "currency_code":"USD", + "checkout_state":"cart" + } + ] + } + } + +Getting a Single Cart +--------------------- + +To retrieve the details of the cart you will need to call the ``/api/v1/carts/{id}`` endpoint with ``GET`` method. + +Definition +^^^^^^^^^^ + +.. code-block:: text + + GET /api/v1/carts/{id} + ++---------------+----------------+--------------------------------------+ +| Parameter | Parameter type | Description | ++===============+================+======================================+ +| Authorization | header | Token received during authentication | ++---------------+----------------+--------------------------------------+ +| id | url attribute | Id of requested resource | ++---------------+----------------+--------------------------------------+ + +Example +^^^^^^^ + +To see the details of the cart with id 21 use the method below. + +.. code-block:: bash + + $ curl http://demo.sylius.org/api/v1/carts/21 \ + -H "Authorization: Bearer SampleToken" \ + -H "Accept: application/json" + +.. note:: + + The value *21* was taken from create response. Your value can be different. Check list of all carts if you are not sure which id should be used. + +Example Response +^^^^^^^^^^^^^^^^ + +.. code-block:: text + + STATUS: 200 OK + +.. code-block:: json + + { + "id":21, + "items":[ + + ], + "items_total":0, + "adjustments":[ + + ], + "adjustments_total":0, + "total":0, + "customer":{ + "id":1, + "email":"shop@example.com", + "first_name":"John", + "last_name":"Doe", + "user":{ + "id":1, + "username":"shop@example.com", + "username_canonical":"shop@example.com" + } + }, + "channel":{ + "code":"US_WEB", + "_links":{ + "self":{ + "href":"\/api\/v1\/channels\/1" + } + } + }, + "currency_code":"USD", + "checkout_state":"cart" + } + +Deleting a Cart +--------------- + +To delete a cart you will need to call the ``/api/v1/carts/{id}`` endpoint with ``DELETE`` method. + +Definition +^^^^^^^^^^ + +.. code-block:: text + + DELETE /api/v1/carts/{id} + ++---------------+----------------+-------------------------------------------+ +| Parameter | Parameter type | Description | ++===============+================+===========================================+ +| Authorization | header | Token received during authentication | ++---------------+----------------+-------------------------------------------+ +| id | url attribute | Id of requested resource | ++---------------+----------------+-------------------------------------------+ + +Example +^^^^^^^ + +To delete the cart with id 21 use the method below. + +.. code-block:: bash + + $ curl http://demo.sylius.org/api/v1/carts/21 \ + -H "Authorization: Bearer SampleToken" \ + -H "Accept: application/json" \ + -X DELETE + +.. note:: + + Remember the *21* value from the previous example. Here we are deleting a previously fetch cart, so it is the same id. + +Example Response +^^^^^^^^^^^^^^^^ + +.. code-block:: text + + STATUS: 204 No Content + +Creating a Cart Item +-------------------- + +To add a new cart item to the existing cart you will need to call the ``/api/v1/carts/{cartId}/items/`` endpoint with ``POST`` method. + +Definition +^^^^^^^^^^ + +.. code-block:: text + + POST /api/v1/carts/{cartId}/items/ + ++---------------+----------------+---------------------------------------------------------------------+ +| Parameter | Parameter type | Description | ++===============+================+=====================================================================+ +| Authorization | header | Token received during authentication | ++---------------+----------------+---------------------------------------------------------------------+ +| cartId | url attribute | Id of requested cart | ++---------------+----------------+---------------------------------------------------------------------+ +| variant | request | Code of item you want to add to cart | ++---------------+----------------+---------------------------------------------------------------------+ +| quantity | request | Amount of variants you want to add to cart (cannot be lower than 1) | ++---------------+----------------+---------------------------------------------------------------------+ + +Example +^^^^^^^ + +To add a new item with one variant with code MEDIUM_MUG_CUP the cart with id 21(assume, that we didn't remove it in a previous example) use the method below. + +.. code-block:: bash + + $ curl http://demo.sylius.org/api/v1/carts/21/items/ \ + -H "Authorization: Bearer SampleToken" \ + -H "Content-Type: application/json" \ + -X POST \ + --data ' + { + "variant": "MEDIUM_MUG_CUP", + "quantity": 1 + } + ' + +Example Response +^^^^^^^^^^^^^^^^ + +.. code-block:: text + + STATUS: 201 Created + +.. code-block:: json + + { + "id":58, + "order":{ + "id":21, + "items":[ + + ], + "items_total":175, + "adjustments":[ + { + + } + ], + "adjustments_total":7515, + "total":7690, + "customer":{ + "id":1, + "email":"shop@example.com", + "first_name":"John", + "last_name":"Doe", + "user":{ + "id":1, + "username":"shop@example.com", + "username_canonical":"shop@example.com" + }, + "_links":{ + "self":{ + "href":"\/api\/v1\/customers\/1" + } + } + }, + "channel":{ + "code":"US_WEB", + "_links":{ + "self":{ + "href":"\/api\/v1\/channels\/2" + } + } + }, + "currency_code":"USD", + "checkout_state":"cart" + }, + "quantity":1, + "unit_price":175, + "total":175, + "units":[ + { + "id":194, + "adjustments":[ + + ], + "adjustments_total":0 + } + ], + "units_total":175, + "adjustments":[ + + ], + "adjustments_total":0, + "variant":{ + + }, + "_links":{ + "product":{ + "href":"\/api\/v1\/products\/21" + }, + "variant":{ + "href":"\/api\/v1\/products\/21\/variants\/61" + } + } + } + +.. tip:: + + In Sylius the prices are stored as an integers. So in order to present a proper amount to the end user, you should divide price by 100 by default + +Updating a Cart Item +-------------------- + +To change the quantity of cart item you will need to call the ``/api/v1/carts/{cartId}/items/{cartItemId}`` endpoint with ``PUT`` method. + +Definition +^^^^^^^^^^ + +.. code-block:: text + + PUT /api/v1/carts/{cartId}/items/{id} + ++---------------+----------------+---------------------------------------------------------------------+ +| Parameter | Parameter type | Description | ++===============+================+=====================================================================+ +| Authorization | header | Token received during authentication | ++---------------+----------------+---------------------------------------------------------------------+ +| cartId | url attribute | Id of requested cart | ++---------------+----------------+---------------------------------------------------------------------+ +| cartItemId | url attribute | Id of requested cart item | ++---------------+----------------+---------------------------------------------------------------------+ +| quantity | request | Amount of variants you want to add to cart (cannot be lower than 1) | ++---------------+----------------+---------------------------------------------------------------------+ + +Example +^^^^^^^ + +.. code-block:: bash + +To change a quantity to 3 of the cart item with id 58 of cart 21 use the method below. + + $ curl http://demo.sylius.org/api/v1/carts/21/items/58 \ + -H "Authorization: Bearer SampleToken" \ + -H "Content-Type: application/json" \ + -X PUT \ + --data '{"quantity": 3}' + +.. note:: + + If you are not sure where did the value 58 came from, check the previous response, and look for cart item id + +.. tip:: + + This action can be send with *PATCH* method as well + +Example Response +^^^^^^^^^^^^^^^^ + +.. code-block:: text + + STATUS: 204 No Content + +Now we can check what does the cart look like after changing quality + +.. code-block:: bash + + $ curl http://demo.sylius.org/api/v1/carts/21 \ + -H "Authorization: Bearer SampleToken" \ + -H "Accept: application/json" + +Example Response +^^^^^^^^^^^^^^^^ + +.. code-block:: text + + STATUS: 200 OK + +.. code-block:: json + + { + "id":21, + "items":[ + { + "id":58, + "quantity":3, + "unit_price":175, + "total":73, + "units":[ + { + "id":194, + "adjustments":[ + { + "id":215, + "type":"order_promotion", + "label":"Christmas", + "amount":-151 + } + ], + "adjustments_total":-151 + }, + { + "id":195, + "adjustments":[ + { + "id":216, + "type":"order_promotion", + "label":"Christmas", + "amount":-151 + } + ], + "adjustments_total":-151 + }, + { + "id":196, + "adjustments":[ + { + "id":217, + "type":"order_promotion", + "label":"Christmas", + "amount":-150 + } + ], + "adjustments_total":-150 + } + ], + "units_total":73, + "adjustments":[ + + ], + "adjustments_total":0, + "variant":{ + + }, + "_links":{ + "product":{ + "href":"\/api\/v1\/products\/21" + }, + "variant":{ + "href":"\/api\/v1\/products\/21\/variants\/61" + } + } + } + ], + "items_total":73, + "adjustments":[ + { + "id":218, + "type":"shipping", + "label":"UPS", + "amount":7515 + } + ], + "adjustments_total":7515, + "total":7588, + "customer":{ + "id":1, + "email":"shop@example.com", + "first_name":"John", + "last_name":"Doe", + "user":{ + "id":1, + "username":"shop@example.com", + "username_canonical":"shop@example.com" + }, + "_links":{ + "self":{ + "href":"\/api\/v1\/customers\/1" + } + } + }, + "channel":{ + "code":"US_WEB", + "_links":{ + "self":{ + "href":"\/api\/v1\/channels\/2" + } + } + }, + "currency_code":"USD", + "checkout_state":"cart" + } + +.. tip:: + + In this response you can see that promotion and shipping have been taken into account to calculate the appropriate price + +Deleting a Cart Item +-------------------- + +To delete the cart item you will need to call the ``/api/v1/carts/{cartId}/items/{cartItemId}`` endpoint with ``DELETE`` method. + +Definition +^^^^^^^^^^ + +.. code-block:: text + +To delete the cart item with id 58 of cart 21 use the method below. + + DELETE /api/v1/carts/{cartId}/items/{id} + ++---------------+----------------+--------------------------------------+ +| Parameter | Parameter type | Description | ++===============+================+======================================+ +| Authorization | header | Token received during authentication | ++---------------+----------------+--------------------------------------+ +| cartId | url attribute | Id of requested cart | ++---------------+----------------+--------------------------------------+ +| cartItemId | url attribute | Id of requested cart item | ++---------------+----------------+--------------------------------------+ + +Example +^^^^^^^ + +.. code-block:: bash + + $ curl http://demo.sylius.org/api/v1/carts/21/items/58 \ + -H "Authorization: Bearer SampleToken" \ + -H "Accept: application/json" \ + -X DELETE + +Example Response +^^^^^^^^^^^^^^^^ + +.. code-block:: text + + STATUS: 204 No Content diff --git a/docs/api/index.rst b/docs/api/index.rst index 40b020198de..bc8c03b7d86 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -7,6 +7,7 @@ The REST API Reference introduction authorization channels + carts orders checkouts products diff --git a/docs/api/map.rst.inc b/docs/api/map.rst.inc index 508336a66c3..eda46bde5c4 100644 --- a/docs/api/map.rst.inc +++ b/docs/api/map.rst.inc @@ -2,6 +2,7 @@ * :doc:`/api/authorization` * :doc:`/api/channels` * :doc:`/api/orders` +* :doc:`/api/carts` * :doc:`/api/checkouts` * :doc:`/api/products` * :doc:`/api/users` diff --git a/docs/api/orders.rst b/docs/api/orders.rst index 42740193a46..556c4a87941 100644 --- a/docs/api/orders.rst +++ b/docs/api/orders.rst @@ -3,165 +3,81 @@ Orders API Sylius orders API endpoint is `/api/v1/orders`. -Index of all orders -------------------- +If you request an order, you will receive an object with the following fields: + ++-----------------------+--------------------------------------------------------------------+ +| Field | Description | ++=======================+====================================================================+ +| id | Id of an order | ++-----------------------+--------------------------------------------------------------------+ +| items | List of items related to order | ++-----------------------+--------------------------------------------------------------------+ +| items_total | Sum of all items prices | ++-----------------------+--------------------------------------------------------------------+ +| adjustments | List of adjustments related to order | ++-----------------------+--------------------------------------------------------------------+ +| adjustments_total | Sum of all order adjustments | ++-----------------------+--------------------------------------------------------------------+ +| total | Sum of items total and adjustments total | ++-----------------------+--------------------------------------------------------------------+ +| customer | :doc:`Customer detailed serialization ` for order | ++-----------------------+--------------------------------------------------------------------+ +| channel | :doc:`Default channel serialization ` | ++-----------------------+--------------------------------------------------------------------+ +| currency_code | Currency of a order | ++-----------------------+--------------------------------------------------------------------+ +| checkout_state | :doc:`State of checkout process ` | ++-----------------------+--------------------------------------------------------------------+ +| state | :doc:`One of available order states ` | ++-----------------------+--------------------------------------------------------------------+ +| checkout_completed_at | Date when the checkout has been completed | ++-----------------------+--------------------------------------------------------------------+ +| number | Serial number of an order | ++-----------------------+--------------------------------------------------------------------+ +| shipping_address | Detailed address serialization | ++-----------------------+--------------------------------------------------------------------+ +| billing_address | Detailed address serialization | ++-----------------------+--------------------------------------------------------------------+ +| shipments | Detailed shipment serialization | ++-----------------------+--------------------------------------------------------------------+ +| payments | Detailed payment serialization | ++-----------------------+--------------------------------------------------------------------+ -You can retrieve the full list order by making the following request: - -.. code-block:: text - - GET /api/v1/orders/ - -Parameters -~~~~~~~~~~ - -page - Number of the page, by default = 1 -limit - Number of items to display per page +Getting a single order +---------------------- -Response -~~~~~~~~ +You can request detailed order information by executing the following request: -The response will contain the newly created order information. +Definition +^^^^^^^^^^ .. code-block:: text - STATUS: 200 OK + GET /api/v1/orders/{id} -.. code-block:: json - - { - "page":1, - "limit":10, - "pages":12, - "total":120, - "_links":{ - "self":{ - "href":"\/api\/orders\/?page=1" - }, - "first":{ - "href":"\/api\/orders\/?page=1" - }, - "last":{ - "href":"\/api\/orders\/?page=12" - }, - "next":{ - "href":"\/api\/orders\/?page=2" - } - }, - "_embedded":{ - "items":[ - { - "id":301, - "checkout_completed_at":"2014-11-26T23:00:33+0000", - "number":"000000048", - "items":[ - { - "id":1353, - "quantity":3, - "unit_price":9054, - "adjustments":[ ++---------------+----------------+--------------------------------------+ +| Parameter | Parameter type | Description | ++===============+================+======================================+ +| Authorization | header | Token received during authentication | ++---------------+----------------+--------------------------------------+ +| id | url attribute | Id of requested resource | ++---------------+----------------+--------------------------------------+ - ], - "adjustments_total":0, - "total":27162, - "immutable":false, - "variant":{ - "id":13099, - "object":{ - "id":2107, - "name":"T-Shirt \"voluptas\"", - "code": "T-SHIRT-VOLUPTAS", - "description":"Non molestias voluptas quae nemo omnis totam. Impedit ad perferendis quaerat sint numquam voluptate eum. Facilis sed accusamus enim repellendus officiis rerum at.", - "created_at":"2014-11-26T23:00:17+0000", - "updated_at":"2014-11-26T23:00:17+0000", - "short_description":"Quos in dignissimos in fugit culpa vitae." - }, - "created_at":"2014-11-26T23:00:17+0000", - "updated_at":"2014-11-26T23:00:34+0000", - "available_on":"2013-12-10T09:16:56+0000", - "sku":"8808" - }, - "inventory_units":[ - ], - "_links":{ - "product":{ - "href":"\/api\/products\/2107" - }, - "variant":{ - "href":"\/api\/products\/2107\/variants\/13099" - } - } - } - ], - "items_total":97783, - "adjustments":[ - ], - "comments":[ - - ], - "adjustments_total":24240, - "total":122023, - "confirmed":true, - "created_at":"2014-04-30T10:41:14+0000", - "updated_at":"2014-11-26T23:00:34+0000", - "state":"pending", - "email":"ygrant@example.com", - "expires_at":"2014-11-27T02:00:33+0000", - "user":{ - "id":476, - "username":"ygrant@example.com", - "username_canonical":"ygrant@example.com", - "email":"ygrant@example.com", - "email_canonical":"ygrant@example.com", - "enabled":false, - "group":[ - - ], - "locked":false, - "expired":false, - "roles":[ - - ], - "credentials_expired":false - }, - "channel":{ - "id":91, - "code":"WEB-UK", - "name":"UK Webstore", - "type":"web", - "color":"Red", - "enabled":true, - "created_at":"2014-11-26T23:00:15+0000", - "updated_at":"2014-11-26T23:00:15+0000", - }, - "shipping_address":{ - }, - "billing_address":{ - }, - "payments":[ - ], - "shipments":[ - ], - "currency":"GBP", - "checkout_state":"cart" - } - ] - } - } +Example +^^^^^^^ -Getting a single order ----------------------- +.. code-block:: bash -You can view a single order by executing the following request: + $ curl http://demo.sylius.org/api/v1/orders/21 \ + -H "Authorization: Bearer SampleToken" \ + -H "Accept: application/json" -.. code-block:: text +.. note:: - GET /api/v1/orders/24/ + The value *21* was taken from previous responses, where we managed a cart. Your value can be different. If you need more information about cart api please, check :doc:`this doc ` -Response -~~~~~~~~ +Example Response +~~~~~~~~~~~~~~~~ .. code-block:: text @@ -170,403 +86,430 @@ Response .. code-block:: json { - "id":301, - "checkout_completed_at":"2014-11-26T23:00:33+0000", - "number":"000000048", + "id":21, + "checkout_completed_at":"2017-01-27T16:15:08+0100", + "number":"000000020", "items":[ { - "id":1353, + "id":54, "quantity":3, - "unit_price":9054, + "unit_price":70, + "total":198, + "units":[ + { + "id":166, + "adjustments":[ + { + "id":139, + "type":"order_promotion", + "label":"Christmas", + "amount":-4 + } + ], + "adjustments_total":-4, + "_links":{ + "order":{ + "href":"\/api\/v1\/orders\/21" + } + } + }, + { + "id":167, + "adjustments":[ + { + "id":140, + "type":"order_promotion", + "label":"Christmas", + "amount":-4 + } + ], + "adjustments_total":-4, + "_links":{ + "order":{ + "href":"\/api\/v1\/orders\/21" + } + } + }, + { + "id":168, + "adjustments":[ + { + "id":141, + "type":"order_promotion", + "label":"Christmas", + "amount":-4 + } + ], + "adjustments_total":-4, + "_links":{ + "order":{ + "href":"\/api\/v1\/orders\/21" + } + } + } + ], + "units_total":198, "adjustments":[ ], "adjustments_total":0, - "total":27162, - "immutable":false, "variant":{ - "id":13099, - "object":{ - "id":2107, - "name":"T-Shirt \"voluptas\"", - "code": "T-SHIRT-VOLUPTAS" - "description":"Non molestias voluptas quae nemo omnis totam. Impedit ad perferendis quaerat sint numquam voluptate eum. Facilis sed accusamus enim repellendus officiis rerum at.", - "created_at":"2014-11-26T23:00:17+0000", - "updated_at":"2014-11-26T23:00:17+0000", - "short_description":"Quos in dignissimos in fugit culpa vitae." + "id":37, + "on_hold":0, + "tracked":false + }, + "_links":{ + "product":{ + "href":"\/api\/v1\/products\/13" }, - "created_at":"2014-11-26T23:00:17+0000", - "updated_at":"2014-11-26T23:00:34+0000", - "available_on":"2013-12-10T09:16:56+0000", - "sku":"8808" + "variant":{ + "href":"\/api\/v1\/products\/13\/variants\/37" + } + } + }, + { + "id":55, + "quantity":1, + "unit_price":818, + "total":769, + "units":[ + { + "id":169, + "adjustments":[ + { + "id":142, + "type":"order_promotion", + "label":"Christmas", + "amount":-49 + } + ], + "adjustments_total":-49, + "_links":{ + "order":{ + "href":"\/api\/v1\/orders\/21" + } + } + } + ], + "units_total":769, + "adjustments":[ + + ], + "adjustments_total":0, + "variant":{ + "id":289, + "on_hold":0, + "tracked":false }, - "inventory_units":[ + "_links":{ + "product":{ + "href":"\/api\/v1\/products\/58" + }, + "variant":{ + "href":"\/api\/v1\/products\/58\/variants\/289" + } + } + }, + { + "id":56, + "quantity":2, + "unit_price":338, + "total":635, + "units":[ { - "id":4061, - "inventory_state":"onhold", - "created_at":"2014-11-26T23:00:34+0000", - "updated_at":"2014-11-26T23:00:34+0000", + "id":170, + "adjustments":[ + { + "id":143, + "type":"order_promotion", + "label":"Christmas", + "amount":-21 + } + ], + "adjustments_total":-21, "_links":{ "order":{ - "href":"\/app_dev.php\/api\/orders\/301" + "href":"\/api\/v1\/orders\/21" } } }, { - "id":4062, - "inventory_state":"onhold", - "created_at":"2014-11-26T23:00:34+0000", - "updated_at":"2014-11-26T23:00:34+0000", + "id":171, + "adjustments":[ + { + "id":144, + "type":"order_promotion", + "label":"Christmas", + "amount":-20 + } + ], + "adjustments_total":-20, "_links":{ "order":{ - "href":"\/app_dev.php\/api\/orders\/301" + "href":"\/api\/v1\/orders\/21" + } + } + } + ], + "units_total":635, + "adjustments":[ + + ], + "adjustments_total":0, + "variant":{ + "id":12, + "on_hold":0, + "tracked":false + }, + "_links":{ + "product":{ + "href":"\/api\/v1\/products\/4" + }, + "variant":{ + "href":"\/api\/v1\/products\/4\/variants\/12" + } + } + }, + { + "id":57, + "quantity":3, + "unit_price":520, + "total":1466, + "units":[ + { + "id":172, + "adjustments":[ + { + "id":145, + "type":"order_promotion", + "label":"Christmas", + "amount":-32 + } + ], + "adjustments_total":-32, + "_links":{ + "order":{ + "href":"\/api\/v1\/orders\/21" } } }, { - "id":4063, - "inventory_state":"onhold", - "created_at":"2014-11-26T23:00:34+0000", - "updated_at":"2014-11-26T23:00:34+0000", + "id":173, + "adjustments":[ + { + "id":146, + "type":"order_promotion", + "label":"Christmas", + "amount":-31 + } + ], + "adjustments_total":-31, "_links":{ "order":{ - "href":"\/app_dev.php\/api\/orders\/301" + "href":"\/api\/v1\/orders\/21" + } + } + }, + { + "id":174, + "adjustments":[ + { + "id":147, + "type":"order_promotion", + "label":"Christmas", + "amount":-31 + } + ], + "adjustments_total":-31, + "_links":{ + "order":{ + "href":"\/api\/v1\/orders\/21" } } } ], + "units_total":1466, + "adjustments":[ + + ], + "adjustments_total":0, + "variant":{ + "id":56, + "on_hold":0, + "tracked":false + }, "_links":{ "product":{ - "href":"\/app_dev.php\/api\/products\/2107" + "href":"\/api\/v1\/products\/19" }, "variant":{ - "href":"\/app_dev.php\/api\/products\/2107\/variants\/13099" + "href":"\/api\/v1\/products\/19\/variants\/56" } } } ], - "items_total":97783, + "items_total":3068, "adjustments":[ { - "id":1011, - "type":"tax", - "description":"EU VAT (23%)", - "amount":22490, - "neutral":false, - "locked":false, - "created_at":"2014-11-26T23:00:33+0000", - "updated_at":"2014-11-26T23:00:34+0000" - }, - { - "id":1012, + "id":148, "type":"shipping", - "description":"UPS Ground", - "amount":2500, - "neutral":false, - "locked":false, - "created_at":"2014-11-26T23:00:33+0000", - "updated_at":"2014-11-26T23:00:34+0000" - }, - { - "id":1013, - "type":"promotion", - "description":"New Year Sale for 3 and more items.", - "amount":-500, - "neutral":false, - "locked":false, - "created_at":"2014-11-26T23:00:33+0000", - "updated_at":"2014-11-26T23:00:34+0000" - }, - { - "id":1014, - "type":"promotion", - "description":"Christmas Sale for orders over 100 EUR.", - "amount":-250, - "neutral":false, - "locked":false, - "created_at":"2014-11-26T23:00:33+0000", - "updated_at":"2014-11-26T23:00:34+0000" + "label":"DHL Express", + "amount":2160 } ], - "comments":[ - - ], - "adjustments_total":24240, - "total":122023, - "confirmed":true, - "created_at":"2014-04-30T10:41:14+0000", - "updated_at":"2014-11-26T23:00:34+0000", - "state":"pending", - "email":"ygrant@example.com", - "expires_at":"2014-11-27T02:00:33+0000", - "user":{ - "id":476, - "username":"ygrant@example.com", - "username_canonical":"ygrant@example.com", - "email":"ygrant@example.com", - "email_canonical":"ygrant@example.com", - "enabled":false, - "group":[ - - ], - "locked":false, - "expired":false, - "roles":[ - - ], - "credentials_expired":false + "adjustments_total":2160, + "total":5228, + "state":"new", + "customer":{ + "id":8, + "email":"eturner@senger.com", + "email_canonical":"eturner@senger.com", + "first_name":"Ricky", + "last_name":"Swift", + "gender":"u", + "user":{ + "id":8, + "username":"eturner@senger.com", + "username_canonical":"eturner@senger.com", + "roles":[ + "ROLE_USER" + ], + "enabled":true + }, + "_links":{ + "self":{ + "href":"\/api\/v1\/customers\/8" + } + } }, "channel":{ - "id":91, - "code":"WEB-UK", - "name":"UK Webstore", - "type":"web", - "color":"Red", + "id":1, + "code":"US_WEB", + "name":"US Web Store", + "hostname":"localhost:8000", + "color":"MediumSpringGreen", + "created_at":"2017-01-27T16:15:02+0100", + "updated_at":"2017-01-27T16:15:02+0100", "enabled":true, - "created_at":"2014-11-26T23:00:15+0000", - "updated_at":"2014-11-26T23:00:15+0000", + "tax_calculation_strategy":"order_items_based", + "_links":{ + "self":{ + "href":"\/api\/v1\/channels\/1" + } + } }, "shipping_address":{ + "id":58, + "first_name":"Mittie", + "last_name":"Schoen", + "country_code":"US", + "street":"Gutmann Parkways", + "city":"West Devonte", + "postcode":"68192-0107", + "created_at":"2017-01-27T16:15:08+0100", + "updated_at":"2017-01-27T16:15:08+0100" }, "billing_address":{ + "id":59, + "first_name":"Mittie", + "last_name":"Schoen", + "country_code":"US", + "street":"Gutmann Parkways", + "city":"West Devonte", + "postcode":"68192-0107", + "created_at":"2017-01-27T16:15:08+0100", + "updated_at":"2017-01-27T16:15:08+0100" }, "payments":[ - ], - "shipments":[ - ], - "currency":"GBP", - "checkout_state":"cart" - } - -Create an order ---------------- - -To create a new order (cart), you need to execute the following request: - -.. code-block:: text - - POST /api/v1/orders/ - -Parameters -~~~~~~~~~~ - -channel - Channel code (e.g. "US_WEB") -customer *(optional)* - The id of customer -localeCode - Locale code (e.g. "en_US") - -Response -~~~~~~~~ - -.. code-block:: text - - STATUS: 201 CREATED - -.. code-block:: json - - { - "id":304, - "items":[ - ], - "items_total":0, - "adjustments":[ - ], - "comments":[ - - ], - "adjustments_total":0, - "total":0, - "confirmed":true, - "created_at":"2014-11-29T12:29:07+0000", - "updated_at":"2014-11-29T12:29:08+0000", - "state":"cart", - "email":"chelsie.witting@example.com", - "expires_at":"2014-11-29T15:29:07+0000", - "user":{ - "id":481, - "username":"chelsie.witting@example.com", - "username_canonical":"chelsie.witting@example.com", - "email":"chelsie.witting@example.com", - "email_canonical":"chelsie.witting@example.com", - "enabled":true, - "group":[ - - ], - "locked":false, - "expired":false, - "roles":[ - - ], - "credentials_expired":false - }, - "channel":{ - "id":91, - "code":"WEB-UK", - "name":"UK Webstore", - "type":"web", - "color":"Red", - "enabled":true, - "created_at":"2014-11-26T23:00:15+0000", - "updated_at":"2014-11-26T23:00:15+0000", - }, - "payments":[ - ], - "shipments":[ - ], - "currency":"USD", - "checkout_state":"cart" - } - -Deleting a single order ------------------------ - -You can delete (soft) an order from the system by making the following DELETE call: - -.. code-block:: text - - DELETE /api/v1/orders/24 - -Response -~~~~~~~~ - -.. code-block:: text - - STATUS: 204 NO CONTENT - -Add an item to order --------------------- - -To add an item to order, you simply need to do a POST request: - -.. code-block:: text - - POST /api/v1/orders/305/items/ - -Parameters -~~~~~~~~~~ - -variant - The id of product variant -unit_price - Unit price of the item -quantity - Desired quantity - -Response -~~~~~~~~ - -Response will contain a representation of the newly created item. - -.. code-block:: text - - STATUS: 201 CREATED - -.. code-block:: json - - { - "_links": { - "product": { - "href": "/app_dev.php/api/v1/products/101" - }, - "variant": { - "href": "/app_dev.php/api/v1/products/101/variants/779" - } - }, - "adjustments": [], - "adjustments_total": 0, - "id": 277, - "immutable": false, - "inventory_units": [ { - "_links": { - "order": { - "href": "/app_dev.php/api/v1/orders/52" + "id":20, + "method":{ + "id":1, + "code":"cash_on_delivery", + "created_at":"2017-01-27T16:15:02+0100", + "updated_at":"2017-01-27T16:15:02+0100", + "channels":[ + { + "id":1, + "code":"US_WEB", + "name":"US Web Store", + "hostname":"localhost:8000", + "color":"MediumSpringGreen", + "created_at":"2017-01-27T16:15:02+0100", + "updated_at":"2017-01-27T16:15:02+0100", + "enabled":true, + "tax_calculation_strategy":"order_items_based", + "_links":{ + "self":{ + "href":"\/api\/v1\/channels\/1" + } + } + } + ], + "_links":{ + "self":{ + "href":"\/api\/v1\/payment-methods\/1" + } } }, - "created_at": "2014-12-15T13:18:48+0000", - "id": 828, - "inventory_state": "checkout", - "updated_at": "2014-12-15T13:18:48+0000" - }, - { - "_links": { - "order": { - "href": "/app_dev.php/api/v1/orders/52" + "amount":5228, + "state":"new", + "created_at":"2017-01-27T16:15:08+0100", + "updated_at":"2017-01-27T16:15:08+0100", + "_links":{ + "self":{ + "href":"\/api\/v1\/payments\/20" + }, + "payment-method":{ + "href":"\/api\/v1\/payment-methods\/1" + }, + "order":{ + "href":"\/api\/v1\/orders\/21" } - }, - "created_at": "2014-12-15T13:18:48+0000", - "id": 829, - "inventory_state": "checkout", - "updated_at": "2014-12-15T13:18:48+0000" - }, + } + } + ], + "shipments":[ { - "_links": { - "order": { - "href": "/app_dev.php/api/v1/orders/52" + "id":20, + "state":"ready", + "method":{ + "id":2, + "code":"dhl_express", + "category_requirement":1, + "calculator":"flat_rate", + "configuration":{ + "US_WEB":{ + "amount":2160 + } + }, + "created_at":"2017-01-27T16:15:02+0100", + "updated_at":"2017-01-27T16:15:02+0100", + "enabled":true, + "_links":{ + "self":{ + "href":"\/api\/v1\/shipping-methods\/dhl_express" + }, + "zone":{ + "href":"\/api\/v1\/zones\/US" + } } }, - "created_at": "2014-12-15T13:18:48+0000", - "id": 830, - "inventory_state": "checkout", - "updated_at": "2014-12-15T13:18:48+0000" - } - ], - "quantity": 3, - "total": 0, - "unit_price": 500000, - "variant": { - "available_on": "2014-04-01T06:43:02+0000", - "created_at": "2014-12-03T09:54:35+0000", - "id": 779, - "object": { - "attributes": [ - { - "id": 238, - "name": "Book author", - "presentation": "Author", - "value": "Marlen Yost" + "created_at":"2017-01-27T16:15:08+0100", + "updated_at":"2017-01-27T16:15:08+0100", + "_links":{ + "self":{ + "href":"\/api\/v1\/shipments\/20" }, - { - "id": 239, - "name": "Book ISBN", - "presentation": "ISBN", - "value": "326ccbc7-92d1-3aec-b3af-df8afdc5651d" + "method":{ + "href":"\/api\/v1\/shipping-methods\/dhl_express" }, - { - "id": 240, - "name": "Book pages", - "presentation": "Number of pages", - "value": "149" + "order":{ + "href":"\/api\/v1\/orders\/21" } - ], - "created_at": "2014-12-03T09:54:35+0000", - "description": "Et eveniet voluptas ut magni vero temporibus nihil. Omnis possimus accusantium quia corporis culpa. Et recusandae asperiores qui architecto culpa autem sint accusantium. Officiis iusto accusantium perferendis aliquid ducimus.", - "id": 101, - "name": "Book \"Quidem\" by \"Marlen Yost\"", - "options": [], - "short_description": "Distinctio quos est eaque fugit totam repellendus.", - "updated_at": "2014-12-03T09:54:35+0000" - }, - "options": [], - "sku": "326ccbc7-92d1-3aec-b3af-df8afdc5651d", - "updated_at": "2014-12-03T09:54:35+0000" - } + } + } + ], + "currency_code":"USD", + "checkout_state":"completed" } - -Removing an item from order ---------------------------- - -To remove an item from order, you can simply call a DELETE on its url. - -.. code-block:: text - - DELETE /api/v1/orders/49/items/245 - -Response -~~~~~~~~ - -.. code-block:: text - - STATUS: 204 NO CONTENT