[IMP] Market Connectors: eBay Marketplace edits

closes odoo/documentation#7076

X-original-commit: 2048c588c4
Signed-off-by: Timothy Kukulka (tiku) <tiku@odoo.com>
Signed-off-by: Zachary Straub (zst) <zst@odoo.com>

content/applications/sales/sales/ebay_connector.rst

@@ -9,3 +9,5 @@ eBay Connector
 
    ebay_connector/setup
    ebay_connector/manage
+   ebay_connector/troubleshooting
+   ebay_connector/linking_listings

content/applications/sales/sales/ebay_connector/linking_listings.rst

@@ -0,0 +1,124 @@
+=========================
+Linking existing listings
+=========================
+
+Once the eBay account is linked existing listings from within the eBay seller account need to be
+added manually to the Odoo product listings.
+
+The process will be as follows:
+- Turn off eBay scheduled actions
+- Add products and link listings
+- Turn on eBay scheduled actions
+
+.. seealso::
+   To learn more about the eBay connector visit these pages as well:
+
+   - :doc:`setup`
+   - :doc:`manage`
+   - :doc:`troubleshooting`
+
+Turn off eBay scheduled actions
+===============================
+
+To start linking existing listings in eBay, first turn off the eBay notifications in the scheduled
+actions in Odoo. The reason for this is so that no orders or eBay data syncs during this process.
+The :guilabel:`Scheduled Actions` can be accessed by first activating
+:ref:`developer mode <developer-mode>`. After doing so, go to :menuselection:`Settings --> Technical
+--> Automation --> Scheduled Actions`.
+
+.. warning::
+  :doc:`../../../general/developer_mode` must be activated to ensure the technical menu appears for
+  the user.
+
+Disabling scheduled actions enables users to sync and validate eBay data before receiving orders.
+The following are descriptions of scheduled actions that need to be temporarily deactivated:
+
+- :guilabel:`eBay: get new orders`: eBay pushes new orders not already in Odoo (based on
+  :guilabel:`client_order_reference`, or :guilabel:`sales order reference` field). This command
+  also updates existing orders, where changes we made in eBay. New and updated orders are then
+  placed in draft mode. Customers will be created if they are not already in Odoo.
+- :guilabel:`eBay: synchronize stock`: eBay displays Odoo's stock on hand.
+- :guilabel:`eBay: update categories`: eBay will push updated monthly categories (only up to fourth
+  layer; a manual update required for the rest).
+
+To toggle off the eBay notification, select the entry from the :guilabel:`Scheduled Actions` list.
+Then, on the page, click the :guilabel:`Active` toggle button to turn it off.
+
+Sync eBay categories
+--------------------
+
+To ensure that Odoo's eBay products have all the categories available on eBay, the eBay categories
+should be synced to Odoo next.
+
+Navigate to :menuselection:`Settings --> Technical --> Automation --> Scheduled Actions`. Click into
+the scheduled action labeled: :guilabel:`Ebay: update categories` and then click :guilabel:`Run
+Manually`. This action will populate the :menuselection:`Sales --> Configuration --> eBay
+Categories` menu item with all standard eBay product categories.
+
+.. important::
+   Odoo only recognizes eBay category paths up to four layers deep. If a product has a listing of
+   more than four, the category field will only populate up to the fourth layer.
+
+   If product categories beyond four paths are required, users need to manually add those paths.
+   This has historically been done by getting a list of all product categories beyond 4 paths,
+   manually importing them into the Product Category model in Odoo, then linking them individually
+   to the product.
+
+Users can import the remaining product categories into the eBay product categories manually using
+using the :guilabel:`Action` menu and :guilabel:`Import` feature.
+
+Link eBay listings
+==================
+
+To add eBay listings in Odoo, either manually add products, using a listing ID, or establish an
+automatic listing link between Odoo and eBay.
+
+.. tip::
+   For more information on listing a product from scratch visit: :ref:`How to list a product?
+   <ebay-connector/listing>`
+
+Manual listing link
+-------------------
+
+To add an eBay listing to products in Odoo, begin by going to :menuselection:`Sales app --> Products
+--> Products` and selecting the desired product. Click on :guilabel:`Sell on eBay` (either in the
+:guilabel:`eBay` tab or under the :guilabel:`Product name`). Select :guilabel:`Save` if necessary.
+
+Still the product form, click :guilabel:`link to listing` in the top menu and enter in listing ID
+from eBay in the pop up (the listing ID is in the eBay product URL).
+
+.. example::
+   An example URL would be as such:
+   `www.ebay.com/itm/272222656444?hash=item3f61bc17bb:g:vJ0AAOSwslJizv8u`. The listing ID is
+   `272222656444` in this case. Once the listing ID has been entered the eBay listing information
+   will sync into Odoo.
+
+Turn on eBay scheduled Actions
+==============================
+
+The next step is to turn on the eBay notifications in the scheduled actions in Odoo so that orders
+and data are exchanged. The :guilabel:`Scheduled Actions` can be accessed by first activating
+:ref:`developer mode <developer-mode>` and go to :menuselection:`Settings --> Technical -->
+Automation --> Scheduled Actions`.
+
+Turning on the following scheduled actions allows users to sync and validate eBay data
+automatically.
+
+- :guilabel:`eBay: get new orders`: eBay will push all new orders not already in Odoo (based on
+  client_order_reference, or sales order reference field), and will update orders if there has been
+  a change from eBay. Orders will be put in draft mode. Customers will be created if they are not
+  already in Odoo.
+- :guilabel:`eBay: synchronize stock`: eBay will display the stock on hand in Odoo.
+- :guilabel:`eBay: update categories`: eBay will push updated monthly categories (only up to fourth
+  layer, will need to manually update the rest).
+
+.. note::
+   If an order comes in and the listing from the order is not linked to a product, eBay will create
+   a consumable product.product in its place. These consumables should be altered on the
+   *Sales Order* while in draft state to represent a storable product, and then the user can link to
+   the listing as they come in.
+
+.. seealso::
+   - :doc:`/applications/sales/sales/ebay_connector/manage`
+   - :doc:`/applications/sales/sales/ebay_connector/troubleshooting`
+   - :doc:`/applications/sales/sales/ebay_connector/setup`

content/applications/sales/sales/ebay_connector/manage.rst

@@ -2,49 +2,154 @@
 How to list a product?
 ======================
 
+.. _ebay-connector/listing:
+
+In order to list a product on eBay and Odoo there are two methods in Odoo to do so:
+
+#. Make a product in Odoo and list the item eBay.
+
+   - Click :guilabel:`List Item on eBay` in the top menu of the product template. The product
+     template can be accessed by navigating to :menuselection:`Sales app --> Products --> Product`
+     and selecting the individual product.
+#. List the item on eBay, then create the product in Odoo, and finally link product to the item on
+   eBay.
+
+   - Click :guilabel:`Link With Existing eBay Listing` in the top menu on the product template.The
+     product template can be accessed by navigating to :menuselection:`Sales app --> Product -->
+     Product` and selecting the individual product.
+
+.. note::
+   If an order comes in and the listing from the order is not linked to a product, eBay will create
+   a consumable product.product in its place. These consumables should be altered on the *sales
+   order* while in draft state to represent a storable product, and then the user can link to the
+   listing as they come in.
+
+.. seealso::
+   To learn more about the eBay connector visit these pages as well:
+
+   - :doc:`setup`
+   - :doc:`linking_listings`
+   - :doc:`troubleshooting`
+
 Listing without variation
 =========================
 
-In order to list a product, you need to check the **use eBay** field on a product
-form. The eBay tab will be available.
+Access the product template by navigating to :menuselection:`Sales app --> Products --> Product` and
+selecting the individual product.
 
-.. image:: manage/manage01.png
+In order to list a product, select the :guilabel:`Sell on eBay` field on a product template.
+:guilabel:`Sell on eBay` is either in an :guilabel:`eBay` tab or under the :guilabel:`Product
+name`. Click :guilabel:`Save` if necessary.
+
+.. image:: manage/manage-ebay-template.png
   :align: center
+  :alt: The eBay template form listed in the product template in Odoo.
 
-When the **Use Stock Quantity** field is checked, the quantity sets on eBay will
-be the Odoo **Forecast Quantity**.
+When the :guilabel:`Use Stock Quantity` field is checked, the quantity set on eBay will be the Odoo
+*Forecast Quantity* (Odoo *Inventory* app).
 
-The **Description Template** allows you to use templates for your listings. The
-default template only use the **eBay Description** field of the product. You can
-use html inside the **Description Template** and in the **eBay Description**.
+The :guilabel:`Description Template` allows the administrator to use templates in listings. The
+default template only use the :guilabel:`eBay Description` field of the product. HTML can be used
+inside the :guilabel:`Description Template` and in the :guilabel:`eBay Description` in Odoo 14.
+Starting in Odoo 15, the powerbox feature is available to use in the template and description.
+Simply type a forward slash `/` to reveal a menu with formatting, layout, and text options. To add
+an image, type `/image`.
 
-To use pictures in your listing, you need to add them as **Attachments** on the product template.
+To use images in the listing, another option is to add them as *Attachments* on the product
+template.
+
+.. seealso::
+   For more information on template configuration in Odoo visit:
+   :doc:`../../../general/email_communication/email_template`.
 
 Listing with variations
 =======================
 
-When the **use eBay** on a product with variations is checked and with **Fixed
-Price** as **Listing Type**, the eBay form is slightly different. In the
-variants array, you can choose which variant will be listed on eBay as well as
-set the price and the quantity for each variant.
+When the :guilabel:`Sell on eBay` is checked on a product containing variations with
+:guilabel:`Fixed Price` as :guilabel:`Listing Type`, the eBay form is slightly different. Go to the
+:guilabel:`Variants` tab to or click :guilabel:`Configure Variants` in the top menu to configure the
+variant settings. Pricing can be configured for each variation.
 
-.. image:: manage/manage02.png
-  :align: center
+When the :guilabel:`Listing Type` is changed to :guilabel:`Fixed Price`, Odoo presents a
+variant table at the bottom of the :guilabel:`eBay` tab, in which the :guilabel:`Fixed Price` can be
+entered, and the decision to :guilabel:`Publish on eBay` can be made for specific variants, along
+with other options.
 
-Listing with item specifics
-===========================
+.. image:: manage/fixed-listing-price.png
+   :align: center
+   :alt: The fixed price listing type in the eBay tab on a product form in Odoo sales.
 
