Calculate surcharges on your server

Server-calculated surcharges allow you to create a complex surcharge/fee system for your store. However, you need to code all logic for such fees on a self-hosted endpoint called discountUrl (the same one used for server-calculated discounts).

Every time cart details are changed, Ecwid sends cart data as a POST request with JSON body to discountUrl and waits for the response with the surcharge details. Your app must deliver the response in the 5-second window. Otherwise, Ecwid allows customers to proceed without the surcharge/fee.

When calculating surcharges, you can refer to Ecwid's flow for calculating the order total, which depends on the gross/net prices in the order:

Gross prices

Check the store settings with the Get store profile > taxSettings > pricesIncludeTax field. If it's false, modifications to the order total are calculated in the following order:

1. Order subtotal

2. Coupon discount

3. Handling fee/surcharges

4. Discounts

5. Shipping

6. Taxes

Net prices

Check the store settings with the Get store profile > taxSettings > pricesIncludeTax field. If it's true, modifications to the order total are calculated in the following order:

1. Order subtotal

2. Coupon discount

3. Handling fee/surcharges

4. Taxes

5. Discounts

6. Shipping

Connect server-calculated surcharges with your store

As a developer, you must develop a self-hosted endpoint that receives POST requests from your Ecwid store and responds with surcharges.

If you don't yet have an app for Ecwid API access, start with the following instructions.

Make sure your app has the customize_cart_calculation access scope and discountUrl endpoint (the same endpoint is used to calculate discounts on your server). Request application update

Process surcharge request from the store

Upon receiving a new surcharge request, parse the JSON body to get all the required details about the cart. Use the example and fields breakdown below:

Example of request coming from the store

POST https://mycoolapp.com/discounts HTTP/1.1

