Steve-Dee-Designs
/
woocommerce
mirror of https://github.com/woocommerce/woocommerce.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add order and checkout order endpoint documentation (https://github.com/woocommerce/woocommerce-blocks/pull/11157) 

* Add order and checkout order endpoint documentation

* Update order and checkout order endpoint documentation

* Update cart endpoint doc
This commit is contained in:
Hsing-yu Flowers 2023-10-11 14:37:42 +08:00 committed by GitHub
parent e88fa94026
commit 748ecb0963
4 changed files with 443 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
plugins/woocommerce-blocks/src/StoreApi/README.md
View File

@ -66,7 +66,9 @@ Available resources in the Store API are listed below, with links to more detail
| | `GET`, `POST`, `PUT`, `DELETE` | [`/wc/store/v1/cart/items/:key`](docs/cart-items.md#single-cart-item) |
| [`Cart Coupons`](docs/cart-coupons.md) | `GET`, `POST`, `DELETE` | [`/wc/store/v1/cart/coupons`](docs/cart-coupons.md#list-cart-coupons) |
| | `GET`, `DELETE` | [`/wc/store/v1/cart/coupon/:code`](docs/cart-coupons.md#single-cart-coupon) |
| [`Checkout`](docs/checkout.md) | `GET`, `POST` | [`/wc/store/v1/checkout`](docs/checkout.md) |
| [`Checkout`](docs/checkout.md) | `GET`, `POST` | [`/wc/store/v1/checkout`](docs/checkout.md)
| [`Checkout order`](docs/checkout-order.md) | `POST` | [`/wc/store/v1/checkout/:id`](docs/checkout-order.md) |
| [`Order`](docs/order.md) | `GET` | [`/wc/store/v1/order/:id`](docs/order.md)
| [`Products`](docs/products.md) | `GET` | [`/wc/store/v1/products`](docs/products.md#list-products) |
| | `GET` | [`/wc/store/v1/products/:id`](docs/products.md#single-product) |
| [`Product Collection Data`](docs/product-collection-data.md) | `GET` | [`/wc/store/v1/products/collection-data`](docs/product-collection-data.md) |

32
plugins/woocommerce-blocks/src/StoreApi/docs/cart.md
View File

@ -2,10 +2,11 @@
## Table of Contents <!-- omit in toc -->
- [Get Cart](#get-cart)
- [Responses](#responses)
- [Cart Response](#cart-response)
- [Error Response](#error-response)
- [Get Cart](#get-cart)
- [Add Item](#add-item)
- [Remove Item](#remove-item)
- [Update Item](#update-item)
@ -18,6 +19,21 @@ The cart API returns the current state of the cart for the current session or lo
All POST endpoints require [Nonce Tokens](nonce-tokens.md) and return the updated state of the full cart once complete.
## Get Cart
```http
GET /cart
```
There are no parameters required for this endpoint.
```sh
curl "https://example-store.com/wp-json/wc/store/v1/cart"
```
Returns the full cart object response (see [Cart Response](#cart-response)).
## Responses
All endpoints under `/cart` (listed in this doc) return responses in the same format; a cart object which includes cart items, applied coupons, shipping addresses and rates, and non-sensitive customer data.
@ -378,20 +394,6 @@ Some error responses indicate conflicts (error 409), for example, when an item c
This allows the client to remain in sync with the cart data without additional requests, should the cart change or become outdated.
## Get Cart
```http
GET /cart
```
There are no parameters required for this endpoint.
```sh
curl "https://example-store.com/wp-json/wc/store/v1/cart"
```
Returns the full cart object response (see [Cart Response](#cart-response)).
## Add Item
Add an item to the cart and return the full cart response, or an error.

167
plugins/woocommerce-blocks/src/StoreApi/docs/checkout-order.md Normal file
View File

@ -0,0 +1,167 @@
# Checkout order API <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->
- [Process Order and Payment](#process-order-and-payment)
- [Payment Data](#payment-data)
The checkout order API facilitates the processing of existing orders and handling payments.
All checkout order endpoints require [Nonce Tokens](nonce-tokens.md).
## Process Order and Payment
Accepts the final chosen payment method, and any additional payment data, then attempts payment and
returns the result.
This endpoint will return an error unless a valid [Nonce Token](nonce-tokens.md) is provided.
```http
POST /wc/store/v1/checkout/{ORDER_ID}
```
| Attribute | Type | Required | Description |
| :----------------- | :----- | :------: | :------------------------------------------------------------------ |
| `key` | string | Yes | The key for the order verification. |
| `billing_email` | string | No | The email address used to verify guest orders. |
| `billing_address` | object | Yes | Object of updated billing address data for the customer. |
| `shipping_address` | object | Yes | Object of updated shipping address data for the customer. |
| `payment_method` | string | Yes | The ID of the payment method being used to process the payment. |
| `payment_data` | array | No | Data to pass through to the payment method when processing payment. |
```sh
curl --header "Nonce: 12345" --request POST https://example-store.com/wp-json/wc/store/v1/checkout/{ORDER_ID} -d '{"key":"wc_order_oFmQYREzh9Tfv","billing_email":"admin@example.com","payment_method":"cheque","billing_address":{...},"shipping_address":{...}'
```
**Example request:**
```json
{
"key": "wc_order_oFmQYREzh9Tfv",
"billing_email": "admin@example.com",
"billing_address": {
"first_name": "Peter",
"last_name": "Venkman",
"company": "",
"address_1": "550 Central Park West",
"address_2": "Corner Penthouse Spook Central",
"city": "New York",
"state": "NY",
"postcode": "10023",
"country": "US",
"email": "admin@example.com",
"phone": "555-2368"
},
"shipping_address": {
"first_name": "Peter",
"last_name": "Venkman",
"company": "",
"address_1": "550 Central Park West",
"address_2": "Corner Penthouse Spook Central",
"city": "New York",
"state": "NY",
"postcode": "10023",
"country": "US",
"phone": "555-2368"
},
"payment_method": "cheque",
"payment_data": []
}
```
**Example response:**
```json
{
"order_id": 146,
"status": "on-hold",
"order_key": "wc_order_oFmQYREzh9Tfv",
"customer_note": "",
"customer_id": 1,
"billing_address": {
"first_name": "Peter",
"last_name": "Venkman",
"company": "",
"address_1": "550 Central Park West",
"address_2": "Corner Penthouse Spook Central",
"city": "New York",
"state": "NY",
"postcode": "10023",
"country": "US",
"email": "admin@example.com",
"phone": "555-2368"
},
"shipping_address": {
"first_name": "Peter",
"last_name": "Venkman",
"company": "",
"address_1": "550 Central Park West",
"address_2": "Corner Penthouse Spook Central",
"city": "New York",
"state": "NY",
"postcode": "10023",
"country": "US",
"phone": "555-2368"
},
"payment_method": "cheque",
"payment_result": {
"payment_status": "success",
"payment_details": [],
"redirect_url": "https://local.wordpress.test/block-checkout/order-received/146/?key=wc_order_VPffqyvgWVqWL"
}
}
```
## Payment Data
There are many payment gateways available for merchants to use, and each one will be expecting different `payment_data`. We cannot comprehensively list all expected requests for all payment gateways, and we would recommend reaching out to the authors of the payment gateway plugins you're working with for further information.
An example of the payment data sent to the Checkout Order endpoint when using the [WooCommerce Stripe Payment Gateway](https://wordpress.org/plugins/woocommerce-gateway-stripe/) is shown below.
For further information on generating a `stripe_source` please check [the Stripe documentation](https://stripe.com/docs).
```json
{
"payment_data": [
{
"key": "stripe_source",
"value": "src_xxxxxxxxxxxxx"
},
{
"key": "billing_email",
"value": "myemail@email.com"
},
{
"key": "billing_first_name",
"value": "Jane"
},
{
"key": "billing_last_name",
"value": "Doe"
},
{
"key": "paymentMethod",
"value": "stripe"
},
{
"key": "paymentRequestType",
"value": "cc"
},
{
"key": "wc-stripe-new-payment-method",
"value": true
}
]
}
```
<!-- FEEDBACK -->
---
[We're hiring!](https://woocommerce.com/careers/) Come work with us!
🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./src/StoreApi/docs/checkout-order.md)
<!-- /FEEDBACK -->

256
plugins/woocommerce-blocks/src/StoreApi/docs/order.md Normal file
View File

@ -0,0 +1,256 @@
# Order API <!-- omit in toc -->
## Table of Contents <!-- omit in toc -->
- [Get Order](#get-order)
- [Responses](#responses)
- [Order Response](#order-response)
- [Error Response](#error-response)
The order API returns the pay-for-order order.
## Get Order
```http
GET /order/{ORDER_ID}?key={KEY}&billing_email={BILLING_EMAIL}
```
There is one required parameter for this endpoint which is `key`. `billing_email` must be added for guest orders.
```sh
curl "https://example-store.com/wp-json/wc/store/v1/order/{ORDER_ID}?key={KEY}&billing_email={BILLING_EMAIL}"
```
Returns the full order object response (see [Order Response](#order-response)).
## Responses
Order endpoints return responses in the same format as `/cart`; an order object which includes order items, applied coupons, shipping addresses and rates, and non-sensitive customer data.
### Order Response
```json
{
"id": 147,
"status": "pending",
"coupons": [
{
"code": "discount20",
"totals": {
"currency_code": "GBP",
"currency_symbol": "£",
"currency_minor_unit": 2,
"currency_decimal_separator": ".",
"currency_thousand_separator": ",",
"currency_prefix": "£",
"currency_suffix": "",
"total_discount": "421",
"total_discount_tax": "0"
}
}
],
"shipping_address": {
"first_name": "Peter",
"last_name": "Venkman",
"company": "",
"address_1": "550 Central Park West",
"address_2": "Corner Penthouse Spook Central",
"city": "New York",
"state": "NY",
"postcode": "10023",
"country": "US",
"phone": "555-2368"
},
"billing_address": {
"first_name": "Peter",
"last_name": "Venkman",
"company": "",
"address_1": "550 Central Park West",
"address_2": "Corner Penthouse Spook Central",
"city": "New York",
"state": "NY",
"postcode": "10023",
"country": "US",
"email": "admin@example.com",
"phone": "555-2368"
},
"items": [
{
"key": "9bf31c7ff062936a96d3c8bd1f8f2ff3",
"id": 15,
"quantity": 1,
"quantity_limits": {
"minimum": 1,
"maximum": 99,
"multiple_of": 1,
"editable": true
},
"name": "Beanie",
"short_description": "<p>This is a simple product.</p>",
"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>",
"sku": "woo-beanie",
"low_stock_remaining": null,
"backorders_allowed": false,
"show_backorder_badge": false,
"sold_individually": false,
"permalink": "https://local.wordpress.test/product/beanie/",
"images": [
{
"id": 44,
"src": "https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2.jpg",
"thumbnail": "https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-324x324.jpg",
"srcset": "https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2.jpg 801w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-324x324.jpg 324w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-100x100.jpg 100w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-416x416.jpg 416w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-300x300.jpg 300w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-150x150.jpg 150w, https://local.wordpress.test/wp-content/uploads/2020/03/beanie-2-768x768.jpg 768w",
"sizes": "(max-width: 801px) 100vw, 801px",
"name": "beanie-2.jpg",
"alt": ""
}
],
"variation": [],
"prices": {
"currency_code": "GBP",
"currency_symbol": "£",
"currency_minor_unit": 2,
"currency_decimal_separator": ".",
"currency_thousand_separator": ",",
"currency_prefix": "£",
"currency_suffix": "",
"price": "1000",
"regular_price": "2000",
"sale_price": "1000",
"price_range": null,
"raw_prices": {
"precision": 6,
"price": "10000000",
"regular_price": "20000000",
"sale_price": "10000000"
}
},
"item_data": [],
"totals": {
"currency_code": "GBP",
"currency_symbol": "£",
"currency_minor_unit": 2,
"currency_decimal_separator": ".",
"currency_thousand_separator": ",",
"currency_prefix": "£",
"currency_suffix": "",
"line_subtotal": "1000",
"line_subtotal_tax": "0",
"line_total": "800",
"line_total_tax": "0"
},
"catalog_visibility": "view"
},
{
"key": "e369853df766fa44e1ed0ff613f563bd",
"id": 34,
"quantity": 1,
"quantity_limits": {
"minimum": 1,
"maximum": 99,
"multiple_of": 1,
"editable": true
},
"name": "WordPress Pennant",
"short_description": "<p>This is an external product.</p>",
"description": "<p>Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat eleifend leo.</p>",
"sku": "wp-pennant",
"low_stock_remaining": null,
"backorders_allowed": false,
"show_backorder_badge": false,
"sold_individually": false,
"permalink": "https://local.wordpress.test/product/wordpress-pennant/",
"images": [
{
"id": 57,
"src": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1.jpg",
"thumbnail": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-324x324.jpg",
"srcset": "https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1.jpg 800w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-324x324.jpg 324w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-100x100.jpg 100w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-416x416.jpg 416w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-300x300.jpg 300w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-150x150.jpg 150w, https://local.wordpress.test/wp-content/uploads/2020/03/pennant-1-768x768.jpg 768w",
"sizes": "(max-width: 800px) 100vw, 800px",
"name": "pennant-1.jpg",
"alt": ""
}
],
"variation": [],
"prices": {
"currency_code": "GBP",
"currency_symbol": "£",
"currency_minor_unit": 2,
"currency_decimal_separator": ".",
"currency_thousand_separator": ",",
"currency_prefix": "£",
"currency_suffix": "",
"price": "1105",
"regular_price": "1105",
"sale_price": "1105",
"price_range": null,
"raw_prices": {
"precision": 6,
"price": "11050000",
"regular_price": "11050000",
"sale_price": "11050000"
}
},
"item_data": [],
"totals": {
"currency_code": "GBP",
"currency_symbol": "£",
"currency_minor_unit": 2,
"currency_decimal_separator": ".",
"currency_thousand_separator": ",",
"currency_prefix": "£",
"currency_suffix": "",
"line_subtotal": "1105",
"line_subtotal_tax": "0",
"line_total": "884",
"line_total_tax": "0"
},
"catalog_visibility": "view"
}
],
"needs_payment": true,
"needs_shipping": true,
"totals": {
"subtotal":"2105",
"total_discount": "421",
"total_shipping": "500",
"total_fees": "0",
"total_tax": "0",
"total_refund": "0",
"total_price": "2184",
"total_items": "2105",
"total_items_tax": "0",
"total_fees_tax": "0",
"total_discount_tax": "0",
"total_shipping_tax": "0",
"tax_lines": []
},
"errors": [],
"payment_requirements": [ "products" ],
}
```
### Error Response
If an order action cannot be performed, an error response will be returned. This will include a reason code and an error message:
```json
{
"code": "woocommerce_rest_invalid_order",
"message": "Invalid order ID or key provided.",
"data": {
"status": 401
}
}
```
<!-- FEEDBACK -->
---
[We're hiring!](https://woocommerce.com/careers/) Come work with us!
🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-blocks/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./src/StoreApi/docs/order.md)
<!-- /FEEDBACK -->