Adding Service charges in Line Item

Questions
1

We want to add Service charges on Line Items, we are able to add Service charges on the entire Order but not on a single Line Item.

Request

result = client.orders.create_order(
  body = {
    "order": {
      "location_id": "LR6QAWGZD3DDN",
      "customer_id": "7TTBK00HX1N05RAXS3ECQGHY1R",
      "line_items": [
        {
          "name": "tea",
          "quantity": "2",
          "item_type": "ITEM",
          "applied_service_charges": [
            {
              "uid": "101",
              "service_charge_uid": "101"
            }
          ],
          "base_price_money": {
            "amount": 500,
            "currency": "JPY"
          }
        },
        {
          "name": "Coffee",
          "quantity": "3",
          "item_type": "ITEM",
          "base_price_money": {
            "amount": 300,
            "currency": "JPY"
          }
        }
      ],
      "discounts": [
        {
          "uid": "101",
          "name": "line item",
          "percentage": "10",
          "scope": "LINE_ITEM"
        }
      ],
      "service_charges": [
        {
          "uid": "101",
          "name": "charge",
          "amount_money": {
            "amount": 150,
            "currency": "JPY"
          },
          "calculation_phase": "TOTAL_PHASE",
          "treatment_type": "LINE_ITEM_TREATMENT",
          "scope": "LINE_ITEM"
        }
      ]
    },
    "idempotency_key": "c9974015-2be5-4d7a-9da5-5755fd200e2b"
  }
)

if result.is_success():
  print(result.body)
elif result.is_error():
  print(result.errors)

Response

{
  "errors": [
    {
      "code": "BAD_REQUEST",
      "detail": "Unexpected calculation phase SURCHARGE_TOTAL_PHASE for applied service charge custom-surcharge:101.",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}
2

This is correct. The service charge can be applied to an order but it’s not scoped to line items at this time. :slightly_smiling_face:

3

@Bryan-Square

I’ve noticed that the order line items from the API now have a total_service_charge_money property (OrderLineItem Object - Square API Reference)

I’ve checked an order that happened a few days ago, which had service charge, however none of the line items had this total_service_charge_money property with anything other than 0.

Few questions:

  1. For this value to be filled, do I need to enroll in some sort of beta? Also do you know when this will graduate from beta?

  2. The docs say “The total amount of apportioned service charge money to collect for the line item.” Can I know the calculation for how the service charge will be apportioned?

  3. When this does fully roll out, will this value be available for all previous orders or only for orders going forward?

4

What’s the order_id you saw this with so we can take a look? :slightly_smiling_face:

5

Hey,

For example, this order y4ErHZBO3g8IvHLrDGfGgOueV from one of our customers.
The order has a total service charge of £15.31
As seen on the API like this

{
    "amount": 1531,
    "currency": "GBP"
}

Each line item has this total_service_charge_money property but it’s always 0, like this:

{
    "amount": 0,
    "currency": "GBP"
}

I have actually already implemented my own logic for assigning service charge at a line item level, but was just curious what this service charge field is on the line item.

6

The service charge that you see in this order is the one the customer configured in the Dashboard. It’s a per person percentage service charge that doesn’t effect any of line items. In the order you’ll see that there is a catalog_object_id UXNH24ZYDL2XESTZ33TAH7ZP for the service charge. Unfortunately, the seller configured service charges aren’t available in a list with our APIs but you will see them in the orders. :slightly_smiling_face: