> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # CalculateAdditionalFees # Package: additionalFees # Namespace: AdditionalFeesSPI # Method link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/additional-fees/additional-fees-service-plugin/calculate-additional-fees.md ## Introduction This method retrieves additional fees calculated by your app. Wix calls this method when certain actions are performed on the cart or checkout. For example, when an item is added to the cart or the amount of an item is updated in the checkout. > __Notes:__ > + Do not call the Estimate Cart Totals, Estimate Current Cart Totals or Get Checkout methods from your implementation code for Calculate Additional Fees. Doing so will result in an error. > + The currency returned in the response object must match the site's currency or those fees will be filtered out and not returned. --- ## REST API ### Schema ``` Method: calculateAdditionalFees Description: This method retrieves additional fees calculated by your app. Wix calls this method when certain actions are performed on the cart or checkout. For example, when an item is added to the cart or the amount of an item is updated in the checkout. > __Notes:__ > + Do not call the Estimate Cart Totals, Estimate Current Cart Totals or Get Checkout methods from your implementation code for Calculate Additional Fees. Doing so will result in an error. > + The currency returned in the response object must match the site's currency or those fees will be filtered out and not returned. URL: null Method: POST Method parameters: param name: appliedDiscounts | type: array | description: Applied discounts. - ONE-OF: - name: coupon | type: Coupon | description: Coupon details. - name: id | type: string | description: Coupon GUID. - name: code | type: string | description: Coupon code. - name: name | type: string | description: Coupon name. - name: amount | type: string | description: - name: merchantDiscount | type: MerchantDiscount | description: Merchant discount. - name: amount | type: string | description: - name: discountRule | type: DiscountRule | description: Discount rule - name: id | type: string | description: Discount rule GUID - name: name | type: DiscountRuleName | description: Discount rule name - name: original | type: string | description: Original discount rule name (in site's default language). - name: translated | type: string | description: Translated discount rule name according to buyer language. Defaults to `original` when not provided. - name: amount | type: string | description: - name: discountType | type: DiscountType | description: Discount type. - enum: - GLOBAL: Global discount. - SPECIFIC_ITEMS: Discount on specific items. - SHIPPING: Discount on shipping. - name: lineItemIds | type: array | description: IDs of line items the discount applies to. param name: businessLocationId | type: businessLocationId | description: The business location GUID associated with the items. Learn more about the [Locations API](https://dev.wix.com/docs/rest/business-management/locations/introduction.md). param name: buyerDetails | type: BuyerDetails - name: contactDetails | type: FullAddressContactDetails | description: Contact details. - name: firstName | type: string | description: Contact's first name. - name: lastName | type: string | description: Contact's last name. - name: phone | type: string | description: Contact's phone number. - name: company | type: string | description: Contact's company name. - name: email | type: string | description: Email associated with the address. - name: vatId | type: VatId | description: Tax info. Currently usable only in Brazil. - name: id | type: string | description: Customer's tax GUID. - name: type | type: VatType | description: Tax type. Supported values: + `CPF`: for individual tax payers + `CNPJ`: for corporations - enum: - UNSPECIFIED: - CPF: CPF - for individual tax payers. - CNPJ: CNPJ - for corporations param name: extendedFields | type: ExtendedFields - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). param name: lineItems | type: array | description: Line items to calculate additional fees for. Max: 300 items - name: id | type: string | description: Line item GUID. - name: quantity | type: integer | description: Quantity of item. Min: `1` Max: `100000` - name: catalogReference | type: CatalogReference | description: Catalog and item reference. Includes GUIDs for the item and the catalog it came from, as well as further optional info. Optional for custom line items, which don't trigger the Catalog service plugin. - name: catalogItemId | type: string | description: GUID of the item within the catalog it belongs to. - name: appId | type: string | description: GUID of the app providing the catalog. You can get your app's GUID from its page in the [app dashboard](https://dev.wix.com/dc3/my-apps/). For items from Wix catalogs, the following values always apply: + Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"` + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` + Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"` - name: options | type: object | description: Additional item details in `key:value` pairs. Use this optional field for more specificity with item selection. The values of the `options` field differ depending on which catalog is providing the items. For Wix Stores products, learn more about integrating with [Catalog V3](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md) or [Catalog V1](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/e-commerce-integration.md), depending on [the version the site uses](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/introduction.md). - name: productName | type: string | description: Item name. - name: price | type: string | description: Price for a single item, after discounts and modifiers. - name: physicalProperties | type: PhysicalProperties | description: Physical properties of the item. When relevant, contains information such as SKU, item weight, and shippability. - name: weight | type: number | description: Line item weight. Measurement unit matches the weight unit specified in `weightUnit` in the request. - name: sku | type: string | description: Stock-keeping unit. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku). - name: shippable | type: boolean | description: Whether this line item is shippable. - name: depositAmount | type: string | description: Partial payment to be paid upfront during the checkout. Only eligible for catalog items with `lineItem.paymentOption` type of `DEPOSIT_ONLINE`. - name: modifierGroups | type: array | description: Modifier groups that were added to the item. - name: id | type: string | description: Modifier group GUID. - name: name | type: TranslatableString | description: Modifier group name. - name: original | type: string | description: __Required.__ String in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. - name: translated | type: string | description: String translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. - name: modifiers | type: array | description: List of modifiers in this group. - name: id | type: string | description: Modifier GUID. - name: quantity | type: integer | description: The quantity of this modifier. - name: label | type: TranslatableString | description: Primary display label for the modifier. - name: details | type: TranslatableString | description: Additional details. - name: price | type: string | description: The price of the modifier. param name: purchaseFlowId | type: purchaseFlowId | description: Persistent GUID that correlates between the various eCommerce elements: cart, checkout, and order. param name: shippingAddress | type: Address | description: Physical address - name: country | type: string | description: Two-letter country code in [ISO-3166 alpha-2](https://www.iso.org/obp/ui/#search/code/) format. - name: subdivision | type: string | description: Code for a subdivision (such as state, prefecture, or province) in [ISO 3166-2](https://www.iso.org/standard/72483.html) format. - name: city | type: string | description: City name. - name: postalCode | type: string | description: Postal or zip code. - name: streetAddress | type: StreetAddress | description: Street address. - name: number | type: string | description: Street number. - name: name | type: string | description: Street name. - name: addressLine | type: string | description: Main address line (usually street name and number). - name: addressLine2 | type: string | description: Free text providing more detailed address info. Usually contains apt, suite, floor. - name: geocode | type: AddressLocation | description: Geocode object containing latitude and longitude coordinates. - name: latitude | type: number | description: Address latitude. - name: longitude | type: number | description: Address longitude. param name: shippingInfo | type: ShippingInformation - name: selectedCarrierServiceOption | type: SelectedCarrierServiceOption | description: Selected carrier shipping option. - name: code | type: string | description: Unique identifier of selected option. For example, `"usps_std_overnight"`. - name: otherCharges | type: array | description: Other charges. - name: type | type: ChargeType | description: Type of charge. - enum: HANDLING_FEE, INSURANCE - name: details | type: string | description: Details of the charge. Max: 200 characters - name: cost | type: SelectedCarrierServiceOptionPrices | description: Cost. `cost` is `price` minus `totalDiscount`. - name: price | type: string | description: Price. - name: totalDiscount | type: string | description: Total shipping discount. param name: subtotal | type: subtotal | description: Subtotal. Calculated as `lineItems[i].price` multiplied by `lineItems[i].quantity`, summed across all line items. Return type: CalculateAdditionalFeesResponse - name: additionalFees | type: array | description: Additional fees calculated. - name: code | type: string | description: Additional fee's unique code or GUID. - name: name | type: string | description: Additional fee's name. Max: 50 characters - name: price | type: string | description: Total additional fees. This `price` does not include any taxes that may apply to these additional fees. - name: taxDetails | type: TaxDetails | description: Tax details. > **Note:** Tax is not calculated in the returned `price` even when `taxDetails.taxable` is `true`. - name: taxable | type: boolean | description: Whether additional fee is taxable. - name: taxGroupId | type: string | description: Reserved for internal use. - name: lineItemIds | type: array | description: Optional - Line items associated with this additional fee. If no `lineItemIds` are provided, the fee will be associated with the whole cart/checkout/order. - name: translatedName | type: string | description: The translated name of the additional fee. The translation language is determined by the `languages` field in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: currency | type: string | description: Currency of additional fees calculated. In three-letter currency code [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. The currency returned in the response object must match the wix site's currency or those fees will be filtered out and not returned. Extract the `currency` from the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-rest.md#request-envelope) to ensure the correct currency is used in your calculation. ``` ### Examples ### Calculate additional fees - decoded JWT The data payload will include the following object as an encoded JWT. For the purposes of this example, we show the request and response objects decoded. ```curl curl -X POST https://provider.example.com/v1/calculate-additional-fees \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ "data": { "request": { "appliedDiscounts": [ { "coupon": { "amount": "10", "code": "summersale", "id": "b8773880-5969-4771-a11f-d3808eccfb69", "name": "" }, "discountType": "SPECIFIC_ITEMS", "lineItemIds": [ "00000000-0000-0000-0000-000000000001" ] } ], "lineItems": [ { "catalogReference": { "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e", "catalogItemId": "05412fb8-e344-f4c1-3b00-903a2573e377" }, "id": "00000000-0000-0000-0000-000000000001", "physicalProperties": { "shippable": true }, "price": "2.00", "productName": "Clamping Tool", "quantity": 100 } ], "buyerDetails": { "contactDetails": { "phone": "6175551905", "email": "bowlbuyer@example.com" } }, "purchaseFlowId": "12b907dd-4a6c-47e7-9397-23e4afcba792", "shippingInfo": { "selectedCarrierServiceOption": { "code": "pickup-00000000-0000-0000-0000-000000000001", "cost": { "price": "0" }, "logistics": { "deliveryTime": "Next Sunday at 13:00", "instructions": "Go to my house", "pickupDetails": { "businessLocation": true, "pickupMethod": "STORE_PICKUP" } }, "title": "Pickup Name" } }, "subtotal": "200.00" } } } ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.additionalFees.AdditionalFeesSPI.calculateAdditionalFees(request, metadata) Description: This method retrieves additional fees calculated by your app. Wix calls this method when certain actions are performed on the cart or checkout. For example, when an item is added to the cart or the amount of an item is updated in the checkout. > __Notes:__ > + Do not call the Estimate Cart Totals, Estimate Current Cart Totals or Get Checkout methods from your implementation code for Calculate Additional Fees. Doing so will result in an error. > + The currency returned in the response object must match the site's currency or those fees will be filtered out and not returned. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: CalculateAdditionalFeesRequest - name: lineItems | type: array | description: Line items to calculate additional fees for. Max: 300 items - name: _id | type: string | description: Line item GUID. - name: quantity | type: integer | description: Quantity of item. Min: `1` Max: `100000` - name: catalogReference | type: CatalogReference | description: Catalog and item reference. Includes GUIDs for the item and the catalog it came from, as well as further optional info. Optional for custom line items, which don't trigger the Catalog service plugin. - name: catalogItemId | type: string | description: GUID of the item within the catalog it belongs to. - name: appId | type: string | description: GUID of the app providing the catalog. You can get your app's GUID from its page in the [app dashboard](https://dev.wix.com/dc3/my-apps/). For items from Wix catalogs, the following values always apply: + Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"` + Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"` + Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"` - name: options | type: object | description: Additional item details in `key:value` pairs. Use this optional field for more specificity with item selection. The values of the `options` field differ depending on which catalog is providing the items. For Wix Stores products, learn more about integrating with [Catalog V3](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md) or [Catalog V1](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v1/catalog/e-commerce-integration.md), depending on [the version the site uses](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-versioning/introduction.md). - name: productName | type: string | description: Item name. - name: price | type: string | description: Price for a single item, after discounts and modifiers. - name: physicalProperties | type: PhysicalProperties | description: Physical properties of the item. When relevant, contains information such as SKU, item weight, and shippability. - name: weight | type: number | description: Line item weight. Measurement unit matches the weight unit specified in `weightUnit` in the request. - name: sku | type: string | description: Stock-keeping unit. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku). - name: shippable | type: boolean | description: Whether this line item is shippable. - name: depositAmount | type: string | description: Partial payment to be paid upfront during the checkout. Only eligible for catalog items with `lineItem.paymentOption` type of `DEPOSIT_ONLINE`. - name: modifierGroups | type: array | description: Modifier groups that were added to the item. - name: _id | type: string | description: Modifier group GUID. - name: name | type: TranslatableString | description: Modifier group name. - name: original | type: string | description: __Required.__ String in the site's default language as defined in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). Min: 1 character. Max: 200 characters. - name: translated | type: string | description: String translated into the buyer's language. Min: 1 character. Max: 400 characters. Default: Same as `original`. - name: modifiers | type: array | description: List of modifiers in this group. - name: _id | type: string | description: Modifier GUID. - name: quantity | type: integer | description: The quantity of this modifier. - name: label | type: TranslatableString | description: Primary display label for the modifier. - name: details | type: TranslatableString | description: Additional details. - name: price | type: string | description: The price of the modifier. - name: shippingAddress | type: Address | description: Shipping address. - name: streetAddress | type: StreetAddress | description: none - name: name | type: string | description: none - name: number | type: string | description: none - name: city | type: string | description: none - name: subdivision | type: string | description: none - name: country | type: string | description: none - name: postalCode | type: string | description: none - name: addressLine2 | type: string | description: none - name: buyerDetails | type: BuyerDetails | description: Information about the buyer, such as contact details. - name: contactDetails | type: FullAddressContactDetails | description: Contact details. - name: firstName | type: string | description: Contact's first name. - name: lastName | type: string | description: Contact's last name. - name: phone | type: string | description: Contact's phone number. - name: company | type: string | description: Contact's company name. - name: email | type: string | description: Email associated with the address. - name: vatId | type: VatId | description: Tax info. Currently usable only in Brazil. - name: _id | type: string | description: Customer's tax GUID. - name: type | type: VatType | description: Tax type. Supported values: + `CPF`: for individual tax payers + `CNPJ`: for corporations - enum: - UNSPECIFIED: - CPF: CPF - for individual tax payers. - CNPJ: CNPJ - for corporations - name: appliedDiscounts | type: array | description: Applied discounts. - ONE-OF: - name: coupon | type: Coupon | description: Coupon details. - name: _id | type: string | description: Coupon GUID. - name: code | type: string | description: Coupon code. - name: name | type: string | description: Coupon name. - name: amount | type: string | description: - name: merchantDiscount | type: MerchantDiscount | description: Merchant discount. - name: amount | type: string | description: - name: discountRule | type: DiscountRule | description: Discount rule - name: _id | type: string | description: Discount rule GUID - name: name | type: DiscountRuleName | description: Discount rule name - name: original | type: string | description: Original discount rule name (in site's default language). - name: translated | type: string | description: Translated discount rule name according to buyer language. Defaults to `original` when not provided. - name: amount | type: string | description: - name: discountType | type: DiscountType | description: Discount type. - enum: - GLOBAL: Global discount. - SPECIFIC_ITEMS: Discount on specific items. - SHIPPING: Discount on shipping. - name: lineItemIds | type: array | description: IDs of line items the discount applies to. - name: shippingInfo | type: ShippingInformation | description: Shipping information. - name: selectedCarrierServiceOption | type: SelectedCarrierServiceOption | description: Selected carrier shipping option. - name: code | type: string | description: Unique identifier of selected option. For example, `"usps_std_overnight"`. - name: otherCharges | type: array | description: Other charges. - name: type | type: ChargeType | description: Type of charge. - enum: HANDLING_FEE, INSURANCE - name: details | type: string | description: Details of the charge. Max: 200 characters - name: cost | type: SelectedCarrierServiceOptionPrices | description: Cost. `cost` is `price` minus `totalDiscount`. - name: price | type: string | description: Price. - name: totalDiscount | type: string | description: Total shipping discount. - name: purchaseFlowId | type: string | description: Persistent GUID that correlates between the various eCommerce elements: cart, checkout, and order. - name: businessLocationId | type: string | description: The business location GUID associated with the items. Learn more about the [Locations API](https://dev.wix.com/docs/rest/business-management/locations/introduction.md). - name: subtotal | type: string | description: Subtotal. Calculated as `lineItems[i].price` multiplied by `lineItems[i].quantity`, summed across all line items. - name: extendedFields | type: ExtendedFields | description: [Extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). Return type: PROMISE - name: additionalFees | type: array | description: Additional fees calculated. - name: code | type: string | description: Additional fee's unique code or GUID. - name: name | type: string | description: Additional fee's name. Max: 50 characters - name: price | type: string | description: Total additional fees. This `price` does not include any taxes that may apply to these additional fees. - name: taxDetails | type: TaxDetails | description: Tax details. > **Note:** Tax is not calculated in the returned `price` even when `taxDetails.taxable` is `true`. - name: taxable | type: boolean | description: Whether additional fee is taxable. - name: taxGroupId | type: string | description: Reserved for internal use. - name: lineItemIds | type: array | description: Optional - Line items associated with this additional fee. If no `lineItemIds` are provided, the fee will be associated with the whole cart/checkout/order. - name: translatedName | type: string | description: The translated name of the additional fee. The translation language is determined by the `languages` field in the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions.md#request-envelope). - name: currency | type: string | description: Currency of additional fees calculated. In three-letter currency code [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format. The currency returned in the response object must match the wix site's currency or those fees will be filtered out and not returned. Extract the `currency` from the [request envelope](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-rest.md#request-envelope) to ensure the correct currency is used in your calculation. ``` ### Examples ### Example of an `additionalFees` return value ```javascript import { additionalFees } from '@wix/ecom/service-plugins'; additionalFees.provideHandlers({ calculateAdditionalFees: async ( payload ) => { const {request, metadata} = payload; // Use the `request` and `metadata` received from Wix and // apply custom logic. return { // Return your response exactly as documented to integrate with Wix. // Return value example: additionalFees: [ { code: "subscription-fee", name: "Subscription Fee", price: "5", taxDetails: { taxable: true } } ], currency: "USD" } } }); ``` ### calculateAdditionalFees (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { additionalFees } from '@wix/ecom/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { additionalFees }, // Include the auth strategy and host as relevant }); async function calculateAdditionalFees(request,metadata) { const response = await myWixClient.additionalFees.calculateAdditionalFees(request,metadata); }; ``` ---