We’ve migrated our documentation to a new site, which means some URLs have changed.
Subscriptions
Subscriptions
Breadcrumbs

Subscription Linking: JSON Schemas and API Call Examples

Create/update a Linked term

Find the main description here.

Please note that you can update the external term ID only if this term doesn't yet have conversions.

JSON schema: Create/update a Linked term 

{
    "type": "object",
    "required": [
        "external_product_ids",
        "external_term_id",
        "term_name"
    ],
    "properties": {
        "external_term_id": {
            "type": "string"
        },
        "term_name": {
            "type": "string"
        },
        "description": {
            "type": "string"
        },
        "external_product_ids": {
            "type": "string"
        },
        "subscription_management_url": {
            "type": "string"
        },
        "custom_data": {
            "type": "object"
        }
    }
}

 

Example: Creating a Linked term

Please note that you can update the External term ID or the External product IDs of your Linked term only if this term doesn't yet have conversions.

The External product IDs must be standard resources or a single bundle.

As you want to add a bundle containing three resources and another bundle containing one resource, you will need to add all four resources manually. That will create a new bundle containing all four resources. The new bundle can also be used in a different Linked Term.

GET /api/v3/publisher/linkedTerm/configuration?aid=JF0ZzghL3U&api_token=qp1f4e9BgYpS4WKLLhGHl1ZoQJLSRk4GcqMUOAN1 HTTP/1.1
Host: api.piano.io
Content-Type: application/json
Content-Length: 122

{
    "external_term_id": "greatest_term_v1",
    "term_name": "Linked Term for sale",
    "description": "Linked term for offer #2339LBV",
    "external_product_ids": "digital_news,pro_access",
    "subscription_management_url": "https://example.com/subsription/manage",
    "custom_data": 
    {
        "period": "monthly",
        "plus_campaign_participant": true
    }
}

Create/update custom fields

JSON schema: Create/update custom fields 

{
    "type": "object",
    "required": [
        "custom_fields"
    ],
    "properties": {
        "custom_fields": {
            "type": "object",
            "additionalProperties": {
                "type": "string"
            }
         }
    }
}

Example: Creating two custom fields for a Linked term 

POST /api/v3/publisher/linkedTerm/customField/configuration?aid=JF0ZzghL3U&api_token=qp1f4e9BgYpS4WKLLhGHl1ZoQJLSRk4GcqMUOAN1

{
 "custom_fields": [
   {
     "name": "field_one",
     "title": "Field 1",
     "type": "Text"
   },
   {
     "name": "field_two",
     "title": "Field 2",
     "type": "Number"
   }
 ]
}

linkedTermSelected

Find the main description here.

JSON schema: LinkedTerm object 

{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "$id": "af9f99fc-d3e7-4a9d-9a53-0fa6cb430f9a",
 "title": "LinkedTerm",
 "type": "object",
 "properties": {
   "name": {
    "type": "string"
   },
   "description": {
  "type": "string"
   },
   "linkedTermData": {
  "type": "object",
     "properties": {
       "externalProductIds": {
        "type": "string"
       },
       "subscriptionManagementUrl": {
        "type": "string"
       },
       "customData": {
        "type": "object"
       },
       "externalTermId": {
        "type": "string"
       },
       "userHasActiveSubscriptionToTerm": {
       "type": "boolean"
       }
     },
     "required": [ 
"externalProductIds",
"externalTermId",
"userHasActiveSubscriptionToTerm"
]
   }
 },
 "required": [
   "name",
   "linkedTermData"
 ]
}

Example: LinkedTerm object 

{
  "name": "Digital annual",
  "linkedTermData": {
    "externalProductIds": "digital_id_1",
    "externalTermId": "digital_id_1",
    "subscriptionManagementUrl": null,
    "customData": {
      "price": {
        "amount": 99,
        "currency": "USD"
      },
      "period": "annual"
    },
    "userHasActiveSubscriptionToTerm": "false"
  }
}

Example: Callback function

For an example named onLinkedTermSelected, the signature will be:

function onLinkedTermSelected (session_id, linkedTerm)

