BigCommerce API Update: Order Level Fees at Checkout Now Available!
We’re excited to announce support to add fees to orders using the new Checkout Fees API or the updated Orders API, now available on all stores!
What is an order level fee?
An order level fee is a fee that is applied on top of the order total. There are a range of use cases that require order level fees. For example, package insurance fee, tips/gratuities, credit card fees and some states have fees such as Colorado’s Retail Delivery Fee.
What’s in the update?
It allows you, the developer, to:
Add fees to orders by making requests to our new Checkout Fees API.
Have fees show up as separate line items in checkout, just above the order total.
Isolate fees from any discounts that impact the order.
Have the option to specify the fee as taxable and then the appropriate tax will be added.
Why do I need it?
We know that developers have to do extra customization to handle order level fees today because fees are commonly represented as digital products. As digital products, fees can be incorrectly considered in the discount weighting distribution. As a result, discount amounts are erroneously attributed to the fees even though they shouldn’t.
Getting started
To add an order level fee, use the new POST v3/checkout/{checkoutId}/fees API:
{
"fees": [
{
"name": "Insurance (Package Protection Fee)",
"type": "custom_fee",
"display_name": "Insurance (Package Protection Fee)",
"cost": "5.00",
"source": "Insurance provider"
}
]
}
That’s it, you’ve now created an order level fee!
The order level fee is displayed just below shipping costs within the checkout’s order summary. A maximum of 5 order level fees can be applied to an order.
You can also create an order level fee via POST v2/orders by including the fee in the payload or updating an existing order using PUT v2/orders/{order_id}/?include=fees
{
"fees": [
{
"id": "1",
"type": "custom_fee",
"name": "Insurance (Package Protection Fee)",
"display_name": "Insurance (Package Protection Fee)",
"cost_inc_tax": 5.00,
"cost_ex_tax": 5.00,
"source": "Insurance provider"
}
]
}
Any order that has order level fees included will have them displayed and itemized back in the control panel to aid in quick referencing of the order’s total amount.
If a refund is requested, the entire amount of any order level fee applied to the order is available for refund as part of the process. Similar to other things like shipping costs, every order level fee is itemized separately for clarity and usability.
Additional Resources
To learn more about refunds experience:
If you have questions, feedback, or issues implementing, please reach out to the BigCommerce DevRel team or join our Developer Community TODAY!