Adding sales tax to payment forms from the Checkout API

I’m using the /v2/online-checkout/payment-links endpoint to capture payments. I am able to send in the items and create the payment link just fine. I have set up sales taxes in Square from Accounts & Settings, Business Information, Sales taxes. I have also gone to Online, Settings, Sales taxes and have an auto calculated tax rate there. However, the checkout form from the payment link that is generated never show any sales tax. I’m just wanting to capture payments in Square - my catalog and inventory are elsewhere.

What am I missing?

Whats your application ID? If the items in the order are items in your catalog and have the tax configured the tax should automatically apply. :slightly_smiling_face:

Hey Bryan, thanks for the quick response.

I don’t have any items in the square catalog - I trying to use it only as a payment system only. My client already has her products in a 3rd party platform and didn’t want to make the switch right away; she only wants to use the payment processing piece of the Square platform for now.

Okay, great! When creating a checkout you’ll want to pass in some form of an item. It’ll be either ad hoc or an item from the catalog. Are they wanting to create links for customers to pay with or a site where they checkout? :slightly_smiling_face:

I am passing in line items like so:

{"lineItems":[{"name":"Peppermint Ginger Tea","quantity":"2","base_price_money":{"amount":4000,"currency":"USD"},"note":""},{"name":"Greene Goddess Lubricant - 1000 mg","quantity":"2","base_price_money":{"amount":8990,"currency":"USD"},"note":"1000 mg"}],"draftOrder":{"draft_order":{"line_items":[{"title":"Peppermint Ginger Tea","price":"40.00","quantity":2},{"title":"Greene Goddess Lubricant - 1000 mg","price":"89.90","quantity":2}],"customer":{"id":null},"use_customer_default_address":true}}}'

They are wanting to launch the Square Checkout API payment screens. To see it in action go here and add something to your cart, and then (this is important) don’t check out immediately, go to the cart and click checkout from there. maggiejanesfarm
pw: tahfro

That’s an ad hoc item which is why the tax isn’t being applied. If you create an item in the Catalog and assign a tax to it it will apply the taxes. Otherwise you’ll have to pass the tax catalog_object_id in when creating the checkout. :slightly_smiling_face:

Thanks Bryan, I want to be sure I understand.

I need to create the items in the Square catalog, and then create a mapping between the 3rd party and Square items so that I have the Square catalog_object_id to pass in with each item to the /v2/online-checkout/payment-links endpoint - does that sound correct?

Yes, that’s correct. :slightly_smiling_face:

Can you tell me if there is a way to get the catalog_object_id from Square? (I can get it by making API calls; I’m just thinking of products added in the future by my client)

You’ll use the Catalog API to pull in all the items from the customers catalog. :slightly_smiling_face:

Hi Bryan,

I’ve done that using this endpoint (/v2/catalog/list?types=ITEM) but I don’t see any properties of the returned objects named catalog_object_id. I do see items and nested variations, so I’ve attempted to use the to no avail. No order is visible in Square and neither does tax show on the payment page.

Here is what I’m sending in to the /v2/online-checkout/payment-links endpoint:

{"idempotency_key":"1697834793305","order":{"location_id":"LB2904TWDYRG3","line_items":[{"catalog_object_id":"4ICQIU527EDYFWVZJ5AHAYJQ","quantity":"1","note":"1000 mg"},{"catalog_object_id":"6X5WIR5DQSZT3EFQBYSTPAY2","quantity":"1","note":"250 mg"}]},"payment_note":"1130045833529","checkout_options":{"redirect_url":"","shipping_fee":{"name":"Standard Shipping","charge":{"amount":500,"currency":"USD"}},"ask_for_shipping_address":true}}

And here’s what I get back

payment-links response:  {
  payment_link: {
    id: 'G3KMLFILXGI2O2FD',
    version: 1,
    order_id: 'jE1ihZhOSMZH7WRDVat3Zamz3gfZY',
    checkout_options: {
      redirect_url: '',
      ask_for_shipping_address: true,
      shipping_fee: [Object]
    url: '',
    long_url: '',
    created_at: '2023-10-20T20:46:34Z',
    payment_note: '1130045833529'
  related_resources: { orders: [ [Object] ] }

Perhaps I’m experiencing a conceptual error here but I would assume that an order would be created on my Square Dashboard for this.

The item_variation_id is the ID you’ll want to pass in as the catalog_object_id. Also the order won’t be visible in the Dashboard till the order is fully paid for. Here’s an example:

    "order": {
      "location_id": "{{location_id}}",
      "line_items": [
          "quantity": "1",
          "catalog_object_id": "M4ZCRV2XZ6E76FC5XDDJZQTK"
      "pricing_options": {
        "auto_apply_taxes": true
    "idempotency_key": "{{$guid}}"


Thanks for all the help.

For anyone else struggling with this, this is the piece of info that made all the difference:

In fact, using that, the taxes even worked on ad hoc items, so I didn’t have to duplicate all the items from the other store in the Square store.

Tried this on by creating an order with an ad hoc line item, and pricing_options.auto_apply_taxes set to true, but the “preview link” page did not show taxes automatically applied.

ask_for_shipping_address is also true (and pre_populated_data.buyer_address is fully filled out)

Even, oddly, allow_tipping is false, but the “preview link” page still shows the boxes for 10%, 15%, 20%, OTHER tipping options.

This is due to the payment links not being fully supported in sandbox which is why the preview doesn’t exactly match the request. If you create a production link it will show correctly. We’re constantly working to improve our features based on feedback like this, so I’ll be sure to share your request to the API product team. :slightly_smiling_face:

Awesome! Thank you, Bryan, for the quick answer. Just to clarify, “pricing_options.auto_apply_taxes” will automatically calculate (using Square’s internal database – not just my account’s sales tax entries at the taxes for the buyer based on their city and state (United States)?

The auto_apply_taxes will only calculate and add the configured taxes to the order that are set in the Dashboard. It won’t automatically build a tax that will apply to orders based on the sellers location. :slightly_smiling_face:

Ok, just trying to wrap my head around this. The buyer has to pay sales tax for online purchases based on their city and state. Square represented to my client that Square “autocalculates taxes” and now that’s the expectation they have for me. If that’s not what Square does, then that needs to be made clear on sales calls. It seems unreasonable for me to have to manually add 10,000 entries in my sales tax table to sell to US customers, and then have Square just multiply $100 * 7.5% and call that “autocalculating” when simple multiplication isn’t really a service. Please let me know if I’ve misunderstood, haha.

Edit (in response to post 19 in this thread, since you’ve now closed it): Right! I’m a bit confused about the fact that Square does offer auto tax calc for online storefronts that Square manages (Shopify competitor product) – but does not offer that same functionality via the API.

Although we’ve built a powerful tax calculation system for Square, Square cannot offer any tax advice or consultation services. Tax compliance is your responsibility. We do not guarantee the applicability or accuracy of our tax tools. If you have any questions about your tax obligations, consider consulting a professional tax advisor.

Also I believe your talking about the Online Store automatic tax calculation:
After setting up your tax registrations, you can use the automatic tax calculator. To automatically calculate US taxes for Square Online:

  1. From your Square Online Overview page, go to Settings > Sales Taxes or Shared Settings > Sales Taxes.
  2. Select Add tax rate.
  3. In the dropdown menu, select United States.
  4. Check Automatically calculate taxes.
  5. Select Save when finished.

Learn more about managing sales tax settings for Square Online. :slightly_smiling_face: