AppliedServiceCharge

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/toast-tab/refs/heads/main/json-schema/orders-applied-service-charge-schema.json",
  "title": "AppliedServiceCharge",
  "description": "A service charge that is added to a check. A service charge can represent an upcharge such as a gratuity or a delivery fee.\n\nWhether the upcharge is taxable is defined in the restaurant-configured `serviceCharge`.\n\nThe fields on the `AppliedServiceCharge` are calculated based on the referenced `ServiceCharge` configuration.\n",
  "type": "object",
  "allOf": [
    {
      "$ref": "#/$defs/ExternalReference"
    },
    {
      "type": "object",
      "required": [
        "serviceCharge"
      ],
      "properties": {
        "chargeAmount": {
          "type": "number",
          "format": "double",
          "description": "The final applied amount excluding tax. Required if `chargeType` is `OPEN`."
        },
        "serviceCharge": {
          "description": "A reference to the restaurant-configured service charge. If a service charge is taxable, the tax amount is applied to the check.",
          "$ref": "#/$defs/ExternalReference"
        },
        "chargeType": {
          "x-toast-read-only": true,
          "description": "The type of service charge. Response only.\n\nValid values:\n\n* `FIXED` - The service charge is for a specific currency amount.\n\n* `PERCENT` - The service charge is for a percentage of the check amount.\n\n* `OPEN` - The service charge is not configured with an amount. The amount is specified by the restaurant employee.\n",
          "type": "string",
          "enum": [
            "FIXED",
            "PERCENT",
            "OPEN"
          ]
        },
        "name": {
          "x-toast-read-only": true,
          "description": "The configured human readable label for the service charge. Response only.",
          "type": "string"
        },
        "delivery": {
          "x-toast-read-only": true,
          "description": "Whether this service charge is a delivery charge. Response only.",
          "type": "boolean"
        },
        "takeout": {
          "x-toast-read-only": true,
          "description": "Whether this service charge is a takeout charge. Response only.",
          "type": "boolean"
        },
        "dineIn": {
          "x-toast-read-only": true,
          "description": "Whether this service charge is a dine-in charge. Response only.",
          "type": "boolean"
        },
        "gratuity": {
          "x-toast-read-only": true,
          "description": "Whether this service charge is a gratuity. Can be used to derive required tip amount on the check. Response only.",
          "type": "boolean"
        },
        "taxable": {
          "x-toast-read-only": true,
          "description": "Whether this service charge is taxable. Response only.",
          "type": "boolean"
        },
        "appliedTaxes": {
          "type": "array",
          "description": "Taxes applied to the service charge.",
          "items": {
            "$ref": "#/$defs/AppliedTaxRate"
          }
        },
        "serviceChargeCalculation": {
          "type": "string",
          "description": "Defines whether a `PERCENT` service charge is applied before (`PRE_DISCOUNT`) or after (`POST_DISCOUNT`) discounts.\n\nThis field is `null` for `FIXED` and `OPEN` service charges.\n",
          "enum": [
            "PRE_DISCOUNT",
            "POST_DISCOUNT"
          ]
        },
        "refundDetails": {
          "description": "A `RefundDetails` object that\ncontains information about refunded payment amounts for the item.\n",
          "type": "object",
          "$ref": "#/$defs/RefundDetails"
        },
        "serviceChargeCategory": {
          "x-toast-read-only": true,
          "description": "The type of service charge. Default is `SERVICE_CHARGE`. Response only.\n\nValid values:\n\n* `SERVICE_CHARGE` - The default type for a service charge.\n\n* `CREDIT_CARD_SURCHARGE` - A fee assessed _only_ on payment transactions that use a credit card.\n\n* `FUNDRAISING_CAMPAIGN` - Service charge associated with fundraising.\n\n* `CASH_ROUNDING` - Adjustment to the check total to account for cash payments with minimum denominations greater than 0.01.\n",
          "type": "string",
          "enum": [
            "SERVICE_CHARGE",
            "CREDIT_CARD_SURCHARGE",
            "FUNDRAISING_CAMPAIGN",
            "CASH_ROUNDING"
          ]
        },
        "paymentGuid": {
          "x-toast-read-only": true,
          "description": "The Toast platform unique identifier for the payment the fee is linked to. The `paymentGuid` value is always `null` unless the `serviceChargeCategory` object value is `CREDIT_CARD_SURCHARGE` or `CASH_ROUNDING`. Response only.",
          "type": "string"
        }
      }
    }
  ],
  "$defs": {
    "ExternalReference": {
      "type": "object",
      "description": "A wrapper object with fields that allow reference to a Toast platform entity by Toast GUID or a partner's identifier.",
      "allOf": [
        {
          "$ref": "#/$defs/ToastReference"
        },
        {
          "type": "object",
          "properties": {
            "externalId": {
              "description": "External identifier string that is prefixed by the naming authority. You can use the orders API to set an `externalId` for an order and then GET the order with that `externalId`.",
              "type": "string"
            }
          }
        }
      ]
    },
    "AppliedTaxRate": {
      "type": "object",
      "description": "A tax rate that is applied to an item or service charge.",
      "required": [
        "taxRate"
      ],
      "allOf": [
        {
          "$ref": "#/$defs/ToastReference"
        },
        {
          "type": "object",
          "properties": {
            "entityType": {
              "description": "The type of object this is.",
              "type": "string"
            },
            "taxRate": {
              "type": "object",
              "$ref": "#/$defs/ToastReference"
            },
            "name": {
              "type": "string",
              "description": "The name of the tax rate."
            },
            "rate": {
              "type": "number",
              "format": "double",
              "description": "The tax rate, which can be a fixed amount, a percentage, or null."
            },
            "taxAmount": {
              "type": "number",
              "format": "double",
              "description": "The tax amount that was actually applied."
            },
            "type": {
              "type": "string",
              "description": "The type of the tax rate. Default is `PERCENT`.\n\nThe value `EXTERNAL` indicates that the tax is for a marketplace\nfacilitator order, and that the marketplace facilitator\norganization calculated the tax amount.\n",
              "enum": [
                "PERCENT",
                "FIXED",
                "NONE",
                "TABLE",
                "EXTERNAL"
              ]
            },
            "facilitatorCollectAndRemitTax": {
              "type": "boolean",
              "description": "Indicates whether the marketplace facilitator that\nreceived a guest order remitted the tax amount on behalf\nof the Toast platform restaurant.\n\nYou can use this information to identify tax amounts that\nhave already been paid by an ordering service provider\nand do not need to be paid again.\n\n* `true` - The marketplace facilitator paid the tax\namount on behalf of the Toast platform restaurant\nlocation.\n\n* `false` - The marketplace facilitator has not paid the\ntax amount. The Toast platform restaurant location may be\nrequired to pay the tax amount.\n\n**Note**: Toast API response data is not guidance or\nadvice for tax compliance.\n"
            },
            "displayName": {
              "type": "string",
              "description": "The name of the tax rate as it appears on guest receipts."
            },
            "jurisdiction": {
              "type": "string",
              "description": "The state or province of the tax rate for reporting purposes."
            },
            "jurisdictionType": {
              "type": "string",
              "description": "The jurisdiction type (ex. STATE, COUNTY, etc.) of the tax rate for reporting purposes."
            }
          }
        }
      ]
    },
    "RefundDetails": {
      "type": "object",
      "description": "Information about refunded currency amounts for an item\nselection, modifier option, or service charge. The refund\ninformation includes separate values for the pre-tax value\nbeing refunded and the tax amount being refunded.\n",
      "properties": {
        "refundAmount": {
          "description": "The value of the menu item or service charge (excluding taxes) being\nrefunded. Includes the value of any nested modifier options that\nincreased the price of the item or modifier option (an upcharge for\nthe modifier option).\n",
          "type": "number",
          "format": "double",
          "example": 1.0
        },
        "taxRefundAmount": {
          "description": "The tax amount being refunded.\n",
          "type": "number",
          "format": "double",
          "example": 1.0
        },
        "refundTransaction": {
          "description": "An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.\n",
          "type": "object",
          "$ref": "#/$defs/RefundTransaction"
        }
      }
    },
    "RefundTransaction": {
      "allOf": [
        {
          "$ref": "#/$defs/ToastReference"
        },
        {
          "type": "object",
          "description": "An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.\n"
        }
      ]
    }
  }
}