flexEngage ecommerce Platform Integration API.

Integration guide

This guide serves to accompany our API Specification. It walks you through common ecommerce flows and how they should be implemented using our API.

The process explanations in this guide assumes your account is using the following features:

Notifications
flexTracker

NOTE:

This API requires token-based authentication. Refer to the Security page for information on obtaining a token.
If your account does not include using flexEngage notifications, flexEngage will not deliver order event notifications.
If your account does not include using flexTracker, shipment tracking will not be available.

Use cases

Every order starts with an order confirmation, that is when your customer places the order, and your Order Management System (OMS) accepts the order. This creates an event that can be sent to our system.

POST ‘https://api.flexengage.com/v1/brand-01/order-events’

{
	"requestId": "1654654646",
	"order": {
		"id": "202009171"
	},
	"eventType": "ORDER_CONFIRMED",
	"retailerEventType": "OrderCreated",
	"data": {
		"order": {
			"id": "202009171"
		},
		"customer": {
			"name": {
				"honorific": null,
				"lastName": "Doe",
				"middleName": null,
				"firstName": "John"
			},
			"emailAddress": "john.doe@flexengage.com",
			"loyaltyProgram": {
				"account": "loyalty-gold-252451114",
				"program": "Loyalty Gold",
				"customAttributes": {
					"attribute": [{
						"key": "OrderTotalPointsEarned",
						"value": "0"
					}]
				},
				"id": "loyalty-gold"
			},
			"customerId": "252451114"
		},
		"billingAddress": {
			"line1": "123 any st.",
			"line2": "Apt. 1808",
			"city": "Orlando",
			"state": "Florida",
			"zipcode": "33137"
		}
	},
	"notificationChannels": [{
		"channelType": "EMAIL",
		"isDigital": true,
		"emailAddress": "john.doe@flexengage.com"
	}],
	"items": [{
			"id": "item-124-funny-hats",
			"name": "Funny Hats",
			"customAttributes": {
				"team": "Dallas Cowboys"
			}
		},
		{
			"id": "item-123-funny-shoes",
			"name": "Funny Shoes",
			"description": "These are some really funny shoes"
		},
		{
			"id": "item-125-funny-pants",
			"name": "Funny Pants",
			"description": "These are some really funny pants"
		}
	]
}

Given the request above, and the default brand configuration, two things will happen:

We will create a new order in our system based on the event we just received. This order will have 3 items in the unfulfilled state.
We will send an email notification to the following email address: “john.doe@flexengage.com” with content (preconfigured through a template) that reflects that the order has been confirmed.

Say that we then receive an ORDER_SHIPPED event like this:

POST ‘https://api.flexengage.com/v1/brand-01/order-events’

{
	"requestId": "1654658758",
	"order": {
		"id": "202009171"
	},
	"eventType": "ORDER_SHIPPED",
	"retailerEventType": "Fulfillment",
	"data": {
		"order": {
			"id": "202009171"
		},
		"customer": {
			"name": {
				"honorific": null,
				"lastName": "Doe",
				"middleName": null,
				"firstName": "John",
				"any": []
			},
			"emailAddress": "john.doe@flexengage.com",
			"loyaltyProgram": {
				"account": "loyalty-gold-252451114",
				"program": "Loyalty Gold",
				"customAttributes": {
					"attribute": [{
						"key": "OrderTotalPointsEarned",
						"value": "0"
					}]
				},
				"id": "loyalty-gold"
			},
			"customerId": "252451114"
		},
		"billingAddress": {
			"line1": "123 any st.",
			"line2": "Apt. 1808",
			"city": "Orlando",
			"state": "Florida",
			"zipcode": "33137"
		}
	},
	"notificationChannels": [{
		"channelType": "EMAIL",
		"emailAddress": "john.doe@flexengage.com"
	}],
	"shipments": [{
		"shipmentId": "EZ1000000001",
		"carrier": "USPS",
		"trackingNumber": "EZ1000000001",
		"items": [{
			"id": "item-124-funny-hats",
			"name": "Funny Hats",
			"customAttributes": {
				"team": "Dallas Cowboys"
			}
		}]
	}]
}

With this event few things will happen:

