Example asynchronous subscription event notification flow

An example of an asynchronous event notification flow is shown below using a create subscription.

1. User Bob purchases application Gizmo123. This creates an asynchronous SUBSCRIPTION_ORDER event identified by URL https://www.acme-marketplace.com/api/integration/v1/events/12345.

2. AppDirect calls http://example.com/create?url=https%3A%2F%2Fwww.acme-marketplace.com%2Fapi%2Fintegration%2Fv1%2Fevents%2F12345.

3. Example.com issues a signed fetch to: https://www.acme-marketplace.com/api/integration/v1/events/12345\. If Example.com wants to receive the response from AppDirect in JSON format, they must add Accept: application/json in their HTTP GET request. If they want to receive the response from AppDirect in XML format they must add Accept: application/xml in their HTTP GET request. If they do not specify the content type an XML payload will be returned.

4. AppDirect sends a JSON or XML response to the vendor.

   • JSON

   {  
       "type": "SUBSCRIPTION_ORDER",  
       "marketplace": {  
         "baseUrl": "https://www.acme.com",  
         "partner": "APPDIRECT"  
       },  
       "creator": {  
         "address": {  
           "city": "Cambridge",  
           "country": "US",  
           "phone": "8582312882",  
           "state": "MA",  
           "street1": "123 Main St",  
           "zip": "02142"  
         },  
         "email": "testuser@testco.com",  
         "firstName": "Test",  
         "language": "en",  
         "lastName": "User",  
         "locale": "en-US",  
         "openId": "https://www.acme.com/openid/id/5d1f6f79-efff-411e-abe5-0b0a01610f04",  
         "uuid": "5d1f6f79-efff-411e-abe6-0b0a01610f04"  
       },  
       "payload": {  
         "company": {  
           "country": "US",  
           "name": "Test User",  
           "phoneNumber": "8582312882",  
           "uuid": "dc61a736-55b6-40fc-9b5a-6b17cbe6eb62"  
         },  
         "order": {  
           "editionCode": "0D5C06DB-FFEC-43a1-A6AF-EFB7E9B17905",  
           "pricingDuration": "MONTHLY",  
           "items": [{  
             "quantity": "3",  
             "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>  
                           <city>Cambridge</city>  
                           <country>US</country>  
                           <phone>8582312882</phone>  
                           <state>MA</state>  
                           <street1>123 Main St</street1>  
                           <zip>02142</zip>  
                   </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/5d1f6f79-efff-411e-abe5-0b0a01610f04</openId>  
                   <uuid>5d1f6f79-efff-411e-abe6-0b0a01610f04</uuid>  
           </creator>  
           <payload>  
                   <company>  
                           <country>US</country>  
                           <name>Test User</name>  
                           <phoneNumber>8582312882</phoneNumber>  
                           <uuid>dc61a736-55b6-40fc-9b5a-6b17cbe6eb62</uuid>  
                   </company>  
                   <order>  
                           <editionCode>0D5C06DB-FFEC-43a1-A6AF-EFB7E9B17905</editionCode>  
                           <pricingDuration>MONTHLY</pricingDuration>  
                           <items>  
                                   <quantity>3</quantity>  
                                   <unit>USER</unit>  
                           </items>  
                   </order>  
           </payload>  
   </event>

5. Example.com starts the creation a new account for Bob in its account system.

6. Example.com returns a JSON or XML response to the original HTTP request.

   • JSON

   Status Code: 202 Accepted  
   {  
    	"success":true  
   }  

   • XML

   Status Code: 202 Accepted  
   <result>  
       <success>true</success>  
   </result>

7. AppDirect puts the subscription into the PENDING_REMOTE_CREATION state. The user cannot do anything with the subscription at this time.

8. The vendor sends an HTTP POST to https://www.acme-marketplace.com/api/integration/v1/events/12345/result to indicate the account creation is complete. Note that the POST body is the same object as a synchronous event response.

• JSON

Status Code: 200 OK  
{  
	"accountIdentifier":"789xyz",  
 	"success":true  
}

• XML

Status Code: 200 OK  
<result>  
	<accountIdentifier>789xyz</success>  
    <success>true</success>  
</result>

Or in the event of an error, Example.com must return a valid error code, see Event error codes.

• JSON

Status Code: 409 Conflict  
{  
 	"success": "false"  
	"errorCode": "USER_ALREADY_EXISTS"  
	"message": "Optional message that the user already exists"  
}

• XML

Status Code: 409 Conflict  
<result>  
    <success>false</success>  
    <errorCode>USER_ALREADY_EXISTS</errorCode>  
    <message>Optional message that the user already exists</message>  
</result>