Create subscription

End users can purchase products (create subscriptions) through the marketplace. A new subscription is typically created in either FREE_TRIAL (when trial is enabled for the selected edition) or ACTIVE state. Subscriptions can be created from the AppDirect user interface or via the AppDirect subscription APIs.

The create subscription event notification (SUBSCRIPTION_ORDER) is sent when an end user purchases a subscription. To allow this flow, configure a subscription create notification URL (for example, https://example.com/create) on the product's Edit integration page.

Only user-adjustable order details are included in this event (for example, edition and quantity). Metered usage and included items are handled by other event types.

End-to-end flow (create subscription)

1. A customer orders your app in the marketplace.
2. AppDirect creates a SUBSCRIPTION_ORDER event and stores it at an eventUrl (for example, https://www.acme-marketplace.com/api/integration/v1/events/<event-uuid>).
3. AppDirect sends an HTTP GET request to your create endpoint, including eventUrl as a query parameter.
4. Your service validates the inbound notification request using your configured integration security. See Validate outbound event notifications.
5. Your service reads eventUrl from the query string and sends an HTTP GET request to that URL to fetch the full event payload.
   • Use Accept: application/json to request JSON.
   • Use Accept: application/xml to request XML.
   • If no Accept header is sent, XML is returned by default.
6. Your service provisions the subscription in your system and responds to the original AppDirect request with a success or error result.

Event payload highlights

The SUBSCRIPTION_ORDER event includes:

• type: Event type (SUBSCRIPTION_ORDER).
• marketplace: Marketplace context (baseUrl, partner).
• creator: User who initiated the order.
• payload.order: Edition, quantity, unit, pricing duration, and trial details (when applicable).
• payload.company: Ordering company details.
• payload.order.discountCode: Optional discount code, when present.

Response requirements

Your create endpoint must return a result payload in JSON or XML.

Required and optional fields:

• success (required): true or false.
• accountIdentifier (required on success): Stable identifier for the created account/subscription in your system.
• errorCode (required on failure): Must be one of the supported Event error codes.
• message (optional): Human-readable details for logs and troubleshooting.

Use HTTP status codes that match outcome semantics (for example, 200 on success, 4xx for business validation failures).

Create vs assign events

Creating a subscription and assigning users are separate operations in AppDirect:

• SUBSCRIPTION_ORDER creates the subscription/account.
• User assignment is handled by assignment-related events later in the lifecycle.

Even if your product usually has one user per subscription, implement both flows to keep marketplace behavior consistent and avoid provisioning gaps.

Integration testing guidance

Integration tests can execute the real marketplace flow, not just a local simulation.

Before running live integration tests, confirm:

• Your endpoint is reachable from the marketplace.
• You understand the test will trigger real create flow behavior.
• Your team is prepared to cancel test subscriptions afterward when needed.
• Downstream automation (emails, provisioning, billing hooks) is safe for test runs.

Recommended approach:

1. Run local or container-based tests first (for example, Dockerized tests that mock event payloads and callback behavior).
2. Run live marketplace integration tests after local validation passes.

Example SUBSCRIPTION_ORDER event

JSON

{
  "type": "SUBSCRIPTION_ORDER",
  "marketplace": {
    "baseUrl": "https://www.acme.com",
    "partner": "APPDIRECT"
  },
  "creator": {
    "email": "testuser@testco.com",
    "firstName": "Test",
    "lastName": "User",
    "language": "en",
    "locale": "en-US",
    "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>
    <email>testuser@testco.com</email>
    <firstName>Test</firstName>
    <lastName>User</lastName>
    <language>en</language>
    <locale>en-US</locale>
    <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>
      <item>
        <quantity>4</quantity>
        <unit>USER</unit>
      </item>
    </order>
  </payload>
</event>