To configure the function, add the following line to the JavaScript integration script:

tp.push(['setLinkedTermSelected', onLinkedTermSelected])

Another option is:

tp.push(['setLinkedTermSelected', (session_id, linkedTerm) => { /* place some code here */ }])

The function itself will look like this:

function onLinkedTermSelected(sessionId, linkedTerm) {
  var data = linkedTerm.linkedTermData;
  var externalTermId = data.externalTermId;
  var amount = data.customData.amount;
  var currency = data.customData.currency;

  openExternalCheckout(sessionId, externalTermId, amount, currency);
}

Example: LinkedTerm object 

{
  "name": "Digital annual",
  "linkedTermData": {
    "externalProductIds": "digital_id_1",
    "externalTermId": "digital_id_1",
    "subscriptionManagementUrl": null,
    "customData": {
      "price": {
        "amount": 99,
        "currency": "USD"
      },
      "period": "annual"
    }
  }
}

Create/update user custom fields

JSON schema

Sync API events

Find the main description here.

subscription_create

This event type is used to create a subscription along with a business conversion, e.g. after a successful purchase.

JSON schema: subscription_create 
{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"$id": "1f8af41f-4b06-4ffc-8a46-b27e361851ef",
	"title": "Event",
	"type": "object",
	"properties": {
		"action": {
			"type": "string"
		},
		"subscription": {
			"type": "object",
			"properties": {
				"subscription_id": {
					"type": "string"
				},
				"user_token": {
					"type": "string"
				},
				"external_term_id": {
					"type": "string"
				},
				"state": {
					"type": "string"
				},
				"valid_to": {
					"type": "number"
				},
				"auto_renew": {
					"type": "boolean"
				},
				"purchase": {
					"type": "object",
					"properties": {
						"trial": {
							"type": "string"
						}
					},
					"required": [
						"trial"
					]
				},
				"access_custom_data": {
					"type": "string"
				},

				"user_custom_fields": {
    				        "type": "object"
  				},

				"period": {
					"type": "string"
				}
			},
			"required": [
				"subscription_id",
				"user_token",
				"external_term_id",
				"state",
				"valid_to"
			]
		},
		"conversion": {
			"type": "object",
			"properties": {
				"conversion_id": {
					"type": "string"
				},
				"create_date": {
					"type": "number"
				},
				"payment": {
					"type": "object",
					"properties": {
						"amount": {
							"type": "number"
						},
						"currency": {
							"type": "string"
						}
					}
				},
				"required": [
					"amount",
					"currency"
				]
			},
			"required": [
				"conversion_id",
				"create_date"
			]
		},
		"session_id": {
			"type": "string"
		}
	},
	"required": [
		"action",
		"subscription"
	]
}
API success response: subscription_create 
{
  "code": 0,
  "ts": "123456789",
  "data": "success"
}

Where "code" is the response code, "ts" is the response timestamp, and "data" is the response content.

Example: Creating a subscription and a conversion after a successful purchase 
POST /api/v3/publisher/linkedTerm/event?api_token=CF3C19D12945F45E4D&aid=8YVYaCUUbJ HTTP/1.1
Host: api.piano.io
Content-Type: application/json

{
  "action": "subscription_create",
  "session_id": "S0TA3f7jHui1tSoHdJXf9hnDG8MS4wap",	
  "subscription": {
    "subscription_id": "SUB253MZAEWCN8VW4", // The subscription with this ID should not exist.
    "user_token": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJhbHBoYV9leHRlcm5hbF9wcm92aWRlciIsInN1YiI6Im15VWlkMzIiLCJhdWQiOiJhbHBoYV9zb2NpYWxfbW9jayIsImZpcnN0X25hbWUiOiJKb2huIiwibGFzdF9uYW1lIjoiRG9lIiwidXNlcl9lbWFpbCI6Im15dWlkMzJAc29jaWFsLW1vY2suY29tIiwiZXhwIjoxNjc1MzM4MTA5LCJpYXQiOjE2NzQ3MzMzMDksImp0aSI6IjJlMDVhNWQ2MjIzMCJ9.TRj2J6e8gQKc8Z8xQBbhkyGP31PXj1v2lBbGedZu42DUQysq1kMzlN5EZabkCVzmY1C8SOKT1wit0RnQpUxOTw",
    "external_term_id":"digital_pass_v13",
    "state": "Active", // The subscription should be active.
    "valid_to": 1669838400, // The subscription should be valid to Wed Nov 30 2022 20:00:00 GMT+0000.
    "purchase": {
      "trial": "Free" // The subscription has a free trial period.
    },
    "access_custom_data": "{\"field\":\"value\"}" // Any string.
"user_custom_fields": { // Send initial custom field values
  "field_one": "initial value",
  "field_two": 1
},
  "conversion": {
    "conversion_id": "CON9U79LR267NL3AT", // The conversion with this ID should not exist.
    "create_date": 1667246400 // The subscription was converted on Mon Oct 31 2022 20:00:00 GMT+0000.
  }
}

subscription_upgrade

This event type is used to create a new subscription after a successful upgrade.

JSON schema: subscription_upgrade 
"$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "1f8af41f-4b06-4ffc-8a46-b27e361851ef",
   "title": "Event",
   "type": "object",
   "properties": {
       "action": {
           "type": "string"
       },
       "subscription": {
           "type": "object",
           "properties": {
               "subscription_id": {
                   "type": "string"
               },
               "user_token": {
                   "type": "string"
               },
               "external_term_id": {
                   "type": "string"
               },
               "state": {
                   "type": "string"
               },
               "valid_to": {
                   "type": "number"
               },
               "auto_renew": {
                   "type": "boolean"
               },
               "purchase": {
                   "type": "object",
                   "properties": {
                       "trial": {
                           "type": "string"
                       }
                   },
                   "required": [
                       "trial"
                   ]
               },
               "upgrade": {
                   "type": "object",
                   "properties": {
                       "from_subscription_id": {
                           "type": "string"
                       }
                   },
                   "required": [
                       "from_subscription_id"
                   ]
               },
               "access_custom_data": {
                   "type": "string"
               },
               "period": {
                   "type": "string"
               }
           },
           "required": [
               "subscription_id",
               "user_token",
               "external_term_id",
               "state",
               "valid_to",
		  "upgrade"
           ]
       },
       "conversion": {
           "type": "object",
           "properties": {
               "conversion_id": {
                   "type": "string"
               },
               "create_date": {
                   "type": "number"
               },
               "payment": {
                   "type": "object",
                   "properties": {
                       "amount": {
                           "type": "number"
                       },
                       "currency": {
                           "type": "string"
                       }
                   }
               },
               "required": [
                   "amount",
                   "currency"
               ]
           },
           "required": [
               "conversion_id",
               "create_date"
           ]
       },
       "session_id": {
           "type": "string"
       }
   },
   "required": [
       "action",
       "subscription"
   ]
}

API success response: subscription_upgrade 
{
 "code": 0,
 "ts": "123456789",
 "data": "success"
}

Where "code" is the response code, "ts" is the response timestamp, and "data" is the response content.

Example: Upgrading a subscription 
POST /api/v3/publisher/linkedTerm/event?api_token=CF3C19D12945F45E4D&aid=8YVYaCUUbJ HTTP/1.1
Host: api.piano.io
Content-Type: application/json

{
 "action": "subscription_upgrade",
 "session_id": "S0TA3f7jHui1tSoHdJXf9hnDG8MS4wap",	
 "subscription": {
   "subscription_id": "SUB053MZAZCCN8VW7", // The subscription with this ID should not exist.
   "user_token": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJhbHBoYV9leHRlcm5hbF9wcm92aWRlciIsInN1YiI6Im15VWlkMzIiLCJhdWQiOiJhbHBoYV9zb2NpYWxfbW9jayIsImZpcnN0X25hbWUiOiJKb2huIiwibGFzdF9uYW1lIjoiRG9lIiwidXNlcl9lbWFpbCI6Im15dWlkMzJAc29jaWFsLW1vY2suY29tIiwiZXhwIjoxNjc1MzM4MTA5LCJpYXQiOjE2NzQ3MzMzMDksImp0aSI6IjJlMDVhNWQ2MjIzMCJ9.TRj2J6e8gQKc8Z8xQBbhkyGP31PXj1v2lBbGedZu42DUQysq1kMzlN5EZabkCVzmY1C8SOKT1wit0RnQpUxOTw",
   "external_term_id":"digital_pass_v13",
   "state": "Active", // The subscription should be active.
   "valid_to": 1669838400, // The subscription should be valid to Wed Nov 30 2022 20:00:00 GMT+0000.
   "purchase": {
     "trial": "Free" // The subscription has a free trial period.
   },
   "upgrade": {
      "from_subscription_id": "SUB253MZAEWCN8VW4" // The subscription we upgrade from
   },
   "access_custom_data": "{\"field\":\"value\"}" // Any string.
 },
 "conversion": {
   "conversion_id": "CON1179L5F67NL3BB", // The conversion with this ID should not exist.
   "create_date": 1667246400 // The subscription was converted on Mon Oct 31 2022 20:00:00 GMT+0000.
 }
}

subscription_renew

This event is used to renew an existing subscription along with creating a business conversion.

JSON schema: subscription_renew 
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "1f8af41f-4b06-4ffc-8a46-b27e361851ef",
    "title": "Event",
    "type": "object",
    "properties": {
        "action": {
            "type": "string"
        },
        "subscription": {
            "type": "object",
            "properties": {
                "subscription_id": {
                    "type": "string"
                },
                "external_term_id": {
                    "type": "string"
                },
                "state": {
                    "type": "string"
                },
                "valid_to": {
                    "type": "number"
                },
                "auto_renew": {
                    "type": "boolean"
                },
                "purchase": {
                    "type": "object",
                    "properties": {
                        "trial": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "trial"
                    ]
                },
                "access_custom_data": {
                    "type": "string"
                },
                "user_custom_fields": {
                    "type": "object"
                }
            },
            "required": [
                "subscription_id",
                "user_token",
                "external_term_id",
                "state",
                "valid_to"
            ]
        },
        "conversion": {
            "type": "object",
            "properties": {
                "conversion_id": {
                    "type": "string"
                },
                "create_date": {
                    "type": "number"
                },
                "payment": {
                    "type": "object",
                    "properties": {
                        "amount": {
                            "type": "number"
                        },
                        "currency": {
                            "type": "string"
                        }
                    }
                },
                "period": {
                    "type": "string"
                },
                "required": [
                    "amount",
                    "currency"
                ]
            },
            "required": [
                "conversion_id",
                "create_date"
            ]
        },
        "session_id": {
            "type": "string"
        }
    },
    "required": [
        "action",
        "subscription"
    ]
}
Example: Renewing a subscription 
POST /api/v3/publisher/linkedTerm/event?api_token=CF3C19D12945F45E4D&aid=8YVYaCUUbJ HTTP/1.1
Host: api.piano.io
Content-Type: application/json

{
  "action": "subscription_renew",
  "session_id": "S0TA3f7jHui1tSoHdJXf9hnDG8MS4wap",
  "subscription": {
    "subscription_id": "SUB253MZAEWCN8VW4", // The subscription with this ID should exist.
     "user_token": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJhbHBoYV9leHRlcm5hbF9wcm92aWRlciIsInN1YiI6Im15VWlkMzIiLCJhdWQiOiJhbHBoYV9zb2NpYWxfbW9jayIsImZpcnN0X25hbWUiOiJKb2huIiwibGFzdF9uYW1lIjoiRG9lIiwidXNlcl9lbWFpbCI6Im15dWlkMzJAc29jaWFsLW1vY2suY29tIiwiZXhwIjoxNjc1MzM4MTA5LCJpYXQiOjE2NzQ3MzMzMDksImp0aSI6IjJlMDVhNWQ2MjIzMCJ9.TRj2J6e8gQKc8Z8xQBbhkyGP31PXj1v2lBbGedZu42DUQysq1kMzlN5EZabkCVzmY1C8SOKT1wit0RnQpUxOTw", // Keep the same token.
    "external_term_id":"digital_pass_v13",  // Keep the external term ID.
    "state": "Active", // Keep the subscription active.
    "valid_to": 1672344000, // Make the subscription valid 1 month more (until Thu Dec 29 2022 20:00:00 GMT+0000).
    "purchase": {
      "trial": "Free" // Keep the free trial period of the subscription.
    },
    "access_custom_data": "{\"field\":\"value\"}" // Keep the custom data of the subscription.
    "user_custom_fields": { // Update custom fields
     "field_one": "updated value",
     "field_two": 10
},
  "conversion": {
    "conversion_id": "CODD_Y67NN9U2L3AT", // The conversion with this ID should not exist.
    "create_date": 1669838400 // The subscription was converted on Wed Nov 30 2022 20:00:00 GMT+0000.
  }
}

subscription_update

This event is used to directly update an existing subscription without creating a conversion (for temporary subscription deactivation or non-commercial subscription modification).

JSON schema: subscription_update 
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "1f8af41f-4b06-4ffc-8a46-b27e361851ef",
    "title": "Event",
    "type": "object",
    "properties": {
        "action": {
            "type": "string"
        },
        "subscription": {
            "type": "object",
            "properties": {
                "subscription_id": {
                    "type": "string"
                },
                "user_token": {
                    "type": "string"
                },
                "external_term_id": {
                    "type": "string"
                },
                "state": {
                    "type": "string"
                },
                "valid_to": {
                    "type": "number"
                },
                "auto_renew": {
                    "type": "boolean"
                },
                "purchase": {
                    "type": "object",
                    "properties": {
                        "trial": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "trial"
                    ]
                },
                "access_custom_data": {
                    "type": "string"
                }
            },
            "required": [
                "subscription_id",
                "user_token",
                "external_term_id",
                "state",
                "valid_to"
            ]
        }
    },
    "required": [
        "action",
        "subscription"
    ]
}
Example: Updating a subscription without creating a conversion to temporarily deactivate it and delete ‘purchase’ data 
POST /api/v3/publisher/linkedTerm/event?api_token=CF3C19D12945F45E4D&aid=8YVYaCUUbJ HTTP/1.1
Host: api.piano.io
Content-Type: application/json

{
  "action": "subscription_update",
  "session_id": "S0TA3f7jHui1tSoHdJXf9hnDG8MS4wap",
  "subscription": {
    "subscription_id": "SUB253MZAEWCN8VW4",
    // The subscription with this ID should exist.
    "user_token": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJhbHBoYV9leHRlcm5hbF9wcm92aWRlciIsInN1YiI6Im15VWlkMzIiLCJhdWQiOiJhbHBoYV9zb2NpYWxfbW9jayIsImZpcnN0X25hbWUiOiJKb2huIiwibGFzdF9uYW1lIjoiRG9lIiwidXNlcl9lbWFpbCI6Im15dWlkMzJAc29jaWFsLW1vY2suY29tIiwiZXhwIjoxNjc1MzM4MTA5LCJpYXQiOjE2NzQ3MzMzMDksImp0aSI6IjJlMDVhNWQ2MjIzMCJ9.TRj2J6e8gQKc8Z8xQBbhkyGP31PXj1v2lBbGedZu42DUQysq1kMzlN5EZabkCVzmY1C8SOKT1wit0RnQpUxOTw",
    // Keep the same token.
    "external_term_id": "digital_pass_v13",
    // Keep the external term ID.
    "state": "Not active",
    // Make the subscription not active.
    "valid_to": 1672344000,
    // Keep the subscription valid until Thu Dec 29 2022 20:00:00 GMT+0000.
    "purchase": {
      // Remove purchase data from the subscription.
      "trial": "Free"
    },
    "access_custom_data": "{\"field\":\"value\"}"
    // Keep the custom data of the subscription.
  }
}

subscription_terminate

Use this event type to terminate a subscription.

Before termination, the subscription data is updated according to the newly received values. 