-In order to add item specifics, you should create a product attribute with one
-value in the **Variants** tab on the product form.
-
-.. image:: manage/manage03.png
-  :align: center
-
-Product Identifiers
+Product identifiers
 ===================
 
-Products identifiers such as EAN, UPC, Brand or MPN are required in most of the eBay category.
-The module manages the EAN and UPC identifiers with the **Barcode** field of the product variant.
-If the **Barcode** field is empty or is value is not valid, the EAN and UPC values will be set as 'Does not apply' as recommended by eBay.
-The Brand and MPN values are working as item specifics and should be define in the **Variants** tab on the product form.
-If these values are not set, 'Does not apply' will be used for the eBay listing.
+Products identifiers such as EAN, UPC, Brand or MPN are required in most of the eBay categories.
+
+EAN and UPC identifiers
+-----------------------
+
+The module manages the EAN and UPC identifiers with the :guilabel:`Barcode` field of the product
+variant. If the :guilabel:`Barcode` field is empty or is value is not valid, the EAN and UPC values
+will be set as 'Does not apply' as recommended by eBay.
+
+Barcodes can be found on the product template, under the the :guilabel:`General Information` tab.
+Access the product template, first, by navigating to :menuselection:`Sales app --> Products -->
+Product` and selecting the individual product.
+
+Listing with item specifics
+---------------------------
+
+In order to add item specifics, one should create a product attribute with a single value in the
+:guilabel:`Attributes & Variants` tab on the product form. Examples of item specifics include: `MPN`
+or `Brand`. The Brand and MPN values are working as item specifics and should be defined in the
+:guilabel:`Attributes & Variants` tab on the product form. If these values are not set, 'Does not
+apply' will be used for the eBay listing.
+
+Process invoices and payments
+=============================
+
+Posting payment
+---------------
+
+When eBay orders are placed they are always paid for up front, via the eBay site. At no point will
+users pay for items on eBay through Odoo. Therefore, once orders are synced into Odoo from eBay they
+are already paid for. Odoo's invoicing and payment functionalities are not utilized. However,
+invoices need to be created and marked as Paid to “close” the *Sales Order*.
+
+Users can opt to mass create and post invoices in batches. To do so, navigate to Quotations in the
+list view by going to :menuselection:`Sales app --> Orders --> Quotations`. In the upper right
+corner, select the list view icon. Hover over the icons to reveal the name of each. Then check the
+boxes on the left that invoices should be made for and go to the :guilabel:`Action` menu or ⚙️ [Gear
+icon] . Click on :guilabel:`Create Invoices`.
+
+A pop-up will appear and click on the :guilabel:`Create and view invoice` button. A new screen will
+populate with the newly created invoices. Next, select all of them by clicking on the box icon next
+to :guilabel:`Number` in the header row of the list, this will select all the records. Then navigate
+to the :guilabel:`Action` menu and click :guilabel:`Post entries`. Following this step, a pop-up
+will appear and click on :guilabel:`Post journal entries`. This will take the invoices out of
+*draft* and set them to *posted*.
+
+Reconciling payments
+--------------------
+
+Users typically utilize PayPal to receive payment from eBay, and then send lump sums from PayPal
+into their bank account. To reconcile this income, users can reconcile the one PayPal transfer with
+all related invoices.
+
+First navigate to the :guilabel:`Accounting Dashboard` by going to the :menuselection:`Accounting
+app --> Dashboard --> Bank`. :guilabel:`Create` a new transaction and enter the :guilabel:`Label`
+as `eBay Sales`. Fill out the :guilabel:`Amount` and enter a :guilabel:`Statement` date in. Click on
+:guilabel:`Create and edit`.
+
+For the :guilabel:`Ending Balance` field, enter the same account that was entered for the
+:guilabel:`Amount` above. Click on :guilabel:`Save`. Next, open the new balance that needs to be
+reconciled. Under the tab marked: :guilabel:`Match Existing Entries` select the entries that are
+included in this balance.
+
+After adding all the necessary entries, click :guilabel:`Validate` to complete the reconciliation.
+To verify the payment, navigate to :menuselection:`Customers --> Invoices` and select the desired
+customer invoice. The *Paid* label should appear under the :guilabel:`Payment Status` column.
+
+.. seealso::
+   - :doc:`/applications/sales/sales/ebay_connector/troubleshooting`
+   - :doc:`/applications/sales/sales/ebay_connector/linking_listings`
+   - :doc:`/applications/sales/sales/ebay_connector/setup`

content/applications/sales/sales/ebay_connector/setup.rst

@@ -1,126 +1,402 @@
-==============================
-How to configure eBay in Odoo?
-==============================
+====================
+eBay connector setup
+====================
 
-Create eBay tokens
-==================
+Overview
+========
 
-In order to create your tokens, you need to create a developer account on the
-`developer portal <https://go.developer.ebay.com/>`_.
-Once you are logged in, you can create **Sandbox Keys** and **Production Keys**
-by clicking on the adequate buttons.
+Odoo's eBay connector allows eBay listings to connect with Odoo products. Once connected,
+:doc:`updates to the listings <linking_listings>` can be made in Odoo or in eBay. When an item sells
+on eBay, draft *sales orders* are created in Odoo for the user to review and confirm. Once the sales
+order is confirmed, Odoo *Inventory* and *Sales* apps function standard to pull products out of
+inventory, and allow the user to create invoices.
 
