Merge pull request #2308 from spryker/vertex-overview

Vertex overview page

_data/sidebars/pbc_all_sidebar.yml

@@ -3641,6 +3641,10 @@ entries:
                         - "202311.0"
                       - title: Disconnect Vertex
                         url: /docs/pbc/all/tax-management/base-shop/third-party-integrations/vertex/disconnect-vertex.html
+                      - title: Vertex FAQ
+                        url: /docs/pbc/all/tax-management/base-shop/third-party-integrations/vertex/vertex-faq.html
+                        include_versions:
+                        - "202311.0"
           - title: Marketplace
             include_versions:
             - "202212.0"

_data/sidebars/scos_user_sidebar.yml

@@ -110,7 +110,7 @@ entries:
         url: /docs/scos/user/intro-to-spryker/spryker-marketplace/marketplace-personas.html
       - title: Back Office for Marketplace Operator
         url: /docs/scos/user/intro-to-spryker/spryker-marketplace/back-office-for-marketplace-operator.html
-      - title: Merchant onborading
+      - title: Merchant onboarding
         url: /docs/scos/user/intro-to-spryker/spryker-marketplace/merchant-onboarding.html
       - title: Marketplace Storefront
         url: /docs/scos/user/intro-to-spryker/spryker-marketplace/marketplace-storefront.html

docs/pbc/all/tax-management/202311.0/base-shop/third-party-integrations/vertex/configure-vertex.md

