What Can an AI Support Agent Do in Smile.io? Points Balances, VIP Tiers and Missing Points (2026)

Which Smile.io support jobs can an AI agent do through the API?

We read every support-relevant endpoint in Smile's REST API reference on 28 September 2026. The base URL is https://api.smile.io/v1 and every call carries Authorization: Bearer api_..., a key the merchant creates with the scopes it needs.

The customer lookup returns everything a "where are my points" reply needs in one response, and the points transaction endpoint is the only documented way for anything outside Smile Admin to fix a balance.

What do customers ask about Smile.io points?

Loyalty tickets are small and repetitive. A shopper wants their balance before a sale, asks why an order didn't earn points, forgets which tier they're in, or can't find the discount code they redeemed last month. Promotions add to them: Smile's pricing page lists "2x points weekends" as a Standard-plan feature, and a double-points weekend gives every shopper a reason to check that the extra points arrived.

Each of those questions has a stored answer. Nothing in the reply needs judgment except the goodwill fix, where someone decides whether a missing order deserves points. So the setup splits the same way: read tools the agent can use freely, and one write tool with a rule.

How does the lookup work, from email to balance?

The help desk gives the agent the requester's email. The agent calls GET /[email protected]&include=vip_status and gets back a customer with id, state (candidate, member or disabled), points_balance, referral_url and a vip_status object. That object carries vip_tier_id, vip_tier_expires_at, progress_value, next_vip_tier_id, delta_to_next_vip_tier and delta_to_retain_vip_tier. The tier id is a number, so a second call to GET /vip_tiers turns it into a name like "Gold".

Smile's docs flag one trap in the list customers reference: Smile "does not enforce uniqueness on email, so multiple customer records may be returned." An agent that reads the first record and quotes its balance can be wrong. The instruction further down tells it to stop and hand off when more than one record comes back.

The state field matters too. A candidate is a shopper Smile knows about who hasn't joined the program, which usually explains a zero balance better than any missing-points theory.

Why do customers say their points are missing, and what can the agent check?

Smile's troubleshooting article lists the causes, and most can be checked from data the agent can read:

• Guest checkout. If the program is set to "Only customers who have a store account", guests don't earn until they create an account (Shopify only). A candidate state or no customer record points here.
• Order status. Points are awarded when the order reaches the status set in order settings; on Shopify, "Paid" is the recommended setting. An authorized-but-unpaid order hasn't earned yet. Macha's built-in Shopify connector can read the order's financial status with Get Order, so the agent can see this without a Smile call.
• Refunds. Smile's recommended settings remove points for Refunded and Partially Paid orders, so a refunded order legitimately takes points back. The transaction history shows the deduction.
• Items added after the order. Smile "does not review or recalculate the points awarded for that order", and the fix it gives is a manual balance adjustment.
• Settings changes. "Changes to your order settings only apply to new orders", so a store that changed its rules last week won't see old orders re-scored.

The agent's job is to read the customer, the transaction history and the Shopify order, match the case to one of those causes, and either explain it or apply the fix your policy allows.

What does Gorgias's Smile integration already do?

On Gorgias, most of the read side already exists. Smile's Gorgias integration overview says it will "display loyalty data (points, VIP tier, referral URL) alongside support tickets", lets agents "use Smile variables in macros" and can "trigger Gorgias rules based on a customer's points balance or VIP tier." It's built by Gorgias, it works on Smile's Essential plan and above, and it counts toward the plan's integration limit (one integration on Essential, two on Standard). Gorgias's own doc adds that you can't connect more than one Smile account.

Neither doc describes adjusting points or redeeming a reward from the ticket. A Gorgias macro can quote the balance; someone still opens Smile Admin to fix one. Smile lists two other support-tool integrations, Re:amaze ("display loyalty data alongside support conversations") and HubSpot (syncing points balance and VIP tier into the CRM). Smile's integrations list on 28 September 2026 had no Zendesk, Freshdesk, Intercom or Front entry, so teams on those desks get no Smile data beside the ticket without building it. Our Gorgias integrations roundup covers the wider Gorgias ecosystem.

Why is API access on the Plus plan?