A subscription_terminate event deactivates the subscription permanently so that it won't be able to receive any synchronization events or be reactivated.

JSON schema: subscription_terminate 
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "1f8af41f-4b06-4ffc-8a46-b27e361851ef",
    "title": "Event",
    "type": "object",
    "properties":
    {
        "action":
        {
            "type": "string"
        },
        "subscription":
        {
            "type": "object",
            "properties":
            {
                "subscription_id":
                {
                    "type": "string"
                },
                "user_token":
                {
                    "type": "string"
                },
                "external_term_id":
                {
                    "type": "string"
                },
                "state":
                {
                    "type": "string"
                },
                "valid_to":
                {
                    "type": "number"
                },
                "auto_renew":
                {
                    "type": "boolean"
                },
                "purchase":
                {
                    "type": "object",
                    "properties":
                    {
                        "trial":
                        {
                            "type": "string"
                        }
                    },
                    "required":
                    [
                        "trial"
                    ]
                },      
                "access_custom_data":
                {
                    "type": "string"
                },
                "user_custom_fields": 
                {
                    "type": "object"
                 },
                "period":
                {
                        "type": "string"
                 },
                "churn": 
                {
                   "type": "object",
                   "properties": 
                   {
                        "amount": 
                        {
                             "type": "number"
                         },
                        "currency": 
                        {
                             "type": "string"
                         }
                    }
                 }
            },
            "required":
            [
                "subscription_id",
                "user_token",
                "external_term_id",
                "state",
                "valid_to"
            ]
        },
        "session_id":
        {
            "type": "string"
        }
    },
    "required":
    [
        "action",
        "subscription"
    ]
}
API success response: subscription_terminate 
{
  "code": 0,
  "ts": "123456789",
  "data": "success"
}

Where "code" is the response code, "ts" is the response timestamp, and "data" is the response content.

Example: Terminating a subscription 
POST /api/v3/publisher/linkedTerm/event?api_token=CF3C19D12945F45E4D&aid=8YVYaCUUbJ HTTP/1.1
Host: api.piano.io
Content-Type: application/json

{
  "action": "subscription_terminate
",
  "session_id": "S0TA3f7jHui1tSoHdJXf9hnDG8MS4wap",
  "subscription": {
    "subscription_id": "SUB253MZAEWCN8VW4", // The external subscription ID. The subscription with this ID should exist.
    "user_token": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJhbHBoYV9leHRlcm5hbF9wcm92aWRlciIsInN1YiI6Im15VWlkMzIiLCJhdWQiOiJhbHBoYV9zb2NpYWxfbW9jayIsImZpcnN0X25hbWUiOiJKb2huIiwibGFzdF9uYW1lIjoiRG9lIiwidXNlcl9lbWFpbCI6Im15dWlkMzJAc29jaWFsLW1vY2suY29tIiwiZXhwIjoxNjc1MzM4MTA5LCJpYXQiOjE2NzQ3MzMzMDksImp0aSI6IjJlMDVhNWQ2MjIzMCJ9.TRj2J6e8gQKc8Z8xQBbhkyGP31PXj1v2lBbGedZu42DUQysq1kMzlN5EZabkCVzmY1C8SOKT1wit0RnQpUxOTw", // Keep the same token.
    "external_term_id":"digital_pass_v13",  // Keep the external term ID.
    "valid_to": 1672344000, // Keep the same valid until Thu Dec 29 2022 20:00:00 GMT+0000.
  "churn": {
    "amount": 5,
    "currency": "USD"
  },
    "access_custom_data": "{\"field\":\"value\"}" // Keep the custom data of the subscription.
  },
  "user_custom_fields": { // Reset custom field values
  "field_one": "",
  "field_two": 0
  }
}

Find the main description here.

JSON schema: shared_access_grant and shared_access_revoke

