What Can an AI Support Agent Do in Yotpo? Loyalty Points by API Key, Reviews Behind an Expiring Token (2026)

Which Yotpo support jobs can an AI agent do through the API?

From Yotpo's Loyalty & Referrals reference and UGC reference, read 28 September 2026. Loyalty calls go to https://loyalty.yotpo.com/api/v2 with X-GUID and X-API-KEY; reviews calls go to api.yotpo.com with X-Yotpo-Token.

Count the loyalty rows and you get two reads and four writes on a key the docs never say expires. Count the reviews rows and you get one read that needs a regenerated token and no documented moderation endpoint at all. Yotpo's reference lists "Create an answer to a question" for Q&A, but nothing that publishes, hides or replies to a review.

Why do Yotpo's loyalty and reviews APIs authenticate differently?

The loyalty API has its own auth: a GUID and an API key from Settings, General Settings in the loyalty admin, sent as two headers or as guid and api_key query parameters (Yotpo authentication). Yotpo's help center lists those credentials under "Free, Pro, Premium, Enterprise" (finding your API key and GUID). Nothing in the loyalty reference says the key expires.

The reviews side runs on Yotpo's newer token model. You send the store ID (Yotpo also calls it the app key) and the API secret to POST /core/v3/stores/{store_id}/access_tokens, and you get back a token for the X-Yotpo-Token header. Yotpo's Generate Access Token page says: "If your token expires and you get a 401 error code, you'll need to generate a new token." It doesn't say how long a token lasts. The secret is harder to get than the loyalty key, too: Yotpo's app key article says it's "only visible to the Yotpo account administrator," and revealing it takes an emailed verification code.

A Macha custom tool is one HTTP request with fixed headers. It can't call the token endpoint, read the result and retry with the new token when the old one returns 401. That's the whole reason the reviews rows above say "not feasible," and it matches what our review apps comparison concluded for Yotpo Reviews.

Plan gates follow the same split. Yotpo's pricing page, read in a browser on 28 September 2026, shows "Integrate via API & Webhooks" with a check only under Premium in the Reviews & UGC comparison, and Premium is quote-only. Enterprise adds "Custom API setup." The loyalty key sits on the Free plan. Our read of the incentive is that loyalty keys have to exist on every plan because the program can't award points without an integration feeding it orders, while reviews API access is one of the things Yotpo uses to move a store from Pro to a custom-quoted plan.

The app key article, though, lists its secret key under "All plans," so a store below Premium can generate a secret. Whether Yotpo honors reviews API calls from a Starter or Pro store isn't something we could test, and the pricing page is the more specific of the two documents.

VIP tier changes through the API, added 28 September 2026

Until 28 September 2026 Yotpo's API could only remove a customer from an action-based tier; our loyalty apps comparison now covers the new endpoint too. On that date Yotpo's changelog added "Manage VIP tiers through the API," with three v3 endpoints: Get VIP Tiers Program, Get VIP Tiers Program Status and Push Customer to Tier. Push Customer to Tier takes the shopper's yotpo_customer_id in the path, a tier_id, an optional planned_end_at date and a rewards_policy of AWARD_ENTRY_REWARDS or IGNORE_ENTRY_REWARDS.

The same page says "Requests require your Yotpo access token in the X-Yotpo-Token header." The tier endpoints moved to api.yotpo.com/loyalty and to the token model, so a store's static loyalty key doesn't reach them. For an AI agent, tier changes are in the same bucket as review lookups: documented, but not reachable with a credential that doesn't expire. The same release added yotpo_customer_id to Fetch Customer Details, which is the ID the tier endpoint wants, so the lookup half of that chain already works on the static key.

How does the lookup work, from email to points and tier?

It's one call. GET /api/v2/[email protected]&with_history=true returns the whole record, per Fetch Customer Details. The fields an agent needs:

• points_balance: what the shopper can spend now.
• points_expire_at: the next expiry date, or null if points never expire under the store's policy. On a "Date Earned" policy it's only the closest upcoming batch, not every batch.
• vip_tier_name, plus vip_tier_upgrade_requirements with points_needed, amount_cents_needed and purchases_needed, which is the answer to "how close am I to Gold?"
• history when with_history=true: earnings, redemptions and expirations, which is how an agent checks a "my points disappeared" claim.
• yotpo_customer_id: Yotpo's internal ID, added on 28 September 2026.

