Managed Agents at Previously $0.06 $0.03/minManaged Agents are Previously $0.06 $0.03/min.
Webhook tool

Square AI voice agents that tell callers if their order is ready

The caller asks about a pickup order, and the agent finds it by caller ID and reads back its state from Square's Orders API, through a service of yours.

Start buildingRead the docs

Pickup order agent

Tells callers whether their pickup order is ready.

Instructions

When a caller asks about an order, look it up by their phone number. Say in plain words whether it has been received, is being made, or is ready to collect. Don't read out order IDs or prices. If no order matches, say so and transfer to the store.

Handoff
Store staff

Connected tools

  • Check pickup orderWebhook
  • Transfer to storeTransfer

What a Square AI voice agent can do

Open one to watch a call. The grey lines are the tools the agent calls mid-sentence.

The agent says whether a pickup order is received, being made or ready, from the fulfillment state your staff set in Square.

Tool definitions

Webhook tools go to POST /v1/agents/tools. Transfers are a system tool on the agent. Replace the placeholder values in capitals with your own.

Webhook

Check pickup order

Returns the state of the caller's open pickup order.

Show the JSON definition
check_pickup_order
{
  "type": "webhook",
  "name": "check_pickup_order",
  "description": "Finds the caller's open pickup order by their phone number. Returns the fulfillment state, or that no open order matches.",
  "pre_tool_speech": "auto",
  "execution_mode": "immediate",
  "response_timeout_secs": 20,
  "api_schema": {
    "url": "https://api.your-company.com/square/pickup-status",
    "method": "POST",
    "request_body_schema": {
      "type": "object",
      "properties": {
        "phone": {
          "type": "string",
          "dynamic_variable": "system__caller_id"
        }
      },
      "required": []
    },
    "authentication": {
      "mode": "bearer",
      "token": {
        "type": "secret",
        "secret_value": "YOUR_SERVICE_TOKEN"
      }
    }
  }
}

Transfer

Transfer to store

Cold transfer to the store's phone.

Show the JSON definition
transfer_to_store
{
  "config": {
    "system_tools": {
      "transfer_to_number": {
        "description": null,
        "pre_tool_speech": "auto",
        "transfers": [
          {
            "destination": {
              "type": "phone",
              "phone_number": "+14155550174"
            },
            "condition": "No open order matches the caller, or the caller wants to change, cancel or pay for an order."
          }
        ]
      }
    }
  }
}

Set it up

No native connector and no Square App Marketplace listing. The tool calls a service of yours, which holds a Square access token and reads orders. Vendor details read in November 2026.

  1. Get an access token

    For your own Square account, copy a production personal access token from the Developer Console. Apps that serve other sellers use OAuth with ORDERS_READ and CUSTOMERS_READ.

  2. Find the customer

    Your service calls POST https://connect.squareup.com/v2/customers/search with an exact phone_number filter on the caller ID.

  3. Find the open order

    Call POST /v2/orders/search with your location_ids, a customer_filter for that customer and a state_filter of OPEN, then read each PICKUP fulfillment's state.

  4. Add the tool and test

    Point the tool at your service with a bearer secret, then place test pickup orders and call about each one as staff move it along.

Documentation

Before you build

Why a service in the middle

The lookup takes two calls, one for the customer and one for orders, and Square returns full orders with items and prices. Your service returns only the state.

What each state means

For pickup, PROPOSED means received, RESERVED means accepted, PREPARED means ready and COMPLETED means picked up. Staff have to mark orders in Square for this to work.

The customer filter is in beta

Square marks the orders customer_filter as Beta, and an order with no customer attached can't match it. Test with orders from each channel you sell through.

Offline orders arrive late

Point of Sale orders taken offline can take up to 72 hours to reach Square, so the agent can't see them until the device syncs.

Use cases for teams on Square

Retail and e-commerce

AI voice agents that answer order questions, offer exchanges instead of refunds, and help shoppers buy with confidence. $0.03/min.

See the use case

Customer support

Resolve support calls on the first try, refund and credit within your rules, and keep customers who call to cancel.

See the use case

More integrations

All integrations
Webhook tool

Stripe

Look up invoices and send a payment link from a voice agent, through a service of yours. The agent never takes card numbers.

  • Managed Agents
See the integration
Webhook tool

QuickBooks Online

Read open invoices, log a payment promise and create customers in QuickBooks Online from a voice agent, through a service of yours.

  • Managed Agents
See the integration
Webhook tool

Xero

Find a Xero contact, read outstanding invoices and add a note from a voice agent, through a service that holds your Xero OAuth token.

  • Managed Agents
See the integration

Enterprise-grade security

  • HIPAA compliant badge

    HIPAA compliant

  • SOC 2 Type 2 badge

    SOC 2 Type 2

  • GDPR badge

    GDPR

Square AI voice agent FAQs

Does Square have an AI phone agent?

Yes. Square AI answers calls to your Square-provided business number and takes orders from your online ordering profile, on Square Plus, Premium or Messages Plus. A Cartesia agent instead reads order status from Square's Orders API, on the number you choose.

Can an AI agent check a Square pickup order's status?

Yes. Your service matches caller ID to a Square customer, searches that customer's open orders, and reads each pickup fulfillment's state. The agent then says whether the order is received, being made or ready. Staff have to mark orders in Square for this to work.

Why can't the agent find some Square orders?

Two cases. Square's orders customer filter is in beta, and an order with no customer attached can't match it. And orders taken offline in Square Point of Sale can take up to 72 hours to reach Square.

Can the agent take a payment over the phone?

No. The tool on this page only reads orders. Payments, changes and cancellations go to your staff through the transfer.

What does a Square order-status agent cost to run?

Agents run at $0.03/min, plus LLM usage and telephony. Your Square plan is billed by Square. Transfers only work on Twilio and SIP trunk calls, so put the number on Twilio or a SIP trunk if the agent hands callers to staff.

Get started today

Talk to an expert.

Connect with a member of our team and learn how Cartesia can help you build world-class voice experiences.

Contact Sales

Start building.

Access our models via API and bring a voice agent into production in minutes.

Try Cartesia