Order Service Charges

Applies to: Orders API

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

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.

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.

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.

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

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.

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.

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

{
"service_charges": [
      {
        "calculation_phase": "APPORTIONED_AMOUNT_PHASE",
        "name": "Fixed amount service charge",
        "treatment_type": "APPORTIONED_TREATMENT",
        "uid": "APPORTIONED_AMOUNT_SERVICE_CHARGE",
        "scope": "LINE_ITEM",
        "amount_money": {
          "amount": 1000,
          "currency": "USD"
        },
        "taxable": true,
        "applied_taxes": [
          {
            "tax_uid": "SERVICE_CHARGE_TAX",
            "uid": "2"
          }
        ]
      }
    ],
    "taxes": [
      {
        "name": "Service charge tax",
        "percentage": "8",
        "scope": "LINE_ITEM",
        "type": "ADDITIVE",
        "uid": "SERVICE_CHARGE_TAX"
      }
    ]
}

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.

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).

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.

Use an order-scoped, non-taxable service charge to represent a tip intended for a 3rd-party courier such as DoorDash rather than the seller’s staff. This keeps the amount out of payment‐level gratuity reporting and avoids affecting item-level taxes.

payment.tip_money is designed for staff gratuities associated with the seller’s team that should be paid out through payroll. An order.service_charge is considered the best place to pass non-line-item order adjustments, including those that are pass-through to the merchants like courier tips and delivery platform fees.

• scope- ORDER (applies to the whole order).
• amount_money - Pass in an explicit tip amount, don't calculate the service charge using a percentage.
• calculation_phase - TOTAL_PHASE or SUBTOTAL_PHASE. While this field is required in API requests, it only affects percentage-based calculations. When providing an explicit amount, the phase value is accepted but not used in calculations. Avoid using apportioned phases (like APPORTIONED_PERCENTAGE_PHASE), as these follow different rules for distributing amounts across line items.
• taxable - false
• name - A clear label like "Courier Tip" for downstream reporting.

This example shows a $1.50 tip for the courier who delivered the order:

"service_charges": [
  {
    "scope": "ORDER",
    "calculation_phase": "TOTAL_PHASE",
    "taxable": false,
    "amount_money": { "amount": 150, "currency": "USD" },
    "name": "Courier Tip"
  }
]

• Order Price Adjustments
• Order Taxes
• Order Discounts