As of July 2023, both 1) sharing subscription with a user access and 2) revoking previously shared subscription access from a user can be passed with the same JSON schema.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Event",
    "type": "object",
    "properties": {
        "action": {
            "type": "string"
        },
        "session_id": {
            "type": "string"
        },
        "shared_access": {
            "type": "object",
            "properties": {
                "subscription_id": {
                    "type": "string",
                },
                "user_tokens": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "minItems": 1,
                    "uniqueItems": true
                }
            },
            "required": [
                "subscription_id",
                "user_tokens"
            ]
        }
    },
    "required": [
        "action",
        "shared_access"
    ]
}

API success response: shared_access_grant and shared_access_revoke

The success response for the event is:

{
 "code": 0,
 "ts": "123456789,
 "data": "success"
}

Where "code" is the response code, "ts" is the response timestamp, and "data" is the response content.

Example: Sharing subscription access with two child users 
POST /api/v3/publisher/linkedTerm/event?api_token=CF3C19D12945F45E4D&aid=8YVYaCUUbJ HTTP/1.1
Host: api.piano.io
Content-Type: application/json

{
  "action": "shared_access_grant",
  "shared_access": {
    "subscription_id": "SUB253MZAEWCN8VW4",// The subscription with this ID should exist.
    "user_token": [          "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJhbHBoYV9leHRlcm5hbF9wcm92aWRlciIsInN1YiI6Im15VWlkMzIiLCJhdWQiOiJhbHBoYV9zb2NpYWxfbW9jayIsImZpcnN0X25hbWUiOiJKb2huIiwibGFzdF9uYW1lIjoiRG9lIiwidXNlcl9lbWFpbCI6Im15dWlkMzJAc29jaWFsLW1vY2suY29tIiwiZXhwIjoxNjc1MzM4MTA5LCJpYXQiOjE2NzQ3MzMzMDksImp0aSI6IjJlMDVhNWQ2MjIzMCJ9.TRj2J6e8gQKc8Z8xQBbhkyGP31PXj1v2lBbGedZu42DUQysq1kMzlN5EZabkCVzmY1C8SOKT1wit0RnQpUxOTw",
"eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJhbHBoYV9leHRlcm5hbF9wcm92aWRlciIsInN1YiI6Im15VWlkMzIiLCJhdWQiOiJhbHBoYV9zb2NpYWxfbW9jayIsImZpcnN0X25hbWUiOiJKb2huIiwibGFzdF9uYW1lIjoiRG9lIiwidXNlcl9lbWFpbCI6Im15dWlkMzJAc29jaWFsLW1vY2suY29tIiwiZXhwIjoxNjc1MzM4MTA5LCJpYXQiOjE2NzQ3MzMzMDksImp0aSI6IjJlMDVhNWQ2MjIzMCJ9.TRj2J6e8gQKc8Z8xQBbhkyGP31PXj1v2lBbGedZu42DUQysq1kMzlN5EZabkCVzmY1C8SOKT1wit0RnQpUxOTw"
    ]
  }
}
Example: Revoking shared subscription access from one child user 
POST /api/v3/publisher/linkedTerm/event?api_token=CF3C19D12945F45E4D&aid=8YVYaCUUbJ HTTP/1.1
Host: api.piano.io
Content-Type: application/json

{
    "action": "shared_access_revoke",
    "shared_access" : {
        "subscription_id": "SUB253MZAEWCN8VW4", // The subscription with this ID should exist.
        "user_token": ["eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJhbHBoYV9leHRlcm5hbF9wcm92aWRlciIsInN1YiI6Im15VWlkMzIiLCJhdWQiOiJhbHBoYV9zb2NpYWxfbW9jayIsImZpcnN0X25hbWUiOiJKb2huIiwibGFzdF9uYW1lIjoiRG9lIiwidXNlcl9lbWFpbCI6Im15dWlkMzJAc29jaWFsLW1vY2suY29tIiwiZXhwIjoxNjc1MzM4MTA5LCJpYXQiOjE2NzQ3MzMzMDksImp0aSI6IjJlMDVhNWQ2MjIzMCJ9.TRj2J6e8gQKc8Z8xQBbhkyGP31PXj1v2lBbGedZu42DUQysq1kMzlN5EZabkCVzmY1C8SOKT1wit0RnQpUxOTw"] // The user should exist in VX and have an access previously shared from the sub specified. 
    },
    "session_id": "S0TA3f7jHui1tSoHdJXf9hnDG8MS4wap"
}

