DEVDOCS-6056 [new]: Price Lists / MSF International Enhancements, add tax inclusive price lists

docs/store-operations/pricing/msf-international-enhancements.mdx

@@ -0,0 +1,94 @@
+# Price Lists - International Enhancements for Multi-Storefront
+
+<Callout type="info">
+  Tax-inclusive or exclusive price lists are in beta. Features may change based on user feedback or internal testing.
+</Callout>
+
+_International Enhancements for Multi-Storefront_ allow you to deliver localized experiences to fit different shopper needs. 
+
+Shoppers expect storefront prices to include or exclude tax depending on their region when you sell internationally. 
+
+When you create separate storefront channels for each region, you may need some storefronts to display prices that include tax, while others display prices that exclude tax.
+
+To do so, specify whether a price list has prices that include or exclude tax when entered. Then assign the price list to storefront channels.
+
+## Limitations
+
+- Stores using [Catalog V2](/docs/store-operations/catalog/migration) have fixed pricing and will use global store settings. 
+- You cannot enter price changes due to product modifier rules, gift wrapping features, and fixed shipping prices into a price list. These inherit global settings and always apply on top of the price list.
+- You cannot mix inclusive and exclusive pricing within a single price list.
+- You must [set the display price](https://support.bigcommerce.com/s/article/Product-Display-Settings?language=en_US#settings) to the lowest variant price when a shopper's preselected options don't match to a price. 
+
+If your store doesn't have multiple storefronts, you can still create tax-inclusive or exclusive price lists and assign them to customer groups.
+
+## Settings
+
+Price lists will have a `prices_entered_with_tax` setting, which overrides the (default) global store setting. Use this setting to choose whether the price list is tax-inclusive or exclusive, or inherits the global settings. For details, see the [Price List endpoints](/docs/rest-management/price-lists) in the REST Management APIs.
+
+When you're using tax-inclusive price lists, tax-inclusive prices remain the same across all tax zones; the tax amount will vary based on the shopper's location. 
+
+If you're inheriting global tax settings, there is an additional option for tax-inclusive prices. The store can subtract the item's store tax rate before calculating tax using the shopper's tax zone. For information on the global settings, see the [Tax Settings](/docs/rest-management/tax-settings) endpoint of the REST Management API. 
+
+## Example
+
+The following example creates a tax-inclusive price list by sending a request to the [Create a Price List](/docs/rest-management/price-lists#create-a-price-list) endpoint. 
+
+<Tabs items={['Request', 'Response']}>
+  <Tab>
+
+  ```http filename="Example request: Create a tax-inclusive price list" showLineNumbers copy
+  POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/pricelists
+  X-Auth-Token: {{ACCESS_TOKEN}}
+  Accept: application/json
+  Content-Type: application/json
+
+  {
+    "name": "Wholesale",
+    "active": true,
+    "prices_entered_with_tax": "entered_inclusive"
+  }
+  ```
+
+  </Tab>
+  <Tab>
+
+  ```json filename="Example response: Create a tax-inclusive price list" showLineNumbers copy
+  {
+    "data": {
+      "id": 4,
+      "name": "Wholesale Group - Trade Show",
+      "date_created": "2022-09-17T18:41:59Z",
+      "date_modified": "2022-09-17T18:41:59Z",
+      "active": false,
+      "prices_entered_with_tax": "entered_inclusive"
+    },
+    "meta": {}
+  }
+  ```
+
+  </Tab>
+</Tabs>
+
+
+## Fallback behavior
+
+The following fallback behavior applies if you set a product as available for purchase, but the price list doesn't have a price entered for the product.
+
+When a price list inherits global settings: 
+- Price lists will default to catalog prices if a price is missing. 
+
+When a price list overrides the global store setting:
+- Prices returned will be `null` if a price is missing in the price list. This applies for the prices returned in the [Pricing](/docs/rest-management/pricing/products) endpoint of the REST Management API and the [GraphQL Storefront API](/docs/storefront/graphql). 
+- On Stencil storefronts, the product, but not the price, will still be visible. You won't be able to purchase it, but you can still add to wishlist.
+
+<Callout type="info">
+  [Update your Stencil theme](https://support.bigcommerce.com/s/article/Marketplace-Theme-Updates) for your Stencil storefront to display these features. 
+</Callout>
+
+## Additional resources
+
+- [Introduction to Multi-Storefront](/docs/storefront/multi-storefront)
+- [Price Lists](/docs/store-operations/pricing/price-lists) overview
+- [Tax Settings](/docs/rest-management/tax-settings) endpoint reference
+- [Pricing](/docs/rest-management/pricing/products) endpoint reference
+- [Update your Stencil theme](https://support.bigcommerce.com/s/article/Marketplace-Theme-Updates) support article

docs/store-operations/tax/index.mdx

@@ -4,7 +4,7 @@ Tax settings allow you to choose how a store handles tax calculation and price d
 
 ## Estimate taxes and display prices based on tax zone
 
-The Tax Settings API supports cross-border transactions. You can localize storefront prices for shoppers from different regions. For example, you can display tax-inclusive or exclusive prices depending on the tax zone. This benefits single-storefront stores that sell to shoppers from different regions. This functionality applies to Stencil and GraphQL-powered storefronts.
+The Tax Settings API supports cross-border transactions. You can localize storefront prices for shoppers from different regions. For example, you can display tax-inclusive or exclusive prices depending on the tax zone. These global tax settings benefit single-storefront stores that sell to shoppers from different regions. If your store has multiple storefronts, see the [Price Lists - International Enhancements for Multi-Storefront](/docs/store-operations/pricing/price-lists-international-enhancements-for-multi-storefront) overview for price display settings. This functionality applies to Stencil and GraphQL-powered storefronts.
 
 To support cross-border transactions, the store identifies a tax zone for the shopper. The store then applies the tax zone and its settings to estimate taxes and display prices. For logged-in customers, the store uses the customer address to identify the tax zone. For guest shoppers, the store can use the shopper's geolocation to identify the zone if you enable this setting. Otherwise, the store uses the provided guest shopper tax zone ID.
 

reference/price_lists.v3.yml

@@ -77,7 +77,12 @@ paths:
       tags:
         - Price Lists
       summary: Get All Price Lists
-      description: Returns a list of *Price Lists*. Optional parameters can be passed in.
+      description: |
+        Returns a list of *Price Lists*. Optional parameters can be passed in.
+
+        > #### Beta
+        > * The `prices_entered_with_tax` setting is in beta.
+        > * For more information on this setting, see [Price Lists - International Enhancements for Multi-Storefront](/docs/store-operations/pricing/price-lists-international-enhancements-for-multi-storefront).
       operationId: getPriceLists
       parameters:
         - name: name
@@ -186,6 +191,14 @@ paths:
                               description: |
                                 Boolean value that specifies whether this `Price List` and its prices are active or not. Defaults to `true`.
                               example: true
+                            prices_entered_with_tax:
+                              type: string
+                              description: Specifies whether the entered prices include or exclude tax. You can also use global settings or override them.
+                              enum:
+                                - use_global
+                                - entered_inclusive
+                                - entered_exclusive
+                              default: use_global
                           description: Specifies the Common Price List properties.
                   meta:
                     title: Collection Meta
@@ -256,6 +269,10 @@ paths:
 
         **Required Fields**
         * name
+
+        > #### Beta
+        > * The `prices_entered_with_tax` setting is in beta.
+        > * For more information on this setting, see [Price Lists - International Enhancements for Multi-Storefront](/docs/store-operations/pricing/price-lists-international-enhancements-for-multi-storefront).
       operationId: createPriceList
       parameters:
         - $ref: '#/components/parameters/ContentType'
@@ -282,6 +299,14 @@ paths:
                       description: |
                         Boolean value that specifies whether this `Price List` and its prices are active or not. Defaults to `true`.
                       example: true
+                    prices_entered_with_tax:
+                      type: string
+                      description: Specifies whether the entered prices include or exclude tax. You can also use global settings or override them.
+                      enum:
+                        - use_global
+                        - entered_inclusive
+                        - entered_exclusive
+                      default: use_global
                   description: Specifies the Common Price List properties.
         required: true
       responses:
@@ -331,6 +356,14 @@ paths:
                             description: |
                               Boolean value that specifies whether this `Price List` and its prices are active or not. Defaults to `true`.
                             example: true
+                          prices_entered_with_tax:
+                            type: string
+                            description: Specifies whether the entered prices include or exclude tax. You can also use global settings or override them.
+                            enum:
+                              - use_global
+                              - entered_inclusive
+                              - entered_exclusive
+                            default: use_global
                         description: Specifies the Common Price List properties.
                   meta:
                     $ref: '#/components/schemas/Meta'
@@ -400,6 +433,32 @@ paths:
                       The error title describing the particular error.
                   type:
                     type: string
+        '400':
+          description: |
+            `prices_entered_with_tax` allowed values: `use_global`.
+          content:
+            application/json:
+              schema:
+                title: Error Response
+                type: object
+                properties:
+                  errors:
+                    title: Detailed Errors
+                    type: object
+                    properties: {}
+                    additionalProperties: true
+                  instance:
+                    type: string
+                  status:
+                    type: integer
+                    description: |
+                      The HTTP status code.
+                  title:
+                    type: string
+                    description: |
+                      The error title describing the particular error.
+                  type:
+                    type: string
     delete:
       tags:
         - Price Lists
@@ -441,7 +500,12 @@ paths:
       tags:
         - Price Lists
       summary: Get a Price List
-      description: ' Returns a single *Price List*.'
+      description: | 
+        Returns a single *Price List*.
+
+        > #### Beta
+        > * The `prices_entered_with_tax` setting is in beta.
+        > * For more information on this setting, see [Price Lists - International Enhancements for Multi-Storefront](/docs/store-operations/pricing/price-lists-international-enhancements-for-multi-storefront).
       operationId: getPriceList
       parameters:
         - name: price_list_id
@@ -494,6 +558,14 @@ paths:
                         description: |
                           Boolean value that specifies whether this `Price List` and its prices are active or not. Defaults to `true`.
                         example: true
+                      prices_entered_with_tax:
+                        type: string
+                        description: Specifies whether the entered prices include or exclude tax. You can also use global settings or override them.
+                        enum:
+                          - use_global
+                          - entered_inclusive
+                          - entered_exclusive
+                        default: use_global
                     description: Specifies the Common Price List properties.
                   meta:
                     $ref: '#/components/schemas/Meta'
@@ -515,7 +587,12 @@ paths:
       tags:
         - Price Lists
       summary: Update a Price List
-      description: Updates a *Price List*.
+      description: |
+        Updates a *Price List*.
+
+        > #### Beta
+        > * The `prices_entered_with_tax` setting is in beta.
+        > * For more information on this setting, see [Price Lists - International Enhancements for Multi-Storefront](/docs/store-operations/pricing/price-lists-international-enhancements-for-multi-storefront).
       operationId: updatePriceList
       parameters:
         - name: price_list_id
@@ -549,6 +626,14 @@ paths:
                       description: |
                         Whether or not this `Price List` and its prices are active. Defaults to `true`.
                       example: true
+                    prices_entered_with_tax:
+                      type: string
+                      description: Specifies whether the entered prices include or exclude tax. You can also use global settings or override them.
+                      enum:
+                        - use_global
+                        - entered_inclusive
+                        - entered_exclusive
+                      default: use_global
                   description: Common Price List properties.
         required: true
       responses:
@@ -598,6 +683,14 @@ paths:
                             description: |
                               Whether or not this `Price List` and its prices are active.  Defaults to `true`.
                             example: true
+                          prices_entered_with_tax:
+                            type: string
+                            description: Specifies whether the entered prices include or exclude tax. You can also use global settings or override them.
+                            enum:
+                              - use_global
+                              - entered_inclusive
+                              - entered_exclusive
+                            default: use_global
                         description: Common Price List properties.
                   meta:
                     $ref: '#/components/schemas/Meta'