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 ProvisionAttempt
with 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
andclientSecret
. - 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:
- Obtain your simulation credentials from your Pax8 Contact. These credentials will be used to gain access to the simulation functionality.
- 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.
- POST to the Order Events endpoint 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 endpoint will receive the simulated order data. - 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 totrue
.
Endpoints
Create Order Event
- Create a Simulation Order Event
- POST /provision-simulations/order-events
The Order Event Object
A simulated order event will create :
Provision Request
- Contains placeholder data similar to a real requestProvision Detail
- You may specify the key/value pairs you'd like to receiveProvision Attempts
- In simulation modeProvision 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 Name | Default Value |
---|---|
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 | {} |
commitmentTermMonths | Random integer between 1 and 36 |
commitmentTermEndDate | Now + commitmentTermMonths |
commitment.volume.minAmount | 1 |
commitment.volume.maxAmount | 10 |
commitment.volume.unitOfMeasure | Users |
commitment.volume.months | 1 |
commitment.term.endDate | Now + commitment.term.months |
commitment.term.months | Random integer between 1 and 36 |
billingTerm | Monthly |
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
Updated 12 days ago
Visit the Request and Response Example and Scenarios Pages