-.. image:: setup/setup01.png
+.. seealso::
+   To learn more about the eBay connector visit these pages as well:
+
+   - :doc:`manage`
+   - :doc:`linking_listings`
+   - :doc:`troubleshooting`
+
+eBay - Odoo linked fields
+-------------------------
+
+The following are eBay product details. Each of these eBay fields update corresponding fields in
+Odoo.
+
+- eBay URL
+- eBay status
+- Quantity sold
+- Start date
+- Title
+- Subtitle
+- Item condition
+- Category
+- Category 2
+- Store category
+- Store category 2
+- Payment policy
+- Seller profiles
+- Postal code
+- Shipping policy
+- Listing type (fixed price or auction)
+
+  - Starting price for Auction
+  - Buy it now price
+  - Fixed Price amount
+
+- Use stock quantity
+- Quantity on eBay
+- Duration
+- Allow best offer
+- Private listing
+- eBay description
+- eBay product image
+- Country
+
+eBay terms
+----------
+
+*Variations* group multiple products into one, with variation (or variant) options. Variations can
+sync to Odoo's attributes and values. Variations will appear in drop down menus near the top of the
+page when viewing an eBay listing. These are comparable to product variants in Odoo.
+
+.. image:: setup/ebay-variation.png
   :align: center
+  :alt: An example on eBay of the variations that can be added to a product.
 
-After the creation of the keys, you can get the user token. To do so, click on
-the **Get a User Token** link in the bottom of the page. Go through the form,
-log in with you eBay account and you will get the keys and token needed to
-configure the module in Odoo.
+*Item specifics*, located at the bottom of the listing, detail product-specific information. These
+specifics don't sync with Odoo fields by default; a development is required to link these fields.
 
-Set up tokens in Odoo?
-======================
-
-To set up the eBay integration, go to :menuselection:`Sales --> Configuration --> Settings`.
-
-.. image:: setup/setup02.png
+.. image:: setup/item-specifics.png
   :align: center
+  :alt: Item specifics listed on an eBay product.
 
-First choose if you want to use the production or the sandbox eBay Site. Then
-fill in the fields **Developer Key**, **Token**, **App Key**, **Cert Key**.
-Apply the changes.
-
-Once the page is reloaded, you need to synchronize information from eBay. Push
-on **Sync countries and currencies**, then you can fill in all the other fields.
-
-When all the fields are filled in, you can synchronize the categories and the
-policies by clicking on the adequate buttons.
-
-Accept account deletion notifications
-=====================================
-
-Since September 2021, **eBay requires supporting customer account deletion/closure notifications**.
-As such, when eBay receives an account request for deletion, all eBay partners must confirm the
-reception of the request and take further action if necessary.
-
-Odoo has a notification endpoint to receive those notifications, confirm the reception of the
-request, and handle the first set of actions to anonymize the account details in **Contacts** and
-remove the customer's access to the portal.
-
-.. important::
-   Make sure to correctly :ref:`set up your subscription to the marketplace account deletion
-   notifications <ebay/subscribe-account-deletion-notifications>` as eBay may temporarily disable
-   the related eBay account until the subscription is completed.
-
-.. _ebay/retrieve-endpoint-details:
-
-Retrieve endpoint details from Odoo
------------------------------------
-
-The endpoint details can be found in :menuselection:`Sales --> Configuration --> Settings --> eBay`.
-Click on *Generate Token* to retrieve your **Verification Token**.
-
-.. image:: setup/verification-token.png
-   :align: center
-   :alt: Button to generate an eBay verification token in Odoo
-
-.. _ebay/subscribe-account-deletion-notifications:
-
-Subscribe to account deletion notifications
--------------------------------------------
-
-Log in on the `developer portal of eBay <https://go.developer.ebay.com/>`_ and go to **Alerts &
-Notifications**.
-
-.. image:: setup/ebay-your-account.png
-   :align: center
-   :alt: Overview of the Alerts & Notifications dashboard of eBay
-
-To subscribe to deletion/closure notifications, eBay needs a few details:
-
-- An **email address** to send notifications to if the endpoint is unreachable.
-- The **endpoint details**:
-
-  - The URL to Odoo's account deletion notification endpoint
-  - A verification token
-
-.. image:: setup/ebay-notification-endpoint.png
-   :align: center
-   :alt: Dedicated fields to enter the endpoint details
+*Sandbox* and *Production* are terms that are used to categorize the eBay environments as either
+still in development/testing (*Sandbox*) or for use in the real instance of the database with real
+customer information/dataset (*Production*). It is recommended to start first in the *Sandbox* to
+test, and then following the processes below, create a *Production* instance.
 
 .. tip::
-   You can edit the last two fields once the email address field is filled out.
+   eBay's sandbox environment can be accessed by navigating to `eBay's sandbox portal
+   <https://sandbox.ebay.com/>`_ at `https://sandbox.ebay.com/`. eBay's production environment can
+   be accessed by navigating to `eBay.com portal <https://www.ebay.com/>`_ or
+   `https://www.ebay.com/`.
 
-Verify the connectivity with the endpoint
------------------------------------------
+.. important::
+   The environment selection **must** remain the same for all environment settings on eBay and on
+   Odoo throughout this setup.
 
-After setting the retrieved endpoint details in eBay's dashboard, consider testing the connectivity
-with the **Send Test Notification** button.
+eBay actions available on Odoo
+------------------------------
 
