This article will cover the following Connector Event topics:
An Event is a message, generated and deployed by Formation, that contains offer details for your customers. These events are triggered by either specific actions taken by your customers or by the crossing of predetermined dates over the course of an offer period. These events are sent in real-time to your internal endpoints.
A Connector is the mapping of a Formation event to a specific endpoint. Each connector contains a single mapping, however, you may choose to configure multiple connectors to send different events to the same endpoint.
Event Types
The following events are utilized in all existing offer types:
| Ready | Sent when you have launched offers from the platform and they can be communicated to customers. This event is often used as a pre-trigger for campaign sends. |
| Achieved | Sent when your customer has made progress in their offer by completing an assigned step. |
| Activated | Sent when your customer has activated their offer. |
| Completed | Sent when your customer has completed all of their assigned steps. |
| Reward | Sent when your customer has completed a step that has an associated reward value. |
The remaining event types are utilized at specific times or for specific offer types.
| Progressed |
Sent when your customer has made progress towards a cumulative offer but has not yet achieved a step. NOTE: This event type is currently only available in the Week Streak offer type. |
| Notification |
Sent at a predetermined time during the associated offer period. NOTE: Notifications are currently managed by Formation on your behalf. Please contact your Formation representative if you're interested in utilizing or adjusting default functionality. |
Event Payloads
Event payloads will be delivered to your configured destination (Kinesis Stream or API Location) in JSON format. You may choose to also apply jq transformation to augment these payloads to your desired schema.
Read more about Connector Transformations.
By default, each event will contain the following:
Top Level Keys
| type | The event (from the list above) is represented in the payload. This enables you to send multiple event types to the same destination as each event type has slightly different characteristics. |
| created | A UTC timestamp for when Formation generated the event. |
Offer Object
| customer_id | A unique identifier for the customer receiving the offer. |
| offer_type | The offer type that is represented in the payload. |
| unique_offer_id | A unique identifier, generated by Formation, for each customer offer. |
| start_time | The local date and time for the start of the offer. |
| end_time | The local date and time for the end of the offer. |
| status |
The current state of the offer. One of:
|
| steps |
An array of objects that describe the specific requirements of each customer's offer. |
| offer_reward |
An object that describes the reward the customer will receive once all assigned steps are completed. |
| total_reward |
An object that describes the sum of rewards the customer is eligible to receive in the offer. |
| tags |
An array of user-entered key-value pairs entered in the platform interface before sending an offer to customers. |
Step Object
| step_type |
The type of step, which informs which conditions will be present. One of:
|
| step_status |
The status of a step in the offer. One of:
|
| conditions |
The offer assignment requirements a customer must complete in order to achieve the step. A step condition may include:
|
| reward | An object that describes the reward the customer will receive for completing the particular step (not applicable to all steps). |
Reward Object
| reward_value |
The amount of reward the customer will receive. |
| reward_currency | The type of reward the customer will receive. |
| reward_type | Whether the reward is a fixed value or variable based on customer spend. |
progressed_steps Object
| progressed_steps |
A set of objects keyed by the step_id found in the offer body that will communicate the progression made in each |
| progressed_steps.status | The current status of the step |
| progressed_steps.new_spend | The new spend that has been contributed towards the step with this progression |
| progressed_steps.total_spend | The total spend up to this point in the offer that has been contributed towards the step with this progression |
Payload Examples
Additional details can be found in the Formation developer site's Status API response payload details or by requesting specific information from your CSM. We've included a selection of different offer types here to best illustrate the structure of events as well as the way elements like step types can be combined in complex offers.
Ready
{
"type": "ready",
"created": "2020-11-10T00:00:00Z",
"offer": {
"customer_id": "darren",
"offer_type": "three_step_offer",
"unique_offer_id": "jibberish",
"start_time": "2020-11-11T00:00:00",
"status": "eligible",
"end_time": "2020-11-11T23:23:59",
"steps": {
"step_1": {
"step_type": "custom_action", // This is a non-purchase action step
"conditions": {
"action": "action_id"
},
"status": "eligible"
},
"step_2": {
"step_type": "single_category_purchase", // This is a category purchase step
"conditions": {
"spend_requirement": 500,
"category": {
"category_id": "category_id",
"category_name": "category_name"
}
},
"status": "eligible"
},
"step_3": {
"step_type": "single_purchase", // This is a purchase step
"conditions": {
"spend_requirement": 500
},
"status": "eligible"
},
"offer_reward": {
"reward_id": "game_reward",
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"total_reward": {
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"tags": {
"jims": "mowing"
}
}
}
}
Activated - Single Purchase Offer
{
"type": "activated",
"created": "2020-11-11T09:23:45",
"offer": {
"customer_id": "darren",
"offer_type": "single_purchase",
"unique_offer_id": "jibberish",
"start_time": "2020-11-11T00:00:00",
"status": "active",
"end_time": "2020-11-11T23:23:59",
"steps": {
"step_1": {
"step_type": "single_purchase",
"conditions": {
"spend_requirement": 500
},
"status": "eligible"
}
},
"offer_reward": {
"reward_id": "offer_reward_id",
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"total_reward": {
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"tags": {
"jims": "mowing"
}
}
}
Achieved - Single Category Purchase Offer
{
"type": "achieved",
"created": "2020-11-11T09:23:45",
"offer": {
"customer_id": "darren",
"offer_type": "single_category_purchase",
"unique_offer_id": "jibberish",
"start_time": "2020-11-11T00:00:00",
"status": "completed",
"end_time": "2020-11-11T23:23:59",
"steps": {
"step_1": {
"step_type": "single_category_purchase",
"conditions": {
"spend_requirement": 500,
"category": {
"category_id": "category_id",
"category_name": "category_name"
}
},
"status": "completed"
}
},
"offer_reward": {
"reward_id": "offer_reward_id",
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"total_reward": {
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"tags": {
"jims": "mowing"
}
}
}
Progressed - Week Streak Offer
{
"type": "progressed",
"created": "2020-11-12T09:23:45",
"progressed_steps": {
"step_1": {
"status": "eligible",
"new_spend": 2000,
"total_spend": 3000
},
"step_2": {
"status": "eligible",
"new_spend": 1000,
"total_spend": 2000
}
},
"offer": {
"customer_id": "darren",
"offer_type": "week_streak",
"unique_offer_id": "jibberish",
"start_time": "2020-11-11T00:00:00",
"status": "active",
"end_time": "2020-11-25T00:00:00",
"steps": {
"step_1": {
"step_type": "cumulative_purchase",
"conditions": {
"spend_requirement": 3500,
"complete_by": "2020-11-17T23:59:59"
},
"status": "eligible"
},
"step_2": {
"step_type": "cumulative_purchase",
"conditions": {
"spend_requirement": 3500,
"complete_by": "2020-11-25T00:00:00"
},
"total_spend": 0,
"status": "eligible"
}
},
"offer_reward": {
"reward_id": "game_reward",
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"total_reward": {
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"tags": {
"jims": "mowing"
}
}
}
Reward - Cumulative Purchase Offer
{
"type": "reward",
"created": "2020-11-11T09:23:45",
"reward": {
"reward_id": "offer_reward_id",
"reward_value": "500",
"reward_currency": "points"
},
"offer": {
"customer_id": "darren",
"offer_type": "cumulative_purchase",
"unique_offer_id": "jibberish",
"start_time": "2020-11-11T00:00:00",
"status": "completed",
"end_time": "2020-11-11T23:23:59",
"steps": {
"step_1": {
"step_type": "cumulative_purchase",
"conditions": {
"spend_requirement": 500
},
"status": "completed"
}
},
"offer_reward": {
"reward_id": "offer_reward_id",
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"total_reward": {
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"tags": {
"jims": "mowing"
}
}
}
Completed - Cumulative Category Purchase Offer
{
"type": "completed",
"created": "2020-11-11T09:23:45",
"offer": {
"customer_id": "darren",
"offer_type": "cumulative_category_purchase",
"unique_offer_id": "jibberish",
"start_time": "2020-11-11T00:00:00",
"status": "completed",
"end_time": "2020-11-11T23:23:59",
"steps": {
"step_1": {
"step_type": "cumulative_category_purchase",
"conditions": {
"spend_requirement": 500,
"category": {
"category_id": "category_id",
"category_name": "category_name"
}
},
"status": "completed"
}
},
"offer_reward": {
"reward_id": "offer_reward_id",
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"total_reward": {
"reward_value": "500",
"reward_currency": "points",
"reward_type": "fixed"
},
"tags": {
"jims": "mowing"
}
}
}