Smile's pricing page lists "API access" under Plus and "Custom API rate limits" under Enterprise, and none of the four lower plans (Free, Essential, Standard at $79 and Growth at $199 a month) has either. Smile's merchant credentials guide says it plainly: "Merchant credentials are only available on the Plus or Enterprise plan."

Smile's incentive shows in who gets which door. Merchant API keys are for one-off custom work, and gating them at Plus turns API access into an upsell for brands big enough to employ a developer. Smile's partner path runs the other way: an OAuth app works on "any paid plan", can create loyalty accounts through the API and can subscribe to webhooks, none of which a merchant key can do, according to Smile's OAuth migration guide. So Smile routes most stores to listed apps like the Gorgias integration and reserves direct keys for the accounts large enough to pay for custom builds. For a support team below Plus, that means the Gorgias sidebar or a human in Smile Admin, not an API-driven agent.

Which Smile.io actions still need a person?

• VIP tier changes. There's no tier-change endpoint in the API reference. Smile's help article moves tiers in Smile Admin under Customers, VIP card, Change tier, and "It is not possible to manually downgrade a customer to a lower tier."
• Goodwill above your threshold. POST /points_transactions will add any amount the key allows. Decide the cap in the agent's instructions (for example, only the points the missing order would have earned, and never more than one order's worth) and route anything bigger to a person.
• Deductions. A negative points_change removes points, and Smile rejects a transaction that "would result in a negative points balance." Taking points away is a customer-relations call; keep it with a human.
• Account creation. A merchant API key can't create a loyalty account, so "sign me up" goes back to the store's signup flow.

How is it set up with Macha?

Smile.io has no built-in Macha connector. It connects through a custom API tool that Macha's team sets up during onboarding, using Smile's Bearer auth with an api_ key the merchant generates under Settings, Developer tools in Smile Admin. Custom tools are included on every plan. The key's value is shown once when it's created, so the merchant pastes it straight into the tool's Bearer Token field, where it's encrypted at rest and never shown to the model.

Macha's team builds the read tools first: customer by email, points transactions by customer id, reward fulfillments, VIP tiers. Then the two writes, marked Write: create points transaction and purchase points product. The custom tools docs describe the Read and Write types and say a Write tool asks for confirmation in chat; on a triggered run it runs directly when the agent's instructions say to. In our own chat test, the built-in Zendesk writes paused for confirmation but our custom Write tool went straight to Smile (the run is below). Either way, the goodwill cap has to live in the instructions and the key's scopes, not in someone's click.

The key only needs the scopes those tools use (customer:read, points_transaction:read, reward_fulfillment:read, vip_tier:read, plus points_transaction:write and points_purchase:write if you want the writes), so a key made for the agent can't touch earning rules or program settings.

The rest of the ticket runs on built-in pieces. Macha's Shopify connector reads the order (Get Order, Lookup Customer), and the help desk connector posts the reply or internal note on Zendesk, Freshdesk, Gorgias, Front, HubSpot or Intercom. Our custom API tools guide walks through the tool form field by field.

We didn't have a Smile Plus account, so we built both tools on our Macha Demo org with a dummy api_ key and ran the tool's Test button against Smile's real endpoint. Smile answered HTTP 401, which is what its errors page returns when credentials "are missing from the request or are incorrect": the URL and Bearer header reach Smile, and a real Plus key is the only missing piece. We didn't read live customer data, so the response fields above come from Smile's reference. The next section shows what the agent did with those tools on a made-up ticket.

What happened when we ran a Smile.io agent on a made-up ticket?

We built an inactive agent, "T4B-Loyalty points helper", on our Macha Demo org on 28 September 2026 and gave it this instruction, written for acting, for a Shopify store whose Smile program earns 5 points per $1 on "Paid" orders. The quoted names are the tool labels on our org; the "T4B-" prefix marks the tool we built for this series.

When a customer asks about loyalty points, rewards or VIP tier:
1. Look up the requester's email with "Smile.io: Find customer by email".
   - The lookup fails (401, 403, 429 or no response): add an internal note with the error
     and hand off. Never guess a balance. Stop.
   - No record: say they aren't in the rewards program yet and link the signup page. Stop.
   - More than one record: add an internal note "Duplicate Smile records for this email"
     and hand off. Stop.
   - state = candidate: explain they need to join the program (create a store account)
     to earn. Stop.
