Export customer actions
For the general submit-and-poll flow, see Exports overview.
Customer actions export contract
POST https://api.maestra.io/v3/operations/sync?endpointId={endpointId}&operation={operation}
Accept: application/json
Content-Type: application/json
Authorization: SecretKey {Secret key}
{
"sinceDateTimeUtc": "<Earliest action datetime — UTC, YYYY-MM-DD hh:mm>",
"tillDateTimeUtc": "<Latest action datetime, exclusive — UTC, YYYY-MM-DD hh:mm>",
"segment": {
"ids": {
"externalId": "<Action segment external ID>"
}
}
}
You can pass:
sinceDateTimeUtc— only actions created in Maestra after this UTC datetime will be included.tillDateTimeUtc— only actions created in Maestra before this UTC datetime will be included.externalIdof an action segment — required if you didn't pick one in the operation step settings.
An action is included when:
sinceDateTimeUtc ≤ creation datetime in Maestra < tillDateTimeUtc
The creation datetime in Maestra is when Maestra processed the action. The customer may have performed it at a different time, so keep this in mind when picking your date range.
Response format
{
"customerActions": [
{
"ids": {
"mindboxId": "<Maestra ID>",
"<transactionId>": "<Transaction ID>"
},
"customFields": {
"<Action custom field>": "<Field value>",
"<Multi-value action field>": "<Field value>"
},
"actionTemplate": {
"ids": {
"systemName": "<Action template system name>"
},
"name": "<Action template name>"
},
"dateTimeUtc": "<Action datetime (UTC)>",
"creationDateTimeUtc": "<Datetime the action was created in Maestra (UTC)>",
"brand": {
"ids": {
"systemName": "<Brand system name>"
}
},
"channel": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Touchpoint external ID>",
"systemName": "<Touchpoint system name>"
},
"utmCampaign": "<utm_campaign value>",
"utmSource": "<utm_source value>",
"utmMedium": "<utm_medium value>",
"utmContent": "<utm_content value>",
"utmTerm": "<utm_term value>"
},
"customer": {
"ids": {
"mindboxId": "<Maestra ID>",
"<External customer identifier>": "<Identifier value>"
}
}
}
]
}
In addition to the base fields shown in the response format above, the operation step lets you enable extra related entities. They're included when the action has that data attached — for example, an order-placement action includes the order, and a click in a campaign includes the campaign.
Campaign
To export interactions with campaigns, use the campaign engagement export.
{
"customerActions": [
{
<base fields>,
"rootAction": {
"ids": {
"mindboxId": "<Maestra ID>"
},
"actionTemplate": {
"ids": {
"systemName": "<Action template system name>"
},
"name": "<Action template name>"
}
},
"mailing": {
"name": "<Campaign name>",
"ids": {
"systemName": "<Campaign system name>",
"id": "<Maestra ID>",
"variantNum": "<Campaign variant number>"
},
"action": "<Campaign event>",
"notSentReason": {
"ids": {
"systemName": "<System name of the not-sent status>"
},
"name": "<Name of the not-sent status>"
},
"notDeliveredReason": {
"ids": {
"systemName": "<System name of the not-delivered status>"
},
"name": "<Name of the not-delivered status>"
},
"link": "<Link>",
"viewEmailMessageUrl": "<Link to view the sent message>"
}
}
]
}Campaign events:
Dispatch— CampaignMailingSend— Campaign sentMailingOpen— Campaign openedMailingNotSent— Campaign not sentMailingNotDelivered— Campaign not deliveredMailingClick— Click on a campaign linkWaitingForDispatch— Campaign participationMailingUnsubscribe— Unsubscribe request
Not-sent reasons:
ContactMissing— No contact on file.InvalidContact— Invalid contact.WaitingForConfirmationSubscriptionStatusRequried— Recipient's subscription status must be Awaiting confirmation.CustomerUnsubscribed— Customer is unsubscribed from campaigns.CustomerInGlobalControlGroup— Customer is in the global control group.CustomerInMailingControlGroup— Customer is in the campaign's control group.
Not-delivered reasons:
EmailBlackList— [Email]: Rejected because the address is on the blocklist.EmailConnectionFailureOnSending— [Email]: Connection dropped during sending.EmailInactiveAccount— [Email]: Inbox is inactive or disabled.EmailIncorrectAddressFormat— [Email]: Invalid address format.EmailMailboxFull— [Email]: Mailbox is full.EmailMxRecordWasntResolved— [Email]: No mail server at the domain.EmailNonExistingAddress— [Email]: Address does not exist.EmailReceiverServerIsUnavailable— [Email]: Recipient's server is unreachable.EmailRejectedBecauseOfContent— [Email]: Rejected because of content.EmailRejectedWithUnknownReason— [Email]: Rejected for an unknown reason.EmailServerProtocolOrTimeoutError— [Email]: Protocol error or server response timeout.UnknownError— [Email]: Unknown error.
Related product category
{
"customerActions": [
{
...
"productCategories": [
{
"ids": {
"<External system name>": "<External product category ID>"
}
}
]
}
]
}
Related product
{
"customerActions": [
{
...
"products": [
{
"ids": {
"<External system name>": "<External product ID>"
}
}
]
}
]
}
Related product groups
{
"customerActions": [
{
...
"productGroups": [
{
"ids": {
"<External system name>": "<External product ID>"
}
}
]
}
]
}
Related balance change
{
"customerActions": [
{
...
"customerBalanceChanges": [
{
"balanceType": {
"ids": {
"systemName": "<Balance system name>"
},
"name": "<Balance name>"
},
"changeAmount": "<Balance change amount>",
"availableFromDateTimeUtc": "<Datetime the balance becomes available>",
"expirationDateTimeUtc": "<Points expiration datetime>",
"comment": "<Balance change comment>",
"balanceChangeKind": "<Balance change kind>"
}
]
}
]
}
Balance change kinds:
| System name | Change type | Display field |
|---|---|---|
| Expired | Points expired | Points expired |
| Custom | Manual or flow-based adjustment | Comment or Points earned |
| RetailOrderBonus | Points from an order — can be positive or negative (in case of returns) | Order bonus |
| RetailOrderPayment | Points spent on an order — can be positive (in case of returns) or negative | Order payment |
Related order
{
"customerActions": [
{
...
"order": {
"firstAction": {
"ids": {
"mindboxId": "<ID of the first order action>"
},
"channel": {
"ids": {
"mindboxId": "<Touchpoint Maestra ID>",
"externalId": "<Touchpoint external ID>"
},
"name": "<Touchpoint name>"
}
},
"ids": {
"mindboxId": "<Maestra ID>",
"orderMobileAppIdId": "<Order ID in the mobile app>"
},
"totalPrice": "<Order total with discounts>",
"lines": [
{
"product": {
"ids": {
"system1c": "<Product ID in 1C>",
"website": "<Product ID on the website>"
}
},
"quantity": "<Product quantity>",
"basePricePerItem": "<Base price per item>",
"priceOfLine": "<Final line total>",
"status": {
"ids": {
"externalId": "<Purchase status ID>"
}
},
"appliedPromotions": [
{
"type": "<earnedBonusPoints>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"balanceType": {
"ids": {
"systemName": "<Balance system name>"
},
"name": "<Balance name>"
},
"amount": "<Applied discount or bonus amount>",
"expirationDateTimeUtc": "<Points expiration datetime>"
},
{
"type": "<spentBonusPoints>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"balanceType": {
"ids": {
"systemName": "<Balance system name>"
},
"name": "<Balance name>"
},
"amount": "<Applied discount or bonus amount>"
},
{
"type": "<discount>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"amount": "<Applied discount or bonus amount>"
},
{
"type": "<deliveryDiscount>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"amount": "<Applied discount or bonus amount>"
},
{
"type": "<message>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
}
},
{
"type": "<issuedCoupon>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"issuedCoupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
}
},
{
"type": "<discount>",
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"amount": "<Applied discount or bonus amount>"
},
{
"type": "<discount>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"amount": "<Applied discount or bonus amount>"
}
],
"giftCard": {
"amount": "<Face value>",
"status": {
"ids": {
"systemName": "<Card status system name>"
}
}
},
"lineNumber": "<Order line number>",
"lineId": "<Order line ID>"
}
],
"appliedPromotions": [
{
"type": "<earnedBonusPoints>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"balanceType": {
"ids": {
"systemName": "<Balance system name>"
},
"name": "<Balance name>"
},
"amount": "<Applied discount or bonus amount>",
"expirationDateTimeUtc": "<Points expiration datetime>"
},
{
"type": "<spentBonusPoints>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"balanceType": {
"ids": {
"systemName": "<Balance system name>"
},
"name": "<Balance name>"
},
"amount": "<Applied discount or bonus amount>"
},
{
"type": "<discount>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"amount": "<Applied discount or bonus amount>"
},
{
"type": "<deliveryDiscount>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"amount": "<Applied discount or bonus amount>"
},
{
"type": "<message>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
}
},
{
"type": "<issuedCoupon>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"issuedCoupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
}
},
{
"type": "<discount>",
"promotion": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promotion external ID>"
},
"name": "<Promotion name>",
"type": "<Promotion type>"
},
"amount": "<Applied discount or bonus amount>"
},
{
"type": "<discount>",
"coupon": {
"ids": {
"code": "<Promo code>"
},
"pool": {
"ids": {
"mindboxId": "<Maestra ID>",
"externalId": "<Promo code pool external ID>"
},
"name": "<Promo code pool name>",
"description": "<Promo code pool description>"
}
},
"amount": "<Applied discount or bonus amount>"
}
],
"area": {
"ids": {
"externalId": "<Customer's geographic zone ID>"
}
},
"deliveryCost": "<Delivery cost>",
"payments": [
{
"type": "<Payment type>",
"id": "<Payment ID>",
"amount": "<Payment amount applied to the order>",
"creditCard": {
"hash": "<Card hash>"
}
}
],
"customFields": {
"defectTestField": "<defectTestField>",
"socialcard": "<Social card>"
}
}
}
]
}Updated about 2 months ago