-You should get the following confirmation message: "A test notification was sent successfully!"
+The following are built-in actions in Odoo that add or update eBay listings:
 
-.. image:: setup/test-notification.png
+- **List**/ **Link**: generate a new eBay listing with an Odoo product by clicking :guilabel:`List
+  Item on eBay` or :guilabel:`Link With Existing eBay Listing`.
+- :guilabel:`Revise item` button: after making changes to an eBay listing in Odoo, save the record,
+  and then click the :guilabel:`Revise Item` in Odoo to update the eBay listing.
+- **Relist**: if an item's listing was ended early or :guilabel:`auto-relist` was not selected, a
+  user can relist the item from Odoo. The start date will reset.
+- :guilabel:`End item's listing` button: end a listing on eBay directly from Odoo.
+- **Unlink product listings**: users can unlink a product from the eBay listing; the listing will
+  stay intact on eBay.
+
+Setup required on Odoo prior to eBay setup
+==========================================
+
+To link eBay with Odoo, install the eBay module by navigating to the Odoo dashboard and clicking
+into the :guilabel:`Apps` application. Search the term `eBay` and install the `eBay Connector`
+module.
+
+The following items must be configured before eBay is set up:
+
+- In Odoo, create and configure products that are intended to be listed in eBay. eBay does not
+  import new products into Odoo. All products must first be created in Odoo, and then linked to
+  listings.
+
+  - Odoo does not allow multiple eBay listings to be linked per product in Odoo. If the company
+    sells the same product for multiple listings, follow these instructions:
+
+    - Set up one *base* product (noted in the :guilabel:`Component` field of the :abbr:`BoM (Bill
+      of Materials)`) from which all eBay listings will pull from. This will be a storable product
+      so stock can be kept. Highlighted in green below, this product will be included in the kit on
+      each subsequent “linked” product below.
+
+    - Set up 2+ *linked* products (noted in the :guilabel:`Product` field of the :abbr:`BoM (Bill
+      of Materials)`, one for each eBay listing. The product type will be determined by the
+      company's accounting settings, as explained in the Odoo documentation. Highlighted in yellow
+      below, each product should have a :guilabel:`BoM type` equal to :guilabel:`Kit` and have the
+      base product as a :guilabel:`Component` of the kit. When this linked eBay product is sold, the
+      delivery order created will have the base product listed in lieu of the linked product.
+
+    .. image:: setup/products-odoo.png
+      :align: center
+      :alt: Setting up bill of materials with base product and linked products.
+
+   .. seealso::
+      :doc:`../../../inventory_and_mrp/manufacturing/management/bill_configuration/`
+
+- eBay does not automatically create invoices for eBay orders that get pushed into Odoo. Set
+  invoicing policy on eBay products: invoicing policy will dictate when the product can be invoiced.
+  Since most eBay users collect payment before the product is shipped, “invoice on ordered” will
+  allow users to mass create invoices for eBay orders every day.
+- Set the :guilabel:`Outgoing Shipments` route for the warehouse to :guilabel:`Deliver goods
+  directly (1 step)`.
+
+  .. warning::
+     When the :guilabel:`Outgoing Shipments` route is set to two or three steps, a known bug occurs:
+     eBay wrongly marks orders as delivered when the pick operation in Odoo is confirmed. The
+     expected behavior is to mark orders as delivered **after** the *delivery order* is confirmed.
+     This mislabeling prevents tracking numbers in eBay from being imported onto the delivery order.
+- If the Accounting/Invoicing apps are installed, practice registering payment and reconciling
+  invoices created from eBay orders with incoming eBay money.
+
+  .. seealso::
+     :doc:`../../..//finance/accounting/bank/reconciliation`
+
+- Generate a marketplace account deletion/closure notification token. To begin, navigate to
+  :menuselection:`Sales app --> Configuration --> Settings`. Under the :guilabel:`eBay` heading,
+  change the mode to :guilabel:`Production`, and input random text values for the
+  :guilabel:`Production Cert Key`. Then click the :guilabel:`Generate Token` button under the
+  :guilabel:`eBay Marketplace Account Deletion/Closure Notifications` section. This token will be
+  used during the setup on eBay for the deletion/closure notifications configuration.
+
+.. image:: setup/generate-token.png
    :align: center
-   :alt: Button to send test notification
+   :alt: Generate a verification token in Odoo.
 
-Using the updated synchronisation method
-========================================
+Set up on eBay
+==============
 
-If you have a lot of products, the eBay API can sometimes refuse some synchronization
-calls due to a time-based limit on the number of requests that eBay enforces.
+Set up eBay developer account
+-----------------------------
 
-To fix this issue, a new implementation mechanism has been developed; however this
-updated mechanism is disabled by default to avoid having the 2 systems running in
-parallel in existing installations.
+To start, create an eBay developer account via `eBay's developer portal
+<https://go.developer.ebay.com/>`_. This site requires a different login and password than the eBay
+account, though the same email address can be used to register. The verification to create a
+developer account is around 24 hours.
 
-To switch to the new synchronization mechanism:
+Set up eBay keyset
+------------------
 
-#. Activate the :ref:`developer mode <developer-mode>`.
-#. Go to :menuselection:`Settings --> Technical --> Scheduled Actions`
-#. Archive the old synchronization actions (both are named *Ebay: update product status*)
-#. Activate the new synchronization actions (*Ebay: get new orders* which runs every 15min by
-   default and *Ebay: synchronise stock (for 'get new orders' synchronisation)* which runs once a
-   day per default)
-#. Ensure that the **Next Execution Date** for both these actions are in the near future
+Once the eBay developer account is created, set up an application on `eBay's developer portal
+<https://go.developer.ebay.com/>`_. Next, navigate to the :guilabel:`Hi [username]` heading at top
+right of screen, then from the drop-down menu options, click :guilabel:`Application Keysets`. Doing
+so opens a pop-up that prompts the user to :guilabel:`Enter Application Title` (up to fifty
+characters), and choose a development environment (:guilabel:`Sandbox` or :guilabel:`Production`).
+These two fields generate first keyset. This application title is not saved until the keyset is
+generated. Click on :guilabel:`Create a keyset` to generate the keyset.
 
