Create subscription

End users can purchase products (create a subscription) through the marketplace. These subscriptions can be either FREE_TRIAL (if the edition purchased has a free trial period) or ACTIVE. Subscriptions are created using the AppDirect user interface or the AppDirect subscription API.

The create subscription event notification allows vendors to receive a notice (SUBSCRIPTION_ORDER) when an end user purchases a subscription. Only items which are adjustable by the end user, for example purchasing or updating an edition, are included in a create subscription event. Metered billing usage and "included items" are handled separately. To allow users to purchase your product, you must define a subscription create notification URL, such as https://example.com/create?eventUrl= eventUrl, on the product's Edit integration page. AppDirect calls this URL when end users purchase new subscriptions.

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

1. A user orders an application from AppDirect.
2. AppDirect creates a uniquely identified SUBSCRIPTION_ORDER event, which is persisted in the AppDirect-powered marketplace. This event is uniquely identified by an event UUID, such as yourmarketplace.com/api/integration/v1/events/event UUID. The eventUrl contains the event UUID. The event UUID is also called an Event token.

For example, https://www.acme-marketplace.com/api/integration/v1/events/d15bb36e-5fb5-11e0-8c3c-00262d2cda03. 3. AppDirect calls the configured subscription order notification URL, passing the eventUrl as a parameter. 4. The vendor must validate the request based on the authorization type configured for their product. See Validate outbound event notifications 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_ORDER event that was triggered. This event contains the following elements:

1. type: The type of the event (SUBSCRIPTION_ORDER in this case).
2. marketplace: Information about the marketplace on which the event took place.
3. creator: The identity of the user who triggered the event.
4. payload: The event payload, containing the following elements:
   1. order: The order information, which contains an edition code, the quantity of units bought, and the unit type such as "users" associated with the order. It also contains the status of the subscription edition.
   2. company: The company creating the order. Contact information about the ordering company is provided if it is available, but may be empty.
   3. discount code: The vendor discount code is an optional field used by Marketplace Managers to store external promotional discount codes.
5. The vendor creates the account and returns a result JSON or XML with these elements:
   1. success: Which should be "true" or "false."
   2. accountIdentifier: A sequence of characters that is used to identify the account. This identifier is used in subsequent transactions to identify this account and cannot be changed.
   3. errorCode: If "success" is false, this should contain one of the supported Event error codes.
   4. message: An optional message containing information about the result of the operation.

Example SUBSCRIPTION_ORDER event notification

• JSON

{
    "type": "SUBSCRIPTION_ORDER",
    "marketplace": {
      "baseUrl": "https://www.acme.com",
      "partner": "APPDIRECT"
    },
    "creator": {
      "address": {
        "firstName": "Test",
        "fullName": "Test User",
        "lastName": "User"
      },
      "email": "testuser@testco.com",
      "firstName": "Test",
      "language": "en",
      "lastName": " User",
      "locale": "en-US",
      "openId": "https://www.acme.com/openid/id/47cb8f55-1af6-5bfc-9a7d-8061d3aa0c97",
      "uuid": "47cb8f55-1af6-5bfc-9a7d-8061d3aa0c97"
    },
    "payload": {
      "company": {
        "country": "US",
        "name": "tester",
        "phoneNumber": "1-800-333-3333",
        "uuid": "385beb51-51ae-4ffe-8c05-3f35a9f99825",
        "website": "www.testco.com"
      },
      "order": {
        "editionCode": "Standard",
        "pricingDuration": "MONTHLY",
      "freeTrial": {
        "active": "true" 
      },
    "discountCode": "FALL2020"
        "items": [{
          "quantity": "4",
          "unit": "USER"
        }]
      }
    }
}

• XML

<?xml version="1.0" encoding="UTF-8" ?>
<event>
	<type>SUBSCRIPTION_ORDER</type>
	<marketplace>
		<baseUrl>https://www.acme.com</baseUrl>
		<partner>APPDIRECT</partner>
	</marketplace>
	<creator>
		<address>
			<firstName>Test</firstName>
			<fullName>Test User</fullName>
			<lastName>User</lastName>
		</address>
		<email>testuser@testco.com</email>
		<firstName>Test</firstName>>
		<language>en</language>
		<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>
		<company>
			<country>US</country>
			<name>tester</name>
			<phoneNumber>1-800-333-3333</phoneNumber>
			<uuid>385beb51-51ae-4ffe-8c05-3f35a9f99825</uuid>
			<website>www.testco.com</website>
		</company>
		<order>
			<editionCode>Standard</editionCode>
			<pricingDuration>MONTHLY</pricingDuration>  
			<freeTrial>
				<active>true</active>
			</freeTrial>
			<discountCode>FALL2020</discountCode> 
			<items>
			    <quantity>4</quantity>
			    <unit>USER</unit>
			</items>
		<order>
	</payload>
</event>