Surcount Properties and Their Values
TotalBeforeSurcounts & TotalAfterSurcounts
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.
- On the order, ie. 20% off the entire order consisting of many items, and;
- 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. Happy surcounting!