-Starting with the next execution date, the new method will be used instead of the old one.
+.. warning::
+   The newly created *production keyset* is disabled by default. Activate it by subscribing to the
+   eBay Marketplace 'account deletion or closure notifications' or by applying to eBay for an
+   exemption. Once enabled, the database can make 5000 calls per day using this keyset.
+
+.. image:: setup/disabled-keyset.png
+   :align: center
+   :alt: Disabled keyset present after creating a keyset.
+
+Configure account deletion / notification settings (Production)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To configure notifications or delete the database on a production environment, navigate to the `eBay
+developer portal <https://go.developer.ebay.com/>`_. Configure the account deletion/notification
+settings in eBay by navigating to the `Hi [username]` at top right of screen, then
+:guilabel:`Application Keysets`.
+
+Next, click the :guilabel:`marketplace deletion/account closure notification` option under the
+:guilabel:`Production` keyset column. Enter an email under :guilabel:`Email to notify if marketplace
+account deletion notification endpoint is down`. Click :guilabel:`Save` to enable the email.
+
+Following this action, enter the :guilabel:`Marketplace account deletion notification endpoint` URL
+provided by Odoo. This HTTPs endpoint is found in Odoo by navigating to :menuselection:`Sales app
+--> Configuration --> Settings`, in the :guilabel:`eBay Marketplace Account Deletion/Closure
+Notifications` field.
+
+Clicking the :guilabel:`Generate Token` button in Odoo below this field creates a verification token
+for the eBay production environment. In Odoo, :guilabel:`Copy` the newly created token and navigate
+to eBay to fill in the :guilabel:`Verification token` field. Click :guilabel:`Save` to enable the
+:guilabel:`Event Notification Delivery Method`.
+
+.. image:: setup/account-closure.png
+   :align: center
+   :alt: Configuring account deletion / notification settings in eBay.
+
+After completing the above fields, click :guilabel:`Send Test Notification` to test the new
+notifications. Proceed to the next step when the green check mark appears. Revisit the above
+settings if the test post is not as expected.
+
+After configuring notification settings, go back to the :menuselection:`Application Keys` page to
+generate production keysets.
+
+Creating the keyset
+~~~~~~~~~~~~~~~~~~~
+
+A successful setup of the notifications enables the ability to create Production Keysets which are
+needed in the remainder of the Odoo configuration. Navigate back to the :menuselection:`Application
+Keys` page generate a production keyset.
+
+The administrator is prompted to :menuselection:`Confirm the Primary Contact`. Enter or confirm the
+account owner (the person legally responsible for the eBay API License Agreement). Fill out
+:guilabel:`First Name`, :guilabel:`Last Name`, :guilabel:`Email`, :guilabel:`Phone`. Then, select
+either the :guilabel:`Individual` or :guilabel:`Business` options.
+
+.. note::
+   The provided email address or phone number does **not** have to match the account's. eBay uses
+   this information to contacting the business or individual in case of issues with user tokens.
+   Additional contacts can be added from the :guilabel:`Profile & Contacts` page on eBay.
+
+Click on :guilabel:`Continue to Create Keys` to confirm the primary contact. The
+:guilabel:`Application Keys` populates in a new screen and an email is also sent to the developer
+account. An :guilabel:`App ID (Client ID)`, :guilabel:`Dev ID`, and :guilabel:`Cert ID (Client
+Secret)` all populate.
+
+.. image:: setup/application-keys.png
+   :align: center
+   :alt: Application keys are populated after creating the app in eBay.
+
+Copy these values down as they will be input into Odoo later in the process.
+
+Create eBay user token
+----------------------
+
+Now, create a *user token* in eBay by navigating to the `Hi [username]` at top right of screen,
+then :guilabel:`User Access Tokens`.
+
+.. image:: setup/user-tokens.png
+   :align: center
+   :alt: Generate user token s on the eBay developer console.
+
+Select the correct :guilabel:`Environment`: :guilabel:`Sandbox` for testing or
+:guilabel:`Production` for the live database. Maintain the same selection for all environment
+settings on both eBay and Odoo.
+
+Next, select the radio button labeled :guilabel:`Auth'n'Auth`.
+
+Choose :guilabel:`Sign in to Production` or :guilabel:`Sign in to Sandbox` to get a user token in
+the chosen environment. This button varies based on the selection made above for either
+:guilabel:`Sandbox` or :guilabel:`Production`.
+
+Doing so triggers a a pop-up window to :guilabel:`Confirm your Legal Address`. Complete the required
+fields, which are :guilabel:`First Name`, :guilabel:`Last Name`, :guilabel:`Primary Email`,
+:guilabel:`Legal Address`, and :guilabel:`Account Type`. For :guilabel:`Account Type`, select either
+:guilabel:`Individual` or :guilabel:`Business`. To complete the confirmation, click :guilabel:`Sign
+into eBay to get a Token`.
+
+.. note::
+   eBay will contact this individual or business should there be any issues with the application
+   keys. Other contacts can be added on the :menuselection:`Profile & Contacts` eBay page.
+
+The administrator will be redirected to either a sandbox or production sign-in page for eBay. This
+login is different than the eBay developer's console, it is the eBay account where the items will be
+sold on. This email and/or login can differ from the eBay developer account.
+
+Enter the :guilabel:`Email` or :guilabel:`Username` for the eBay account and sign into the eBay
+account.
+
+.. important::
+   Should an additional user be needed for the sandbox simulation, a test user needs to be created.
+   Visit `eBay's Register for Sandbox form <https://developer.ebay.com/sandbox/register>`_. Detailed
+   instructions can be found on eBay's help pages: `Create a test Sandbox user
+   <https://developer.ebay.com/api-docs/static/gs_create-a-test-sandbox-user.html>`_.
+
+Grant application access
+------------------------
+
+After signing into the production or sandbox environment, eBay presents the administrator with an
+*agreement* to grant access to the user's eBay data.
+
+Clicking :guilabel:`Agree` allows eBay to link the eBay account with the *application programming
+interface* (API). This agreement can be changed at any time by visiting eBay's account preferences.
+
+.. warning::
+   eBay has a timed sequence between signing in and agreeing to the terms for the :abbr:`API
+   (Application Programming Interface)` linkage to the account. Once complete a :guilabel:`User
+   Token` will populate on the :menuselection:`User Tokens` page.
+
+A :guilabel:`User Token` will populate on the screen. Make sure to copy this token down as it will
+be used in the next steps along with the :guilabel:`Application Keyset`.
+
+.. image:: setup/user-token.png
+   :align: center
+   :alt: Generated user token and API explorer link on the eBay developer console.
+
+.. important::
+   Signing in to the eBay account is necessary to create to the token. The eBay developer can also
+   revoke the token by clicking on the :guilabel:`Revoke a Token` link.
+
+API explorer
+------------
+
+Now that the :guilabel:`Application Keyset` and :guilabel:`User Token` have been created, a test can
+be executed via the `API Explorer
+<https://developer.ebay.com/DevZone/build-test/test-tool/default.aspx>`_ to ensure that the
+:abbr:`API (Application Programming Interface)` is configured correctly. This test will execute a
+simple search using the :abbr:`API (Application Programming Interface)`.
+
+To begin the :abbr:`API (Application Programming Interface)` test, click on :guilabel:`Get OAuth
+Application Token`. This will populate the key into the :guilabel:`Token` field.
+
+A basic search function is set to execute. Click on :guilabel:`Execute` to complete the test. A
+successful test will respond with a :guilabel:`Call Response` of `200 OK` with a corresponding
+:guilabel:`Time`.
+
+Entering credentials into Odoo
+==============================
+
+The previously copied :guilabel:`User Token` and :guilabel:`Application Keyset` are now ready to be
+entered into the Odoo database.
+
+Navigate back the eBay settings in Odoo (:menuselection:`Sales app --> Configuration --> Settings
+--> eBay`) and paste the following credentials from eBay into the corresponding fields in Odoo.
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Platform
+     - Dev Key/ID
+     - Token
+     - App Key/ID
+     - Cert Key/ID
+   * - eBay
+     - Dev ID
+     - User Token
+     - App ID (Client ID)
+     - Cert ID (Client Secret)
+   * - Odoo
+     - Developer Key
+     - Production/Sandbox Token
+     - Production/Sandbox App Key
+     - Production/Sandbox Cert Key
+
+.. important::
+   The :guilabel:`Application Keyset` can be accessed by going to `eBay's developer portal
+   <https://go.developer.ebay.com/>`_ and navigate to the `Hi [username]` at top right of screen,
+   then click on :guilabel:`Application Keysets`. Get to the *User Token* in eBay by navigating to
+   the `Hi [username]` at top right of screen, then :guilabel:`User Access Tokens` and click on
+   :guilabel:`Sign in to Sandbox`. The :guilabel:`User Token` can also be accessed by clicking on
+   :guilabel:`User Tokens` from the :menuselection:`Application Keys` page.
+
+Confirm that the setup is correct by saving the credentials in Odoo. Once the initial setup is
+complete, a new menu tab in products will appear called `eBay` with the option to :guilabel:`Sell on
+eBay`. See the :doc:`manage` documentation on how to list products.
+
+.. tip::
+   Sync product categories by clicking :guilabel:`Product Categories`. After syncing, a new menu
+   item, `eBay Category`, appears available for products to be configured with. These eBay
+   categories are imported from the Odoo database and are available when listing an item on eBay
+   through Odoo.
+
+   .. important::
+      If Product Categories beyond four paths are required, users will need to manually add those
+      paths. This has historically been done by getting a list of all product categories beyond four
+      paths, manually importing them into the Product Category model in Odoo, and then linking them
+      individually to the product.
+
+.. seealso::
+   Now that the setup is complete, proceed to either:
+
+   - :doc:`Create listings <manage>`
+   - :doc:`Link existing listings <linking_listings>`