The call also accepts customer_id (your store's ID), pos_account_id or phone_number. Yotpo says the phone number must be in E.164 format and "must be an exact match," so an agent has to turn "(555) 555-0123" into +15555550123 before it asks. Email is simpler, and it's what arrives on the ticket.

Money fields come back in cents. amount_cents_needed: 4000 means $40 of spend to the next tier, and an agent that reads it as 4,000 dollars has made the most embarrassing mistake available here. The instruction below says so.

Here's the read tool as we configured it on our Macha Demo account, with a placeholder key. X-API-KEY goes in the tool's API key field and X-GUID goes in as a static header, since custom tools can send several fixed headers.

Run Test sent the request to Yotpo's live API and got HTTP 401 with {"error":"merchant not found"}. That's the answer a wrong GUID gets. It proves the request reached Yotpo with both headers; it says nothing about how a real record reads.

What do Yotpo's Gorgias and Zendesk integrations already do, and where does an AI agent add something?

Check these before building anything, because on the right plan they cover a lot.

Gorgias. Yotpo's Gorgias integration guide lists "Premium, Enterprise" for both Reviews and Loyalty & Referrals, while the pricing table above checks Gorgias Integration on Pro as well. The Yotpo Customer Widget in the Gorgias sidebar shows VIP tier, point balance, lifetime points, redemptions and referrals, plus review averages, sentiment, Yotpo's top topics and the five latest reviews with their published status. Reviews and questions can be escalated from Yotpo into Gorgias tickets and moderated from there. The guide also shows how to add an Adjust Points button: POST to https://loyalty.yotpo.com/api/v2/points/adjust with x-api-key and x-guid headers, customer_email filled from the ticket and the point amount left as an editable field. That's the same endpoint and headers our custom tool uses, clicked by a person instead of chosen by an agent. Our Yotpo and Gorgias setup guide walks through the install.

One timing detail matters for anyone reading that widget: Yotpo says loyalty data syncs "within five minutes" after a message event and doesn't refresh again until the next one. A shopper who earned points this morning and writes in this afternoon may see a different number in Yotpo than the widget showed yesterday.

Zendesk. Yotpo's Zendesk integration, on Premium and Enterprise, does something else entirely: it emails a service review request after a ticket is solved, two days later by default, and on install it sends requests for every ticket solved in the previous 15 days. It doesn't show loyalty or review data inside a Zendesk ticket. We found no Yotpo integration guide for Freshdesk, Front, Intercom or HubSpot that shows loyalty data beside a ticket; the pricing table's "Help Desk Integrations" row describes collecting service reviews from "Zendesk, Freshdesk, and more."

Where an AI agent adds something. The Gorgias widget displays and the button waits for a person. An agent can read the record when the ticket arrives, answer the balance or tier question in the first reply and apply a points rule you've written down, such as giving back expired points once. On Zendesk and the other desks, where Yotpo shows nothing beside the ticket, the agent is also the only thing that brings the loyalty record to the conversation.

Which Yotpo actions should stay with a person?

• VIP tier changes. The endpoint now exists, but it needs the expiring token. Hand these off with the current tier and the upgrade requirements in a note.
• Anything about a review. Removal requests, "why isn't my review showing," a complaint written in a review. The API an agent could reach doesn't touch reviews.
• Points for orders that aren't in the history. Yotpo awards order points through your campaigns. If an order is missing, the fix is usually in the store integration, and adding points by hand can double-award when the order syncs later.
• Large or repeated goodwill. Set a cap in the instructions. Above it, a person decides.
• Refund reversals. POST /api/v2/refunds reverses points in proportion to the refunded amount, per Yotpo's refund recipe. If your store integration already sends refunds, a second call from an agent reverses them twice.

How is it set up with Macha?

Yotpo has no built-in Macha connector. Yotpo Loyalty connects through a custom API tool that Macha's team sets up during onboarding, authenticated with the GUID and API key as two fixed headers. Custom tools are included on every plan. Yotpo Reviews and the VIP tier endpoints aren't feasible today, for the token reason above.

Macha's team builds the read tool first, then a Write tool only for the action your team wants automated. We built "Restore expired points" as a narrow Write tool rather than a general "adjust points" one. It always sends apply_adjustment_to_points_earned: false, the value Yotpo's Adjust a Customer's Point Balance table gives for refunding points lost to expiration, so a restored balance doesn't inflate the shopper's lifetime points and push them toward a tier they didn't earn. The agent only chooses the email and the number.

Before pointing it at Yotpo, we pointed a temporary copy at an echo service to see exactly what Macha sends. With points set to 300, the body arrived as "point_adjustment_amount":300, an integer, next to "apply_adjustment_to_points_earned":false, and both X-Api-Key and X-Guid were on the request. Yotpo's reference says a non-number gets a 422, "point_adjustment_amount is not a number," so this check is worth the two minutes. We deleted the echo copy afterward.

This endpoint has no ID in the URL, so the body-template limit we hit on the Judge.me page doesn't apply. If you build a tool for an endpoint with a path ID, put that parameter in a header so Macha fills the URL.

In our 28 September dashboard tests, custom Write tools ran without a confirmation card. Built-in Zendesk writes showed one. So the safety has to live in the agent's instructions: when to write, how much, and when to hand off.

Agent instruction example

This is the instruction we gave the test agent, word for word.

You handle tickets about our rewards program. Our loyalty app is Yotpo Loyalty & Referrals. 1. Read the ticket and work out what the customer wants: their points balance, points missing for an order, points that expired, a reward or coupon they redeemed, their VIP tier or how far they are from the next one, or a referral. 2. Call "T4-155 Yotpo Loyalty: Fetch customer by email" with the requester's email. If Yotpo has no record for that email, ask the customer which email they used at checkout. Never look anyone up by a different email unless the customer gives it to you in this ticket. 3. Answer from the record. points_balance is what they can spend now. points_expire_at is when their next points expire; if it's empty, their points don't expire. vip_tier_name is their current tier, and vip_tier_upgrade_requirements says what's left for the next one (points_needed, amount_cents_needed in cents, purchases_needed). Quote those numbers exactly; don't round them or convert points to dollars. 4. Missing points for an order: look for the order in the history. If it isn't there, don't add points. Reply that a teammate will check the order and add an internal note with the order number, order date and what the customer expected. 5. Expired points: you may give back expired points once per customer, only when the history shows an expiration in the last 30 days and the customer asks for them back. Call "T4-155 Yotpo Loyalty: Restore expired points" with the exact number that expired, never more than 500. For anything else (over 500, older than 30 days, a second request, or points lost to a refund) hand off to a teammate with a note. 6. You can't change a VIP tier. Tier changes go to a teammate: reply that someone will look at it today and add a note with the current tier and the upgrade requirements. 7. If a Yotpo tool returns an error, don't call any other Yotpo tool on this ticket, and never call the Restore tool. Don't tell the customer what went wrong inside our systems. Reply that a teammate is checking and will follow up today, add an internal note with the tool name, the HTTP status, the error message and everything the customer asked for, and tag the ticket app_tool_error. Never paste the customer's address or phone number into a note.

The 30-day window and the 500-point cap are placeholders. Set them from your own program's expiry policy and what a point is worth to you.

What happened when we ran a Yotpo agent on a test ticket

On 28 September 2026 we created an inactive agent, "T4-155-Yotpo loyalty points", on our Macha Demo account with the instruction above, four Zendesk tools (get ticket, public reply, internal note, tags), the Yotpo read tool and the Restore expired points Write tool. Both Yotpo tools used a placeholder GUID and key, so any call would reach Yotpo's live API and be refused. We don't have a Yotpo store to test against, and with a placeholder key the Write tool couldn't change anything even if the agent called it.

We used Macha's Test run, which creates a new ticket on our d3v-macha Zendesk sandbox and runs the agent with only its attached tools. The made-up customer, Maya, wrote that 300 points expired on September 20 before she could use them in a fall sale, asked for them back, and asked how close she was to Gold after an $84 order, #1502. That's a write request and a tier question in one ticket, which tests whether the agent reads before it writes.

What the agent did, in order:

1. Called "Fetch customer by email" with [email protected] from the trigger payload. Yotpo returned HTTP 401, "merchant not found." The run's step card labeled it "Failed, no change made."
2. Read the ticket.
3. Tagged it app_tool_error.
4. Posted a public reply saying a teammate was checking her rewards account, the expired points, her Gold status and the order, and would follow up today.
5. Added an internal note with the tool name, the status, Yotpo's error text and all three of Maya's points: the 300 expired points, the Gold question and order #1502.

It never called Restore expired points. Its summary said, "No further Yotpo actions were taken, and no point restoration was attempted, per instructions." The run completed in 10.9 seconds.

That's rule 7 doing its job. Our Smile.io test the same day went the other way: that agent guessed a points rate and attempted a goodwill write. The instructions differed: this one names the Write tool and says when never to call it. The reply also didn't mention an error or Yotpo, which is what the instruction asked for.

What we didn't see: a successful Yotpo response, a real vip_tier_upgrade_requirements object, or the restore branch. Those need a live GUID and key. The 401 proves the request shape reached Yotpo with both headers; it doesn't prove the agent reads cents correctly or picks the right expired amount from a real history.

What goes wrong with the Yotpo API?

• Two different rate limits. Yotpo's loyalty Welcome page says 1,500 calls a minute, and its Guidelines & Conventions page says 10 requests a second per merchant account. 1,500 a minute is 25 a second (1,500 ÷ 60), so plan for the lower figure. One lookup and at most one write per ticket stays far below either.
• HTTP 423 on a busy record. Adjust and Create Redemption return 423, "Resource is currently being processed," when the customer record is mid-update. Yotpo says to retry the same request after a few seconds. An agent shouldn't retry a write on its own; hand it off.
• The wrong flag on an adjustment. apply_adjustment_to_points_earned changes lifetime points, which can feed tier progress. true for a reward, false for restoring expired or redeemed points, per Yotpo's table. Fix it in the body template, not in the agent's judgment.
• Cents read as dollars. amount_cents_needed and total_spend_cents are in cents. credit_balance is a formatted string like "$0".
• "merchant not found" means the GUID. That's the 401 a bad GUID gets. Check the GUID before the key.
• Tokens that expire on the other APIs. Reviews, VIP tier pushes and the Core API all use X-Yotpo-Token. A tool built for them works until the token expires, then returns 401 on every call with nothing to regenerate it.
• Stale data on reads you can make. Yotpo's Retrieve all reviews returns data "with a delay of 1 hour" and Search reviews with a delay of 3 hours, so even a token-holding integration answers "where's my review?" from slightly old data.

Where Macha fits

Macha fits Shopify stores on Yotpo Loyalty that run Zendesk, Freshdesk, Gorgias, Front, HubSpot or Intercom and get points tickets by email or chat: "where are my points," "my points expired," "how close am I to Gold." The agent looks up the shopper by email, answers from the balance, expiry and tier fields, applies the one points rule you've written down and hands the rest to a person with the record in a note. Yotpo Loyalty connects through a custom API tool that Macha's team sets up during onboarding, authenticated with the GUID and API key as two fixed headers, and that key is on every Yotpo loyalty plan including Free. Yotpo Reviews and VIP tier changes stay with your team and Yotpo's own tools, because both need a token that expires. On Gorgias with Yotpo Premium or Enterprise (per Yotpo's guide; its pricing page also checks Pro), the widget and Adjust Points button already put the record in front of a person; Macha adds the first reply and the rule. On Zendesk, where Yotpo's integration only sends service review requests, Macha is what brings the loyalty record to the ticket. It's the wrong fit if your Yotpo tickets are mostly about reviews or tier moves, because those are exactly the jobs the static key can't reach. Macha is priced per ticket from $299/month for 750 tickets (see pricing), so a points ticket with one lookup, one note and one reply is one charge. The loyalty apps comparison covers Smile.io, LoyaltyLion, Stamped and the rest, and which Shopify apps an AI agent can work with maps the whole stack. How custom tools are configured is in the custom tools docs.

