Order Service Charges

Applies to: Orders API

Learn how to apply service charges to an order using the Orders API.

Link to section

Overview

Building on the example order created in Order Price Adjustments, learn how the calculation phases you set on an order affect service charges applied to an order.

Square calculates and applies any discounts on the order before service charges are applied. After discounted prices are applied to the order, service charges are applied. Service charges are scoped as follows:

  • Based on the total amount of the order - If the service charge will be taxed, it's applied before taxes are calculated.
  • Apportioned based on the individual items in the order - The apportioned charge is based on a percentage or a fixed amount.
Link to section

Calculation phases

The time that the service charge calculation happens is a calculation phase. The Orders API supports any of four calculation phases for a service charge:

  • Subtotal phase - The service charge is calculated before taxes.
  • Total phase - The service charge is calculated after taxes.
  • Apportioned amount phase - The service charge is calculated after any percentage-based apportioned service charges and before taxes.
  • Apportioned percentage phase - The service charge is calculated before any amount-based apportioned service charges and taxes.
Link to section

Phase limitations

Each calculation phase is intended to work with only certain types of service charges. When a given phase is used in the wrong type of charge, your application receives a 400 BAD_REQUEST response.

Subtotal phase service charge - Cannot be used on an order in the following condition:

  • The service charge is applied at the order line-item level.

Total phase service charge - Cannot be used on an order in the following conditions:

  • The service charge is taxable.
  • The service charge is applied at the order line-item level.

Apportioned amount phase service charge - Cannot be used on an order in the following conditions:

  • The treatment_type of the service charge is LINE_ITEM_TREATMENT.
  • The service charge has a percentage amount instead of an amount.

Apportioned percentage phase service charge - Cannot be used on an order in the following conditions:

  • The treatment_type of the service charge is LINE_ITEM_TREATMENT.
  • The service charge has a dollar amount instead of a percentage.

Important

Apportioned service charges aren't accounted for in the line_item.gross_sales_money attribute. If your sales report includes service charges in line-item totals, report on the total_money attribute instead of gross_sales_money.

Link to section

Apportioned amount service charge

An apportioned amount service charge adds a portion of the total service charge to line items in the order. If the service_charges[].scope is set to ORDER, a portion of the service charge is applied to every line. If the scope is set to LINE_ITEM, only those line items where the service charge is applied get a portion of the service charge.

Suppose the total service charge on an order is $10 and the order subtotal is $116 for the three line items. $10 needs to be apportioned across all line items using the following calculation:

  • Dog Biscuits - Chicken Flavor: ((2 @ $15 per box = $30) / $116) * 10 = $2.59
  • Handmade Sweater - Blue: (($50) / $116) * 10 = $4.31
  • Chewy Rawhide - Beef Flavor: ((3 @ $12 per box = $30) / $116) * 10 = $3.10

The following example request specifies the $10 apportioned amount service charge and the three line items:

Calculate order

Link to section

Apportioned percentage service charge

Suppose the total service charge on the order is 10% of the order subtotal (before tax). The order subtotal is $116, which means that the service charge is $11.60. That amount needs to be apportioned across all line items using the following calculation:

  • Dog Biscuits - Chicken Flavor: ((2 @ $15 per box = $30) / $116) * 11.60 = $3.00
  • Handmade Sweater - Blue: (($50) / $116) * 11.60 = $5.00
  • Chewy Rawhide - Beef Flavor: ((3 @ $12 per box = $30) / $116) * 11.60 = $3.60

The three apportioned line-item service charges ($3.00 + $5.00 + $3.60) equal the $11.60 total service charge.

Link to section

Apportioned service charge taxes

Apportioned service charges cannot have their own tax rate or amount. Instead, applied_service_charges inherit the tax of the line item it's applied to. If you add an applied tax to an apportioned service charge, it's ignored.

Link to section

Ignored service charge taxes

In the following example, an apportioned service charge is declared with a tax applied directly to the service charge:

A non-apportioned line-item service charge must have its own tax information configured with its own rate, which can be different from the line-item tax rate. If a seller wants to ensure that a service charge is taxed at the same rate as its associated line item, an apportioned service charge should be used.

Link to section

Percentage service charges

When you specify a percentage service charge to an order, Square calculates the service charge as a percentage of the whole order. If you want to apply service charges to individual line items, you need to use apportioned service charges.

Raphael's Puppy-Care Emporium has established a fund to help encourage pet adoption and is adding a service charge for this. The service charge is applied after discounts, but before taxes (subtotal phase).

The following CalculateOrder request defines this service charge (PET-ADOPT-1.5-PCT) and applies it to the order:

Calculate order

Link to section

Service charge taxes

You can apply a tax to an order-level service charge in the same way you can apply a tax to a line item. In the following example, an order-level service charge of $10 is added to an order. The service charge applies a special service charge line-item tax of 8%. The order-scoped service charge is treated as a single line item, which is why the tax needs to be a LINE_ITEM tax.

Calculate order

Note

Setting service_charges.taxable has no bearing on whether a tax is charged on the service charge. As long as you set service_charges.applied_taxes, a tax will be applied.

Link to section

See also