Submit Form
Reward customers for custom actions outside your system by letting them submit proof (text, link, images or a video) for your review.
This feature is available for Advanced and above plans
Overview
Submit Form is an earning program for actions that can't be tracked automatically — like sharing on social media, posting UGC content, or leaving feedback on external platforms. Customers complete the task, submit proof via a customizable form, and receive rewards after admin approval.
Use case: Merchants wanting to reward social shares, TikTok posts with hashtags, Google reviews, UGC content, or any custom action.
How to set up
Step 1: Create the program
Go to Reward programs → Earning programs → Add new
Select Submit form
You can create multiple Submit Form programs for different actions
Step 2: Configure Rule tab
- Program name and Description
- Start/End date (optional)
- Reward value: Points earned after approval
- Instant reward: (optional) Give small points immediately on submit, before review
- Differ by VIP tier: (optional) Set different rewards per tier
- Fraud prevention: Limit submissions per timeframe (e.g., 3 per day)
- Form fields: build the form customers fill in. See Form fields
- Approval settings: auto-approve submissions, and add customer tags (optional)
Form fields
The Submission requirements card on the Rule tab holds the Form fields customers fill in. It shows how many fields you use and how many are required, for example "3 of 10 fields · 2 required".
Click Add field and choose a type:
| Field type | What customers enter |
|---|---|
| Short text | A short written answer |
| Number | A numeric answer, such as an order total |
| An email address | |
| File upload | An image or video as proof. One per form |
In the Edit field window, set:
- Label: the name customers see above the field. Each label must be different, up to 120 characters.
- Placeholder: the hint inside the field. File upload has none.
- Required: customers cannot submit while the field is empty.
- Accepted format (File upload only): Image only, Video only or Both. Video needs a paid plan; on the free plan the two video options are disabled.
Click Done, then Save the program. Use the arrows beside a field to reorder it, and the edit and delete buttons to change or remove it. Customers see nothing new until you save.
A form has 1 to 10 fields and at most one File upload field. At 10 fields Add field is disabled, and saving a form with no fields shows "Add at least one field before saving".
Joy checks every field before it saves a submission. An empty required field, a Number that is not a number or an invalid Email is rejected: nothing is stored and no points are awarded. This applies on the storefront and when a submission arrives through the API.
Number fields accept digits with at most one comma or period as the decimal mark, such as 64,90 or 59.90, up to 15 digits. A minus sign or a currency symbol ($59.90) is rejected.
Existing programs keep their current form until you edit Form fields.
The limits shown under the file options are the ones Joy enforces:
| Formats | Limit | |
|---|---|---|
| Image | JPG, JPEG, PNG | 10MB per file, up to 5 per submission |
| Video | MP4, MOV, WEBM | 50MB, 1 per submission |
Video upload works in the Unified widget and on the loyalty page. In the Loyalty Hub the upload field is hidden for a Video only program, and a Both program accepts images only.
Languages: edit the field structure (type, order, Required, accepted format) in your primary language. In another language you edit only the label and placeholder text. Joy translates labels and placeholders automatically when you save and the primary-language text has changed.
Where customers see custom fields
A form with your own fields shows in the Unified widget and on the Loyalty page. The legacy widget (V3), the Loyalty Hub and headless storefronts (API and the Hydrogen package) hide a Submit Form program whose form differs from the original text field plus optional upload, so customers there never meet a form they cannot complete.
Tag customers when you approve
In the Approval settings card, add up to 5 Customer tags (40 characters each, no commas, no duplicates). When a submission is approved for the first time, Joy adds these tags to the customer in Shopify.
- The tags are added once, whether you approve by hand, in bulk or with Auto-approve submissions.
- Pending and Disapproved submissions add nothing. Changing an approved submission to Disapproved keeps the tags.
- Joy only adds tags. It never removes one.
- If Joy cannot add the tags after several attempts, the row in Submitted forms shows Tags not added. Choose Approved on that row again to retry the same tags. Points are not awarded a second time.
Step 3: Configure Design tab
Customize the popup customers see when submitting.
Use-case template: pick Social share, Share review, Unboxing video or Purchase proof to fill every copy field below with text written for that action: headline, description, how-to-earn steps, button and success message, plus the label and placeholder of the text field and the label of the upload field. On a form you have already customised in Form fields, a template leaves your field labels as they are. The success message follows your approval settings, so an auto-approved program thanks the customer for points already added, while a reviewed program says the points arrive after approval.
Applying a template replaces the copy in every language of this program, not only the one you are editing. Copy you wrote before is lost once you save.
Form view:
- Header image
- Headline and description
- How-to-earn instructions: a label (default "How to earn") and a list of steps. Drag the handle to reorder, add a step with Add step, remove one with the X. Steps are numbered when there are two or more; with no steps, the section is hidden from customers.
- Submit button text
Field labels and placeholders are not on this tab. Edit them in Form fields on the Rule tab.
Success view:
- Success icon
- Success headline and message. Use the variable picker beside each field to insert customer-specific values:
| Variable | Shows |
|---|---|
{{customer_name}} | The customer's name |
{{shop_name}} | Your store name |
{{earning_points}} | Points this submission earns |
{{loyalty_point}} | Your points name |
{{points_balance}} | The customer's balance |
{{earning_program}} | The program name |
{{instant_reward}} | The instant reward, if one is set |
Use Preview success view to check the result before you save.
Step 4: Save and activate
Click Save. Make sure program status is Active.
Customer experience
Submitting a form
Customers can submit from:
- Widget → Way to earn → Submit form program
- Loyalty page → Block "Way to earn" → Submit form program
They follow the how-to-earn steps, fill in each field, and attach proof in the format the program accepts (see Form fields). A required field left empty, a Number that is not a number or an invalid Email shows a message under the field, and the form is not sent.
After submission
- Customer sees success message
- If Instant reward enabled → points added immediately
- Submission status is Pending until staff reviews
- Once approved → full reward granted, logged in activity history
- If rejected → no reward. If instant reward was given, it will be refunded
Admin review process
View submissions
Go to Activities → Submitted forms to see all submissions.
Table columns:
- Submitted time
- Program name
- Customer name & email
- Submitted content: the first answer as "Label: value" (hover to see every answer), with a copy button
- Images (click to view/zoom)
- Video (click to play). Videos are kept for 60 days, after which the row shows the video as expired.
- Status (Pending / Approved / Disapproved)
- Actions
Open a submission
Click a row to open the full submission: the customer, the status, a table of every answer with a copy button beside each (and Copy all), the attached images or video, the tags and whether they were added. Use the arrows at the bottom to move to the next or previous submission on the page.
Answers keep the field labels from the moment the customer submitted. If you rename or change a field later, earlier submissions still read as they were sent.
Approve or Disapprove
- Approve: Customer receives reward points, activity is logged, and your customer tags are added
- Disapprove: No reward. If instant reward was given, it will be refunded (deducted)
Notifications (Shopify Flow & Klaviyo - Coming soon)
FAQ
Can I create multiple Submit Form programs? Yes. You can create different programs for different actions (e.g., one for TikTok, one for Instagram).
What types of content can customers submit? Whatever fields you add: short text, numbers and email addresses, plus one optional file upload of up to 5 images (JPG, PNG, JPEG, max 10MB each), one video (MP4, MOV, WEBM, max 50MB), or either. See Form fields.
Can I run a text-only form? Yes. Delete the File upload field in Form fields.
Can I make a field required? Yes. Tick Required in the Edit field window. Customers cannot send the form until that field is filled in, and Joy rejects a submission that arrives without it.
Why did my Submit Form program disappear from the Loyalty Hub or the legacy widget? Those surfaces only show the original form: one required text field plus an optional upload. Once your form goes beyond that, for example with a Number or Email field, the program shows in the Unified widget and on the Loyalty page only.
When are customer tags added? The first time a submission becomes Approved, by hand, in bulk or with auto-approve. Joy adds the tags in the background, so they can appear a moment after the approval.
What does "Tags not added" mean? Joy could not add the tags after several attempts. The submission stays Approved. Choose Approved on that row again to add the same tags; points are not awarded twice.
How long can I watch a submitted video? 60 days from upload. Review video submissions within that window.
What is Instant Reward? A small amount of points given immediately when customer submits, before review. If rejected, instant points will be refunded.
Can I change approved to disapproved later? Yes. The reward points will be refunded automatically.
What happens if customer exceeds submission limit? They will see an error and cannot submit until the limit resets.