From e995ee387df2af83a272dde33315dd7d04be9197 Mon Sep 17 00:00:00 2001 From: Brent MacKinnon Date: Fri, 19 Jan 2024 17:56:19 -0400 Subject: [PATCH] Atomizing and tagging Endpoint documentation (#43833) * Atomizing and taggig Endpoint documentation * Create manifest.json * regenerating manifest * fix manifest --------- Co-authored-by: Jacklyn Biggin --- docs/docs-manifest.json | 41 +++++++--- .../customizing-endpoint-urls.md | 79 +++++++++++++++++++ .../troubleshooting-endpoints.md | 49 ++++++++++++ docs/getting-started/woocommerce-endpoints.md | 76 ++---------------- 4 files changed, 163 insertions(+), 82 deletions(-) create mode 100644 docs/getting-started/customizing-endpoint-urls.md create mode 100644 docs/getting-started/troubleshooting-endpoints.md diff --git a/docs/docs-manifest.json b/docs/docs-manifest.json index 5a8598e840c..cf4843571c3 100644 --- a/docs/docs-manifest.json +++ b/docs/docs-manifest.json @@ -154,7 +154,7 @@ "menu_title": "WooCommerce Git flow", "tags": "reference", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/contributing/woocommerce-git-flow.md", - "hash": "05a314c4fd40a46c81baa32b2c1307bcc8a232e72e3c7d405622befb907c0d75", + "hash": "6395c1af4edfa153b0d51b755075eb76f2ce3b2e055032b217c2cb9fe5d23c94", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/contributing/woocommerce-git-flow.md", "id": "9e5c2da0c341b88f32483ec2435740cd16d48676" }, @@ -258,7 +258,7 @@ "post_title": "Contributing Technical Documentation", "menu_title": "Contributing Docs", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/contributing-docs/contributing-docs.md", - "hash": "08c51b50b47987639aa1df68563748a001435404411780517667057dfca984db", + "hash": "dc0db6128b5a934f54bde3d6bd568c95c9472292c41ea0417c59207ff4f198ce", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/contributing-docs/contributing-docs.md", "id": "71c1a72bfd4d5ae6aa656d4264b1bf3beb6eca1c" } @@ -437,12 +437,22 @@ "category_title": "Getting Started", "posts": [ { - "post_title": "WooCommerce Endpoints", + "post_title": "Understanding WooCommerce Endpoints", + "menu_title": "WooCommerce Endpoints", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/getting-started/woocommerce-endpoints.md", - "hash": "4cff74381eeda1cd75bab699faa271c57852a1931c98b8acaa9417747f0de040", + "hash": "1c4bb0a46074017669b2c51e126345c2688d14a4b922b641e9f2c64c4538ea31", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/getting-started/woocommerce-endpoints.md", "id": "31a11f74bcd9f21f97cd4c6c719240b3d84e40f4" }, + { + "post_title": "Troubleshooting WooCommerce Endpoints", + "menu_title": "Troubleshooting Endpoints", + "tags": "how-to", + "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/getting-started/troubleshooting-endpoints.md", + "hash": "afbc874ab03b5ca1d2728cddd688035321effcbfdf5fa7a541e1a423e049ab20", + "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/getting-started/troubleshooting-endpoints.md", + "id": "dff57bd736ae83850bfc7e4ac994bd22141d96ee" + }, { "post_title": "Setting up your development environment", "menu_title": "Development environment setup", @@ -477,6 +487,15 @@ "hash": "cb7be473c9f814b6c60e72578b7c2d4ef052ef859f5a3f48d37cdabd0d3fd114", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/getting-started/debugging.md", "id": "75c020ee52329c09f4dc04e33dc8aeb11c088534" + }, + { + "post_title": "Customizing WooCommerce Endpoint URLs", + "menu_title": "Customizing Endpoint URLs", + "tags": "how-to", + "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/getting-started/customizing-endpoint-urls.md", + "hash": "74c1d648c57acb4ebd9d82c9ca036edf08b8af52608f3dae2c81def1c50cd4f4", + "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/getting-started/customizing-endpoint-urls.md", + "id": "c19e1b1da6543f8a95ee04ba120f4f171f8e6e40" } ], "categories": [] @@ -525,7 +544,7 @@ "menu_title": "Payment Token API", "tags": "reference", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/payments/payment-token-api.md", - "hash": "4836db96fba51c51e4fd28c2a9c4f8544fe32f3508226d5c02443a2cc2c09140", + "hash": "441908f0678b9ff90f33adc3831ac75a5c49038a0b068dfc41456c232a851c7d", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/payments/payment-token-api.md", "id": "5f345b53875981703d4b80e8d04eae2daafe4c81" }, @@ -533,7 +552,7 @@ "post_title": "WooCommerce payment gateway plugin base", "tags": "code-snippet", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/payments/payment-gateway-plugin-base.md", - "hash": "9a77f78360de83bf0d13316fb064087472e4da5e34e57fd8891ea3f8fb1ac598", + "hash": "707cf9e5386c1d66fc84d6fc09fb0b0f2f3ed8c20376a66b3e0fa7b0802a363a", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/payments/payment-gateway-plugin-base.md", "id": "1934a5305524d7111a91f1e52a7495cf126f33f2" }, @@ -542,7 +561,7 @@ "menu_title": "Payment Gateway API", "tags": "reference", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/payments/payment-gateway-api.md", - "hash": "1b73bbacdac68afedceb7d578b0ec86a85ad866d1e1201b6a2a8ce0b01a8cb3b", + "hash": "b1661642abe47dffb015f9e9d7f625a1df60f27a4f364df2610d24c3e6c77439", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/payments/payment-gateway-api.md", "id": "b337203996650b567f91c70306e1010d6f1ae552" } @@ -742,7 +761,7 @@ "menu_title": "Shipping method API", "tags": "reference", "edit_url": "https://github.com/woocommerce/woocommerce/edit/trunk/docs/shipping/shipping-method-api.md", - "hash": "32214d4a7c3ca6f813aa967150593e0e6c765ddbfd2b10483fa8fcdf72f7fab0", + "hash": "9a417b9e722ca819f860cedd25c4139bd67bdae39d10d9701ada93ed66c6bf6c", "url": "https://raw.githubusercontent.com/woocommerce/woocommerce/trunk/docs/shipping/shipping-method-api.md", "id": "70270a01c8f1f2b630c809c0b9611940e99293a9" } @@ -898,7 +917,7 @@ "categories": [] }, { - "content": "\nWhen building payments extensions, you should ensure you follow the [WooCommerce Extension Guidelines](./user-experience-guidelines).\n\nPayments plugins come in many types: payment processors and gateways, wallets, Buy Now Pay Later, crypto, and more.\n\nThe choice between payment plugins depends on the specific needs and preferences of the merchant and their customers. Some merchants may choose to use multiple types of payment plugins to offer their customers a wider range of payment options.\n\nA merchant can discover a payments plugin in the following ways:\n\n- Through direct installation from WordPress plugins.\n- Through Woo’s public list of payment services on the Marketplace.\n- Through the admin onboarding tasks and payments settings. To be added to the list of payment gateways in the Woo admin, the payments plugin must meet the criteria listed in these guidelines.\n\n", + "content": "\nWhen building payments extensions, you should ensure you follow the [WooCommerce Extension Guidelines](./user-experience-guidelines).\n\nPayments plugins come in many types: payment processors and gateways, wallets, Buy Now Pay Later, crypto, and more.\n\nThe choice between payment plugins depends on the specific needs and preferences of the merchant and their customers. Some merchants may choose to use multiple types of payment plugins to offer their customers a wider range of payment options.\n\nA merchant can discover a payments plugin in the following ways:\n\n- Through direct installation from WordPress plugins.\n- Through Woo's public list of payment services on the Marketplace.\n- Through the admin onboarding tasks and payments settings. To be added to the list of payment gateways in the Woo admin, the payments plugin must meet the criteria listed in these guidelines.\n\n", "category_slug": "user-experience-payments", "category_title": "Payments Guidelines", "posts": [ @@ -1059,7 +1078,7 @@ "categories": [] }, { - "content": "\nWooCommerce CLI (WC-CLI) offers the ability to manage WooCommerce (WC) via the command-line, using WP CLI. The documentation here covers the version of WC CLI that started shipping in WC 3.0.0 and later.\n\nWC CLI is powered by the [WC REST API](https://woocommerce.github.io/woocommerce-rest-api-docs/), meaning most of what is possible with the REST API can also be achieved via the command-line.\n\n_If you're looking for documentation on the [WC 2.5 and 2.6's CLI go here](https://github.com/woocommerce/woocommerce/wiki/Legacy-CLI-commands-(v2.6-and-below))._\n\n## What is WP-CLI?\n\nFor those who have never heard before WP-CLI, here's a brief description extracted from the [official website](http://wp-cli.org/).\n\n> **WP-CLI** is a set of command-line tools for managing WordPress installations. You can update plugins, set up multisite installs and much more, without using a web browser.\n\n## WooCommerce Commands\n\nA full listing of WC-CLI commands and their accepted arguments can be found on the [commands page](https://github.com/woocommerce/woocommerce/wiki/WC-CLI-Commands).\n\nAll WooCommerce-related commands are grouped into `wp wc` command. The available commands (as of WC 3.0) are:\n\n```bash\n$ wp wc\nusage: wp wc customer \n or: wp wc customer_download \n or: wp wc order_note \n or: wp wc payment_gateway \n or: wp wc product \n or: wp wc product_attribute \n or: wp wc product_attribute_term \n or: wp wc product_cat \n or: wp wc product_review \n or: wp wc product_shipping_class \n or: wp wc product_tag \n or: wp wc product_variation \n or: wp wc shipping_method \n or: wp wc shipping_zone \n or: wp wc shipping_zone_location \n or: wp wc shipping_zone_method \n or: wp wc shop_coupon \n or: wp wc shop_order \n or: wp wc shop_order_refund \n or: wp wc tax \n or: wp wc tax_class \n or: wp wc tool \n or: wp wc webhook \n or: wp wc webhook_delivery \n\nSee 'wp help wc ' for more information on a specific command.\n```\n\n**Note**: When using the commands, you must specify your username or user ID using the `--user` argument. This is to let the REST API know which user should be used.\n\nYou can see more details about the commands using `wp help wc` or with the `--help` flag, which explains arguments and subcommands.\n\nExample:\n\n`wp wc customer --help`\n\n```bash\nNAME\n\n wp wc customer\n\nSYNOPSIS\n\n wp wc customer \n\nSUBCOMMANDS\n\n create Create a new item.\n delete Delete an existing item.\n get Get a single item.\n list List all items.\n update Update an existing item.\n```\n\n`wp wc customer list --help`\n\n```bash\nNAME\n\n wp wc customer list\n\nDESCRIPTION\n\n List all items.\n\nSYNOPSIS\n\n wp wc customer list [--context=] [--page=]\n [--per_page=] [--search=] [--exclude=]\n [--include=] [--offset=] [--order=]\n [--orderby=] [--email=] [--role=] [--fields=]\n [--field=] [--format=]\n\n\nOPTIONS\n\n [--context=]\n Scope under which the request is made; determines fields present in\n response.\n\n [--page=]\n Current page of the collection.\n\n [--per_page=]\n Maximum number of items to be returned in result set.\n\n [--search=]\n Limit results to those matching a string.\n\n [--exclude=]\n Ensure result set excludes specific IDs.\n\n [--include=]\n Limit result set to specific IDs.\n\n [--offset=]\n Offset the result set by a specific number of items.\n\n [--order=]\n Order sort attribute ascending or descending.\n\n [--orderby=]\n Sort collection by object attribute.\n\n [--email=]\n Limit result set to resources with a specific email.\n\n [--role=]\n Limit result set to resources with a specific role.\n\n [--fields=]\n Limit response to specific fields. Defaults to all fields.\n\n [--field=]\n Get the value of an individual field.\n\n [--format=]\n Render response in a particular format.\n ---\n default: table\n options:\n - table\n - json\n - csv\n - ids\n - yaml\n - count\n - headers\n - body\n - envelope\n ---\n```\n\nArguments like `--context`, `--fields`, `--field`, `--format` can be used on any `get` or `list` WC CLI command.\n\nThe `--porcelain` argument can be used on any `create` or `update` command to just get back the ID of the object, instead of a response.\n\nUpdating or creating some fields will require passing JSON. These are fields that contain arrays of information - for example, setting [https://woocommerce.github.io/woocommerce-rest-api-docs/#customer-properties](billing information) using the customer command. This is just passing key/value pairs.\n\nExample:\n\n`$ wp wc customer create --email='me@woo.local' --user=1 --billing='{\"first_name\":\"Justin\",\"last_name\":\"S\",\"company\":\"Automattic\"}' --password='he\nllo'`\n\n`Success: Created customer 16.`\n\n`$ wp wc customer get 16 --user=1`\n\n```bash\n+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| id | 16 |\n| date_created | 2016-12-09T20:07:35 |\n| date_modified | 2016-12-09T20:07:35 |\n| email | me@woo.local |\n| first_name | |\n| last_name | |\n| role | customer |\n| username | me |\n| billing | {\"first_name\":\"Justin\",\"last_name\":\"S\",\"company\":\"Automattic\",\"address_1\":\"\",\"address_2\":\"\",\"city\":\"\",\"state\":\"\",\"postcode\":\"\",\"country\":\"\",\"email\":\"\",\"phone\" |\n| | :\"\"} |\n| shipping | {\"first_name\":\"\",\"last_name\":\"\",\"company\":\"\",\"address_1\":\"\",\"address_2\":\"\",\"city\":\"\",\"state\":\"\",\"postcode\":\"\",\"country\":\"\"} |\n| is_paying_customer | false |\n| meta_data | |\n| orders_count | 0 |\n\n| total_spent | 0.00 |\n| avatar_url | http://2.gravatar.com/avatar/81a56b00c3b9952d6d2c107a8907e71f?s=96 |\n+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+\n```\n\n## Examples\n\nFull documentation for every command is available using `--help`. Below are some example commands to show what the CLI can do.\n\nAll the examples below use user ID 1 (usually an admin account), but you should replace that with your own user account.\n\nYou can also find other examples (without output) by looking at [the testing files for our CLI tests](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/tests/cli/features).\n\nEach command will have a `.feature` file. For example, [these some payment gateway commands](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/tests/cli/features/payment_gateway.feature).\n\n### Clearing the product/shop transients cache\n\nCommand: \n\n`$ wp wc tool run clear_transients --user=1`\n\nResponse:\n\n`Success: Updated system_status_tool clear_transients.`\n\n### Listing all system tools\n\nCommand: \n\n`$ wp wc tool list --user=1`\n\nResponse:\n\n```bash\n+----------------------------+----------------------------------+-------------------------------+-----------------------------------------------------------------------------------+\n| id | name | action | description |\n+----------------------------+----------------------------------+-------------------------------+-----------------------------------------------------------------------------------+\n| clear_transients | WC transients | Clear transients | This tool will clear the product/shop transients cache. |\n| clear_expired_transients | Expired transients | Clear expired transients | This tool will clear ALL expired transients from WordPress. |\n| delete_orphaned_variations | Orphaned variations | Delete orphaned variations | This tool will delete all variations which have no parent. |\n| recount_terms | Term counts | Recount terms | This tool will recount product terms - useful when changing your settings in a wa |\n| | | | y which hides products from the catalog. |\n| reset_roles | Capabilities | Reset capabilities | This tool will reset the admin, customer and shop_manager roles to default. Use t |\n| | | | his if your users cannot access all of the WooCommerce admin pages. |\n| clear_sessions | Customer sessions | Clear all sessions | Note: This tool will delete all customer session dat |\n| | | | a from the database, including any current live carts. |\n| install_pages | Install WooCommerce pages | Install pages | Note: This tool will install all the missing WooComm |\n| | | | erce pages. Pages already defined and set up will not be replaced. |\n| delete_taxes | Delete all WooCommerce tax rates | Delete ALL tax rates | Note: This option will delete ALL of your tax rates, |\n| | | | use with caution. |\n| reset_tracking | Reset usage tracking settings | Reset usage tracking settings | This will reset your usage tracking settings, causing it to show the opt-in banne |\n| | | | r again and not sending any data. |\n+----------------------------+----------------------------------+-------------------------------+-----------------------------------------------------------------------------------+\n````\n\n### Creating a customer\n\nCommand:\n\n`$ wp wc customer create --email='woo@woo.local' --user=1 --billing='{\"first_name\":\"Bob\",\"last_name\":\"Tester\",\"company\":\"Woo\", \"address_1\": \"123 Main St.\", \"city\":\"New York\", \"state:\": \"NY\", \"country\":\"USA\"}' --shipping='{\"first_name\":\"Bob\",\"last_name\":\"Tester\",\"company\":\"Woo\", \"address_1\": \"123 Main St.\", \"city\":\"New York\", \"state:\": \"NY\", \"country\":\"USA\"}' --password='hunter2' --username='mrbob' --first_name='Bob' --last_name='Tester'`\n\nResponse:\n\n`Success: Created customer 17.`\n\n### Getting a customer in CSV format\n\nCommand:\n\n`$ wp wc customer get 17 --user=1 --format=csv`\n\nResponse:\n\n```bash\nField,Value\nid,17\ndate_created,2016-12-09T20:22:10\ndate_modified,2016-12-09T20:22:10\nemail,woo@woo.local\nfirst_name,Bob\nlast_name,Tester\nrole,customer\nusername,mrbob\nbilling,\"{\"\"first_name\"\":\"\"Bob\"\",\"\"last_name\"\":\"\"Tester\"\",\"\"company\"\":\"\"Woo\"\",\"\"address_1\"\":\"\"123 Main St.\"\",\"\"address_2\"\":\"\"\"\",\"\"city\"\":\"\"New York\"\",\"\"state\"\":\"\"\"\",\"\"postcode\"\":\"\"\"\",\"\n\"country\"\":\"\"USA\"\",\"\"email\"\":\"\"\"\",\"\"phone\"\":\"\"\"\"}\"\nshipping,\"{\"\"first_name\"\":\"\"Bob\"\",\"\"last_name\"\":\"\"Tester\"\",\"\"company\"\":\"\"Woo\"\",\"\"address_1\"\":\"\"123 Main St.\"\",\"\"address_2\"\":\"\"\"\",\"\"city\"\":\"\"New York\"\",\"\"state\"\":\"\"\"\",\"\"postcode\"\":\"\"\"\",\n\"\"country\"\":\"\"USA\"\"}\"\nis_paying_customer,false\nmeta_data,\"[{\"\"id\"\":825,\"\"key\"\":\"\"shipping_company\"\",\"\"value\"\":\"\"Woo\"\"},{\"\"id\"\":829,\"\"key\"\":\"\"_order_count\"\",\"\"value\"\":\"\"0\"\"},{\"\"id\"\":830,\"\"key\"\":\"\"_money_spent\"\",\"\"value\"\":\"\"0\"\"}]\"\norders_count,0\ntotal_spent,0.00\navatar_url,http://2.gravatar.com/avatar/5791d33f7d6472478c0b5fa69133f09a?s=96\n```\n\n### Adding a customer note on order 355\n\nCommand:\n\n`$ wp wc order_note create 355 --note=\"Great repeat customer\" --customer_note=true --user=1`\n\nResponse:\n\n`Success: Created order_note 286.`\n\n### Getting an order note\n\nCommand:\n\n`$ wp wc order_note get 355 286 --user=1`\n\nResponse:\n\n```bash\n+---------------+-----------------------+\n| Field | Value |\n+---------------+-----------------------+\n| id | 286 |\n| date_created | 2016-12-09T20:27:26 |\n| note | Great repeat customer |\n| customer_note | true |\n+---------------+-----------------------+\n```\n\n### Updating a coupon\n\nCommand:\n\n`$ wp wc shop_coupon update 45 --amount='10' --discount_type='percent' --free_shipping=true --user=1`\n\nResponse:\n\n`Success: Updated shop_coupon 45.`\n\n### Getting a coupon\n\nCommand:\n\n`$ wp wc shop_coupon get 45 --user=1`\n\nResponse:\n\n```bash\n+-----------------------------+---------------------+\n| Field | Value |\n\n+-----------------------------+---------------------+\n| id | 45 |\n| code | hello |\n| amount | 10.00 |\n| date_created | 2016-08-09T17:37:28 |\n| date_modified | 2016-12-09T20:30:32 |\n| discount_type | percent |\n| description | Yay |\n| date_expires | 2016-10-22T00:00:00 |\n| usage_count | 2 |\n| individual_use | false |\n| product_ids | [] |\n| excluded_product_ids | [] |\n| usage_limit | null |\n| usage_limit_per_user | null |\n| limit_usage_to_x_items | null |\n| free_shipping | true |\n| product_categories | [] |\n| excluded_product_categories | [] |\n| exclude_sale_items | false |\n| minimum_amount | 0.00 |\n| maximum_amount | 0.00 |\n| email_restrictions | [] |\n| used_by | [\"1\",\"1\"] |\n| meta_data | [] |\n+-----------------------------+---------------------+\n```\n\n## Frequently Asked Questions\n\n### I get a 401 error when using commands, what do I do?\n\nIf you are getting a 401 error like `Error: Sorry, you cannot list resources. {\"status\":401}`, you are trying to use the command unauthenticated. The WooCommerce CLI as of 3.0 requires you to provide a proper user to run the action as. Pass in your user ID using the `--user` flag.\n\n### I am trying to update a list of X, but it's not saving\n\nSome 'lists' are actually objects. For example, if you want to set categories for a product, [the REST API expects an _array of objects_](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-properties).\n\nTo set this you would use JSON like this:\n\n```bash\nwp wc product create --name='Product Name' --categories='[ { \"id\" : 21 } ]' --user=admin\n```\n", + "content": "\nWooCommerce CLI (WC-CLI) offers the ability to manage WooCommerce (WC) via the command-line, using WP CLI. The documentation here covers the version of WC CLI that started shipping in WC 3.0.0 and later.\n\nWC CLI is powered by the [WC REST API](https://woocommerce.github.io/woocommerce-rest-api-docs/), meaning most of what is possible with the REST API can also be achieved via the command-line.\n\n_If you're looking for documentation on the [WC 2.5 and 2.6's CLI go here](https://github.com/woocommerce/woocommerce/wiki/Legacy-CLI-commands-(v2.6-and-below))._\n\n## What is WP-CLI?\n\nFor those who have never heard before WP-CLI, here's a brief description extracted from the [official website](http://wp-cli.org/).\n\n> **WP-CLI** is a set of command-line tools for managing WordPress installations. You can update plugins, set up multisite installs and much more, without using a web browser.\n\n## WooCommerce Commands\n\nA full listing of WC-CLI commands and their accepted arguments can be found on the [commands page](https://github.com/woocommerce/woocommerce/wiki/WC-CLI-Commands).\n\nAll WooCommerce-related commands are grouped into `wp wc` command. The available commands (as of WC 3.0) are:\n\n```bash\n$ wp wc\nusage: wp wc customer \n or: wp wc customer_download \n or: wp wc order_note \n or: wp wc payment_gateway \n or: wp wc product \n or: wp wc product_attribute \n or: wp wc product_attribute_term \n or: wp wc product_cat \n or: wp wc product_review \n or: wp wc product_shipping_class \n or: wp wc product_tag \n or: wp wc product_variation \n or: wp wc shipping_method \n or: wp wc shipping_zone \n or: wp wc shipping_zone_location \n or: wp wc shipping_zone_method \n or: wp wc shop_coupon \n or: wp wc shop_order \n or: wp wc shop_order_refund \n or: wp wc tax \n or: wp wc tax_class \n or: wp wc tool \n or: wp wc webhook \n or: wp wc webhook_delivery \n\nSee 'wp help wc ' for more information on a specific command.\n```\n\n**Note**: When using the commands, you must specify your username or user ID using the `--user` argument. This is to let the REST API know which user should be used.\n\nYou can see more details about the commands using `wp help wc` or with the `--help` flag, which explains arguments and subcommands.\n\nExample:\n\n`wp wc customer --help`\n\n```bash\nNAME\n\n wp wc customer\n\nSYNOPSIS\n\n wp wc customer \n\nSUBCOMMANDS\n\n create Create a new item.\n delete Delete an existing item.\n get Get a single item.\n list List all items.\n update Update an existing item.\n```\n\n`wp wc customer list --help`\n\n```bash\nNAME\n\n wp wc customer list\n\nDESCRIPTION\n\n List all items.\n\nSYNOPSIS\n\n wp wc customer list [--context=] [--page=]\n [--per_page=] [--search=] [--exclude=]\n [--include=] [--offset=] [--order=]\n [--orderby=] [--email=] [--role=] [--fields=]\n [--field=] [--format=]\n\n\nOPTIONS\n\n [--context=]\n Scope under which the request is made; determines fields present in\n response.\n\n [--page=]\n Current page of the collection.\n\n [--per_page=]\n Maximum number of items to be returned in result set.\n\n [--search=]\n Limit results to those matching a string.\n\n [--exclude=]\n Ensure result set excludes specific IDs.\n\n [--include=]\n Limit result set to specific IDs.\n\n [--offset=]\n Offset the result set by a specific number of items.\n\n [--order=]\n Order sort attribute ascending or descending.\n\n [--orderby=]\n Sort collection by object attribute.\n\n [--email=]\n Limit result set to resources with a specific email.\n\n [--role=]\n Limit result set to resources with a specific role.\n\n [--fields=]\n Limit response to specific fields. Defaults to all fields.\n\n [--field=]\n Get the value of an individual field.\n\n [--format=]\n Render response in a particular format.\n ---\n default: table\n options:\n - table\n - json\n - csv\n - ids\n - yaml\n - count\n - headers\n - body\n - envelope\n ---\n```\n\nArguments like `--context`, `--fields`, `--field`, `--format` can be used on any `get` or `list` WC CLI command.\n\nThe `--porcelain` argument can be used on any `create` or `update` command to just get back the ID of the object, instead of a response.\n\nUpdating or creating some fields will require passing JSON. These are fields that contain arrays of information - for example, setting [https://woocommerce.github.io/woocommerce-rest-api-docs/#customer-properties](billing information) using the customer command. This is just passing key/value pairs.\n\nExample:\n\n`$ wp wc customer create --email='me@woo.local' --user=1 --billing='{\"first_name\":\"Justin\",\"last_name\":\"S\",\"company\":\"Automattic\"}' --password='he\nllo'`\n\n`Success: Created customer 16.`\n\n`$ wp wc customer get 16 --user=1`\n\n```bash\n+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| id | 16 |\n| date_created | 2016-12-09T20:07:35 |\n| date_modified | 2016-12-09T20:07:35 |\n| email | me@woo.local |\n| first_name | |\n| last_name | |\n| role | customer |\n| username | me |\n| billing | {\"first_name\":\"Justin\",\"last_name\":\"S\",\"company\":\"Automattic\",\"address_1\":\"\",\"address_2\":\"\",\"city\":\"\",\"state\":\"\",\"postcode\":\"\",\"country\":\"\",\"email\":\"\",\"phone\" |\n| | :\"\"} |\n| shipping | {\"first_name\":\"\",\"last_name\":\"\",\"company\":\"\",\"address_1\":\"\",\"address_2\":\"\",\"city\":\"\",\"state\":\"\",\"postcode\":\"\",\"country\":\"\"} |\n| is_paying_customer | false |\n| meta_data | |\n| orders_count | 0 |\n\n| total_spent | 0.00 |\n| avatar_url | http://2.gravatar.com/avatar/81a56b00c3b9952d6d2c107a8907e71f?s=96 |\n+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+\n```\n\n## Examples\n\nFull documentation for every command is available using `--help`. Below are some example commands to show what the CLI can do.\n\nAll the examples below use user ID 1 (usually an admin account), but you should replace that with your own user account.\n\nYou can also find other examples (without output) by looking at [the testing files for our CLI tests](https://github.com/woocommerce/woocommerce/tree/trunk/plugins/woocommerce/tests/cli/features).\n\nEach command will have a `.feature` file. For example, [these some payment gateway commands](https://github.com/woocommerce/woocommerce/blob/trunk/plugins/woocommerce/tests/cli/features/payment_gateway.feature).\n\n### Clearing the product/shop transients cache\n\nCommand: \n\n`$ wp wc tool run clear_transients --user=1`\n\nResponse:\n\n`Success: Updated system_status_tool clear_transients.`\n\n### Listing all system tools\n\nCommand: \n\n`$ wp wc tool list --user=1`\n\nResponse:\n\n```bash\n+----------------------------+----------------------------------+-------------------------------+-----------------------------------------------------------------------------------+\n| id | name | action | description |\n+----------------------------+----------------------------------+-------------------------------+-----------------------------------------------------------------------------------+\n| clear_transients | WC transients | Clear transients | This tool will clear the product/shop transients cache. |\n| clear_expired_transients | Expired transients | Clear expired transients | This tool will clear ALL expired transients from WordPress. |\n| delete_orphaned_variations | Orphaned variations | Delete orphaned variations | This tool will delete all variations which have no parent. |\n| recount_terms | Term counts | Recount terms | This tool will recount product terms - useful when changing your settings in a wa |\n| | | | y which hides products from the catalog. |\n| reset_roles | Capabilities | Reset capabilities | This tool will reset the admin, customer and shop_manager roles to default. Use t |\n| | | | his if your users cannot access all of the WooCommerce admin pages. |\n| clear_sessions | Customer sessions | Clear all sessions | Note: This tool will delete all customer session dat |\n| | | | a from the database, including any current live carts. |\n| install_pages | Install WooCommerce pages | Install pages | Note: This tool will install all the missing WooComm |\n| | | | erce pages. Pages already defined and set up will not be replaced. |\n| delete_taxes | Delete all WooCommerce tax rates | Delete ALL tax rates | Note: This option will delete ALL of your tax rates, |\n| | | | use with caution. |\n| reset_tracking | Reset usage tracking settings | Reset usage tracking settings | This will reset your usage tracking settings, causing it to show the opt-in banne |\n| | | | r again and not sending any data. |\n+----------------------------+----------------------------------+-------------------------------+-----------------------------------------------------------------------------------+\n```\n\n### Creating a customer\n\nCommand:\n\n`$ wp wc customer create --email='woo@woo.local' --user=1 --billing='{\"first_name\":\"Bob\",\"last_name\":\"Tester\",\"company\":\"Woo\", \"address_1\": \"123 Main St.\", \"city\":\"New York\", \"state:\": \"NY\", \"country\":\"USA\"}' --shipping='{\"first_name\":\"Bob\",\"last_name\":\"Tester\",\"company\":\"Woo\", \"address_1\": \"123 Main St.\", \"city\":\"New York\", \"state:\": \"NY\", \"country\":\"USA\"}' --password='hunter2' --username='mrbob' --first_name='Bob' --last_name='Tester'`\n\nResponse:\n\n`Success: Created customer 17.`\n\n### Getting a customer in CSV format\n\nCommand:\n\n`$ wp wc customer get 17 --user=1 --format=csv`\n\nResponse:\n\n```bash\nField,Value\nid,17\ndate_created,2016-12-09T20:22:10\ndate_modified,2016-12-09T20:22:10\nemail,woo@woo.local\nfirst_name,Bob\nlast_name,Tester\nrole,customer\nusername,mrbob\nbilling,\"{\"\"first_name\"\":\"\"Bob\"\",\"\"last_name\"\":\"\"Tester\"\",\"\"company\"\":\"\"Woo\"\",\"\"address_1\"\":\"\"123 Main St.\"\",\"\"address_2\"\":\"\"\"\",\"\"city\"\":\"\"New York\"\",\"\"state\"\":\"\"\"\",\"\"postcode\"\":\"\"\"\",\"\n\"country\"\":\"\"USA\"\",\"\"email\"\":\"\"\"\",\"\"phone\"\":\"\"\"\"}\"\nshipping,\"{\"\"first_name\"\":\"\"Bob\"\",\"\"last_name\"\":\"\"Tester\"\",\"\"company\"\":\"\"Woo\"\",\"\"address_1\"\":\"\"123 Main St.\"\",\"\"address_2\"\":\"\"\"\",\"\"city\"\":\"\"New York\"\",\"\"state\"\":\"\"\"\",\"\"postcode\"\":\"\"\"\",\n\"\"country\"\":\"\"USA\"\"}\"\nis_paying_customer,false\nmeta_data,\"[{\"\"id\"\":825,\"\"key\"\":\"\"shipping_company\"\",\"\"value\"\":\"\"Woo\"\"},{\"\"id\"\":829,\"\"key\"\":\"\"_order_count\"\",\"\"value\"\":\"\"0\"\"},{\"\"id\"\":830,\"\"key\"\":\"\"_money_spent\"\",\"\"value\"\":\"\"0\"\"}]\"\norders_count,0\ntotal_spent,0.00\navatar_url,http://2.gravatar.com/avatar/5791d33f7d6472478c0b5fa69133f09a?s=96\n```\n\n### Adding a customer note on order 355\n\nCommand:\n\n`$ wp wc order_note create 355 --note=\"Great repeat customer\" --customer_note=true --user=1`\n\nResponse:\n\n`Success: Created order_note 286.`\n\n### Getting an order note\n\nCommand:\n\n`$ wp wc order_note get 355 286 --user=1`\n\nResponse:\n\n```bash\n+---------------+-----------------------+\n| Field | Value |\n+---------------+-----------------------+\n| id | 286 |\n| date_created | 2016-12-09T20:27:26 |\n| note | Great repeat customer |\n| customer_note | true |\n+---------------+-----------------------+\n```\n\n### Updating a coupon\n\nCommand:\n\n`$ wp wc shop_coupon update 45 --amount='10' --discount_type='percent' --free_shipping=true --user=1`\n\nResponse:\n\n`Success: Updated shop_coupon 45.`\n\n### Getting a coupon\n\nCommand:\n\n`$ wp wc shop_coupon get 45 --user=1`\n\nResponse:\n\n```bash\n+-----------------------------+---------------------+\n| Field | Value |\n\n+-----------------------------+---------------------+\n| id | 45 |\n| code | hello |\n| amount | 10.00 |\n| date_created | 2016-08-09T17:37:28 |\n| date_modified | 2016-12-09T20:30:32 |\n| discount_type | percent |\n| description | Yay |\n| date_expires | 2016-10-22T00:00:00 |\n| usage_count | 2 |\n| individual_use | false |\n| product_ids | [] |\n| excluded_product_ids | [] |\n| usage_limit | null |\n| usage_limit_per_user | null |\n| limit_usage_to_x_items | null |\n| free_shipping | true |\n| product_categories | [] |\n| excluded_product_categories | [] |\n| exclude_sale_items | false |\n| minimum_amount | 0.00 |\n| maximum_amount | 0.00 |\n| email_restrictions | [] |\n| used_by | [\"1\",\"1\"] |\n| meta_data | [] |\n+-----------------------------+---------------------+\n```\n\n## Frequently Asked Questions\n\n### I get a 401 error when using commands, what do I do?\n\nIf you are getting a 401 error like `Error: Sorry, you cannot list resources. {\"status\":401}`, you are trying to use the command unauthenticated. The WooCommerce CLI as of 3.0 requires you to provide a proper user to run the action as. Pass in your user ID using the `--user` flag.\n\n### I am trying to update a list of X, but it's not saving\n\nSome 'lists' are actually objects. For example, if you want to set categories for a product, [the REST API expects an _array of objects_](https://woocommerce.github.io/woocommerce-rest-api-docs/#product-properties).\n\nTo set this you would use JSON like this:\n\n```bash\nwp wc product create --name='Product Name' --categories='[ { \"id\" : 21 } ]' --user=admin\n```\n", "category_slug": "wc-cli", "category_title": "WooCommerce CLI", "posts": [ @@ -1076,5 +1095,5 @@ "categories": [] } ], - "hash": "f7c0574f9c07c864981a47732f78786ace557cb0a30111eb9d078c053471531b" + "hash": "9abb5ed7e5cc846dfacb5afd5064195c97687d82186bc9ff129d9f73150f095e" } \ No newline at end of file diff --git a/docs/getting-started/customizing-endpoint-urls.md b/docs/getting-started/customizing-endpoint-urls.md new file mode 100644 index 00000000000..b6c3a83ad4b --- /dev/null +++ b/docs/getting-started/customizing-endpoint-urls.md @@ -0,0 +1,79 @@ +--- +post_title: Customizing WooCommerce Endpoint URLs +menu_title: Customizing Endpoint URLs +tags: how-to +--- + +Before you start, check out [WooCommerce Endpoints](./docs/woocommerce-endpoints). + +## Customizing endpoint URLs + +The URL for each endpoint can be customized in **WooCommerce > Settings > Advanced** in the Page setup section. + +![Endpoints](https://woo-docs-multi-com.go-vip.net/wp-content/uploads/2023/12/endpoints.png) + +Ensure that they are unique to avoid conflicts. If you encounter issues with 404s, go to **Settings > Permalinks** and save to flush the rewrite rules. + +## Using endpoints in menus + +If you want to include an endpoint in your menus, you need to use the Links section: + +![The Links section of a menu item in WordPress](https://woo-docs-multi-com.go-vip.net/wp-content/uploads/2023/12/2014-02-26-at-14.26.png) + +Enter the full URL to the endpoint and then insert that into your menu. + +Remember that some endpoints, such as view-order, require an order ID to work. In general, we don't recommend adding these endpoints to your menus. These pages can instead be accessed via the my-account page. + +## Using endpoints in Payment Gateway Plugins + +WooCommerce provides helper functions in the order class for getting these URLs. They are: + +`$order->get_checkout_payment_url( $on_checkout = false );` + +and: + +`$order->get_checkout_order_received_url();` + +Gateways need to use these methods for full 2.1+ compatibility. + +## Troubleshooting + +### Endpoints showing 404 + +- If you see a 404 error, go to **WordPress Admin** > **Settings > Permalinks** and Save. This ensures that rewrite rules for endpoints exist and are ready to be used. +- If using an endpoint such as view-order, ensure that it specifies an order number. /view-order/ is invalid. /view-order/10/ is valid. These types of endpoints should not be in your navigation menus. + +### Endpoints are not working + +On Windows servers, the **web.config** file may not be set correctly to allow for the endpoints to work correctly. In this case, clicking on endpoint links (e.g. /edit-account/ or /customer-logout/) may appear to do nothing except refresh the page. In order to resolve this, try simplifying the **web.config** file on your Windows server. Here's a sample file configuration: + +```xml + + + + + + + + + + + + + + + + + + +``` + +### Pages direct to wrong place + +Landing on the wrong page when clicking an endpoint URL is typically caused by incorrect settings. For example, clicking 'Edit address' on your account page takes you to the Shop page instead of the edit address form means you selected the wrong page in settings. Confirm that your pages are correctly configured and that a different page is used for each section. + +### How to Remove "Downloads" from My Account + +Sometimes the "Downloads" endpoint on the "My account" page does not need to be displayed. This can be removed by going to **WooCommerce → Settings → Advanced → Account endpoints** and clearing the Downloads endpoint field. + +![Account endpoints](https://woo-docs-multi-com.go-vip.net/wp-content/uploads/2023/12/Screenshot-2023-04-09-at-11.45.58-PM.png) diff --git a/docs/getting-started/troubleshooting-endpoints.md b/docs/getting-started/troubleshooting-endpoints.md new file mode 100644 index 00000000000..21ab6949304 --- /dev/null +++ b/docs/getting-started/troubleshooting-endpoints.md @@ -0,0 +1,49 @@ +--- +post_title: Troubleshooting WooCommerce Endpoints +menu_title: Troubleshooting Endpoints +tags: how-to +--- + +This document outlines common troubleshooting steps for [WooCommerce Endpoints](./docs/woocommerce-endpoints). + +For more information, learn how to [Customize Endpoints](./docs/customizing-endpoint-urls). + +## Endpoints showing 404 + +- If you see a 404 error, go to **WordPress Admin** > **Settings > Permalinks** and Save. This ensures that rewrite rules for endpoints exist and are ready to be used. +- If using an endpoint such as view-order, ensure that it specifies an order number. /view-order/ is invalid. /view-order/10/ is valid. These types of endpoints should not be in your navigation menus. + +## Endpoints are not working + +On Windows servers, the **web.config** file may not be set correctly to allow for the endpoints to work correctly. In this case, clicking on endpoint links (e.g. /edit-account/ or /customer-logout/) may appear to do nothing except refresh the page. In order to resolve this, try simplifying the **web.config** file on your Windows server. Here's a sample file configuration: + +```xml + + + + + + + + + + + + + + + + + + +``` + +## Pages direct to wrong place + +Landing on the wrong page when clicking an endpoint URL is typically caused by incorrect settings. For example, clicking 'Edit address' on your account page takes you to the Shop page instead of the edit address form means you selected the wrong page in settings. Confirm that your pages are correctly configured and that a different page is used for each section. + +## How to Remove "Downloads" from My Account + +Sometimes the "Downloads" endpoint on the "My account" page does not need to be displayed. This can be removed by going to **WooCommerce → Settings → Advanced → Account endpoints** and clearing the Downloads endpoint field. + +![Account endpoints](https://woo-docs-multi-com.go-vip.net/wp-content/uploads/2023/12/Screenshot-2023-04-09-at-11.45.58-PM.png) diff --git a/docs/getting-started/woocommerce-endpoints.md b/docs/getting-started/woocommerce-endpoints.md index cf325643443..78dbdc8104e 100644 --- a/docs/getting-started/woocommerce-endpoints.md +++ b/docs/getting-started/woocommerce-endpoints.md @@ -1,5 +1,6 @@ --- -post_title: WooCommerce Endpoints +post_title: Understanding WooCommerce Endpoints +menu_title: WooCommerce Endpoints --- Endpoints are an extra part in the website URL that is detected to show different content when present. @@ -33,74 +34,7 @@ The following endpoints are used for account-related functionality and are appen - Lost password - `/lost-password/` - Logout - `/customer-logout/` -## Customizing endpoint URLs +## Learn more -The URL for each endpoint can be customized in **WooCommerce > Settings > Advanced** in the Page setup section. - -![Endpoints](https://woo-docs-multi-com.go-vip.net/wp-content/uploads/2023/12/endpoints.png) - -Ensure that they are unique to avoid conflicts. If you encounter issues with 404s, go to **Settings > Permalinks** and save to flush the rewrite rules. - -## Using endpoints in menus - -If you want to include an endpoint in your menus, you need to use the Links section: - -![The Links section of a menu iteam in WordPress](https://woo-docs-multi-com.go-vip.net/wp-content/uploads/2023/12/2014-02-26-at-14.26.png) - -Enter the full URL to the endpoint and then insert that into your menu. - -Remember that some endpoints, such as view-order, require an order ID to work. In general, we don't recommend adding these endpoints to your menus. These pages can instead be accessed via the my-account page. - -## Using endpoints in Payment Gateway Plugins - -WooCommerce provides helper functions in the order class for getting these URLs. They are: - -`$order->get_checkout_payment_url( $on_checkout = false );` - -and: - -`$order->get_checkout_order_received_url();` - -Gateways need to use these methods for full 2.1+ compatibility. - -## Troubleshooting - -### Endpoints showing 404 - -- If you see a 404 error, go to **WordPress Admin** > **Settings > Permalinks** and Save. This ensures that rewrite rules for endpoints exist and are ready to be used. -- If using an endpoint such as view-order, ensure that it specifies an order number. /view-order/ is invalid. /view-order/10/ is valid. These types of endpoints should not be in your navigation menus. - -### Endpoints are not working - -On Windows servers, the **web.config** file may not be set correctly to allow for the endpoints to work correctly. In this case, clicking on endpoint links (e.g. /edit-account/ or /customer-logout/) may appear to do nothing except refresh the page. In order to resolve this, try simplifying the **web.config** file on your Windows server. Here's a sample file configuration: - -```xml - - - - - - - - - - - - - - - - - - -``` - -### Pages direct to wrong place - -Landing on the wrong page when clicking an endpoint URL is typically caused by incorrect settings. For example, clicking 'Edit address' on your account page takes you to the Shop page instead of the edit address form means you selected the wrong page in settings. Confirm that your pages are correctly configured and that a different page is used for each section. - -### How to Remove "Downloads" from My Account - -Sometimes the "Downloads" endpoint on the "My account" page does not need to be displayed. This can be removed by going to **WooCommerce → Settings → Advanced → Account endpoints** and clearing the Downloads endpoint field. - -![Account endpoints](https://woo-docs-multi-com.go-vip.net/wp-content/uploads/2023/12/Screenshot-2023-04-09-at-11.45.58-PM.png) +- [Customizing endpoint URLs](./docs/customizing-endpoint-urls) +- [Troubleshooting endpoints](.docs/troubleshooting-endpoints)