{
  "storeId": 1003,
  "merchantAppSettings": {},
  "cart": {
    "id": null,
    "orderNumber": null,
    "vendorOrderNumber": null,
    "subtotal": 2130,
    "ipAddress": null,
    "couponDiscount": 213,
    "paymentStatus": "INCOMPLETE",
    "fulfillmentStatus": "NEW",
    "refererUrl": null,
    "orderComments": null,
    "volumeDiscount": 0,
    "membershipBasedDiscount": 0,
    "totalAndMembershipBasedDiscount": 0,
    "discount": 0,
    "customerGroupId": null,
    "customerGroup": null,
    "customerId": null,
    "customerEmail": null,
    "discountCoupon": {
      "id": 135823561,
      "ownerId": 1003,
      "name": "Coupon",
      "code": "YOURCODE",
      "discountType": "PERCENT",
      "status": "ACTIVE",
      "discount": 10,
      "launchDate": "2019-09-30 23:00:00 +0000",
      "expirationDate": null,
      "totalLimit": null,
      "usesLimit": "UNLIMITED",
      "applicationLimit": "UNLIMITED",
      "creationDate": "2021-09-21 13:40:21 +0000",
      "orderCount": 0,
      "legacyCatalogLimit": null,
      "catalogLimit": null,
      "repeatCustomerOnly": false,
      "newCustomerOnly": false,
      "parentId": 41576009,
      "customerId": 0,
      "cartId": 1950723716,
      "updateDate": "2021-02-23 02:01:30 +0000"
    },
    "discountInfo": null,
    "handlingFee": {
      "name": "Handling Fee",
      "value": 0,
      "description": ""
    },
    "hidden": false,
    "items": [
      {
        "weight": 120,
        "price": 2130,
        "amount": 1,
        "productId": 352841275,
        "combinationId": 12345,
        "name": "Test Product",
        "categoryId": null,
        "sku": "00002312",
        "selectedOptions": [
          {
            "name": "Size",
            "nameTranslated": null,
            "type": "CHOICE",
            "value": "S",
            "valueTranslated": {
              "en": "S"
            },
            "valuesArray": [
              "S"
            ],
            "valuesArrayTranslated": null,
            "files": null,
            "selections": [
              {
                "selectionTitle": "S",
                "selectionModifier": 0,
                "selectionModifierType": "ABSOLUTE"
              }
            ]
          }
        ],
        "dimensions": {
          "length": 0,
          "width": 0,
          "height": 0
        },
        "productPrice": 2130,
        "categoryIds": [],
        "categories": [],
        "quantity": null,
        "unlimited": true,
        "inStock": true,
        "priceInProductList": 2130,
        "isShippingRequired": true,
        "productClassId": 0,
        "enabled": true,
        "warningLimit": 0,
        "fixedShippingRateOnly": false,
        "fixedShippingRate": 0,
        "options": [
          {
            "type": "SELECT",
            "name": "Size",
            "defaultChoice": 0,
            "required": false,
            "choices": [
              {
                "text": "S",
                "priceModifier": 0,
                "priceModifierType": "ABSOLUTE"
              },
              {
                "text": "M",
                "priceModifier": 0,
                "priceModifierType": "ABSOLUTE"
              }
            ]
          }
        ],
        "wholesalePrices": [],
        "compareToPrice": null,
        "url": "https://store.ecwid.com/#!/Test-Product/p/352841275",
        "created": "2021-05-03 18:23:13 +0000",
        "updated": "2021-09-21 13:42:21 +0000",
        "createTimestamp": 1620066193,
        "updateTimestamp": 1632231741,
        "defaultCombinationId": 222806564,
        "imageUrl": null,
        "thumbnailUrl": null,
        "smallThumbnailUrl": null,
        "hdThumbnailUrl": null,
        "originalImageUrl": null,
        "originalImage": null,
        "borderInfo": null,
        "galleryImages": [],
        "defaultCategoryId": 0,
        "seoTitle": "",
        "seoDescription": "",
        "favorites": {
          "count": 0,
          "displayedCount": "0"
        },
        "attributes": [
          {
            "id": 27942320,
            "name": "UPC",
            "type": "UPC",
            "value": "TEST",
            "show": "DESCR"
          },
          {
            "id": 27942321,
            "name": "Brand",
            "type": "BRAND",
            "value": "GENERIC",
            "show": "DESCR"
          }
        ],
        "relatedProducts": {
          "productIds": [],
          "relatedCategory": {
            "enabled": false,
            "categoryId": 0,
            "productCount": 5
          }
        },
        "combinations": [
          {
            "id": 222806563,
            "sku": "00002444",
            "combinationNumber": 2,
            "options": [
              {
                "name": "Size",
                "nameTranslated": {
                  "en": "Size"
                },
                "value": "M",
                "valueTranslated": {
                  "en": "M"
                }
              }
            ],
            "smallThumbnailUrl": null,
            "hdThumbnailUrl": null,
            "thumbnailUrl": null,
            "imageUrl": null,
            "originalImageUrl": null,
            "price": null,
            "defaultDisplayedPrice": 2130,
            "defaultDisplayedPriceFormatted": "$2 130.00",
            "compareToPrice": null,
            "wholesalePrices": null,
            "quantity": null,
            "unlimited": true,
            "inStock": true,
            "warningLimit": 0,
            "weight": 190,
            "borderInfo": null,
            "attributes": [],
            "isShippingRequired": null
          },
          {
            "id": 222806564,
            "sku": "00002312",
            "combinationNumber": 1,
            "options": [
              {
                "name": "Size",
                "nameTranslated": {
                  "en": "Size"
                },
                "value": "S",
                "valueTranslated": {
                  "en": "S"
                }
              }
            ],
            "smallThumbnailUrl": null,
            "hdThumbnailUrl": null,
            "thumbnailUrl": null,
            "imageUrl": null,
            "originalImageUrl": null,
            "price": null,
            "defaultDisplayedPrice": 2130,
            "defaultDisplayedPriceFormatted": "$2 130.00",
            "compareToPrice": null,
            "wholesalePrices": null,
            "quantity": null,
            "unlimited": true,
            "inStock": true,
            "warningLimit": 0,
            "weight": 120,
            "borderInfo": null,
            "attributes": [],
            "isShippingRequired": null
          }
        ],
        "showOnFrontpage": 2
      }
    ],
    "shippingAddress": {
      "street": "test",
      "city": "test",
      "countryCode": "US",
      "postalCode": "10001",
      "stateOrProvinceCode": "NY",
      "stateOrProvinceName": "New York"
    },
    "originAddress": {
      "street": "1 Teema, Harris Road, South End\n",
      "city": "Port Elizabeth",
      "countryCode": "DE",
      "postalCode": "54570",
      "stateOrProvinceCode": ""
    },
    "weight": 120,
    "weightUnit": "kg",
    "dimensionUnit": "CM",
    "currency": "USD",
    "predictedPackages": null,
    "paymentMethod": "PayPal",
    "extraFields": null
  },
 "lang": "en"

Request contains a JSON object with the following fields:

Name	Type	Description
storeId	number	Ecwid store ID.
merchantAppSettings	json	Merchant settings for your integration set up by your code.
cart	object cart	All available cart details.
lang	string	Customer's storefront language (e.g. en).

cart

Field	Type	Description
Id	string	Unique order ID.
subtotal	number	Cost of all products in the order (item's price x quantity) before any cost modifiers such as discounts, taxes, fees, etc. are applied.
email	string	Customer's email address.
paymentMethod	string	Name of the payment method customer chosen at the checkout.
ipAddress	string	Customer's IP address detected at the checkout.
paymentStatus	string	Order payment status. Supported values: AWAITING_PAYMENT, PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, INCOMPLETE, CUSTOM_PAYMENT_STATUS_1, CUSTOM_PAYMENT_STATUS_2, CUSTOM_PAYMENT_STATUS_3. Read more about order statuses in Help Center.
fulfillmentStatus	string	Order fulfillment status. Supported values: AWAITING_PROCESSING, PROCESSING, SHIPPED, DELIVERED, WILL_NOT_DELIVER, RETURNED, READY_FOR_PICKUP, OUT_FOR_DELIVERY, CUSTOM_FULFILLMENT_STATUS_1, CUSTOM_FULFILLMENT_STATUS_2, CUSTOM_FULFILLMENT_STATUS_3. Read more about order statuses in Help Center.
refererUrl	string	URL of the page when order was placed without page slugs (hash # part).
orderComments	string	Order comments, left by a customer at the checkout.
volumeDiscount	number	Sum of applied advanced discounts (promotions) based on subtotal. Included in the discount field.
membershipBasedDiscount	number	Sum of applied advanced discounts (promotions) based on customer group. Included in the discount field.
totalAndMembershipBasedDiscount	number	Sum of applied advanced discounts (promotions) based on both subtotal and customer group. Included in the discount field.
discount	number	Sum of all applied advanced discounts. Does not include discount coupons. Total order discount is the sum of thecouponDiscount and discount fields.
couponDiscount	number	Discount value from applied discount coupon, e.g. 10. Total order discount is the sum of thecouponDiscount and discount fields.
discountInfo	array discounts	Detailed information about applied advanced discounts (promotions).
discountCoupon	object discountCoupon	Detailed information about applied discount coupons (promotions).
customerId	number	Unique internal ID assigned to the customer.
customerGroup	string	Name of the group the customer belongs to (if any). Read mroe about customer groups.
customerGroupId	number	ID of the group the customer belongs to.
items	array items	Detailed information about products in the order.
shippingAddress	object shippingAddress	Details about the shipping address entered at the checkout by the customer.
originAddress	object originAddress	Store address from where the shipping starts.
predictedPackages	object predictedPackages	Ecwid-calculated details about one package fit to ship all items.
handlingFee	object handlingFee	Details about fees applied to order.
extraFields	object extraFields	Names and values of custom checkout fields applied to the order.

items

Field	Type	Description
productId	number	Internal product ID. Can be used to find full product details with the GET /products request.
combinationId	number	ID of a product variation whos options mathes with values chosen by the customer at the checkout. Read more on product variations in Help Center.
categoryId	number	ID of the category this product belongs to or was added from. Returns -1 if the product was added to the cart via the Buy Now button.
price	number	Price of product in the order with all price modifier applied.
productPrice	number	Basic product price without any modifiers: options markups, discounts, taxes, fees.
priceInProductList	number	Product price displayed in a storefront. May differ from the price value when the product has options and variations and the default variation's price is different from the base product price. Does not include taxes
weight	number	Weight of the product.
name	string	Name of the product.
sku	string	Product SKU. If the chosen options match a variation, this will be a variation SKU.
amount	number	Quantity of the product in the cart.
nameTranslated	object translations	Available translations for the product name.
isShippingRequired	boolean	Defines if the product requires shipping.
fixedShippingRateOnly	boolean	Defines if the product has a unique fixed shipping rate. If true, shipping costs won't calculate for the product and fixedShippingRate value will be used instead.
fixedShippingRate	number	Fixed shipping costs for the product. Affects shipping costs only if fixedShippingRateOnly is true.
selectedOptions	array selectedOptions	Product options values selected by the customer at the checkout.
imageUrl	string	Link to the main product image.
files	array of objects files	Details about downloadable files attached to the product.
dimensions	object dimensions	Details about product dimensions used for shipping costs calculations.
discounts	array discounts	Advanced discounts (promotions) applied to the specific product in the order.
isCustomerSetPrice	boolean	If true, customer set a custom product price using the "Pay What You Want" feature. In this case, both the product price and selectedPrice -> value fields contain the price set by a customer. If false, customer didn't choose the custom price. Therefore, the selectedPrice -> value field will be absent and the price field contains default product price set by the store owner.
selectedPrice	object selectedPrice > value	If isCustomerSetPrice is true, this field contains the "Pay What You Want" price set by a customer at the checkout. Example with the PWYW price set to 100: "selectedPrice": { "value": 100 }
attributes	array of objects attributes	Details about product attributes. Read more on product attributes in Help Center.

attributes

Field	Type	Description
name	string	Name of the product attribute.
value	string	Attribute value.

files

Field	Type	Description
id	number	Internal unique file ID.
name	string	File name visible to the customer.
size	number	File size in bytes (64-bit integer).
url	string	File download link sent to the customer after the order was paid.

selectedOptions

Field	Type	Description
name	string	Name of the product option.
nameTranslated	object translations	Available translations for product option name.
type	string	Type of the product option that defines its functionality. One of: CHOICE - Dropdown, radio button, or size. Allows selecting only one value from the list. CHOICES - Checkbox. Allows selecting multiple values. TEXT - Text input or area. DATE - Datetime selector. FILES - Upload file option.
value	string	Selected/entered value for the option as string. For CHOICES type, provides a string with all selected values separated by a comma.
valueTranslated	object translations	Available translations for the product option value.
valuesArray	array	Selected/entered value for the option as array. For the CHOICES type, provides an array with all selected values.
valuesArrayTranslated	object translations	Available translations for the product options values array.
files	array of objects files	Detailed information about files attached to the selected option. Available only if the option type is FILES.
selections	array of objects selections	Details of selected product options. If sent in "Update order" request, other fields will be recalculated based on information from selections.

selections

Field	Type	Description
selectionTitle	string	Name of the selected option value.
selectionModifier	number	Price modifier of the selected option value. Value can be negative, for example, -10 if it decreases the product price.
selectionModifierType	string	Price modifier type. One of: PERCENT - Price modifier applies as a percent from the product price. ABSOLUTE - Price modifier applies as a flat value.

dimensions

Field	Type	Description
length	number	Length of a product
width	number	Width of a product
height	number	Height of a product

discounts

Field	Type	Description
discountInfo	array of objects discountInfo	Details about advanced discounts (promotions) applied to the product.
total	number	Sum of advanced discounts (promotions) applied to the order.

discountInfo

Field	Type	Description
value	number	Discount value.
type	string	Discount type. One of: PERCENT - Price modifier applies as a percent from the product price. ABS - Price modifier applies as a flat value.
base	string	Discount base. One of: SUBTOTAL - Discount is based on order subtotal. ITEM - Discount is only applied to certain products in the order. SHIPPING - Discount is only applied to order shipping costs. ON_MEMBERSHIP - Discount is only applied if customer belongs to a certain customer group. ON_TOTAL_AND_MEMBERSHIP - Discount is applied to CUSTOM - Discount is created by an app with a custom logic.
orderTotal	number	Minimum order subtotal value for the advanced discount to apply.
description	string	Description the store owner added for the advanced discount.
appliesToItems	array of numbers	List of product IDs advanced discount apply to. For example, [123456, 234567]. If specified, the discount can't apply to all other products.

discountCoupon

Field	Type	Description
id	number	Internal discount coupon ID.
name	string	Name of the discount coupon visible in Ecwid admin.
code	string	Discount coupon code.
discountType	string	Discount type. One of: ABS PERCENT SHIPPING ABS_AND_SHIPPING PERCENT_AND_SHIPPING
status	string	Discount coupon state. One of: ACTIVE PAUSED EXPIRED USEDUP
discount	number	Discount value applied to the order total.
launchDate	string	The date of coupon launch, for example, 2014-06-06 08:00:00 +0000.
expirationDate	string	Coupon expiration date, for example, 2014-06-06 08:00:00 +0000.
totalLimit	number	The minimum order subtotal the coupon applies to.
usesLimit	string	Number of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
applicationLimit	string	Application limit for discount coupons. One of: UNLIMITED NEW_CUSTOMER_ONLY REPEAT_CUSTOMER_ONLY
creationDate	string	Discount coupon creation date.
updateDate	string	Date of the last discount coupon update.
orderCount	number	Amount of orders where the discount coupon was used previously.
catalogLimit	object catalogLimit	Products and categories the coupon can be applied to

catalogLimit

Field	Type	Description
products	array of numbers	List of product IDs the coupon can be applied to.
categories	array of numbers	List of category IDs the coupon can be applied to.

handlingFee

Field	Type	Description
name	string	Handling fee name set by store admin, for example, Wrapping.
value	number	Handling fee flat value.
description	string	Handling fee's description for customers.

extraFields

Field	Type	Description
ecwid_order_delivery_time_interval_start	string	Start of the delivery date/datetime interval.
ecwid_order_delivery_time_interval_end	string	End of the delivery date/datetime interval.
ecwid_order_delivery_time_display_format	string	Format of the delivery date chosen. One of: DATE DATETIME

orderExtraFields

Field	Type	Description
id	string	Internal ID defined for the checkout extra field.
value	string	Extra field value. Length cannot exceed 255 characters.
customerInputType	string	One of: "","TEXT", "SELECT", "DATETIME"
title	string	Extra field title visible at the checkout.
orderDetailsDisplaySection	string	Defines a place where the field is visible to the store admin on the order details page. One of: shipping_info billing_info customer_info order_comments Empty if the field is hidden.
orderBy	string	Extra field position. Use it to sort fields within the same orderDetailsDisplaySection

predictedPackages

Name	Type	Description
height	number	Height of a predicted package
width	number	Width of a predicted package
length	number	Length of a predicted package
weight	number	Total weight of a predicted package
declaredValue	number	Declared value of a predicted package (subtotal of items in package)

shippingAddress

Name	Type	Description
street	string	Customer's street
city	string	Customer's city
countryCode	string	Customer's country code in Ecwid
countryName	string	Customer's country name in Ecwid
postalCode	string	Customer's postal code
stateOrProvinceCode	string	Customer's state or province code in Ecwid
stateOrProvinceName	string	Customer's state or province name in Ecwid

originAddress

Name	Type	Description
street	string	Customer's street
city	string	Customer's city
countryCode	string	Customer's country code in Ecwid
postalCode	string	Customer's postal code
stateOrProvinceCode	string	Customer's state or province code in Ecwid

translations

Object with text field translations in the "lang": "text" format, where the "lang" is an ISO 639-1 language code. For example:

{
    "en": "Sample text",
    "nl": "Voorbeeldtekst"
}

Translations are available for all active store languages. Only the default language translations are returned if no other translations are provided for the field. Find active store languages with GET /profile request > languages > enabledLanguages.

Respond with surcharges

With the cart details, you can calculate surcharges using your own logic and conditions. Ecwid doesn't have access to this part of application flow.

However, your response must meet API requirements. Surcharges' details must be sent as a response to the initial request in a JSON format in 5 seconds or less.

Respond with several different discounts limited to different products to create complex logic.

Response JSON example

{
    "surcharges": [
        {
          "id": "paypal",
          "value": 1.5,
          "type": "PERCENT",
          "description": "+1.5% processing PayPal fee",
          "taxable": true
        },
        {
          "id": "gift_wrap",
          "value": 5,
          "type": "ABSOLUTE",
          "description": "+$5 for gift wrap",
          "taxable": false
        }
    ]

}

Response must contain a JSON object with the following fields:

Name	Type	Description
id	string	Internal surcharge ID. You can use later to identify different surcharges applied to the order. Required
value	number	Discount amount. Required
type	number	Discount type. One of: ABSOLUTE PERCENT If not specified, discount is applied as ABSOLUTE. Required
description	string	Surcharge description displayed to the customer at the checkout and later in order receipts.
taxable	boolean	Defines if taxes should apply to the surcharge.