Frequently asked questions

Does Yotpo have an API an AI support agent can use? Yes, for loyalty. Yotpo's Loyalty & Referrals API takes a static GUID and API key and lets an agent read a shopper's points, expiry and VIP tier by email and adjust or redeem points. The reviews API needs an access token that expires, so it isn't practical for a tool with fixed headers.

Which Yotpo plan includes API access? Yotpo's help center lists the loyalty API key and GUID on Free, Pro, Premium and Enterprise. For reviews, Yotpo's pricing page checks "Integrate via API & Webhooks" only on Premium, which is sold on a custom quote, and Enterprise adds custom API setup.

How do you authenticate with the Yotpo Loyalty API? Send the GUID in an X-GUID header and the API key in an X-API-KEY header, both copied from Settings, General Settings in the loyalty admin. Yotpo also accepts them as guid and api_key query parameters, but headers keep the key out of URLs and logs.

Can an AI agent change a Yotpo VIP tier? Not with the static loyalty key. Yotpo added a Push Customer to Tier endpoint on 28 September 2026, but it requires an X-Yotpo-Token access token, which expires and has to be regenerated from the store's API secret.

Can an AI agent reply to or remove a Yotpo review? No. Yotpo's UGC API reference has no endpoint that replies to, publishes or hides a review, and reading reviews needs the expiring token. Yotpo's Gorgias integration lets a person moderate escalated reviews from tickets. Yotpo's Gorgias guide lists that integration on Premium and Enterprise, while its pricing page also checks it on Pro.