2. Balance, tier or referral questions: answer from points_balance, vip_status
   (tier and delta_to_next_vip_tier) and referral_url. Never round points.
3. Missing points for an order:
   a. Get the order with Shopify Get Order. If financial status is not paid, explain points
      arrive once payment completes. Stop.
   b. List the customer's points transactions with "T4B-Smile.io: List points transactions".
      If one is for that order, quote it and its date. Stop.
   c. If the order is paid and has no transaction: add the points it should have earned
      (5 points per $1 of subtotal) with "Smile.io: Add points (goodwill)", description
      "Points for order #<number>", internal_note "Added by AI agent, ticket <id>".
      Maximum 500 points. Above 500, hand off.
4. Never change VIP tiers, remove points or promise points not yet earned. Hand those off.

The 500-point cap and the 5-point rate are placeholders; set them from your own program. The agent also had Shopify Get Order and Search Orders and Zendesk Get Ticket and Add Internal Note. On our d3v-macha Zendesk sandbox we created ticket #1118 from a made-up "Maya Test" ([email protected]): order #1097 was paid on 14 September and her rewards balance didn't move. Order #1097 is a real order on our Shopify test store, placed by a different customer, so Maya's email doesn't match it. Sandbox tickets don't trigger production agents, so we pasted the ticket into the agent's Try it chat.

The first run took 5.8 seconds and 9 tool calls. Get Order returned the order as paid, with a $20.50 subtotal and a $24.20 total. The Smile lookup returned HTTP 401 on the dummy key, and the agent followed step 1: no guessed balance, an internal note, a handoff. It also did two things the instruction didn't ask for. It noticed the order belonged to a different email than the requester's and searched Shopify for Maya (no customer found), and it retried Smile with the order's email (401 again). Each Zendesk write paused for confirmation in chat. We confirmed the internal note, since it went to our own sandbox ticket, and left the other two unconfirmed: a public reply asking Maya which email she'd used, and a status change. Neither was sent.

Read that note closely. It says "Sent customer a reply asking them to confirm the email", and no reply went out, because we never confirmed it. The note records what the agent meant to do. Whoever picks up the handoff should check the public thread, not only the note.

Then we tested the write. In a new chat we gave the agent a made-up Smile customer id (412083776), said a teammate had confirmed there was no points transaction for #1097, and asked it to apply the goodwill "under step 3c". That run took 1 minute 31 seconds and 25 steps. The agent read the order, then searched the knowledge base about ten times for an earning rate. It treated "step 3c" as the name of a document, which is our prompt's fault, found nothing, and settled on 10 points per $1: 205 points. The instruction's rule gives 102 for a $20.50 subtotal (5 x 20.50 = 102.5, rounded down). It then called "Smile.io: Add points (goodwill)" with 205 points. No confirmation card appeared for that custom Write tool, and the call reached Smile, which answered 401 "Invalid credentials." with its own request id. Macha's tools panel labels the payload "not sent" and "no change made", which is true of the result: Smile refused it. With a real Plus key, 205 points would have landed, under the 500 cap and at double the intended rate.

Three changes follow from the run. Put a worked example in the instruction ("a $20.50 subtotal earns 102 points") so the rate isn't something the agent can go looking for. Set the cap at the largest amount you'd accept without review; 500 points didn't stop a wrong 205. And keep points_transaction:write off the key until you've read a week of the agent's internal notes, because the read side already answers most loyalty tickets.

What goes wrong?

• 429s at peak. Every token gets 10 requests per second, per Smile's rate limits page. One ticket uses three or four calls, so a batch of triggered runs during a double-points weekend can hit the limit. Enterprise buys custom limits.
• Duplicate emails. Covered above: the list endpoint can return two customers.
• Deprecated field. The top-level vip_tier_id on the customer object is deprecated in favor of vip_status.vip_tier_id. Tools built from older examples read the wrong field.
• Expired tier dates. vip_tier_expires_at is null on all-time programs and set on calendar-year ones. An agent that says "your tier expires" must check which kind the store runs.
• Wrong scope. A key missing a scope returns 403, and Smile doesn't let you add scopes to an existing key; the merchant makes a new one.
• A 422 on redeem. Smile returns 422 for "trying to redeem more points than the customer has." The agent should read the balance first rather than learn it from the error.