Subscription-import event

This event type is used to create a subscription without reporting and segmentation when importing external subscriptions. Find the main description here.

JSON schema: subscription_import 
{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"$id": "1f8af41f-4b06-4ffc-8a46-b27e361851ef",
	"title": "Event",
	"type": "object",
	"properties": {
		"action": {
			"type": "string"
		},
		"subscription": {
			"type": "object",
			"properties": {
				"subscription_id": {
					"type": "string"
				},
				"user_token": {
					"type": "string"
				},
				"external_term_id": {
					"type": "string"
				},
				"state": {
					"type": "string"
				},
				"valid_to": {
					"type": "number"
				},
				"auto_renew": {
					"type": "boolean"
				},
				"purchase": {
					"type": "object",
					"properties": {
						"trial": {
							"type": "string"
						}
					},
					"required": [
						"trial"
					]
				},
				"access_custom_data": {
					"type": "string"
				},
				"period": {
					"type": "string"
				}
			},
			"required": [
				"subscription_id",
				"user_token",
				"external_term_id",
				"state",
				"valid_to"
			]
		},
		"conversion": {
			"type": "object",
			"properties": {
				"conversion_id": {
					"type": "string"
				},
				"create_date": {
					"type": "number"
				},
				"payment": {
					"type": "object",
					"properties": {
						"amount": {
							"type": "number"
						},
						"currency": {
							"type": "string"
						}
					}
				},
				"required": [
					"amount",
					"currency"
				]
			},
			"required": [
				"conversion_id",
				"create_date"
			]
		},
		"session_id": {
			"type": "string"
		}
	},
	"required": [
		"action",
		"subscription"
	]
}
API success response: subscription_import 
{
  "code": 0,
  "ts": "123456789",
  "data": "success"
}

Where "code" is the response code, "ts" is the response timestamp, and "data" is the response content.

Example: Creating a subscription and a conversion after importing an external Linked term subscription 
POST /api/v3/publisher/linkedTerm/event?api_token=CF3C19D12945F45E4D&aid=8YVYaCUUbJ HTTP/1.1
Host: api.piano.io
Content-Type: application/json

{
  "action": "subscription_import",
  "session_id": "S0TA3f7jHui1tSoHdJXf9hnDG8MS4wap",
  "subscription": {
    "subscription_id": "SUB253MZAEWCN8VW4", 
    // The subscription with this ID should not exist.
    "user_token": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJhbHBoYV9leHRlcm5hbF9wcm92aWRlciIsInN1YiI6Im15VWlkMzIiLCJhdWQiOiJhbHBoYV9zb2NpYWxfbW9jayIsImZpcnN0X25hbWUiOiJKb2huIiwibGFzdF9uYW1lIjoiRG9lIiwidXNlcl9lbWFpbCI6Im15dWlkMzJAc29jaWFsLW1vY2suY29tIiwiZXhwIjoxNjc1MzM4MTA5LCJpYXQiOjE2NzQ3MzMzMDksImp0aSI6IjJlMDVhNWQ2MjIzMCJ9.TRj2J6e8gQKc8Z8xQBbhkyGP31PXj1v2lBbGedZu42DUQysq1kMzlN5EZabkCVzmY1C8SOKT1wit0RnQpUxOTw",
    "external_term_id": "digital_pass_v13",
    "state": "Active", 
    // The subscription should be active.
    "valid_to": 1669838400, 
    // The subscription should be valid to Wed Nov 30 2022 20:00:00 GMT+0000.
    "purchase": {
      "trial": "Free" 
      // The subscription has a free trial period.
    },
    "access_custom_data": "{\"field\":\"value\"}" 
    // Any string.
  },
  "conversion": {
    "conversion_id": "CON9U79LR267NL3AT", 
    // The conversion with this ID should not exist.
    "create_date": 1667246400 
    // The subscription was converted on Mon Oct 31 2022 20:00:00 GMT+0000.
  }
}

Last updated: