Subscriptions¶
Closely related to tracking transactions is the tracking of subscription related events.
A subscription is a special type of product. After the product is initially bought, or in terms of subscriptions: requested, events will happen related to the subscription.
A subscription is initiated by a request of the customer to start a subscription. With a request we main that a customer wants to subscribe for a subscription. Usually this request is immediately accepted. This, however, is not the case for insurancs, loans, etc. These subscription often have to be validated and can be accepted or rejected.
We have the following subscription events:
- Request
- Acceptation
- Rejection
- Payment
- Change
- Prolongation
- Cancellation
You will have to POST to the tracking endpoint:
https://pipeline.harvest.graindata.com/track
You can also make use of your own domain. For more information read our CNAME sub domain documentation.
Note that not all possible variables are mentioned in the code below. For a full list of meta data, check our meta data documentation.
A full example of the syntax can be found below:
{
"event":"transaction",
"eventData": {
"eventID": "7c229310-fca4-ddf7-ccc7-b976b10ba169", //UUID
"harvestAccount": "example", //The name of your account
"harvestEnv" : "prod" // The name of the environment you want to send data to
},
"debugData": {
"userAgentData": {
"ua" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36"
}
},
"userData": {
"userID": "7c229310-fca4-ddf7-ccc7-b976b10ba169", // Optional, the userID of the user on the website. Allows to stitch missing transactions
"hashedEmail": "adj123jklsdfj123", //Optional - Allows to stitch transactions
"stitchID<number>": "12399123" // Optional - Your custom stitch ID - Allows to stitch transactions
},
"sessionData": {
"sessionID": "7c229310-fca4-ddf7-ccc7-b976b10ba169" // Optional, the sessionID of the user on the website. Allows to stitch missing transactions
},
"productData": [{
"name": "Product A", //Name or ID is required
"id": "123123", //Name or ID is required,
"subscriptionID": "123123", // This is the unique ID/reference for this subscription instance
"subscriptionIntervals: 12, // This is the amount of "base" intervals the subscription takes. For example if you specify the base as a month, a year will be 12
"subscriptionIntervalValue: 100 // The price per base interval, so if you choose month as a base interval it is the price per month
"subscriptionActions": [ "Request"], //This is the list of actions performed for this subscription, default will be Request, Acceptation and Payment
"paymentValue": 100, //This is the value that was paid. Only relevant for Payment action
"paymentMethod": "iDEAL", //This is the method that used to pay. Only relevant for Payment action
}],
"event": "subscription",
"origin": "example", //Optional - You can add the second level domain of the related website here
"originType": "server"
}
Examples¶
Below you will find some examples of each subscription action and how to send the data to the Harvest server.
Subscription request
This can be used to submit missing subscriptions on the website.
{
"eventData": {
"eventID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"harvestAccount": "example",
"harvestEnv": "prod"
},
"debugData": {
"userAgentData": {
"ua" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36"
}
},
"userData": {
"userID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"hashedEmail": "adj123jklsdfj123",
"stitchID1": "12399123"
},
"sessionData": {
"sessionID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
},
"productData": [{
"name" : "Product A",
"subscriptionID": "1233",
"subscriptionIntervals": 12,
"subscriptionIntervalValue": 100,
"subscriptionActions": ["Request"]
}],
"event": "subscription",
"origin": "example",
"originType": "server"
}
Subscription acceptation
It is possible that after the request came in, the request need to be checked. If everything is ok and the subscription is accepted, then you can send this event.
{
"eventData": {
"eventID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"harvestAccount": "example",
"harvestEnv": "prod"
},
"debugData": {
"userAgentData": {
"ua" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36"
}
},
"userData": {
"userID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"hashedEmail": "adj123jklsdfj123",
"stitchID1": "12399123"
},
"sessionData": {
"sessionID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
},
"productData": [{
"name" : "Product A",
"subscriptionID": "1233",
"subscriptionIntervals": 12,
"subscriptionIntervalValue": 100,
"subscriptionActions": ["Acceptation"]
}],
"event": "subscription",
"origin": "example",
"originType": "server"
}
Subscription rejection
{
"eventData": {
"eventID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"harvestAccount": "example",
"harvestEnv": "prod"
},
"userData": {
"userID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"hashedEmail": "adj123jklsdfj123",
"stitchID1": "12399123"
},
"debugData": {
"userAgentData": {
"ua" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36"
}
},
"sessionData": {
"sessionID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
},
"productData": [{
"name" : "Product A",
"subscriptionID": "1233",
"subscriptionIntervals": 12,
"subscriptionIntervalValue": 100,
"subscriptionActions": ["Rejection"]
}],
"event": "subscription",
"origin": "example",
"originType": "server"
}
Subscription payment
Each interval a payment will be incurred. Use the event below to track payments.
{
"eventData": {
"eventID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"harvestAccount": "example",
"harvestEnv": "prod"
},
"userData": {
"userID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"hashedEmail": "adj123jklsdfj123",
"stitchID1": "12399123"
},
"debugData": {
"userAgentData": {
"ua" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36"
}
},
"sessionData": {
"sessionID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
},
"productData": [{
"name" : "Product A",
"subscriptionID": "1233",
"subscriptionIntervals": 12,
"subscriptionIntervalValue": 100,
"subscriptionActions": ["Payment"],
"paymentValue": 100,
"paymentMethod": "iDEAL"
}],
"event": "subscription",
"origin": "example",
"originType": "server"
}
Subscription cancellation
{
"eventData": {
"eventID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"harvestAccount": "example",
"harvestEnv": "prod"
},
"debugData": {
"userAgentData": {
"ua" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36"
}
},
"userData": {
"userID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"hashedEmail": "adj123jklsdfj123",
"stitchID1": "12399123"
},
"sessionData": {
"sessionID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
},
"productData": [{
"name" : "Product A",
"subscriptionID": "1233",
"subscriptionIntervals": 12,
"subscriptionIntervalValue": 100,
"subscriptionActions": ["Cancellation"]
}],
"event": "subscription",
"origin": "example",
"originType": "server"
}
Subscription change
{
"eventData": {
"eventID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"harvestAccount": "example",
"harvestEnv": "prod"
},
"debugData": {
"userAgentData": {
"ua" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36"
}
},
"userData": {
"userID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"hashedEmail": "adj123jklsdfj123",
"stitchID1": "12399123"
},
"sessionData": {
"sessionID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
},
"productData": [{
"name" : "Product A",
"subscriptionID": "1233",
"subscriptionIntervals": 12,
"subscriptionIntervalValue": 100,
"subscriptionActions": ["Change"]
}],
"event": "subscription",
"origin": "example",
"originType": "server"
}
Subscription prolongation
When the user chooses to extend their subscription, use the event below.
{
"eventData": {
"eventID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"harvestAccount": "example",
"harvestEnv": "prod"
},
"debugData": {
"userAgentData": {
"ua" : "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.103 Safari/537.36"
}
},
"userData": {
"userID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
"hashedEmail": "adj123jklsdfj123",
"stitchID1": "12399123"
},
"sessionData": {
"sessionID": "7c229310-fca4-ddf7-ccc7-b976b10ba169",
},
"productData": [{
"name" : "Product A",
"subscriptionID": "1233",
"subscriptionIntervals": 12,
"subscriptionIntervalValue": 100,
"subscriptionActions": ["Prolongation"]
}],
"event": "subscription",
"origin": "example",
"originType": "server"
}
