Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from 8 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
9164c5d
add draft
bc-andreadao Sep 25, 2024
39c8a65
update title
bc-andreadao Sep 25, 2024
3796b98
update yml file
bc-andreadao Sep 26, 2024
e8d9e3d
update overview, yml endpoints
bc-andreadao Sep 26, 2024
0a3af18
edit tax settings overview, add error code
bc-andreadao Sep 26, 2024
c358587
Merge branch 'main' into DEVDOCS-6056-tax-incl
bc-andreadao Sep 26, 2024
aa91197
update intro in overview & description for 400 error
bc-andreadao Sep 26, 2024
18c8ff9
Merge branch 'DEVDOCS-6056-tax-incl' of https://github.com/bigcommerc…
bc-andreadao Sep 26, 2024
6073633
update limitations wording
bc-andreadao Oct 10, 2024
fe6c02b
update settings & limitations section
bc-andreadao Oct 10, 2024
d75ad33
add usage example, update limitations based on feedback
bc-andreadao Oct 10, 2024
e37cf72
add null price handling
bc-andreadao Oct 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 93 additions & 0 deletions docs/store-operations/pricing/msf-international-enhancements.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Price Lists - International Enhancements for Multi-Storefront

<Callout type="info">
Tax-inclusive and exclusive price lists are in beta. Features may change based on user feedback or internal testing.
</Callout>

When you sell internationally, you may need your storefront to display prices that either include or exclude tax based on regional expectations. You may need some storefront channels to display prices that include tax, while others display prices that exclude tax.

To localize your storefronts, you can do the following:
- Specify whether a price list has prices that include or exclude tax when entered.
- Assign the price list to storefront channels (or customer groups).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

at this point is it understood that the store needs to be MSF enabled?



## 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.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if this sentence is accurate

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we need to change the wordings here - modifier rules, gift wrapping features, and fixed shipping prices into a price list. These inherit global settings because we apply the prices from modifier rules, gift wrapping features, and fixed shipping on top of the prices in price list true, but it doesnt inherit global settings, its inherits the tax inc/ex setting from the price list that will apply for that instant of channel and customer, even though its not part of the price list yet. I think giving this clarity might help merchants less confused how the global setting prices will apply with price list inc/ex.
cc @megdesko

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bc-vinbase is correct. These will inherit the setting from the price list and will not be treated as the global setting.

Maybe These inherit global settings and always apply on top of the price list. should be changed to These prices will be applied as-is with with the prices entered with tax setting for the current shopper applied or similar?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we need an example here like

Your store has (in USD)

  • $5 modifier rule
    $1.99 fixed shipping
    +$3 for gift wrapping

Those are entered global (ex tax)

You add an inc tax price list that has prices in Australian dollars- for simplicity, let's say it's 2 AUD to 1 USD
So maybe $55.97 AUD for the price of the product
We will currency convert the $5 modifier rule to $10 AUD
$3.98 for fixed shipping
$6 for gift wrapping

These prices will inherit the price list setting, so they'll be added as is, so the cart total for that item with the modifier rule selected will be
55.97 + 5 + 6 + 3.98 = $70.95 AUD

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@megdesko Thanks, clarified it and added an example. I assume you meant to use the $10 modifier rule in your final calculation (to total $75.95)

- 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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given MSF feature is turned on :) just clarifying it for myself too

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They can still do it via API, no?


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should also add something about going into Settings > Tax > Store Tax Settings and turning on Keep prices as entered for When calculating the taxes on sales made outside the pricing tax zone

especially for folks on default ex tax stores

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see this below now :-)

## 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is only true if they turn on the setting I mentioned above- otherwise tax unwinding will kick in and sadness will ensue.

I think this is being changed to make it the default for ex tax stores, but depending on when someone sees this doc that may not be completed/ totally rolled out.

Copy link
Collaborator Author

@bc-andreadao bc-andreadao Oct 10, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I added a sentence about the setting, but I believe my doc could be further clarified.

I rethought about the feature, and my current understanding is:

  • When calculating the taxes on sales made outside the pricing tax zone setting is only important when you want tax-inclusive prices (the setting doesn't matter if you want tax-exclusive prices).
  • When you want a tax-inclusive price list, there's noWhen calculating the taxes on sales made outside the pricing tax zone setting for the price list. So I'm guessing this pretty-pricing setting would inherit the global value (assuming the global store is also set to tax-inclusive).
  • If you want a tax-inclusive price list and the global store is tax-exclusive, we'll have to confirm with @bigcommerce/team-tax what the default is. I'm actually taking a closer look at the Tax Settings API reference, and now I'm thinking the setting actually defaults to non-pretty pricing. But people can still choose if they want pretty pricing or not, is that correct? And they would have to do so through the global tax setting?

^ @benpratt77 can you comment on the default value?


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">
You must [update your Stencil theme](https://support.bigcommerce.com/s/article/Marketplace-Theme-Updates) for your Stencil storefront.
</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
2 changes: 1 addition & 1 deletion docs/store-operations/tax/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
99 changes: 96 additions & 3 deletions reference/price_lists.v3.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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'
Expand All @@ -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:
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -400,6 +433,32 @@ paths:
The error title describing the particular error.
type:
type: string
'400':
description: |
(For Catalog V2 stores) `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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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'
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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'
Expand Down
Loading
Loading