@@ -12,7 +12,7 @@ Once you have [integrated the Vertex app](/docs/pbc/all/tax-management/{{page.ve
 Before configuring Vertex, ensure the following prerequisites are met:
 
 - You have an account with [Vertex](https://www.vertexinc.com/). Contact the Spryker Support team or your Customer Success Manager if you need support getting a Vertex account.
-- Company Code is set up in Vertex and added to your project. See the Guidelines LINK for more details.
+- Company Code is set up in Vertex and added to your project. See the [information about Company code](#company-code) for more details.
 - You removed the default tax rate value from the Back Office. When you use Vertex to determine taxes, the tax rate received from Vertex does not overwrite the existing tax rate values in the Back Office. Therefore, before using Vertex, we recommend removing the default values from the Back Office. To remove the default tax rates, in your store's Back Office, go to **Administration -> Tax rates** and delete the tax rates.
 
 ## Configure Vertex
@@ -32,6 +32,8 @@ To configure Vertex, do the following:
 
 ![vertex-configuration](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/configure-vertex/vertex-configuration.png)
 
+<a name="company-code"></a>
+
 {% info_block infoBox "Company code" %}
 
 Vertex expects to receive the Company Code you have set in Vertex from Spryker and use it to determine taxes. Although the Company Code field is not currently included in the Vertex app configuration page, we recommend that you provide this code as [Quote/Order TaxMetadata](/docs/pbc/all/tax-management/202311.0/third-party-integrations/vertex/install-vertex.html#reference-quoteorder-object-to-vertex-api-mapping) in your projects.
@@ -41,6 +43,12 @@ Vertex expects to receive the Company Code you have set in Vertex from Spryker a
 
 ## Configuration verification
 
+{% info_block warningBox "Test the configuration" %}
+
+To ensure accuracy and compiance with tax laws, We highly recommend to thoroughly test the Vertex integration.
+
+{% endinfo_block %}
+
 Once you have configured Vertex, the taxes are calculated in real time in the checkout. The respective note appears on the checkout page.
 
 ![vertex_checkout_page](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/configure-vertex/vertex_checkout_page.png)

docs/pbc/all/tax-management/202311.0/base-shop/third-party-integrations/vertex/vertex-faq.md

@@ -0,0 +1,20 @@
+---
+title: Vertex FAQ
+description: FAQ about Vertex 
+template: concept-topic-template
+---
+
+**What is a Product Class Code for Vertex, and how can we use it?**
+The Product Class Code is used to represent groups or categories of products or services with identical taxability. By default, Spryker Product SKU is sent as `LineItems[].product.value` and `LineItems.lineItemId. Keep in mind that the Vertex App doesn't create any Vertex Tax Categories.
+
+**How should we use Item Flexible Fields? Should it contain some Product Class Code? Should we provide some class codes for order expenses as well?**
+​Item Flexible Fields are optional fields provided by a project. They are needed for customization of tax calculation. Flexible Fields are supported by the Vertex app, and whether or not to use them is a business decision.
+
+**How will stock address information be used in the Marketplace? Does it calculate freight tax for shipment?**
+
+We do not support freight shipment in terms of big packaging support, but if it’s about just calculating taxes for shipping price, yes, it’s supported.
+
+**Could you share more information about sending invoices to Vertex through the OMS feature?**
+
+The Spryker OMS transition command has to be used as an execution point to send a full order with all existing and custom fields provided by the project. The results will be visible in the Invoice Tax Details report.
+

docs/pbc/all/tax-management/202311.0/base-shop/third-party-integrations/vertex/vertex.md

@@ -13,12 +13,79 @@ redirect_from:
 
 ![vertex-hero](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/vertex.md/vertex-hero.png)
 
-*Vertex O Series* is a software that delivers the latest sales and use tax calculations to your shopping cart or invoicing system at the point of purchase while accounting for the following:
+The Spryker-Vertex integration is part of the tax Category of Spryker’s App Composition Platform. This integration is built with support for both the default Storefront as well as Spryker’s GLUE APIs. For more information about Vertex, see the [Vertex website](https://www.vertexinc.com/).
+
+The Spryker Vertex app, constructed on the basis of the *Vertex O Series* software, performs automatic, near-real-time tax calculations at the point of purchase while accounting for the following:
 
 * Tax rates in each state, county, and city.  
 * Laws, rules, and jurisdiction boundaries.  
 * Special circumstances like tax holidays and product exemptions.
 
+For more information about how Vertex calculates taxes, see the [Vertex O Series website](https://www.vertexinc.com/solutions/products/vertex-indirect-tax-o-series).
+
+The Spryker Vertex app offers the following features that are worth considering when comparing it to the default Spryker [Tax Management capability](/docs/pbc/all/tax-management/{{page.version}}/tax-management.html):
+
+- *Compliance in states or countries with complex tax calculations*: Takes into account various tax jurisdictions and rates applicable to different states and countries. This helps a lot with tax calculations if you sell in states or countries where tax calculations are complex. 
+- *Dynamic tax calculation*: As tax rules or rates change in Vertex, these changes are applied to customer’s quote during the checkout process.
+- *Reduction of manual errors*: Helps to automate tax calculations, hence reducing manual errors and saving time.
+- *Tax exemption management*: You can manage tax exemptions and certificates efficiently, ensuring that exempt customers are not charged taxes during the checkout process while maintaining proper documentation.
+- *Tax reporting and filing*: You have the option of sending invoice requests to Vertex after an order is paid. You can generate accurate tax reports, which helps in the filing of sales tax returns across multiple jurisdictions, reducing the risk of audit and penalties.
+- *Application of custom tax rules to products*: You can implement custom tax rules to accommodate unique product categorizations or specific tax regulations that apply to your business. The Vertex Integration provides a means for taxes to be calculated using these rules.
+
+## Using the Vertex app in Spryker projects
+
+To start using the Spryker Vertex app in your project, you need to do the following:
+
+1. Since the Vertex integration in Spryker is built on Spryker’s App Composition Platform (ACP) as an ACP application, make sure your project is ACP-enabled. See [App Composition Platform installation](/docs/acp/user/app-composition-platform-installation.html) for details.
+2. Make sure you use NET prices in your project, as Vertex app only works with NET prices. GROSS prices aren't supported.
+3. Get an account with [Vertex](https://www.vertexinc.com/). Contact the Spryker Support team or your Customer Success Manager if you need support getting a Vertex account.
+4. Install the Vertex app. See [Install Vertex](/docs/pbc/all/tax-management/{{page.version}}/base-shop/third-party-integrations/vertex/install-vertex.html) for details.
+5. Configure the Vertex app. See [Configure Vertex](/docs/pbc/all/tax-management/{{page.version}}/base-shop/third-party-integrations/vertex/configure-vertex.html) for details.
+
+Once you have installed and configured the Vertex app, the taxes will be calculated by Vertex during the checkout process. See this video to understand the experience for the end user:
+
+![vertex-demo](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/vertex.md/Vertex+Demo.mp4)
+
+By default, the following data is sent to Vertex for tax calculation:
+
+ - Shipping address
+ - Product SKU
+ - Warehouse address that also includes the Merchant warehouse address for a Marketplace model
+
+{% info_block infoBox "Company code" %}
+
+Vertex uses a hierarchy structure for tax determination. The highest in the structure is the Company code. Therefore, it is important to set up your company code in Vertex and add it on your project as it determines what rate applies. For information about how to add the Company code, see [Configure Vertex]((/docs/pbc/all/tax-management/{{page.version}}base-shop/third-party-integrations/vertex/configure-vertex.html#company-code)).
+
+{% endinfo_block %}
+
+Thus, the buyers see the tax amount calculated by Vertex during the checkout after they have provided their shipping address.
+The Back Office users can see the taxes calculated by Vertex on the order details page.
+
+{% info_block infoBox "Default tax values in the Back Office" %}
+
+Keep in mind that when using Vertex for tax determination, no exact tax rate is received from Vertex instead of a default tax value in the Back Office. Therefore, to avoid confusion, we recommend removing the default tax rate that appears in the Back Office. 
+
+When the Vertex integration isn’t working, SCCOS displays the default tax, provided the plugins for Tax Calculation aren't disabled. This solution applies to the following errors:
+- Timeout error
+- Shipping address error
+
+
+{% endinfo_block %}
+
+The following diagram demonstrates the flow of the Vertex app integration:
+
+![vertex-app-flow](https://spryker.s3.eu-central-1.amazonaws.com/docs/pbc/all/tax-management/vertex/vertex.md/vertex-app-flow.png)
+
+
+### Vertex app configuration options
+
+You can configure the Vertex app so that the invoice is saved in Vertex. However, we recommend to send invoice requests only for paid orders, as specified in [Vertex installation](https://docs.spryker.com/docs/pbc/all/tax-management/{{page.version}}/base-shop/third-party-integrations/vertex/install-vertex.html#optional-if-you-plan-to-send-invoices-to-vertex-through-oms-configure-your-payment-oms). The current implementation works asynchronously hence no response is saved in SCCOS.
+
+If you want to include other data, such as Customer Exemption Certificate in the requests to Vertex, you can do so via plugins and the `taxMetadata` fields. You can add more data to request any specific information that is not available in Spryker by default. For example, this could be data from ERP, other systems, and customized Spryker instances. For the implementation details, see [Vertex installation](https://docs.spryker.com/docs/pbc/all/tax-management/202311.0/base-shop/third-party-integrations/vertex/install-vertex.html#implement-vertex-specific-metadata-extender-plugins).
+
+
+If you still have questions about the Spryker Vertex app, see the [Vertex FAQ](/docs/pbc/all/tax-management/{{page.version}}/base-shop/third-party-integrations/vertex/vertex-faq.html), which provides clarification on several aspects. 
+
 ## Next steps
 
 [Install Vertex](/docs/pbc/all/tax-management/{{site.version}}/vertex/install-vertex.html)

docs/pbc/all/tax-management/202311.0/tax-management.md

@@ -4,6 +4,16 @@ description: Tax Management PBC lets you define tax rates for different stores a
 template: concept-topic-template
 ---
 
-Tax Management lets you manage taxes per store, product, and country.
+The default Spryker Tax Management capability lets you manage taxes per store, product, and country.
 
 The capability consists of a base shop and the marketplace addon. The base shop features are needed for running a regular shop in which your company is the only entity fulfilling orders. To run a marketplace, the features from both the base shop and the marketplace addon are required.
+
+We recommend using the Spryker OOTB Tax Capability if the following applies:
+
+- You are operating in regions such as the European Union where tax rates aren't as complex as compared to other regions such as North America.
+- You want to import or manually create tax rates in Spryker.
+- You have both NET prices and GROSS prices and don't need an external system to determine taxes.
+- You want to manually manage changes in Tax Rates.
+- You do not want to send or record invoices in an external tax system.
+
+However, if you need a solution that would automatically calculate taxes in near real-time, taking into account country-specific tax rates, laws, rules, etc., we recommend using the [Vertex app](/docs/pbc/all/tax-management/{{page.version}}/base-shop/third-party-integrations/vertex/vertex.html) or [Avalara](/docs/pbc/all/tax-management/{{page.versoin}}/base-shop/third-party-integrations/avalara/avalara.html) instead of the default Spryker Tax Management capability.