Provisioning Integration Testing

Before you go live with Pax8, you can test your integration by creating simulated events and viewing test data.

Pax8 provides the ability to simulate an order coming from our system. You can make a POST request to our order events endpoint, and our system will act as though an order was just placed in our marketplace. Our system will create a ProvisionRequest, ProvisionDetail, and ProvisionAttemptwith some test data, as well as send a Provision Notification Webhook with the newly created objects to the endpoint configured in your webhook configuration.

Simulating orders using the order events endpoint is only possible with a separate set of credentials. When you first get credentials to use with the provisioning api, you will get two sets: one for live production requests, and another to use for simulating order events. You cannot use live production credentials to hit the order events endpoint; only the simulation credentials will work.

When you simulate an order, that persists some test data in the Pax8 system that has a lifespan of 7 days. This test data is siloed away from real production data. You can use the simulation credentials to query the provisioning api for the test data that has been created, as well as post ProvisionResults for any test ProvisionRequests that have been created. When using simulation credentials to query the api, you will not be able to see any live production data. Similarly, when using live production credentials to query the provisioning api, no simulated data will be returned.

Despite the facts that simulated and production data are siloed from each other, and that you need separate credentials to simulate orders, the simulation feature does not represent a true staging or sandbox environment. There is no Pax8 marketplace sandbox UI to view test data created by the simulations feature. Requests to simulate orders are still just made to the Pax8 production api; they just require separate credentials. Outbound Provision Webhook Notifications for simulated orders will still come from the Pax8 production api servers.

When using simulation credentials, you will have a different provisionerId in the Pax8 system than when you are using the live production credentials. Similarly, webhook configurations for simulated events are a separate entity from the webhook configurations made by live production credentials. This means that you will have to go through the exercise of configuring your webhook using simulation credentials to point at your testing system, and later you will need to do this again using the live production credentials and point the webhook configuration at your production system.

Credentials for generating simulated orders

Your Pax8 contact will give you testing credentials, which you can use in place of your live clientId and clientSecret.
Use these credentials whenever you trigger testing events or to access any data created as part of a simulation.
Live data is not visible to test credentials and test data is not visible to live credentials
You will have a different provisionerId when using production credentials compared to testing credentials
Test data only persists for 7 days
Provisioner and Webhook configurations when doing simulations are not subject to expiration, whereas most other data will expire after 7 days
- Check each specific simulation section for more information about data expiration

Simulated Order

You can simulate an incoming order from Pax8 to test your integration to our Provisioning API. A simulated order event provides you with data identical to what you would receive from a Provision Request.

Steps to simulating an order :

Obtain your testing credentials from your Pax8 Contact. These credentials will be used to gain access to the testing environment.
Register your webhook with our simulation environment using an auth token generated from the testing credentials provided by your pax8 contact. To set up the webhook, refer to our webhook configuration guide.
Use the following POST to simulate an order event.
Handle the Simulated Data. Once the request is made to the testing endpoint /provision-simulations/order-events, your testing webhook will receive the simulated order data. Your application should be designed to handle incoming webhook requests and process the data accordingly. You can also respond to an order event by sending a Provision Result to the simulated Provision Attempt.

All simulated webhooks have the isSimulation flag set to true.

POST  /provision-simulations/order-events

The Order Event Object

A simulated order event will create :

Provision Request - Contains placeholder data similar to what a real request
Provision Detail - You may specify the key/value pairs you'd like to receive
Provision Attempts - In simulation mode Provision Attempts are not retried when they are not acknowledged

{
    "isSimulation": true,
    "provisionRequest": {
        "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
        "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
        "partnerName": "Example Partner Name",
        "partnerDomain": "example.com",
        "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3aa9e9e02",
        "trialEndDate": "2022-12-03T10:15:30Z",
        "trialAutoConverts": "true",
        "partnerAddress": {
            "street": "123 Partner Ave.",
            "street2": "Unit b",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99",
        "companyName": "Example Company Name",
        "compayDomain": "example.com",
        "companyAddress": {
            "street": "123 Company Ave.",
            "street2": "Unit c",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1",
        "productName": "Product ABC",
        "quantity": 1,
        "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064",
        "type": "TrialCreate",
        "createdDate": "2024-04-08T19:54:03Z",
        "commitmentTermMonths": 12,
        "commitmentTermEndDate": "2025-04-08T19:54:03Z",
      	"billingTerm": "Monthly"
    },
    "provisionDetail": {
        "id": "8fcf68db-c30e-4f34-b773-bc1631cd1fef4",
        "provisionRequestId": "eb77429f-b313-4916-9bed-ccc1c373dff7",
        "details": {
            "key": "value",
            "key2": "value"
        }
    },
    "provisionAttempt": {
        "id": "3a11dbb9-226d-4788-86cd-4c6601da81e9",
        "provisionDetailId": "8fcf68db-c30e-4f34-b773-bc1631cd1fef4",
        "webhookId": "21110b5d-55b1-4cdf-82f7-2bcc9fef6c41",
        "status": "Acknowledged",
        "createdDate": "2022-10-03T10:15:30Z"
    }
}

Create a Provision Order Event

All fields are optional when you create an Order Event. Pax8 will default the value according to the following conventions:

All UUID fields: Random UUID
quantity: 1
partnerName: Example Partner Name
partnerDomain: example.com
partnerAddress: { street: 123 Partner Ave., street2: Unit b, city: Denver, postcode: 80210, country": US, stateOrProvince: CO }
companyDomain: example.com
companyAddress: { street: 123 Company Ave., street2: Unit c, city: Denver, postcode: 80210, country": US, stateOrProvince: CO }
type: NetNew
productName: Product ABC
companyName: Example Company Name
provisionDetail: {}
commitmentTermInMonths: Random integer between 1 and 36
billingTerm: Monthly

Keep in mind that if you want to simulate events that assume a prior action has happened, as is the case for
Deprovision or Update type provision requests, which assume a NetNew has happened sometime prior,
you will have to persist data in your system from the prior action, and then provide that data in the body of your request for the subsequent simulation request. Any field not included in the request body will be set to their defaults shown above.

Full Example

If you specify every single field in the order events body like the request below, all of the information will be echoed back to you in the webhook that Pax8 sends you.

POST /provision-simulations/order-events
{
    "provisionRequest": {
        "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
        "partnerName": "Example Partner Name",
        "partnerDomain": "example.com",
        "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3aa9e9e02",
        "partnerAddress": {
            "street": "123 Partner Ave.",
            "street2": "Unit b",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99",
        "companyName": "Example Company Name",
        "compayDomain": "example.com",
        "companyAddress": {
            "street": "123 Company Ave.",
            "street2": "Unit c",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1",
        "productName": "Product ABC",
        "quantity": 10,
        "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064",
        "type": "NetNew",
        "commitmentTermMonths": 12,
        "commitmentTermEndDate": "2025-04-08T19:54:03Z",
      	"billingTerm": "Monthly"
    },
    "provisionDetail": {
        "details": {
            "key": "value",
            "key2": "value2"
        }
    }
}

{
    "provisionRequest": {
        "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
        "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
        "partnerName": "Example Partner Name",
        "partnerDomain": "example.com",
        "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3aa9e9e02",
        "partnerAddress": {
            "street": "123 Partner Ave.",
            "street2": "Unit b",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99",
        "companyName": "Example Company Name",
        "compayDomain": "example.com",
        "companyAddress": {
            "street": "123 Company Ave.",
            "street2": "Unit c",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1",
        "productName": "Product ABC",
        "quantity": 10,
        "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064",
        "type": "NetNew",
        "createdDate": "2024-04-08T19:54:03Z",
        "commitmentTermMonths": 12,
        "commitmentTermEndDate": "2025-04-08T19:54:03Z",
      	"billingTerm": "Monthly"
    },
    "provisionDetail": {
        "id": "277e2819-7d16-4b71-8187-e5bf978843b4",
        "provisionRequestId": "eb77429f-b313-4916-9bed-ccc1c373dff7",
        "details": {
            "key": "value",
            "key2": "value2"
        },
        "createdDate": "2022-10-03T10:15:30Z"
    },
    "provisionAttempt": {
        "id": "3a11dbb9-226d-4788-86cd-4c6601da81e9",
        "provisionDetailId": "277e2819-7d16-4b71-8187-e5bf978843b4",
        "webhookId": "21110b5d-55b1-4cdf-82f7-2bcc9fef6c41",
        "status": "Acknowledged",
        "createdDate": "2022-10-03T10:15:30Z"
    }
}

Side Effect: Generated Webhook

POST /your-configured-webhook-url-and-path
{
    "isSimulation": true,
    "provisionRequest": {
        "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
        "partnerName": "Example Partner Name",
        "partnerDomain": "example.com",
        "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3aa9e9e02",
        "partnerAddress": {
            "street": "123 Partner Ave.",
            "street2": "Unit b",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99",
        "companyName": "Example Company Name",
        "compayDomain": "example.com",
        "companyAddress": {
            "street": "123 Company Ave.",
            "street2": "Unit c",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1",
        "productName": "Product ABC",
        "quantity": 10,
        "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064",
        "type": "NetNew",
        "createdDate": "2024-04-08T19:54:03Z",
        "commitmentTermMonths": 12,
        "commitmentTermEndDate": "2025-04-08T19:54:03Z",
      	"billingTerm": "Monthly"
    },
    "provisionDetail": {
        "id": "277e2819-7d16-4b71-8187-e5bf978843b4",
        "provisionRequestId": "eb77429f-b313-4916-9bed-ccc1c373dff7",
        "details": {
            "key": "value",
            "key2": "value2"
        },
        "createdDate": "2022-10-03T10:15:30Z"
    },
    "provisionAttempt": {
        "id": "3a11dbb9-226d-4788-86cd-4c6601da81e9",
        "provisionDetailId": "277e2819-7d16-4b71-8187-e5bf978843b4",
        "webhookId": "21110b5d-55b1-4cdf-82f7-2bcc9fef6c41",
        "status": "Acknowledged",
        "createdDate": "2022-10-03T10:15:30Z"
    }
}

Empty or Partial Example

Since every field in the payload to the order events page is optional, it is possible to POST to the order events endpoint with an empty request body, and Pax8 will auto generate values for anything that was absent. For example, if you make a request like the one below:

POST /provision-simulations/order-events
{}

You would still receive a full response from the order events endpoint, and you would still receive a full webhook, like in the previous example, only all the values will have been generated by the Pax8 system according to the defaults listed above these examples.

You can also omit or include any number of the fields from the body. If, for example, you only care to to test that your system can ingest certain provision detail keys called adminEmail and adminPhone, you could send an order events request that looks like this:

POST /provision-simulations/order-events
{
  	"provisionDetail": {
        "details": {
            "adminEmail": "[email protected]",
            "adminPhone": "800-555-7777"
        }
    }
}

In this case, the webhook you receive from Pax8 will have auto generated default values for everything except these provision details. It might look like this:

{
    "provisionRequest": {
        "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
        "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
        "partnerName": "Example Partner Name",
        "partnerDomain": "example.com",
        "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3aa9e9e02",
        "partnerAddress": {
            "street": "123 Partner Ave.",
            "street2": "Unit b",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "companyId": "0b4d7ee2-8335-433e-8196-a65b962b9f99",
        "companyName": "Example Company Name",
        "compayDomain": "example.com",
        "companyAddress": {
            "street": "123 Company Ave.",
            "street2": "Unit c",
            "city": "Denver",
            "postcode": "80210",
            "country": "US",
            "stateOrProvince": "CO"
        },
        "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1",
        "productName": "Product ABC",
        "quantity": 10,
        "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064",
        "type": "NetNew",
        "createdDate": "2024-04-08T19:54:03Z",
        "commitmentTermMonths": 12,
        "commitmentTermEndDate": "2025-04-08T19:54:03Z",
      	"billingTerm": "Monthly"
    },
    "provisionDetail": {
        "id": "277e2819-7d16-4b71-8187-e5bf978843b4",
        "provisionRequestId": "eb77429f-b313-4916-9bed-ccc1c373dff7",
        "details": {
            "adminEmail": "[email protected]",
            "adminPhone": "800-555-7777"
        },
        "createdDate": "2022-10-03T10:15:30Z"
    },
    "provisionAttempt": {
        "id": "3a11dbb9-226d-4788-86cd-4c6601da81e9",
        "provisionDetailId": "277e2819-7d16-4b71-8187-e5bf978843b4",
        "webhookId": "21110b5d-55b1-4cdf-82f7-2bcc9fef6c41",
        "status": "Acknowledged",
        "createdDate": "2022-10-03T10:15:30Z"
    }
}

Notice how all of the fields have their default values except in the details map, where the details you specified in the initial request are echoed back just as you entered them.

Data Expiration

The following simulation resources will expire after 1 week:

Provision Requests
Provision Detail
Provision Attempts
Provision Results

The following simulation resources do not expire:

Provisioners
Webhooks