---
title: "Surcounts: Surcharges & Discounts"
description: What's a Surcount? How Are Surcounts Used? Surcount Type Surcount Properties and Their Values Surcounts and Quantities TotalBeforeSurcounts & TotalAfterSurcounts Surcounts on Transactions   Surcounts
---

[Skip to content](https://support.doshii.com/developer-support/hc/en-us/articles/115003338974-surcounts-surcharges-discounts#main-content)

English

Show submenu for translations

Doshii Connect Pty Ltd

Open main navigation

Close main navigation

- English
  
  Show submenu for translations
- Go to Doshii Connect Pty Ltd

 Go to Doshii Connect Pty Ltd

 Help for Partners

- There are no suggestions because the search field is empty.

1. [Help for Partners](https://support.doshii.com/developer-support?hsLang=en)
2. [API concepts](https://support.doshii.com/developer-support/api-concepts?hsLang=en)

# Surcounts: Surcharges & Discounts

[What's a Surcount?](https://support.doshii.com/developer-support/hc/en-us/articles/115003338974-surcounts-surcharges-discounts#whats-a-surcount)

[How Are Surcounts Used?](https://support.doshii.com/developer-support/hc/en-us/articles/115003338974-surcounts-surcharges-discounts#how-are-surcounts-used)

[Surcount Type](https://support.doshii.com/developer-support/hc/en-us/articles/115003338974-surcounts-surcharges-discounts#surcount-type)

[Surcount Properties and Their Values](https://support.doshii.com/developer-support/hc/en-us/articles/115003338974-surcounts-surcharges-discounts#surcount-properties-and-their-values)

[Surcounts and Quantities](https://support.doshii.com/developer-support/hc/en-us/articles/115003338974-surcounts-surcharges-discounts#surcounts-and-quantities)

[TotalBeforeSurcounts & TotalAfterSurcounts](https://support.doshii.com/developer-support/hc/en-us/articles/115003338974-surcounts-surcharges-discounts#totalbeforesurcounts-totalaftersurcounts)

[Surcounts on Transactions](https://support.doshii.com/developer-support/hc/en-us/articles/115003338974-surcounts-surcharges-discounts#h_01GJYCCZ8DCPEGAAM7T9WETAGH)

 

## What's a Surcount?

Surcounts are a combination of discounts and surcharges, the word itself is a concatenation of both.

The reason we use surcounts is because discounts and surcharges are the same, only in opposition.

Example of a 10% surcharge on a $10 order. Note the **positive** values.

```
"surcounts": [
  {
    "name": "Public holiday surcharge",
    "type": "percentage",
    "value": "100",
    "amount": "10"
  }
]
```

Example of a $1 discount on a $10 order. Note the **negative** values.

```
"surcounts": [
  {
    "name": "Tuesday special deal",
    "type": "absolute",
    "value": "-100",
    "amount": "-100"
  }
]
```

## How Are Surcounts Used?

In our API, surcounts exist in two places.

1. On the order, ie. 20% off the entire order consisting of many items, and;
2. On the individual items, ie. 20% off the individual item.

Note that it is possible to have a surcount on both the order **and** item in combination for a single order.

Order and item level surcounts are both an array so that multiple surcharges or discounts may be applied.

## Surcount Type

There is a property on surcounts object called `type`. The type can be either `percentage` (eg. 10% discount) or `absolute` (eg. $1 discount).

## Surcount Properties and Their Values

With both order and item level surcounts, Doshii does not perform calculations. We take the output of the calculation from either the POS vendor or the partner application for a surcharge or discount.

There are two important properties on a surcount:

**Value** is the dollar value of the surcount. It is recorded as cents rather than dollars. For example if a $1 discount is applied to a $10 item, the value is "-100", which is the discount value of $1 in cents. The value field is *always* in cents.

**Amount** represent the discount details that were applied. In the case that it is a percent discount (10%), the amount is "-10". In the case where a surcount is absolute ($1) the amount is "-100", same as the value property.

Amounts exist to communicate the appropriate information to consumers or staff, i.e. displaying the 10% discount on a receipt.

Example: A surcount object with a $15 'absolute' type discount

```
"surcounts": [
  {
    "name": "Free delivery",
    "type": "absolute",
    "value": "-1500",
    "amount": "-1500"
  }
]
```

Example: A surcount object with a 10% 'percentage' type discount on a $10 item. Note the value field is the calculated discount in cents.

```
"surcounts": [
  {
    "name": "Free delivery",
    "type": "percentage",
    "value": "-100",
    "amount": "-10"
  }
]
```

## Surcounts and Quantities

Surcounts on either the order or the item should be the total discount inclusive of quantities.

If, on an item level discount, you supply a quantity of 2, an `absolute` type discount will not be multiplied.

Some Examples:

**$1 off a $10 item total (absolute)** -

```
{
  "items": [
    {
      "name": "Long Black",
      "posId": "long_black",
      "options": [],
      "quantity": 2,
      "surcounts": [
        {
          "name": "Tuesday morning $1 discount",
          "type": "absolute",
          "value": "-100",
          "amount": "-100"
        }
      ],
      "unitPrice": "500",
      "description": "Dave's favourite coffee",
      "totalAfterSurcounts": "900",
      "totalBeforeSurcounts": "1000"
    }
  ],
  ...
}
```

**10% discount off a $10 item total (percentage)**

```
{
  "items": [
    {
      "name": "Large Flat White",
      "posId": "large_fw",
      "options": [],
      "quantity": 2,
      "surcounts": [
        {
          "name": "Wednesday morning 10% discount",
          "type": "percentage",
          "value": "-100",
          "amount": "-10"
        }
      ],
      "unitPrice": "500",
      "description": "Jimmy's favourite coffee",
      "totalAfterSurcounts": "900",
      "totalBeforeSurcounts": "1000"
    }
  ],
  ...
}
```

**2x items costing $10 with 10% surcharge on each**

```
{
  "items": [
    {
      "name": "Toasted Sourdough Bread & Eggs",
      "posId": "toasted_eggs",
      "options": [],
      "quantity": 2,
      "surcounts": [
        {
          "name": "Extra egg surcharge",
          "type": "percentage",
          "value": "200",
          "amount": "10"
        }
      ],
      "unitPrice": "1000",
      "description": "Just ye old classic",
      "totalAfterSurcounts": "2200",
      "totalBeforeSurcounts": "2000"
    }
  ],
  ...
}
```

***OR* create two individual surcounts.**

```
{
  "items": [
    {
      "name": "Toasted Sourdough Bread & Eggs",
      "posId": "toasted_eggs",
      "options": [],
      "quantity": 2,
      "surcounts": [
        {
          "name": "Extra egg surcharge",
          "type": "percentage",
          "value": "100",
          "amount": "10"
        },
        {
          "name": "Extra egg surcharge",
          "type": "percentage",
          "value": "100",
          "amount": "10"
        }
      ],
      "unitPrice": "1000",
      "description": "Just ye old classic",
      "totalAfterSurcounts": "2200",
      "totalBeforeSurcounts": "2000"
    }
  ],
  ...
}
```

**Example on an Order level**

```
{
  "items": [
    {
      "name": "Toasted Sourdough Bread & Eggs",
      "posId": "toasted_eggs",
      "options": [],
      "quantity": 1,
      "surcounts": [],
      "unitPrice": "1100",
      "description": "Just ye old classic",
      "totalAfterSurcounts": "1100",
      "totalBeforeSurcounts": "1100"
    },
    {
      "name": "Regular Flat White",
      "posId": "large_fw",
      "options": [],
      "quantity": 1,
      "surcounts": [],
      "unitPrice": "380",
      "description": "Just ye old classic",
      "totalAfterSurcounts": "380",
      "totalBeforeSurcounts": "380"
    },
  ],
  "surcounts": [
    {
      "name": "Free coffee with toast and eggs",
      "type": "absolute",
      "value": "-380",
      "amount": "-380"
    }
  ],
  ...
}
```

## TotalBeforeSurcounts & TotalAfterSurcounts

Finally, there are two properties on items impacted by surcounts. The `TotalBeforeSurcounts` and `TotalAfterSurcounts` properties are summaries of the items' calculated values inclusive of their variants (modifiers).

**TotalBeforeSurcounts** should include the item unit price times quantity plus the variants times quantity.

`totalBeforeSurcounts = ((unitPrice + SUM(variant[].price) * quantity) + taxes[exclusive].value`

**TotalAfterSurcounts** should then show TotalBeforeSurcounts plus the Item level surcounts.

`totalAfterSurcounts = totalBeforeSurcounts + SUM(surcounts[].value)`

In an example where there are 2x items costing $10 each with a 10% discount ($1 each) and including an added variant costing $1:

```
{
  "items": [
    {
      "name": "Toasted Sourdough Bread & Eggs",
      "posId": "toasted_eggs",
      "options": [
        {
          "name": "Extra Toppings",
          "posId": "extra_toppings",
          "variants": [
            {
              "name": "Extra Pepperoni",
              "posId": "extra_pepperoni",
              "price": "100"
            }
          ]
        },
      ],
      "quantity": 2,
      "surcounts": [
        {
          "name": "Tuesday free extra pepperoni",
          "type": "percentage",
          "value": "-200",
          "amount": "-10"
        }
      ],
      "unitPrice": "1000",
      "description": "Just ye old classic",
      "totalAfterSurcounts": "2000",
      "totalBeforeSurcounts": "2200"
    }
  ],
  ...
}
```

In an example using the same items and variants as above but this time applying a 10% discount to the entire item inclusive of the variant (each item costing a total of $11). The surcount would contain the following values:

```
"surcounts": [
  {
    "name": "10% discount on toast and eggs including extras",
    "type": "percentage",
    "value": "-220",
    "amount": "-10"
  }
],
```

*This is 10% of the $11 ($1.10) multiplied by 2.*

Subsequently, your surcount calculations would be:

```
"totalAfterSurcounts": "1980",
"totalBeforeSurcounts": "2200"
```

If you do not want the variant to be applied to all items then send two item objects with the appropriate quantities and variants.

## Surcounts on Transactions

Surcounts can also be submitted as part of a transaction payload.  In doing so, it is important to ensure that the **transaction amount** is **not** impacted by the **surcount** **value**; these are exclusive of each other.

```
{ "amount": "2500", "reference": "123", "method": "visa", "prepaid": false, "surcounts": [ { "posId": "123", "name": "Surcharge", "description": "Payment Surcharge", "amount": "100", "type": "absolute", "value": "100" } ] }
```

Above example stipulates the end customer will make a payment of $25 for their order, and the payment provider will additionally charge a $1.00 surcharge. The total amount being debited from the customer's credit card would be $26.

```
{ "amount": "2500", "reference": "123", "method": "visa", "prepaid": false, "surcounts": [ { "posId": "124", "name": "Loyalty", "description": "Loyalty points discount", "amount": "-2000", "type": "absolute", "value": "-2000" } ] }
```

Above example stipulates the end customer will make a payment of $25 for their order, and $20 of this has been discounted on account of loyalty points.  The total amount being debited from the customer's credit card would be $5.

This covers the basics of surcounts. More information on the structure of sending and receiving surcounts is available in our [API reference](https://support.doshii.io/hc/en-us/articles/115004489433). Happy surcounting!

- [API concepts](https://support.doshii.com/developer-support/api-concepts?hsLang=en)
- [Members](https://support.doshii.com/developer-support/members?hsLang=en)
- [Model](https://support.doshii.com/developer-support/model?hsLang=en)
- [FAQ - Developers](https://support.doshii.com/developer-support/faq-developers?hsLang=en)
- [Resources](https://support.doshii.com/developer-support/resources?hsLang=en)
- [Orders](https://support.doshii.com/developer-support/orders?hsLang=en)
- [Rewards](https://support.doshii.com/developer-support/rewards?hsLang=en)
- [Check-ins](https://support.doshii.com/developer-support/check-ins?hsLang=en)
- [Getting started - App partners](https://support.doshii.com/developer-support/getting-started-app-partners?hsLang=en)
- [Employees](https://support.doshii.com/developer-support/employees?hsLang=en)
- [Getting started - Doshii Dashboard](https://support.doshii.com/developer-support/getting-started-doshii-dashboard?hsLang=en)
- [Quick start for developers](https://support.doshii.com/developer-support/quick-start-for-developers?hsLang=en)
- [Onboarding](https://support.doshii.com/developer-support/onboarding?hsLang=en)
- [Location](https://support.doshii.com/developer-support/location?hsLang=en)
- [All App Partners Event](https://support.doshii.com/developer-support/all-app-partners-event?hsLang=en)
- [Menus](https://support.doshii.com/developer-support/menus?hsLang=en)
- [Loyalty / Checkins](https://support.doshii.com/developer-support/loyalty-checkins?hsLang=en)
- [WebSocket - App partners](https://support.doshii.com/developer-support/websocket-app-partners?hsLang=en)
- [All POS vendor events](https://support.doshii.com/developer-support/all-pos-vendor-events?hsLang=en)
- [Loyalty / Gift Cards](https://support.doshii.com/developer-support/loyalty-gift-cards?hsLang=en)
- [Devices](https://support.doshii.com/developer-support/devices?hsLang=en)
- [Tables](https://support.doshii.com/developer-support/tables?hsLang=en)
- [Workflows](https://support.doshii.com/developer-support/workflows?hsLang=en)
- [FAQ - Doshii Dashboard](https://support.doshii.com/developer-support/faq-doshii-dashboard?hsLang=en)
- [Bookings](https://support.doshii.com/developer-support/bookings?hsLang=en)
- [Transactions](https://support.doshii.com/developer-support/transactions?hsLang=en)
- [Webhooks](https://support.doshii.com/developer-support/webhooks?hsLang=en#main-content)
  
  
  
  
  
    - [App Partners](https://support.doshii.com/developer-support/webhooks?hsLang=en#app-partners)
    - [POS Vendors](https://support.doshii.com/developer-support/webhooks?hsLang=en#pos-vendors)
- [App Partner Guide](https://support.doshii.com/developer-support/app-partner-guide?hsLang=en)
- [Authentication](https://support.doshii.com/developer-support/authentication?hsLang=en)
- [Getting started - POS vendors](https://support.doshii.com/developer-support/getting-started-pos-vendors?hsLang=en)
- [Ordering](https://support.doshii.com/developer-support/ordering?hsLang=en)
- [Reservations](https://support.doshii.com/developer-support/reservations?hsLang=en)
- [Pilot](https://support.doshii.com/developer-support/pilot?hsLang=en)
- [Bulk data](https://support.doshii.com/developer-support/bulk-data?hsLang=en)
- [Playbooks](https://support.doshii.com/developer-support/playbooks?hsLang=en)
- [Rejection codes](https://support.doshii.com/developer-support/rejection-codes?hsLang=en)
- [Getting started](https://support.doshii.com/developer-support/getting-started?hsLang=en)
- [WebSocket - POS partners](https://support.doshii.com/developer-support/websocket-pos-partners?hsLang=en)
- [Events - App partners](https://support.doshii.com/developer-support/events-app-partners?hsLang=en)
- [Service channels](https://support.doshii.com/developer-support/service-channels?hsLang=en)
- [Events](https://support.doshii.com/developer-support/events?hsLang=en)
- [Concepts](https://support.doshii.com/developer-support/concepts?hsLang=en)
- [Apps](https://support.doshii.com/developer-support/apps?hsLang=en)

# Doshii Connect Pty Ltd

Doshii Connect Pty Ltd Help Center

Copyright © 2026, Doshii Connect Pty Ltd