We will update the state of the order based on this event, specifically the item with id=”item-124-funny-hats” will change to a shipped state.
We will send an email notification to the following email address: “john.doe@flexengage.com” with content (preconfigured through a template) that reflects that the item has been shipped.
If the flexTracker feature is enabled, we will start tracking this shipment and send notifications about the shipment journey to the customer. The customer will also be able to see the state of the shipment on our FlexTracker page.
The other 2 items remain in the same state since they were not affected by this shipment.

Say that we then receive another ORDER_SHIPPED event like this:

POST ‘https://api.flexengage.com/v1/brand-01/order-events’

{
	"requestId": "16543458725",
	"order": {
		"id": "202009171"
	},
	"eventType": "ORDER_SHIPPED",
	"retailerEventType": "Fulfillment",
	"data": {
		"order": {
			"id": "202009171"
		},
		"customer": {
			"name": {
				"honorific": null,
				"lastName": "Doe",
				"middleName": null,
				"firstName": "John",
				"any": []
			},
			"emailAddress": "john.doe@flexengage.com",
			"loyaltyProgram": {
				"account": "loyalty-gold-252451114",
				"program": "Loyalty Gold",
				"customAttributes": {
					"attribute": [{
						"key": "OrderTotalPointsEarned",
						"value": "0"
					}]
				},
				"id": "loyalty-gold"
			},
			"customerId": "252451114"
		},
		"billingAddress": {
			"line1": "123 any st.",
			"line2": "Apt. 1808",
			"city": "Orlando",
			"state": "Florida",
			"zipcode": "33137"
		}
	},
	"notificationChannels": [{
		"channelType": "EMAIL",
		"emailAddress": "john.doe@flexengage.com"
	}],
	"shipments": [{
		"shipmentId": "EZ2000000002",
		"carrier": "FEDEX",
		"trackingNumber": "EZ2000000002",
		"items": [{
			"id": "item-123-funny-shoes",
			"name": "Funny Shoes",
			"description": "These are some really funny shoes"
		}]
	}]
}

With this event few things will happen:

We will update the state of the order based on this event, specifically the item with id=”item-123-funny-shoes” will change to a shipped state.
We will send an email notification to the following email address: “john.doe@flexengage.com” with content (preconfigured through a template) that reflects that the item has been shipped.
If the flexTracker feature is enabled, we will start tracking this shipment and send notifications about the shipment journey to the customer. The customer will also be able to see on our FlexTracker page the state of the shipment.
The item with id=item-125-funny-pants remains in the same state since it was not affected by this shipment.

So far we have an order that has been confirmed and 2 different shipments, one for each item. we still have one item that has not been fulfilled. So we might get an event like the following:

POST ‘https://api.flexengage.com/v1/brand-01/order-events’

{
	"requestId": "16546546430",
	"order": {
		"id": "202009171"
	},
	"eventType": "ORDER_CANCELLED",
	"retailerEventType": "OrderCancellation",
	"data": {
		"order": {
			"id": "202009171"
		},
		"customer": {
			"name": {
				"honorific": null,
				"lastName": "Doe",
				"middleName": null,
				"firstName": "John"
			},
			"emailAddress": "john.doe@flexengage.com",
			"loyaltyProgram": {
				"account": "loyalty-gold-252451114",
				"program": "Loyalty Gold",
				"customAttributes": {
					"attribute": [{
						"key": "OrderTotalPointsEarned",
						"value": "0"
					}]
				},
				"id": "loyalty-gold"
			},
			"customerId": "252451114"
		},
		"billingAddress": {
			"line1": "123 any st.",
			"line2": "Apt. 1808",
			"city": "Orlando",
			"state": "Florida",
			"zipcode": "33137"
		}
	},
	"notificationChannels": [{
		"channelType": "EMAIL",
		"isDigital": true,
		"emailAddress": "john.doe@flexengage.com"
	}],
	"items": [{
		"id": "item-125-funny-pants",
		"name": "Funny Pants",
		"description": "These are some really funny pants"
	}]
}

With this event few things will happen:

We will update the state of the order based on this event, specifically the item with id=”item-125-funny-pants” will change to a cancelled state.
We will send an email notification to the following email address: “john.doe@flexengage.com” with content (preconfigured through a template) that reflects that the item has been canceled.

We have seen a typical order’s journey through a set of events, and the different things that would happen based on these events.