content/applications/sales/sales/ebay_connector/troubleshooting.rst

@@ -0,0 +1,129 @@
+==============================
+Troubleshooting eBay connector
+==============================
+
+.. seealso::
+   To learn more about the eBay connector visit these pages as well:
+
+   - :doc:`setup`
+   - :doc:`manage`
+   - :doc:`linking_listings`
+
+Accept account deletion notifications
+=====================================
+
+Since September 2021, **eBay requires supporting customer account deletion/closure notifications**.
+As such, when eBay receives an account request for deletion, all eBay partners must confirm the
+reception of the request and take further action if necessary.
+
+Odoo has a notification endpoint to receive those notifications, confirm the reception of the
+request, and handle the first set of actions to anonymize the account details in *Contacts* and
+remove the customer's access to the portal.
+
+.. important::
+   Make sure to correctly :ref:`set up the subscription to the marketplace account deletion
+   notifications <ebay/subscribe-account-deletion-notifications>` as eBay may temporarily disable
+   the related eBay account until the subscription is completed.
+
+Verify the installation of Odoo is up to date
+---------------------------------------------
+
+In order to activate the endpoint, the module *eBay Connector - Account Deletion* must be installed.
+If the Odoo database was first created after September 2021, the module is installed automatically
+and the administrator can proceed to the :ref:`next step <ebay/retrieve-endpoint-details>`.
+
+Update Odoo to the latest release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The notification endpoint is made available through a new Odoo module; to be able to install it, the
+administrator must make sure that the Odoo source code is up-to-date.
+
+- If the company uses Odoo on Odoo.com or Odoo.sh platform, the code is already up-to-date, so
+  proceed to the next step.
+- If the company uses Odoo with an on-premise setup or through a partner, then the administrator
+  must update the installation as detailed in :doc:`this documentation page
+  </administration/maintain/update>` or by contacting an integrating partner.
+
+Update the list of available modules
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+New modules must be *discovered* by the Odoo instance to be available in the :menuselection:`Apps`
+menu.
+
+To do so, activate the :ref:`developer mode <developer-mode>`, and go to :menuselection:`Apps ->
+Update Apps List`. A wizard will ask for confirmation.
+
+Install the eBay Connector - Account Deletion update
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+   **Never** install new modules in the production database without testing them in a duplicate or
+   staging environment. For Odoo.com customers, a duplicate database can be created from the
+   database management page. For Odoo.sh users, the administrator should use a staging or duplicate
+   database. For on-premise users, the administrator should use a staging environment - contact the
+   integrating partner for more information regarding how to test a new module in a particular
+   setup.
+
+To install the module, go to the :menuselection:`Apps` menu, remove the `Apps` search facet and
+search for `eBay`. If the module *eBay Connector - Account Deletion* is present and marked as
+installed, the Odoo database is already up-to-date and the administrator can proceed with the next
+step. If it is not yet installed, install it now.
+
+.. _ebay/retrieve-endpoint-details:
+
+Retrieve endpoint details from Odoo
+-----------------------------------
+
+The endpoint details can be found in :menuselection:`Sales --> Configuration --> Settings --> eBay`.
+First, input random text values for the :guilabel:`Production App Key` and for the
+:guilabel:`Production Cert Key`. Click on :guilabel:`Generate Token` to retrieve the
+:guilabel:`Verification Token`.
+
+.. image:: troubleshooting/generate-token.png
+   :align: center
+   :alt: Generate a verification token in Odoo.
+
+.. _ebay/subscribe-account-deletion-notifications:
+
+Subscribe to account deletion notifications
+-------------------------------------------
+
+Navigate to the `eBay developer portal <https://go.developer.ebay.com/>`_. Configure the account
+deletion/notification settings in eBay by navigating to the `Hi [username]` at the top right of
+screen, then go to :guilabel:`Alerts & Notifications`.
+
+.. image:: troubleshooting/ebay-your-account.png
+   :align: center
+   :alt: Overview of the Alerts & Notifications dashboard of eBay
+
+To subscribe to deletion/closure notifications, eBay needs a few details:
+
+- An *email address* to send notifications to if the endpoint is unreachable.
+- The *endpoint details*:
+
+  - The URL to Odoo's account deletion notification endpoint
+  - A verification token
+
+.. image:: troubleshooting/ebay-notification-endpoint.png
+   :align: center
+   :alt: Dedicated fields to enter the endpoint details
+
+.. tip::
+   The administrator can edit the last two fields once the email address field is filled out.
+
+Verify the connectivity with the endpoint
+-----------------------------------------
+
+After setting the retrieved endpoint details in eBay's dashboard, consider testing the connectivity
+with the :guilabel:`Send Test Notification` button.
+
+ The following confirmation message should be received: "A test notification was sent successfully!"
+
+.. image:: troubleshooting/test-notification.png
+   :align: center
+   :alt: Button to send test notification
+
+.. seealso::
+   - :doc:`/applications/sales/sales/ebay_connector/manage`
+   - :doc:`/applications/sales/sales/ebay_connector/linking_listings`
+   - :doc:`/applications/sales/sales/ebay_connector/setup`