Change subscription

Subscriptions on the marketplace are updated using the AppDirect user interface or the AppDirect subscription API.

A subscription change notification is triggered when an existing subscription is changed by the end user. The subscription change can be one of the following:

• An upgrade
• A downgrade
• A change in plan value
• A change in plan ID
• A change in subscription owner
• A vendor discount was added

To allow users to make changes to subscriptions, Developers must configure a Subscription Change Notification URL, such as https://example.com/change?eventUrl= eventUrl, in the product Edit integration page.

The general flow for a change subscription event notification is as follows:

1. A user changes (upgrades or downgrades) a subscription from AppDirect.
2. AppDirect creates a uniquely identified SUBSCRIPTION_CHANGE event, which is persisted in the marketplace. This event is uniquely identified by an eventUrl, such as https://www.acme-marketplace.com/api/integration/v1/events/d15bb36e-5fb5-11e0-8c3c-00262d2cda03.
3. AppDirect calls the configured subscription change notification URL, passing the eventUrl as a parameter.
4. The vendor validates the request based on the authorization type configured for their product. See Authorize inbound API requests for information on how to securely receive event notifications.
   Vendors can specify the format of the response they receive from AppDirect. They can add Accept: application/json in their HTTP GET request to receive the response from AppDirect in JSON format. They can add Accept: application/xml in their HTTP GET request to receive the response from AppDirect in XML format. If vendors do not specify the content type, an XML payload will be returned.
5. The vendor can then get the eventUrl from the URL parameters and read information regarding the SUBSCRIPTION_CHANGE that was triggered. This event contains the following elements:
   • type: The type of the event (SUBSCRIPTION_CHANGE in this case)
   • marketplace: Information about the AppDirect-powered marketplace on which the event took place.
   • creator: The identity of the admin creating the event.
   • payload: The event payload, containing the following elements:
     • order: The order change information.
     • account: The account identifier provided by the vendor in the initial Subscription Order Event.
     • The status of the subscription edition.
     • discount code: The vendor discount code is an optional field used by Marketplace Managers to store external promotional discount codes.
6. The vendor returns a result JSON or XML with the following:
   • success: Which should be "true" or "false."
   • errorCode: If "success" is false, this should contain one of the supported Event error codes.
   • message: An optional message containing information about the result of the operation.

Example SUBSCRIPTION_CHANGE event notification.

• JSON

{
    "type": "SUBSCRIPTION_CHANGE",
    "marketplace": {
      "baseUrl": "https://www.acme.com",
      "partner": "APPDIRECT"
    },
    "creator": {
      "address": {
        "city": "San Jose",
        "country": "US",
        "firstName": "Test",
        "fullName": "Test User",
        "lastName": "User",
        "state": "CA",
        "street1": "1 Main St",
        "zip": "95131"
      },
      "email": "testuser@testco.com",
      "firstName": "Test",
      "language": "en",
      "lastName": "User",
      "locale": "en-US",
      "openId": "https://www.acme.com/openid/id/7f59aad1-85cd-4c04-b35b-906ee53acc71",
      "uuid": "7f59aad1-85cd-4c04-b35b-906ee53acc71"
    },
    "payload": {
      "account": {
        "accountIdentifier": "206123",
        "status": "ACTIVE"
      },
      "order": {
        "editionCode": "DME",
        "pricingDuration": "DAILY",
      "freeTrial": {
        "active": "true"
        },
	"discountCode":"FALL2020"
        "items": [{
          "quantity": "0",
          "unit": "GIGABYTE"
        }]
      }
    }
}

• XML

  
<?xml version="1.0" encoding="UTF-8" ?>
<event>
	<type>SUBSCRIPTION_CHANGE</type>
	<marketplace>
		<baseUrl>https://www.acme.com</baseUrl>
		<partner>APPDIRECT</partner>
	</marketplace>
	<creator>
		<address>
			<city>San Jose</city>  
                       <country>US</country>  
                       <firstName>Test</firstName>  
			<fullName>Test User</fullName>
			<lastName>User</lastName>  
                       <state>CA</state>  
                       <street1>1 Main St</street1>  
                       <zip>95131</zip>  
               </address>
		<email>testuser@testco.com</email>
		<firstName>Test</firstName>>  
               <lastName>User</lastName>
               <locale>en-US</locale>
		<openId>https://www.acme.com/openid/id/47cb8f55-1af6-5bfc-9a7d-8061d3aa0c97</openId>
		<uuid>47cb8f55-1af6-5bfc-9a7d-8061d3aa0c97</uuid>  
       </creator>
	<payload>  
               <account>  
                       <accountIdentifier>206123</accountIdentifier>  
                       <status>ACTIVE</status>  
               </account>
		<order>
			<editionCode>DME</editionCode>
			<pricingDuration>DAILY</pricingDuration>  
			<freeTrial>
				<active>true</active>
			</freeTrial>
		    <discountCode>FALL2020</discountCode>
			<items>
				<quantity>0</quantity>
				<unit>GIGABYTE</unit>
			</items>
		<order>
	</payload>
</event>