Where to find this: Shopify admin → Apps → Yuko Loyalty → Loyalty → Programs → Ways to earn → Add another way → Custom Action
Introduction
A Custom Action rewards customers for something that happens outside the built-in ways to earn, such as completing a survey, attending an event or finishing an onboarding quiz. You define the action and the points in Yuko. Your own system then tells Yuko when a customer completed it, through the REST API, and Yuko credits the points. Custom actions are available on paid plans.What problem this solves
The built-in ways to earn cover orders, sign-ups, reviews, social actions and opt-ins. Many brands also want to reward actions that only their own tools can see. A Custom Action gives those actions a points value, limits and expiry, and keeps the earning inside your loyalty program.When to use
- You want to reward an action that happens in another tool, such as a survey, quiz, app or event check-in.
- You have a developer or an automation tool that can send an HTTP request when the action happens.
- You want to cap how often each customer can earn for the action.
Overview
- You can add as many Custom Actions as you need, one for each action you want to reward.
- Points are credited only through the REST API. Customers can’t earn by clicking anything on your storefront.
- Optional limit on how many times each customer can earn: per day, week, month or year.
- Optional Hide from on-site displays, to keep the action out of your loyalty widgets.
- Optional points expiry and VIP tier multipliers.
- Available on paid plans.
Before you start
Yuko app is installed on your Shopify store — see Install Yuko on Shopify.
The Yuko Theme App Embed is enabled in your active theme — see Theme App Embed.
Your loyalty program is enabled under Loyalty Program Status at Shopify admin → Apps → Yuko Loyalty → Loyalty → Programs.
Your point labels are set in Loyalty Settings.
You have a Yuko API key with the
write:transactions scope. Create one in Integrations → REST API. If that page shows Approval required, ask the Yuko team to turn on REST API access first. See REST API.Setup guide
1
Add the way to earn
In your Shopify admin, go to Apps → Yuko Loyalty → Loyalty → Programs. In Ways to earn, click Add another way and pick Custom Action.
2
Fill in Basic Details
- Action Name — the name of the action, shown to customers. Write it in the present tense, for example
Complete a survey. - Description — short copy shown with the action.
3
Choose whether customers see it (optional)
Tick Hide from on-site displays to keep this action out of all your loyalty widgets. The action keeps working, and you can still credit points for it through the API. Leave it unticked to list the action in Ways to earn in your widgets.
4
Set the points
Under Earning points, enter the points to award each time the action is credited (a whole number, at least 1).
5
Set a limit (recommended)
Tick Limit how many times each customer can earn points for completing this action, then enter how many times per day, week, month or year. The limit must be a whole number of at least 1. When you first tick the box, it’s set to 1 per year.With year, choose the Year calculation method:
- Rolling year (365-day window) — the default. Counts the last 365 days.
- Calendar year — resets on January 1 in your store’s timezone.
6
Set Expiry (optional)
Turn on Expiry, then set Expire after and a Period (Day, Week, Month or Year). Expiry is available on select plans.
7
Review the side panel
- Status — on by default. A disabled action can’t be credited.
- Icon — Default, or Custom to upload your own.
- Tiers — turn on to apply VIP tier multipliers to this action.
8
Save and copy the URL
Click Save. The REST API card then shows the URL for crediting points for this action. Click Copy to copy it. Before you save, the card shows Save this action to get the URL for crediting points.
How it works
- A customer completes the action in your own tool, such as a survey platform.
- Your system sends a
POSTrequest to the URL from the REST API card, with your API key and the customer’sidentifier(Shopify customer ID, Yuko customer ID, email address or phone number). See Credit points for a custom action. - Yuko checks that the action is enabled, that the customer exists and isn’t excluded from the program, and that the customer hasn’t reached the action’s limit.
- Yuko credits the points to the customer’s balance and records the activity. With Tiers on, the customer’s tier multiplier applies.
limit_reached error and no points are awarded. If the action is disabled, it returns action_inactive.
How limits are counted
- day, week and month follow calendar periods in your store’s timezone. Weeks start on Monday.
- year uses the method you chose: the last 365 days, or the calendar year.
- Yuko counts the times the customer earned from this action in the current period. Each Custom Action has its own count.
What customers see
Unless you tick Hide from on-site displays, the action appears in Ways to earn in your loyalty widgets with its name, description and points. It has no button: customers learn how to complete the action from your own channels, and the points arrive once your system reports it.Decision guidance
- Always set a limit unless your own system already prevents repeat calls. For a one-off action, use 1 per year with Calendar year, or a long rolling window.
- Hide actions that aren’t public, such as rewards for internal events or staff-run activities.
- Use clear, present-tense names like
Complete a surveyso customers know what to do.
Limitations
- Points can only be credited through the REST API. There’s no storefront button and no automatic trigger.
- The customer must already exist in Yuko. Unknown customers return
not_found. - Customers excluded from the loyalty program don’t earn.
Examples
- A skincare brand awards 50 points, once per calendar year, for completing its annual skin-profile survey. Its survey tool calls the URL when a response is submitted.
- An outdoor store awards 100 points for checking in at an in-person event, limited to 1 per day, and hides the action from on-site displays.
Best practices
FAQs
How many Custom Actions can I create?
How many Custom Actions can I create?
As many as you need. Create one for each action you want to reward. Each has its own URL, points, limit and expiry.
Where do I find the URL to call?
Where do I find the URL to call?
Open the Custom Action after saving it. The REST API card shows the URL, with a Copy button and a link to the API documentation. The last part of the URL is the action’s ID.
What does Hide from on-site displays do?
What does Hide from on-site displays do?
It removes the action from all your loyalty widgets. The action keeps working, so the API can still credit points for it.
What happens when a customer reaches the limit?
What happens when a customer reaches the limit?
The API returns a
limit_reached error and Yuko awards no points. The customer can earn again in the next period.Related
Credit points for a custom action
API reference for crediting a Custom Action.
REST API
Create and manage your Yuko API keys.
Ways to Earn
Configure how customers earn points across your store.
Ways to Redeem
Set up the rewards customers can redeem with their points.
Bonus Campaigns
Run time-bound multipliers, bonuses and challenges on top of earning.
Loyalty Settings
Point labels, earning and revert statuses, exclusions and order tags.
Customers
View balances and activity, adjust points and assign tiers.
VIP Tiers
Reward your best customers with tier multipliers and benefits.
Book a Free Setup Call
Talk to our team for personalised setup help.Time: 30 minutes
Contact Support
Visit our support hub for help articles, live chat and ticket submission.
Browse the Guides
Documentation across loyalty, referrals, memberships and more.
Install Yuko
Add Yuko to your Shopify store from the Shopify App Store.