Does Yotpo integrate with Zendesk? Yes, but only for service reviews. On Premium and Enterprise, Yotpo emails a review request two days after a Zendesk ticket is solved, and sends requests for tickets solved in the last 15 days when you connect it. It doesn't show loyalty or review data in the ticket.

How we researched this

• Loyalty API: Yotpo's Loyalty & Referrals reference, read on 28 September 2026 from its markdown pages: Welcome, Authentication, Guidelines & Conventions, Fetch Customer Details (updated 27 September 2026), Adjust a Customer's Point Balance, Create Redemption, the redeem and refund recipes, and the changelog, where "Manage VIP tiers through the API" and the yotpo_customer_id entry carry a 28 September 2026 date.
• VIP tier endpoint: Push Customer to Tier, 28 September 2026, including its X-Yotpo-Token requirement and api.yotpo.com/loyalty server.
• Reviews API and tokens: Yotpo's UGC API welcome, its reference index, Retrieve all reviews, Search reviews, and the Core API's Generate Access Token, all 28 September 2026. None of these states a token lifetime.
• Credentials and plans: Yotpo help center articles on the app key and secret key and the loyalty API key and GUID, and Yotpo's pricing page Reviews & UGC feature table, read in a headless browser, all 28 September 2026. The pricing page and the Gorgias guide disagree on whether Pro includes the Gorgias integration; we report both.
• Help desk integrations: Yotpo's Gorgias guide and Zendesk integration articles, 28 September 2026.
• Popularity: Shopify App Store listings on 28 September 2026: Yotpo Product Reviews 4.8 from 4,627 reviews, and Yotpo Loyalty Rewards Program 4.7 from 968.
• Arithmetic: 1,500 calls a minute ÷ 60 seconds = 25 calls a second, against the 10 a second on the guidelines page.
• What we ran: on 28 September 2026 we built two custom tools on our Macha Demo account with a placeholder GUID and key: "T4-155 Yotpo Loyalty: Fetch customer by email" (Read) and "T4-155 Yotpo Loyalty: Restore expired points" (Write). Each tool's Run Test got HTTP 401, "merchant not found," from Yotpo's live API. A temporary copy of the Write tool pointed at httpbin.org confirmed the body Macha sent; we deleted it afterward. We then ran the inactive agent once with Macha's Test run on made-up ticket #1156 on our d3v-macha sandbox; the run completed in 10.9 seconds. The customer, email, order number and points are synthetic, and no real Yotpo account was read or changed.
• Not tested live: any successful Yotpo call, the restore branch, redemptions, refunds, the reviews API and the VIP tier endpoints.

To see the same setup on your own help desk, start a trial with $50 of free usage (about 125 tickets), no credit card, no time limit, and ask the Macha team to build the Yotpo Loyalty tools during onboarding.