diff --git a/content/applications/sales/sales/ebay_connector.rst b/content/applications/sales/sales/ebay_connector.rst index 06581117a..aa6086f09 100644 --- a/content/applications/sales/sales/ebay_connector.rst +++ b/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 diff --git a/content/applications/sales/sales/ebay_connector/linking_listings.rst b/content/applications/sales/sales/ebay_connector/linking_listings.rst new file mode 100644 index 000000000..f1a91f0d8 --- /dev/null +++ b/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 `. 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? + ` + +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 ` 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` diff --git a/content/applications/sales/sales/ebay_connector/manage.rst b/content/applications/sales/sales/ebay_connector/manage.rst index cb14ea245..754e4d691 100644 --- a/content/applications/sales/sales/ebay_connector/manage.rst +++ b/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` diff --git a/content/applications/sales/sales/ebay_connector/manage/fixed-listing-price.png b/content/applications/sales/sales/ebay_connector/manage/fixed-listing-price.png new file mode 100644 index 000000000..6de317a76 Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/manage/fixed-listing-price.png differ diff --git a/content/applications/sales/sales/ebay_connector/manage/manage-ebay-template.png b/content/applications/sales/sales/ebay_connector/manage/manage-ebay-template.png new file mode 100644 index 000000000..07c6abc17 Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/manage/manage-ebay-template.png differ diff --git a/content/applications/sales/sales/ebay_connector/manage/manage01.png b/content/applications/sales/sales/ebay_connector/manage/manage01.png deleted file mode 100644 index eba851fe9..000000000 Binary files a/content/applications/sales/sales/ebay_connector/manage/manage01.png and /dev/null differ diff --git a/content/applications/sales/sales/ebay_connector/manage/manage02.png b/content/applications/sales/sales/ebay_connector/manage/manage02.png deleted file mode 100644 index 8fc878886..000000000 Binary files a/content/applications/sales/sales/ebay_connector/manage/manage02.png and /dev/null differ diff --git a/content/applications/sales/sales/ebay_connector/manage/manage03.png b/content/applications/sales/sales/ebay_connector/manage/manage03.png deleted file mode 100644 index b49b43e41..000000000 Binary files a/content/applications/sales/sales/ebay_connector/manage/manage03.png and /dev/null differ diff --git a/content/applications/sales/sales/ebay_connector/setup.rst b/content/applications/sales/sales/ebay_connector/setup.rst index fbe36ad2f..0998b629e 100644 --- a/content/applications/sales/sales/ebay_connector/setup.rst +++ b/content/applications/sales/sales/ebay_connector/setup.rst @@ -1,170 +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 `_. -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 ` 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 ` as eBay may temporarily disable - the related eBay account until the subscription is completed. - -Verify your installation of Odoo is up to date ----------------------------------------------- - -In order to activate the endpoint, the module **eBay Connector - Account Deletion** must be -installed. If your Odoo database was first created after September 2021, the module is installed -automatically and you can proceed to the :ref:`next step `. - -Update Odoo to the latest release -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The notification endpoint is made available through a new Odoo module; to be able to install it, -you must make sure that your Odoo source code is up-to-date. - -- If you use Odoo on Odoo.com or Odoo.sh platform, your code is already up-to-date and you can - proceed to the next step. -- If you use Odoo with an on-premise setup or through a partner, then you must update your - installation as detailed in :doc:`this documentation page ` or by - contacting your integrating partner. - -Update the list of available modules -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -New modules must be *discovered* by your Odoo instance to be available in the :menuselection:`Apps` -menu. - -To do so, activate the :ref:`developer mode `, and go to :menuselection:`Apps -> -Update Apps List`. A wizard will ask for confirmation. - -Install the eBay Connector - Account Deletion update -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. warning:: - You should never install new modules in your 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, you should use a staging or duplicate - database. For on-premise users, you should use a staging environment - you should contact your - integrating partner for more information regarding how to test a new module in your 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, your Odoo database is already up-to-date and you 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`. -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 `_ 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 + `_ at `https://sandbox.ebay.com/`. eBay's production environment can + be accessed by navigating to `eBay.com portal `_ 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 +`_. 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 `. -#. 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 +`_. 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 `_. 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 `_. Detailed + instructions can be found on eBay's help pages: `Create a test Sandbox user + `_. + +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 +`_ 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 + `_ 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 ` + - :doc:`Link existing listings ` diff --git a/content/applications/sales/sales/ebay_connector/setup/account-closure.png b/content/applications/sales/sales/ebay_connector/setup/account-closure.png new file mode 100644 index 000000000..541f43318 Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/setup/account-closure.png differ diff --git a/content/applications/sales/sales/ebay_connector/setup/application-keys.png b/content/applications/sales/sales/ebay_connector/setup/application-keys.png new file mode 100644 index 000000000..476f5b061 Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/setup/application-keys.png differ diff --git a/content/applications/sales/sales/ebay_connector/setup/disabled-keyset.png b/content/applications/sales/sales/ebay_connector/setup/disabled-keyset.png new file mode 100644 index 000000000..293a03f53 Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/setup/disabled-keyset.png differ diff --git a/content/applications/sales/sales/ebay_connector/setup/ebay-variation.png b/content/applications/sales/sales/ebay_connector/setup/ebay-variation.png new file mode 100644 index 000000000..f97886743 Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/setup/ebay-variation.png differ diff --git a/content/applications/sales/sales/ebay_connector/setup/ebay-your-account.png b/content/applications/sales/sales/ebay_connector/setup/ebay-your-account.png deleted file mode 100644 index 73a02a1c4..000000000 Binary files a/content/applications/sales/sales/ebay_connector/setup/ebay-your-account.png and /dev/null differ diff --git a/content/applications/sales/sales/ebay_connector/setup/generate-token.png b/content/applications/sales/sales/ebay_connector/setup/generate-token.png new file mode 100644 index 000000000..91b1f9f95 Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/setup/generate-token.png differ diff --git a/content/applications/sales/sales/ebay_connector/setup/item-specifics.png b/content/applications/sales/sales/ebay_connector/setup/item-specifics.png new file mode 100644 index 000000000..27ad1bf40 Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/setup/item-specifics.png differ diff --git a/content/applications/sales/sales/ebay_connector/setup/products-odoo.png b/content/applications/sales/sales/ebay_connector/setup/products-odoo.png new file mode 100644 index 000000000..a6dc3962b Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/setup/products-odoo.png differ diff --git a/content/applications/sales/sales/ebay_connector/setup/setup01.png b/content/applications/sales/sales/ebay_connector/setup/setup01.png deleted file mode 100644 index 6b0fa8f09..000000000 Binary files a/content/applications/sales/sales/ebay_connector/setup/setup01.png and /dev/null differ diff --git a/content/applications/sales/sales/ebay_connector/setup/setup02.png b/content/applications/sales/sales/ebay_connector/setup/setup02.png deleted file mode 100644 index 6c99ac35b..000000000 Binary files a/content/applications/sales/sales/ebay_connector/setup/setup02.png and /dev/null differ diff --git a/content/applications/sales/sales/ebay_connector/setup/user-token.png b/content/applications/sales/sales/ebay_connector/setup/user-token.png new file mode 100644 index 000000000..70fe2c9e3 Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/setup/user-token.png differ diff --git a/content/applications/sales/sales/ebay_connector/setup/user-tokens.png b/content/applications/sales/sales/ebay_connector/setup/user-tokens.png new file mode 100644 index 000000000..2d409270f Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/setup/user-tokens.png differ diff --git a/content/applications/sales/sales/ebay_connector/troubleshooting.rst b/content/applications/sales/sales/ebay_connector/troubleshooting.rst new file mode 100644 index 000000000..41469e672 --- /dev/null +++ b/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 ` 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 `. + +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 + ` 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 `, 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 `_. 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` diff --git a/content/applications/sales/sales/ebay_connector/setup/ebay-notification-endpoint.png b/content/applications/sales/sales/ebay_connector/troubleshooting/ebay-notification-endpoint.png similarity index 100% rename from content/applications/sales/sales/ebay_connector/setup/ebay-notification-endpoint.png rename to content/applications/sales/sales/ebay_connector/troubleshooting/ebay-notification-endpoint.png diff --git a/content/applications/sales/sales/ebay_connector/troubleshooting/ebay-your-account.png b/content/applications/sales/sales/ebay_connector/troubleshooting/ebay-your-account.png new file mode 100644 index 000000000..d949bbb1a Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/troubleshooting/ebay-your-account.png differ diff --git a/content/applications/sales/sales/ebay_connector/troubleshooting/generate-token.png b/content/applications/sales/sales/ebay_connector/troubleshooting/generate-token.png new file mode 100644 index 000000000..91b1f9f95 Binary files /dev/null and b/content/applications/sales/sales/ebay_connector/troubleshooting/generate-token.png differ diff --git a/content/applications/sales/sales/ebay_connector/setup/test-notification.png b/content/applications/sales/sales/ebay_connector/troubleshooting/test-notification.png similarity index 100% rename from content/applications/sales/sales/ebay_connector/setup/test-notification.png rename to content/applications/sales/sales/ebay_connector/troubleshooting/test-notification.png diff --git a/content/applications/sales/sales/ebay_connector/setup/verification-token.png b/content/applications/sales/sales/ebay_connector/troubleshooting/verification-token.png similarity index 100% rename from content/applications/sales/sales/ebay_connector/setup/verification-token.png rename to content/applications/sales/sales/ebay_connector/troubleshooting/verification-token.png