MSP billing API

MSP configuration is the floor. Managed-client configuration and plan routes are nested under the client. Promo code responses omit the redemption secret.

On this page

• Who pays
• MSP rates floor
• Managed-client configuration
• Managed-client plan
• Plan changes
• Renewal and top-up
• Promotional grants

Endpoints

Update who pays

PUT /api/msps/:mspId/clients/:clientId/configurations sets billingTo to client or msp. Rates below the MSP floor are raised, not rejected.

curl -X PUT "https://api.requestrocket.com/api/msps/:mspId/clients/:clientId/configurations" \
  -H "Authorization: u-your-token" \
  -H "Content-Type: application/json" \
  -d '{
  "billingTo": "client"
}'

import axios from "axios";

const response = await axios.request({
  method: "PUT",
  url: "https://api.requestrocket.com/api/msps/:mspId/clients/:clientId/configurations",
  headers: {
    "Authorization": "u-your-token",
    "Content-Type": "application/json",
  },
  data: {
  "billingTo": "client"
}
});

console.log(response.status, response.data);

import requests

response = requests.request(
    "PUT",
    "https://api.requestrocket.com/api/msps/:mspId/clients/:clientId/configurations",
    headers={
        "Authorization": "u-your-token",
        "Content-Type": "application/json",
    },
    data="{\n  \"billingTo\": \"client\"\n}"
)
print(response.status_code, response.json())

package main

import (
    "fmt"
    "io"
    "net/http"
    "strings"
)

func main() {
    payload := strings.NewReader(`{
  "billingTo": "client"
}`)
    req, _ := http.NewRequest("PUT", "https://api.requestrocket.com/api/msps/:mspId/clients/:clientId/configurations", payload)
    req.Header.Set("Authorization", "u-your-token")
    req.Header.Set("Content-Type", "application/json")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(resp.StatusCode, string(body))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.requestrocket.com/api/msps/:mspId/clients/:clientId/configurations"))
            .method("PUT", HttpRequest.BodyPublishers.ofString("{\n  \"billingTo\": \"client\"\n}"))
            .header("Authorization", "u-your-token")
            .header("Content-Type", "application/json")
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

{
  "configuration": {
    "billingTo": "client",
    "billingType": "stripe",
    "billingStatus": "active"
  },
  "message": "Configuration updated successfully"
}

{
  "message": "Input failed data validation",
  "errors": [
    "/billingTo: must be equal to one of the allowed values"
  ]
}

{
  "message": "Unauthorized"
}

{
  "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy"
}

{
  "message": "method / endpoint not supported"
}

All fields are optional. Omit a field to leave it unchanged. Rates below the MSP floor are raised, not rejected.

Request body

Plan fields, promoOverrides, promotionalCodes, billingStatus, and sharing are not changed by this call. Redeem a code on the promocodes route. Change the plan on the plan route.

Returns the saved configuration. The balance in budget.current is left as stored.

Response

Read the MSP rates floor

GET /api/msps/:mspId/configurations returns the MSP billing type and the rates floor.

Query parameters

None.

Response

Update the MSP rates floor

PUT /api/msps/:mspId/configurations updates the MSP's own configuration. All fields are optional. Omit a field to leave it unchanged. Rates and billing type are applied for a system admin. Raising the floor re-clamps managed organisations whose stored rates sit below the new floor. Client balances are not overwritten.

Request body

promotionalCodes is not writable here. Redeem a code on the managed-client promocodes route, or on POST /api/msps/:mspId/promocodes for the MSP itself.

Returns the saved configuration. When the new floor raises one or more managed organisations, the response also includes clientsReclamped.

Response

Read a managed client's configuration

GET /api/msps/:mspId/clients/:clientId/configurations returns the organisation configuration, including who pays, rates, and the plan fields stored on the configuration.

Query parameters

None.

Response

Read a managed client's plan

GET /api/msps/:mspId/clients/:clientId/plan returns the current plan, the features it includes, and the prices after the MSP plan multiplier.

Query parameters

None.

Response

Request a plan change

PUT /api/msps/:mspId/clients/:clientId/plan requests an upgrade, schedules a downgrade, or cancels a pending change by sending the current tier. The MSP can change the plan when billingTo is msp.

Request body

Returns the plan after the request. An upgrade on Stripe billing also returns invoiceId and leaves the tier unchanged until the invoice is paid. A downgrade stays on the current tier until planPendingEffectiveAt. Sending the current tier with nothing pending returns the plan unchanged.

Response

Renew a lapsed plan

POST /api/msps/:mspId/clients/:clientId/plan/renew renews a plan that is expired or payment-failed. This call has no request body. The MSP can renew when billingTo is msp.

Returns the plan. Stripe billing also returns invoiceId and waits for payment. Invoice and marketplace billing renew immediately.

Response

Request a manual top-up

POST /api/msps/:mspId/clients/:clientId/plan/topup submits a top-up for an organisation whose topUpMethod is manual. This call has no request body. The MSP can submit it when billingTo is msp.

Returns a confirmation. The call does not include a new balance.

Response

Redeem a code for a managed client

POST /api/msps/:mspId/clients/:clientId/promocodes redeems a promotional code for the organisation. The response returns the grant name, not the redemption secret.

Request body

Returns the grant that matched, whether it was already applied, and the full grant list.

Response

Shared status codes, the 5.5 MB cap, and plan rate limits are on Platform limits.

Next