This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Specifying prices and tax amounts

When you create a marketplace facilitator order, you can provide the prices and tax amounts for the order. You typically select this option when you have a tax partner that calculates the tax amounts for you.

When you choose this option, make sure that the prices that you provide are consistent with the restaurant menu prices. You can get the prices for the current order (see Getting check prices before you submit an order), or get the prices from the menu configuration (see Get menus).

In a marketplace facilitator order that specifies prices and tax amounts:

  • For each menu item selection, provide the item price as the value of externalPriceAmount.

    For menu items that use size pricing, specify the item price as the value of externalPriceAmount for the size-price modifier. For the parent item, set externalPriceAmount to 0.00. For more information, see Specifying size prices in marketplace facilitator orders.

  • In the MarketplaceFacilitatorTaxInfo object for the order, include a taxes array of AppliedTaxRate objects.

    You provide an AppliedTaxRate object for each type of tax that applies to the order. In each AppliedTaxRate object:

    • Set name to the name of the tax. This value is not used outside of the Toast API. It can be any value that is useful for you.

    • Set taxAmount to the total amount for the tax across all of the checks and menu item selections.

    • Use the facilitatorCollectAndRemitTax value to indicate whether you will remit the amount for that tax.

      If you will remit the tax amount, set facilitatorCollectAndRemitTax to true.

      If you will not remit the tax amount, set facilitatorCollectAndRemitTax to false.

The Order object in the following example creates a marketplace facilitator order that provides the prices and tax amounts for the order. The marketplace facilitator remits the tax amount for one of the taxes, but does not remit the tax amount for the other tax.

Marketplace facilitator order that specifies prices and tax amounts

{
  "entityType": "Order",

    [contents omitted]

  "marketplaceFacilitatorTaxInfo": {1
    "taxes": [2
      {
        "name": "SomeTax",
        "taxAmount": 3.21,3
        "facilitatorCollectAndRemitTax": true4
      },
      {
        "name": "SomeOtherTax",
        "taxAmount": 2.34,
        "facilitatorCollectAndRemitTax": false5
      }
    ]
  },
  "checks": [
    {
      "entityType": "Check",
      "selections": [
        {
          "entityType": "MenuItemSelection",
          "externalPriceAmount": 123.45,6
          "itemGroup": {
            "guid": "881472e6-dd94-48c6-b5c6-25e51a864208",
            "entityType": "MenuGroup"
          },
          "item": {
            "entityType": "MenuItem",
            "guid": "9c59d4ab-8242-450f-8f36-b16e1b3ab802"
          },
          "quantity": 1,
          "modifiers": []
        }
      ],

    [contents omitted]

    }
  ]
}

1

Contains information about the taxes that a marketplace facilitator organization remits on behalf of a Toast restaurant.

2

Include the taxes value if you specify prices and tax amounts for a marketplace facilitator order.

3

Specifies the total tax amount for this tax type across all of the checks and menu item selections in the order.

4

The value true indicates that the marketplace facilitator organization will pay this tax amount for the order on behalf of the restaurant that fulfills the order.

5

The value false indicates that the marketplace facilitator organization will not pay this tax amount for the order on behalf of the restaurant that fulfills the order.

6

Specifies the price for this menu item selection. To specify prices and tax amounts for a marketplace facilitator order, include the externalPriceAmount value for each menu item selection. The specified price should correspond to the price that is configured in the restaurant menu.