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 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 simulation credentials, which you can use in place of your production clientId and clientSecret.
  • Use these simulation credentials whenever you trigger testing events or to access any data created as part of a simulation.
  • Live data is not visible when using simulation credentials and test data is not visible to production credentials
  • You will have a different provisionerId when using production credentials compared to simulation credentials
  • Test data only persists for 7 days. Please see the Data Expiration section for more info.

Simulating an Order

You can simulate an incoming order from Pax8 to test your integration to our Provisioning API. Simulating an order event provides you with data in the same form as what you would receive from a production Provision Notification.

Steps to simulating an order:

  1. Obtain your simulation credentials from your Pax8 Contact. These credentials will be used to gain access to the simulation functionality.
  2. Configure your webhook within our simulation environment using an authorization token generated from the simulation credentials provided. To configure your webhook, refer to our webhook configuration guide.
  3. POST to the Order Events endpoint to simulate an order event.
  4. Handle the Simulated Data. Once the request is made to the testing endpoint /provision-simulations/order-events, your testing webhook endpoint will receive the simulated order data.
  5. Your application must be designed to handle incoming Provision Notifications, process the data accordingly, and send a Provision Result to the Pax8 system.

All simulated Provision Notifications have the isSimulation flag set to true.

Endpoints

Create Order Event

The Order Event Object

A simulated order event will create :

  • Provision Request - Contains placeholder data similar to 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",
        "commitment": {
            "term": {
                "months": 12,
                "endDate": "2025-04-08T19:54:03Z"
            },
            "volume": {
                "minAmount": 1,
                "maxAmount": 10,
                "unitOfMeasure": "Users",
                "months": 1
            }
        },
        "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:

Field NameDefault Value
All UUID fields *Random UUID
quantity1
partnerNameExample Partner Name
partnerDomainexample.com
partnerAddress{
"street": "123 Partner Ave.",
"street2": "Unit b",
"city": "Denver",
"postcode": "80210",
"country": "US",
"stateOrProvince": "CO"
}
companyDomainexample.com
companyAddress{
"street": "123 Company Ave.",
"street2": "Unit c",
"city": "Denver",
"postcode": "80210",
"country": "US",
"stateOrProvince": "CO"
}
typeNetNew
productNameProduct ABC
companyNameExample Company Name
provisionDetail{}
commitmentTermMonthsRandom integer between 1 and 36
commitmentTermEndDateNow + commitmentTermMonths
commitment.volume.minAmount1
commitment.volume.maxAmount10
commitment.volume.unitOfMeasureUsers
commitment.volume.months1
commitment.term.endDateNow + commitment.term.months
commitment.term.monthsRandom integer between 1 and 36
billingTermMonthly
trialEndDate**Now
trialAutoConverts **true

* oldProductId only appears for ChangeProduct Provision Request types

** Only appears forTrialCreate Provision Request types

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.

Data Expiration

The following simulation resources will expire after 1 week:

  • Provision Requests
  • Provision Detail
  • Provision Attempts
  • Provision Results
  • Webhooks - Your latest webhook will never expire, but all others expire after 1 week

The following simulation resources do not expire:

  • Provisioners

What’s Next

Visit the Request and Response Example and Scenarios Pages