Where Macha fits

Macha fits teams on Smile Plus or Enterprise, running Zendesk, Freshdesk, Gorgias, Front, HubSpot or Intercom, who want loyalty tickets answered and fixed inside the ticket: the balance and tier read, the Shopify order check and the capped goodwill write in one run. On Gorgias, it adds the write side the sidebar integration doesn't document. On the other desks, which Smile's integrations list doesn't cover, it brings Smile data to the ticket for the first time. It's the wrong fit if you're below Plus: there's no merchant key to connect, and the options are the Gorgias integration or a person in Smile Admin. Macha is priced from $299/month for 750 tickets (see pricing), per ticket rather than per action, so the extra Smile calls in a missing-points ticket don't change the charge. Our loyalty apps comparison maps the other loyalty apps, and the Yotpo page covers Yotpo's loyalty API, which needs two headers instead of one. The whole Shopify app stack is in which Shopify apps an AI agent can work with, and help desk options for Shopify stores are in AI customer service for Shopify.

Frequently asked questions

Does Smile.io have a public API? Yes. Smile.io has a REST API at https://api.smile.io/v1 with Bearer authentication. Merchant API keys are available only on the Plus and Enterprise plans; partners building listed apps use OAuth, which works on any paid plan.

Can an AI agent check a customer's Smile.io points balance? Yes, with a Plus or Enterprise API key. GET /customers filtered by email returns points_balance, the VIP status object and the referral URL in one response.

Can an AI agent add missing points in Smile.io? Yes. POST /points_transactions adds or removes points with a customer-visible description and a merchant-only internal note, and Smile rejects any transaction that would leave a negative balance. Cap the amount in the agent's instructions.

Can the Smile.io API change a customer's VIP tier? No. The API reference has no tier-change endpoint. Smile Admin changes tiers by hand, and only upward.

Does the Gorgias Smile.io integration let agents adjust points? Neither Smile's nor Gorgias's documentation describes it. The integration shows points, VIP tier and referral URL beside tickets and supports Smile variables in macros and rules, on Smile's Essential plan and above.

What is Smile.io's API rate limit? 10 requests per second per token, with HTTP 429 returned past that until the next second. Enterprise plans list custom API rate limits.

How we researched this

• API behavior: Smile's REST API reference and guides on dev.smile.io, read 28 September 2026: introduction, authentication, rate limits, errors, list customers, create a points transaction, list points transactions, purchase a points product, list VIP tiers, list reward fulfillments.
• Plans and keys: Smile pricing and the help article on managing API keys, both 28 September 2026.
• Missing points and tiers: Smile help center articles on troubleshooting earning, Shopify order settings and changing VIP tiers.
• Help desk integrations: Smile's Gorgias overview and integrations list, and Gorgias's Smile doc.
• Popularity: the Shopify App Store listing showed 4.9 stars from 4,608 reviews on 28 September 2026.
• What we ran: on 28 September 2026 we used three custom tools on our Macha Demo org with dummy api_ keys (two built earlier, one built that day); the Test button and every agent call to api.smile.io got HTTP 401. We ran an inactive test agent in Macha's Try it chat three times on a made-up ticket (#1118 on our d3v-macha sandbox, requester Maya Test), because sandbox tickets don't trigger production agents: run 1 is the lookup and handoff above, run 2 continued that chat and didn't reach the write, and run 3 is the goodwill attempt. Order #1097 is a real order on our Shopify test store; its customer isn't shown. The 205 and 102 figures are 20.50 x 10 and 20.50 x 5, rounded down. We had no Smile Plus account, so no live Smile data was read and no points were changed. The ticket, the requester and the Smile customer id are synthetic.

To try 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 Smile tools during onboarding.