Shopify orders

Two calls make up most of a store’s phone volume: “where is my order?” and “do you have this in stock?”. Both have exact answers sitting in Shopify, and both are answerable without a person.

The shape of it

Vociply talks to Shopify’s Admin API as a custom app — one you create inside your own store. There is nothing to install from the Shopify App Store and nothing to wait for approval on. You generate an access token, paste it into Vociply once, and the agent can read orders and products from that moment.

Three things the agent can do, and one it deliberately cannot:

• Look up a specific order, or a customer’s recent orders by email.
• Search products and read real stock, down to the variant.
• Build a draft order and have Shopify email the caller a payment link.
• It cannot take a card payment on the call. That is on purpose — see Taking an order.

1. Connect Shopify

1. Create a custom app in Shopify

   In your Shopify admin, go to SettingsApps and sales channelsDevelop apps and choose Create an app. Name it something you will recognise later — “Vociply phone agent” does the job.

2. Give it the three scopes it needs

   Under ConfigurationAdmin API integration, enable exactly these:

   Scope	What it is for
   read_orders	Answering “where is my order?”
   read_products	Quoting stock and prices
   write_draft_orders	Building an order on the call

   Nothing else. If you never want the agent building orders, leave write_draft_orders off — everything else still works.

3. Install it and copy the token

   Install the app, then open API credentials and reveal the Admin API access token. It starts shpat_.

   Shopify shows this once

   Copy it before leaving the page. If you lose it, you can uninstall and reinstall the app to get a new one — which invalidates the old token, so update Vociply afterwards.

4. Paste it into Vociply

   Go to IntegrationsShopifyConnect. You need two things:

   • Store domain — the one in your Shopify admin URL, like my-store.myshopify.com.
   • Admin API access token — the shpat_ value you just copied.

   Use the myshopify domain, not your storefront one

   If your shop is at shop.mybrand.com, that is not the domain to enter. Shopify’s Admin API only answers on the permanent .myshopify.com address. Vociply refuses the wrong one at the form rather than letting it fail on a live call.

   Saving calls your store to confirm the token works, and names the shop back to you. A wrong domain, a revoked token or a missing scope fails here, not mid-call.

5. Attach it to the agent

   On the agent, enable the Shopify tool. See attaching an integration if you have not done this before.

2. What the agent can do

3. “Where is my order?”

Shopify tracks two statuses, and callers usually mean the first while stores often quote the second. The agent gets both, so it can answer the question actually being asked.

4. Taking an order

The agent builds a draft order and Shopify emails the caller a payment link. It does not take payment on the call.

That is a deliberate limit, not a missing feature. Reading card numbers to a voice agent puts card data through your call recordings and your transcripts, which is a PCI problem you do not want and your customers should not be asked to accept. A payment link keeps the card on Shopify’s checkout, where it already belongs.

The one thing that goes wrong

A draft order needs a variant_id — not a product id. A t-shirt is one product and six variants, and only the variant knows the size. The agent must call search_products first and use the variant_id that comes back. The instructions below say so in as many words; if you rewrite them, keep that.

The instructions

A starting point. Replace {{store_name}} and adjust the tone, but keep the rules — each one exists because of a way this goes wrong.

## Who you are
You answer the phone for {{store_name}}. Today is {{date}}.

## Order status
When a caller asks about an order:
1. Ask for the order number. It usually starts with a #.
2. Use get_order with that number.
3. If they do not have it, ask for the email they ordered with and use
   search_orders instead, then confirm which order they mean by date and
   total before saying anything else about it.
4. Tell them the fulfilment status in plain words. "Fulfilled" means it
   has shipped. "Unfulfilled" means it has not shipped yet.
5. NEVER promise a delivery date. Shopify does not tell you one.

## Stock questions
1. Use search_products with what the caller said.
2. Read back the exact product name and whether it is in stock.
3. If several variants match, read out up to three and ask which they mean.
4. NEVER state a stock number you did not get from search_products.

## Taking an order
1. For every item, use search_products FIRST and keep the variant_id it
   returns. Never guess an id.
2. Confirm each line back: product name, variant, and quantity.
3. Read the whole order back before creating it.
4. Use create_draft_order with the items and the caller's email.
5. Tell them you have emailed a payment link, and give them the draft
   order number.

## Rules you never break
- You cannot take card details. If they want to pay now, tell them the
  link does it securely and offer to stay on while it arrives.
- Never confirm an order you have not read back.
- If create_draft_order fails, do NOT say the order is placed. Say you
  will call back to confirm, and take their number.

Testing it

1. Ask about a real order

   Call the agent and read out an order number you can check yourself. Confirm the status it reports matches what your admin shows.

2. Ask for something out of stock

   It should say so plainly rather than offering to order it anyway. This is the most common failure, and it only appears when stock is actually zero.

3. Place an order for a product with variants

   Pick something sold in sizes. Check the draft order in OrdersDrafts has the right variant, not just the right product — that is what a guessed id gets wrong.

4. Check the payment link arrives

   Use an email you can read. The link should open your normal Shopify checkout.

Questions