Provision Request Types

Provision Requests can come in many forms, and those forms are indicated by the type field.

The Provision Request Types

The type field may contain
- NetNew - Request to start new subscription for a given product
- Update - Request to update existing subscription
- Deprovision - Request to stop services for an existing trial or subscription
- TrialCreate - Request to start a new trial subscription for the given product.
- TrialConvert - Request to convert an existing trial subscription into a paid subscription
- ChangeProduct - Request to upgrade or downgrade current subscription from one product to another
- PartnerEnrollment - Optional request that allows the creation of a partner-level account

NetNew

NetNew requests represent a request for a new subscription. One company is allowed per provision request.

{
    "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
    "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
    "partnerName": "Example Partner Name",
    "partnerDomain": "partner.com",
    "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02",
    "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",
    "companyDomain": "company.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": "NetNew",
    "createdDate": "2024-04-08T19:54:03Z",
    "commitmentTermMonths": 12,
    "commitmentTermEndDate": "2025-04-08T19:54:03Z",
    "billingTerm": "Monthly"
}

Update

Update requests represent a change to an existing subscription, usually a quantity change. They have the same form as NetNew requests. When a subscription is updated through the Pax8 Marketplace, it will be assigned a new subscription ID but will remain within the same subscription tree.

{
    "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
    "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
    "partnerName": "Example Partner Name",
    "partnerDomain": "partner.com",
    "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02",
    "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",
    "companyDomain": "company.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": "Update",
    "createdDate": "2024-04-08T19:54:03Z",
    "commitmentTermMonths": 12,
    "commitmentTermEndDate": "2025-04-08T19:54:03Z",
    "billingTerm": "Monthly"
}

Deprovision

Deprovision requests represent a cancellation request for a subscription or trial. Unlike NetNew and Update requests, Deprovision requests do not have a quantity field.

{
    "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
    "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
    "partnerName": "Example Partner Name",
    "partnerDomain": "partner.com",
    "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02",
    "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",
    "companyDomain": "company.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",
    "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064",
    "type": "Deprovision",
    "createdDate": "2024-04-08T19:54:03Z",
    "commitmentTermMonths": 12,
    "commitmentTermEndDate": "2025-04-08T19:54:03Z",
    "billingTerm": "Monthly"
}

TrialCreate

TrialCreate requests represent a request to start a new trial subscription. These differ from a NetNew request in that TrialCreate requests contain two additional fields: a trialEndDate date field and a trialAutoConverts boolean field that are not included on any other request types.

When trialAutoConverts is true, you can expect to receive a TrialConvert provision request from Pax8 on the trialEndDate. When trialAutoConverts is false, Pax8 will not send any request on the trialEndDate and the trial should simply expire. Please note that our system automatically converts trials at 12:30 a.m. MST on the specified trial end date. To ensure a smooth transition, it is advisable to implement a buffer period of several hours before canceling the trial on that day.

Trials can be cancelled by partners in the Pax8 platform. When this happens, Pax8 will send a Deprovision request for that trial.

{
    "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
    "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
    "partnerName": "Example Partner Name",
    "partnerDomain": "partner.com",
    "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02",
    "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",
    "companyDomain": "company.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"
}

TrialConvert

A TrialConvert request represents a request to convert a trial into a paid subscription. They take the same form as a NetNew request

{
    "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
    "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
    "partnerName": "Example Partner Name",
    "partnerDomain": "partner.com",
    "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02",
    "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",
    "companyDomain": "company.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": "TrialConvert",
    "createdDate": "2024-04-08T19:54:03Z",
    "commitmentTermMonths": 12,
    "commitmentTermEndDate": "2025-04-08T19:54:03Z",
    "billingTerm": "Monthly"
}

ChangeProduct

A ChangeProduct request represents a request to upgrade or downgrade an existing subscription onto a new product. A ChangeProduct request has one additional field compared to a NetNew request called oldProductId in order to indicate the old product. The new product will be indicated by productId.

At this time, Pax8 does not support upgrading or downgrading partial quantities on an existing subscription. It's all or nothing.

{
    "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
    "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
    "partnerName": "Example Partner Name",
    "partnerDomain": "partner.com",
    "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02",
    "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",
    "companyDomain": "company.com",
    "companyAddress": {
        "street": "123 Company Ave.",
        "street2": "Unit c",
        "city": "Denver",
        "postcode": "80210",
        "country": "US",
        "stateOrProvince": "CO"
    },
    "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1",
    "oldProductId": "667a881b-31ef-4f95-8ebe-69bc95afa15e",
    "productName": "Product ABC",
    "quantity": 1,
    "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064",
    "type": "ChangeProduct",
    "createdDate": "2024-04-08T19:54:03Z",
    "commitmentTermMonths": 12,
    "commitmentTermEndDate": "2025-04-08T19:54:03Z",
    "billingTerm": "Monthly"
}

PartnerEnrollment

A PartnerEnrollment request represents a request to create a new partner account. Pax8 recommends to avoid using partner enrollments if you can, but if you require a separate process for partner accounts creation, they can be utilized to do so. A PartnerEnrollment request omits much of the data present in other provision requests, since only partner information will be relevant.

{
    "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
    "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
    "partnerName": "Example Partner Name",
    "partnerDomain": "partner.com",
    "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02",
    "partnerAddress": {
        "street": "123 Partner Ave.",
        "street2": "Unit b",
        "city": "Denver",
        "postcode": "80210",
        "country": "US",
        "stateOrProvince": "CO"
    },
    "type": "PartnerEnrollment",
    "createdDate": "2022-10-03T10:15:30Z"
}