A custom event is a message that another platform sends to Instant when something happens, for example “interview completed” or “booking accepted”. You can start a custom flow from that event, so the shopper gets an email at that moment.

Use custom events when the moment you want to email about happens outside your store. If the data is already in Shopify, a Shopify tag is often simpler. See How to run a custom waitlist or competition flow.

Example: send a reward after a customer interview

A survey platform interviews your shoppers. You want to email a reward code to each shopper who completes an interview.

  1. The survey platform sends Instant an interview.completed event with the shopper’s email address and an outcome property.
  2. You build a custom flow in Instant that starts from interview.completed, with a filter of outcome equals completed.
  3. When the next interview ends, the shopper enters the flow and receives the reward email.

Each step in this article uses this example.

Setup checklist

# Who Task
1 You Ask your customer success manager to turn on custom flows and API access, and to give you an API key and your site ID.
2 You and your developer Agree on the event names and properties (see Plan your events).
3 Your developer or partner Send events to Instant (see Send events to Instant).
4 Your developer or partner Send one test event that includes every property you plan to use.
5 You Build the custom flow (see Build the flow).
6 You Send another test event with the flow on, and check that the email arrives.
7 You Turn off any email that the other platform or another tool already sends for the same event.

Plan your events

Plan from the email back to the event. Write down the emails you want to send, then the event that starts each one, then the details each email or filter needs.

For the interview example:

Email Event name Properties
Reward for a completed interview interview.completed campaign, outcome, duration_minutes
Reminder to finish an interview interview.incomplete campaign

Do and do not

Do Do not
Use one event for each real-world moment, for example interview.started, interview.completed, interview.incomplete. Send one interview event with a status property and try to split it later.
Use letters, numbers, ., _, : and - in event names, for example interview.completed. Use spaces. Interview Completed is rejected.
Keep event names in the same case every time. Mix cases. interview.completed and Interview.Completed are two different events.
Put properties you want to filter on at the top level, as text, a number or true/false. Put them inside nested objects or lists. Flow filters cannot read them.
Keep each property name and type the same in every event. Send duration_minutes as a number in one event and as text in another.
Send only the data the email needs. Send sensitive data such as full interview transcripts.

Send events to Instant

This section is for your developer or the partner platform.

Quick start

curl -X POST https://public.api.instant.one/v1/event \
  -H "Authorization: Bearer $INSTANT_API_KEY" \
  -H "X-Instant-Site-Id: $INSTANT_SITE_ID" \
  -H "Idempotency-Key: interview-8f2c1a" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": 1794274436000,
    "backfill": false,
    "profile": { "email": "[email protected]", "first_name": "Sam" },
    "event": {
      "name": "interview.completed",
      "properties": {
        "campaign": "post_purchase_q4",
        "outcome": "completed",
        "duration_minutes": 12
      }
    }
  }'

A 202 response means Instant accepted the event. Processing happens after the response.

Keep the API key on your server. Do not put it in website or app code.

Headers

Header Required Value
Authorization Yes Bearer <API key>
X-Instant-Site-Id Yes Your site ID. It must match the site of the API key.
Idempotency-Key Yes A unique ID for this event, up to 128 characters. Use the event’s ID in your system.
Content-Type Yes application/json

Body fields

Field Required Notes
timestamp Yes When the event happened, in Unix time in milliseconds.
backfill Yes false for live events, which can start flows. true for historical events, which are stored but never start flows.
profile.email One of email or phone The shopper’s email address.
profile.phone One of email or phone The shopper’s phone number in international format, for example +61412345678.
profile.first_name, profile.last_name No Updates the shopper’s name.
profile.address No line_1, line_2, city, region_code, postal_code, country_code.
profile.attributes No Custom profile fields. Values can be text, a number, true/false or a list of text.
event.name Yes The event name. This is the name you select in the flow.
event.properties Yes Details of the event. Send {} if there are none.

Limits

Item Limit
Event name 1 to 100 characters. Letters, numbers, ., _, :, -. Must start with a letter or number.
Event properties 100 keys per object, 64 KiB of JSON, 10 levels of nesting, 1,000 items per list
Profile attributes 100 keys, 32 KiB of JSON
Request body 128 KiB
Live event timestamp Up to 24 hours in the past and 5 minutes in the future
Backfill timestamp 1 January 2010 to one year from now
Idempotency key Kept for 24 hours for each site
Rate limit 350 requests a second or 3,500 requests a minute for each site

Retries

  • If you get a 429 or 503, retry the same request with the same Idempotency-Key.
  • A retry with the same key returns the first response and does not create a second event.
  • Do not reuse a key for a different event.

Error responses

Status Meaning What to do
400 The body is not valid JSON. Fix the JSON.
401 The API key or site ID is missing, wrong or revoked, or they do not match. Check both values.
403 The key does not have the Events permission, or its app is paused. Ask your customer success manager.
413 The body is larger than 128 KiB. Send less data.
415 Content-Type is not application/json. Set the header.
422 A field breaks a rule (for example a space in the event name, or a live timestamp older than 24 hours), or the idempotency key was used on another endpoint. Read the detail in the response and fix the field.
429 Rate limit reached. Wait, then retry with the same key.
503 Temporary problem. Retry with the same key.

The full API reference is at public.api.instant.one/docs.

Build the flow

Instant shows an event in the flow setup only after it has received that event at least once. The properties you can filter on come from the events Instant has received. Send a test event first.

  1. Go to Flows in your Instant AI dashboard.
  2. Scroll to the Custom section and click Add custom flow.
  3. Enter a Name, for example Interview reward.
  4. Under Starting point, select Custom event · interview.completed.
  5. Optional: under Event attributes, click Add attribute filter. Choose outcome, Equals, and type completed. You can add up to 5 filters.
  6. Under Messages, choose how many messages the flow sends.
  7. Under Send the first message after, set a short wait, for example 5 minutes.
  8. Under Entry requirements, choose Shoppers can only enter this flow once or Shoppers can enter this flow multiple times.
  9. Click Create flow.
  10. Write the messages, then enable the flow.

Tip: Make one flow for each event. For example, a reward flow from interview.completed and a reminder flow from interview.incomplete. Separate flows are easier to test and to report on.

How it works

  • A live event with a matching name, which passes all the filters, starts the flow.
  • Backfilled events never start a flow.
  • Instant matches the shopper by the email address or phone number in the event.
  • The shopper receives each message only if they have consent for that channel and are not suppressed.
  • Custom flows run alongside your other flows. The shopper can still receive other flows and campaigns.
  • Each event shows in the shopper’s activity on their profile in Shoppers.

Troubleshooting

Problem Likely cause Fix
The request gets a 422. The event name has a space or another character that is not allowed, or the live timestamp is more than 24 hours old. Read the detail in the response. Rename the event or send it as a backfill.
The event is not in the Starting point list. Instant has not received a live event with that name yet. Send a test event, wait a few minutes, then open the flow setup again.
A property is not in the Event attributes list. No event has included it yet, or it is nested, or it is a list. Send a test event with the property at the top level, as text, a number or true/false.
The event shows on the profile, but no email was sent. No email marketing consent, the shopper is suppressed, a filter did not match, the flow is off, or the shopper already went through a flow set to enter once. Check the profile’s consent and the flow settings.
The shopper got two emails. The other platform or another email tool also sends an email for this event. Turn off the other email.
The flow started twice for one event. The same event was sent twice with different idempotency keys. Use the event’s own ID as the Idempotency-Key.