Guides

Provision Request

Suggest Edits

Overview

A ProvisionRequest contains basic information about a purchase which cannot change. This includes things such as partnerId, partnerAddress, companyAddress, productId, etc

For collecting non-static information such as an admin email address or phone number, you should refer the Provision Details section of our guide which contains information a user entered at checkout.

Endpoints

List All Provision Requests

Get A Provision Request

List All Unfulfilled Provision Requests

The Provision Request Object

{
    "id": "eb77429f-b313-4916-9bed-ccc1c373dff7",
    "partnerId": "2bb54fa0-21ed-481e-8627-26e3ee9e9e02",
    "partnerName": "Example Partner Name",
    "partnerDomain": "partner.com",
    "partnerAddress": {
        "street": "123 Partner Avenue",
        "street2": "Unit A",
        "city": "Denver",
        "postcode": "80210",
        "country": "US",
        "stateOrProvince": "Colorado"
    },
    "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02",
    "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "companyName": "Example Company Name",
    "companyDomain": "company.com",
    "companyAddress": {
        "street": "123 Company Avenue",
        "street2": "Unit A",
        "city": "Denver",
        "postcode": "80210",
        "country": "US",
        "stateOrProvince": "CO"
    },
    "productId": "ada2a119-9892-4a91-8bae-b0bb3b0e81a1",
    "oldProductId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "productName": "Product ABC",
    "quantity": 0,
    "subscriptionId": "475df9f9-2558-4f91-903b-5130dad67064",
    "type": "NetNew",
    "createdDate": "2025-07-09T19:52:34.641303Z",
    "trialEndDate": "2025-08-01T19:52:34.641303Z",
    "trialAutoConverts": true,
    "commitmentTermEndDate": "2026-07-31T19:50:02Z",
    "commitmentTermMonths": 12,
    "commitment": {
        "term": {
            "months": 12,
            "endDate": "2026-07-31T19:50:02Z"
        },
        "volume": {
            "minAmount": 250.0000,
            "maxAmount": 500.0000,
            "unitOfMeasure": "USD",
            "months": 1
        }
    },
    "billingTerm": "Monthly"
}

Null fields will be omitted.

Additional Information

Commitments

Terms

If you require partners to agree to a set commitment term when buying a product, you can have that configured in Pax8. For example, if you require partners to buy a full year of service at a time, Pax8 can configure a 12 month commitment term for your products.

In this example, any ProvisionRequest for your product would include a commitment.term.months field which would be 12, and a commitment.term.endDate field, which would contain a date 12 months in the future from the purchase date.

Volume

In addition to time only based commitment terms, Pax8 supports volume commitments that specify minimum and (optionally) maximum volume requirements for subscriptions for a certain unit and length of time. Volume commitments work alongside time-based commitments to provide more flexible commitment options.

Note: Volume commitments are always paired with time-based commitments. Volume-only commitments are not currently available.

Backward Compatibility

For backward compatibility, provision requests continue to include the legacy commitment fields:

  • commitmentTermMonths - Duration in months (deprecated, use commitment.term.months)
  • commitmentTermEndDate - End date (deprecated, use commitment.term.endDate)

Billing Terms

All provision requests will contain a billingTerm whose value represents the frequency at which the product is billed. The possible values for billingTerm are as follows:

  • One-Time
  • Monthly
  • Annual
  • 2 Year
  • 3 Year
  • Trial
  • Activation

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
    • Renewal - Request to renew subscription at the end of it's current commitment term

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",
    "commitment": {
        "term": {
            "months": 12,
            "endDate": "2025-04-08T19:54:03Z"
        },
        "volume": {
            "minAmount": 1,
            "maxAmount": 10,
            "unitOfMeasure": "Users",
            "months": 1
        }
    },
    "billingTerm": "Monthly"
}

Update

Update requests represent a change to an existing subscription, usually a quantity change. They have the same form as NetNew requests.

{
    "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",
    "commitment": {
        "term": {
            "months": 12,
            "endDate": "2025-04-08T19:54:03Z"
        },
        "volume": {
            "minAmount": 1,
            "maxAmount": 10,
            "unitOfMeasure": "Users",
            "months": 1
        }
    },
    "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",
    "commitment": {
        "term": {
            "months": 12,
            "endDate": "2025-04-08T19:54:03Z"
        },
        "volume": {
            "minAmount": 1,
            "maxAmount": 10,
            "unitOfMeasure": "Users",
            "months": 1
        }
    },
    "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",
    "commitment": {
        "term": {
            "months": 12,
            "endDate": "2025-04-08T19:54:03Z"
        },
        "volume": {
            "minAmount": 1,
            "maxAmount": 10,
            "unitOfMeasure": "Users",
            "months": 1
        }
    },
    "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",
    "commitment": {
        "term": {
            "months": 12,
            "endDate": "2025-04-08T19:54:03Z"
        },
        "volume": {
            "minAmount": 1,
            "maxAmount": 10,
            "unitOfMeasure": "Users",
            "months": 1
        }
    },
    "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",
    "commitment": {
        "term": {
            "months": 12,
            "endDate": "2025-04-08T19:54:03Z"
        },
        "volume": {
            "minAmount": 1,
            "maxAmount": 10,
            "unitOfMeasure": "Users",
            "months": 1
        }
    },
    "billingTerm": "Monthly"
}

Renewal

A Renewal request represents a request to confirm the continuation of an existing subscription for another commitment term. Term duration is determined – and, when applicable, selected - within the Pax8 Marketplace. The duration of the term will be passed in the request based on the product's renewal terms.

Unlike an Update request, which is typically used for quantity changes, a Renewal request specifically handles the transition from one commitment term to the next while maintaining the same product and configuration.

Renewal requests will be sent upon every renewal event and cannot be disabled. This will be configured by Pax8 on to fit your needs and will be communicated with you beforehand. Not all vendors require renewal support.

The new renewal commitment date posted in the Renewal request will be the source of truth for billing and future renewal events. Even if no additional action is required on your end, you are expected to respond to every 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": "Renewal",
    "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"
}

PartnerEnrollment

A PartnerEnrollment request represents a request to create a new partner account. Pax8 recommends to ignore the PartnerEnrollment type. Creating a Partner account upon receiving a NetNew or TrialCreate provision is typically sufficient.

If you require that a partner-level account is created before the partner can even create an order. This type 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",
    "partnerAddress": {
        "street": "123 Partner Ave.",
        "street2": "Unit b",
        "city": "Denver",
        "postcode": "80210",
        "country": "US",
        "stateOrProvince": "CO"
    },
    "partnerEnrollmentId": "7bb64fa0-21ed-481e-8627-26e3gg9e9e02",
    "type": "PartnerEnrollment",
    "createdDate": "2022-10-03T10:15:30Z"
}

Updated 10 days ago