Create taxid via api?

Is it possible to create a new tax setting (taxId) through the api. I only see an API to apply taxids to the catalogItem.
Use case is that if we maintain a list of tax rates per location, we want to automate the full setup of a new location.

You can create every Catalog type (discount, item, tax, modifier, etc) though the upsert endpoints: https://developer.squareup.com/reference/square/catalog-api/upsert-catalog-object or https://developer.squareup.com/reference/square/catalog-api/batch-upsert-catalog-objects

Does this mean there is no way to do a tax that is just scoped to the ORDER?

For example when I read:

It notes:

taxes OrderLineItemTax
The list of all taxes associated with the order.
Taxes can be scoped to either ORDER or LINE_ITEM. For taxes with LINE_ITEM scope, an
OrderLineItemAppliedTax must be added to each line item that the tax applies to. For taxes with
ORDER scope, the server generates an OrderLineItemAppliedTax for every line item.
On reads, each tax in the list includes the total amount of that tax applied to the order

So it seems I can do just an ORDER based tax and not Catalog line item level tax.

And if so then does the user have to visit the website to setup taxes and can not use the API?

If this is correct then is there anyway to get this UUID for future api based orders from the Tax they create other than the URL of the Tax when they edit it.

Also I noticed I can add a random tax to any order

  "idempotency_key": "{{$guid}}",
  "order": {
  	"reference_id": "my-order-0001",
   "taxes": [
        {
          "uid": "{{$randomUUID}}",
          "name": "Default Tax On the Fly",
          "percentage": "8",
          "scope": "ORDER"
        }
    ],  

which is fine then the app I am building can store the UUID for later reference.

Does this line up with the patterns Square was hoping for developers to use?

With orders the uid is unique to that order. You’ll need to apply the ID of the tax object from the Sellers catalog to the order to have the correct tax apply. :slightly_smiling_face:

is there a reason this is not part of the API?

eg

  • Create Tax Resource
  • Get Tax Resource
  • List Tax Resources

Clover, Stripe and Vend all have this as part of the API.

Thanks

With Square you can Create, Get, and List taxes with our APIs. You’ll use the Catalog API to UpsertCatalogObject to create the tax object with the type TAX. Once created you can ListCatalog with the type TAX. Lastly if you have that catalog_object_id for the tax you can retrieve it with RetrieveCatalogObject.

Additionally you can SearchCatalogObject to query for taxes as well. :slightly_smiling_face:

That seems to be about “items” but I would like to, as the docs note, make an ORDER level tax eg Exclusive tax. Looking at the links you gave me, unless I am misunderstand, that is an Inclusive pattern eg adding a tax to each item.
I checked in the API in Postman as well and when I add an ORDER level tax to an order it applies it automatically to the items in the order which is great.

But ideally I was hoping to not have to add this to each order.

Below is an example of what the docs need me to do

{
   "idempotency_key":"some-uid",
   "order":{
      "reference_id":"my-order-0001",
      "taxes":[
         {
            "uid":"JOFDRDSVY5CPOUS4OUPTCY4S",
            "name":"Default Tax",
            "percentage":"8",
            "scope":"ORDER"
         }
      ],
      "line_items":[
         {
            "name":"New York Strip Steak",
            "quantity":"1",
            "variation_name":"Re",
            "base_price_money":{
               "amount":100,
               "currency":"USD"
            }
         }
      ]
   }
}

but I would have assumed, as it works with Line items in the ORDERS API I could do this instead

{
   "idempotency_key":"some-key",
   "order":{
      "reference_id":"my-order-0001",
      "taxes":[
         {
            "tax_uid":"uid-of-existing-tax-resource"
         }
      ],
      "line_items":[
         {
            "catalog_object_id":"uuid-of-existing-product",
            "quantity":"1"
         }
      ]
   }
}

you can create a tax that is scoped to the entire order without adding it to each line Item. For example:

{
    "idempotency_key": "random_uid",
    "order": {
      "location_id": "{{location_id}}",
      "taxes": [
        {
          "scope": "ORDER",
          "name": "order tax",
          "percentage": "2"
        }
      ],
      "line_items": [
        {
          "quantity": "1",
          "name": "Burger",
          "base_price_money": {
            "amount": 200,
            "currency": "USD"
          }
        }
      ]
    }
  }

:slightly_smiling_face:

Yes, I know but thanks.

I will close this thread I think in the end my feedback would be to consider making the API allow an app to create an ORDER level tax resource that can later, as I show in the examples above, by using the tax_uid of that. This way, like order line items, it is easier to add it to an order.

Thanks for you time.

You can do that with the catalog_object_id. For example here is an order request with a catalog_object_id that’s of type: TAX of 7%.

{
    "idempotency_key": "{{$guid}}",
    "order": {
      "location_id": "{{location_id}}",
      "pricing_options": {},
      "taxes": [
        {
          "scope": "ORDER",
          "catalog_object_id": "ZPTKVRGA2UDO2OZWL6ULID3H"
        }
      ],
      "line_items": [
        {
          "quantity": "1",
          "name": "Burger",
          "base_price_money": {
            "amount": 200,
            "currency": "USD"
          }
        }
      ]
    }
  }

It gives me the following response:

{
    "order": {
        "id": "BxvairsL4B5IIXpLoFrUNbQc3DFZY",
        "location_id": "{{location_id}}",
        "line_items": [
            {
                "uid": "04veW4XBo0drQyj4mcEug",
                "quantity": "1",
                "name": "Burger",
                "base_price_money": {
                    "amount": 200,
                    "currency": "USD"
                },
                "gross_sales_money": {
                    "amount": 200,
                    "currency": "USD"
                },
                "total_tax_money": {
                    "amount": 10,
                    "currency": "USD"
                },
                "total_discount_money": {
                    "amount": 0,
                    "currency": "USD"
                },
                "total_money": {
                    "amount": 210,
                    "currency": "USD"
                },
                "variation_total_price_money": {
                    "amount": 200,
                    "currency": "USD"
                },
                "applied_taxes": [
                    {
                        "uid": "Zp4H4F5zZtjccy2xT6fZvD",
                        "tax_uid": "5HSkHYm8G5fuDN4tDSC0aD",
                        "applied_money": {
                            "amount": 10,
                            "currency": "USD"
                        }
                    }
                ],
                "item_type": "ITEM"
            }
        ],
        "taxes": [
            {
                "uid": "5HSkHYm8G5fuDN4tDSC0aD",
                "catalog_object_id": "ZPTKVRGA2UDO2OZWL6ULID3H",
                "catalog_version": 1662141843438,
                "name": "Sales Tax",
                "percentage": "5.0",
                "type": "ADDITIVE",
                "applied_money": {
                    "amount": 10,
                    "currency": "USD"
                },
                "scope": "ORDER"
            }
        ],
        "created_at": "2022-09-02T20:36:47.940Z",
        "updated_at": "2022-09-02T20:36:47.940Z",
        "state": "OPEN",
        "version": 1,
        "total_tax_money": {
            "amount": 10,
            "currency": "USD"
        },
        "total_discount_money": {
            "amount": 0,
            "currency": "USD"
        },
        "total_tip_money": {
            "amount": 0,
            "currency": "USD"
        },
        "total_money": {
            "amount": 210,
            "currency": "USD"
        },
        "total_service_charge_money": {
            "amount": 0,
            "currency": "USD"
        },
        "net_amounts": {
            "total_money": {
                "amount": 210,
                "currency": "USD"
            },
            "tax_money": {
                "amount": 10,
                "currency": "USD"
            },
            "discount_money": {
                "amount": 0,
                "currency": "USD"
            },
            "tip_money": {
                "amount": 0,
                "currency": "USD"
            },
            "service_charge_money": {
                "amount": 0,
                "currency": "USD"
            }
        },
        "source": {
            "name": "Boats"
        },
        "pricing_options": {},
        "net_amount_due_money": {
            "amount": 210,
            "currency": "USD"
        }
    }
} 

:slightly_smiling_face: