🚧
Notice
Self-service APIs are under active development and are not subject to our breaking change policy.

Overview

MonetizeNow Contract Management APIs allow your customers to perform changes to the products they have purchased, which we call Contract Management.

Regardless of if your customers have signed up for service from your website or were sold service from your enterprise sales channel, you can use the Contract Management APIs to programmatically make changes to your customers contracts.

Our Self-Service APIs are designed to make it easy to programmatically interact with your customers products and services and are optimized for common self-service use-cases and aer easy to integrate with.
For complex use-cases, refer to our Contract and Quote APIs where you can perform any action that is available in the MonetizeNow UI.

All of our self-service APIs operate contracts and will create amendment quotes in the background to track the change just like any other amendment.

You have the option to indicate if you would like Approval Rules to be evaluated for self-service amendment quotes. This allows you to have the change saved in a pending state so someone can review the process. This is useful for certain changes, such as cancellation.

Validation Rules are never evaluated for self-service amendment quotes.

Contract Management API Flows

Our Contract Management APIs support the following use-cases:

Perform a quantity changes for an offering
Change rates for an offering
Change an offering to a different offering
Remove an offering
Cancel the entire contract

All API operations operate on a unified endpoint and are differentiated based on the HTTP method and the request payload.

POST /api/selfService/contract

Quickstart

Here are examples of two very common operations:

Add more seats effective today
Change from Monthly to Annual effective on the next bill cycle

POST /api/selfService/contract

{
  "action": "QUANTITY_CHANGE",
  "contractId": "ctrct_xNE4v9dkjXjorYAM",
  "payload": {
    "offerings": [
      {
        "offeringId": "offer_fYyrKcVaJRgVN7jg",
        "products": [
          {
            "productId": "prod_sVd2qS8nXCP7X1Uf",
            "quantity": 11
          }
        ]
      }
    ]
  }
}

{
  "action": "RATE_CHANGE",
  "contractId": "ctrct_xNE4v9dkjXjorYAM",
  "relativeEffectiveDate": "NEXT_BILL_CYCLE",
  "payload": {
    "offerings": [
      {
        "offeringId": "offer_fYyrKcVaJRgVN7jg",
        "rateId": "rate_Y6FfLGv3Ycipd1cw",
      }
    ]
  }
}

Request Data Model

Property	Data Type	Description
action	QUANTITY_CHANGE RATE_CHANGE OFFERING_CHANGE ADD_OFFERING REMOVE_OFFERING CANCELLATION	The action to perform against the contract
contractId	String	Id of the contract to perform the action on
effectiveDate	Date	Effective date or relativeEffectiveDate If neither is provided, the change will be effective today The effective date must be in the future If relativeEffectiveDate is provided, effectiveDate will be ignored If you make a change prior to the next bill cycle, there may be a prorated charge
relativeEffectiveDate	NEXT_BILL_CYCLE	Effective date or relativeEffectiveDate If neither is provided, the change will be effective today The effective date must be in the future If relativeEffectiveDate is provided, effectiveDate will be ignored If you make a change prior to the next bill cycle, there may be a prorated charge
payload	Varies based on action	Depending on the action, the payload structure will vary, refer to the data model for the type structure for each action

type ContractOperation =
  | QuantityOperation
  | RateChangeOperation
  | OfferingChangeOperation
  | AddOfferingOperation
  | RemoveOfferingOperation
  | CancellationOperation;

interface ContractOperationBase {
  /**
   * Action to perform
   */
  action:
    | "QUANTITY_CHANGE"
    | "RATE_CHANGE"
    | "OFFERING_CHANGE"
    | "ADD_OFFERING"
    | "REMOVE_OFFERING"
    | "CANCELLATION";
  /**
   * Contract Id to operate on
   */
  contractId: string;
  /**
   * Effective date or relativeEffectiveDate
   * If neither is provided, the change will be effective today
   *
   * The effective date must be in the future
   * If relativeEffectiveDate is provided, effectiveDate will be ignored
   *
   * If you make a change prior to the next bill cycle, there may be a prorated charge
   */
  effectiveDate?: Date;
  relativeEffectiveDate?: "NEXT_BILL_CYCLE";
}

interface QuantityOperation extends ContractOperationBase {
  action: "QUANTITY_CHANGE";
  payload: {
    offerings: {
      /**
       * Id of the offering to modify
       */
      offeringId: string;
      /**
       * New quantity for specified product
       * Any products not included will not have their quantity modified
       * The quantity provided will be the new total quantity
       */
      products: {
        productId: string;
        quantity: number;
      }[];
    }[];
  };
}

interface RateChangeOperation extends ContractOperationBase {
  action: "RATE_CHANGE";
  payload: {
    offerings: {
      /**
       * Id of the offering to modify
       */
      offeringId: string;
      /**
       * New rateId for specified product
       */
      rateId: string;
      /**
       * Optional products, only required if quantity is also being adjusted
       */
      products?: {
        productId: string;
        quantity: number;
      }[];
    }[];
  };
}

interface OfferingChangeOperation extends ContractOperationBase {
  /**
   * This will delete the old offering and replace it with the new offering
   */
  action: "OFFERING_CHANGE";
  payload: {
    offerings: {
      /**
       * Id of the offering to modify
       */
      offeringId: string;
      /**
       * Id of the new offering to replace the old offering
       */
      newOfferingId: string;
      /**
       * quantity for specified product
       * Any products not included will be set to 1 or the minimum lower bound based on the rate configuration
       */
      products: {
        productId: string;
        quantity: number;
      }[];
    }[];
  };
}

interface AddOfferingOperation extends ContractOperationBase {
  action: "ADD_OFFERING";
  payload: {
    offerings: {
      /**
       * Id of the offering being added
       */
      offeringId: string;
      /**
       * quantity for specified product
       * Any products not included will be set to 1 or the minimum lower bound based on the rate configuration
       */
      products: {
        productId: string;
        quantity: number;
      }[];
    }[];
  };
}

interface RemoveOfferingOperation extends ContractOperationBase {
  /**
   * If all offerings are removed, this will result in a contract cancellation
   */
  action: "REMOVE_OFFERING";
  payload: {
    offerings: {
      /**
       * Id of the offering being removed
       */
      offeringId: string;
    }[];
  };
}

interface CancellationOperation extends ContractOperationBase {
  action: "CANCELLATION";
  /**
   * There are no additional fields for a cancellation
   */
  payload: null;
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "ContractOperationBase": {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "enum": ["QUANTITY_CHANGE", "RATE_CHANGE", "OFFERING_CHANGE", "ADD_OFFERING", "REMOVE_OFFERING", "CANCELLATION"]
        },
        "contractId": {
          "type": "string"
        },
        "effectiveDate": {
          "type": "string",
          "format": "date-time"
        },
        "relativeEffectiveDate": {
          "type": "string",
          "enum": ["NEXT_BILL_CYCLE"]
        }
      },
      "required": ["action", "contractId"]
    },
    "QuantityOperation": {
      "allOf": [
        {
          "$ref": "#/definitions/ContractOperationBase"
        },
        {
          "type": "object",
          "properties": {
            "action": {
              "type": "string",
              "enum": ["QUANTITY_CHANGE"]
            },
            "payload": {
              "type": "object",
              "properties": {
                "offerings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "offeringId": {
                        "type": "string"
                      },
                      "products": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "productId": {
                              "type": "string"
                            },
                            "quantity": {
                              "type": "number"
                            }
                          },
                          "required": ["productId", "quantity"]
                        }
                      }
                    },
                    "required": ["offeringId", "products"]
                  }
                }
              },
              "required": ["offerings"]
            }
          },
          "required": ["action", "payload"]
        }
      ]
    },
    "RateChangeOperation": {
      "allOf": [
        {
          "$ref": "#/definitions/ContractOperationBase"
        },
        {
          "type": "object",
          "properties": {
            "action": {
              "type": "string",
              "enum": ["RATE_CHANGE"]
            },
            "payload": {
              "type": "object",
              "properties": {
                "offerings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "offeringId": {
                        "type": "string"
                      },
                      "rateId": {
                        "type": "string"
                      }
                    },
                    "required": ["offeringId", "rateId"]
                  }
                }
              },
              "required": ["offerings"]
            }
          },
          "required": ["action", "payload"]
        }
      ]
    },
    "OfferingChangeOperation": {
      "allOf": [
        {
          "$ref": "#/definitions/ContractOperationBase"
        },
        {
          "type": "object",
          "properties": {
            "action": {
              "type": "string",
              "enum": ["OFFERING_CHANGE"]
            },
            "payload": {
              "type": "object",
              "properties": {
                "offerings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "offeringId": {
                        "type": "string"
                      },
                      "newOfferingId": {
                        "type": "string"
                      },
                      "products": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "productId": {
                              "type": "string"
                            },
                            "quantity": {
                              "type": "number"
                            }
                          },
                          "required": ["productId", "quantity"]
                        }
                      }
                    },
                    "required": ["offeringId", "newOfferingId", "products"]
                  }
                }
              },
              "required": ["offerings"]
            }
          },
          "required": ["action", "payload"]
        }
      ]
    },
    "AddOfferingOperation": {
      "allOf": [
        {
          "$ref": "#/definitions/ContractOperationBase"
        },
        {
          "type": "object",
          "properties": {
            "action": {
              "type": "string",
              "enum": ["ADD_OFFERING"]
            },
            "payload": {
              "type": "object",
              "properties": {
                "offerings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "offeringId": {
                        "type": "string"
                      },
                      "products": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "productId": {
                              "type": "string"
                            },
                            "quantity": {
                              "type": "number"
                            }
                          },
                          "required": ["productId", "quantity"]
                        }
                      }
                    },
                    "required": ["offeringId", "products"]
                  }
                }
              },
              "required": ["offerings"]
            }
          },
          "required": ["action", "payload"]
        }
      ]
    },
    "RemoveOfferingOperation": {
      "allOf": [
        {
          "$ref": "#/definitions/ContractOperationBase"
        },
        {
          "type": "object",
          "properties": {
            "action": {
              "type": "string",
              "enum": ["REMOVE_OFFERING"]
            },
            "payload": {
              "type": "object",
              "properties": {
                "offerings": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "offeringId": {
                        "type": "string"
                      }
                    },
                    "required": ["offeringId"]
                  }
                }
              },
              "required": ["offerings"]
            }
          },
          "required": ["action", "payload"]
        }
      ]
    },
    "CancellationOperation": {
      "allOf": [
        {
          "$ref": "#/definitions/ContractOperationBase"
        },
        {
          "type": "object",
          "properties": {
            "action": {
              "type": "string",
              "enum": ["CANCELLATION"]
            },
            "payload": {
              "type": "null"
            }
          },
          "required": ["action", "payload"]
        }
      ]
    }
  },
  "oneOf": [
    { "$ref": "#/definitions/QuantityOperation" },
    { "$ref": "#/definitions/RateChangeOperation" },
    { "$ref": "#/definitions/OfferingChangeOperation" },
    { "$ref": "#/definitions/AddOfferingOperation" },
    { "$ref": "#/definitions/RemoveOfferingOperation" },
    { "$ref": "#/definitions/CancellationOperation" }
  ]
}

Response Data Model

The response will include a status of the request along with the related quote, contract, and optionally the invoice.

If the response was not successful, then an error message will be returned.

interface ContractOperationResponse {
  action:
    | "QUANTITY_CHANGE"
    | "RATE_CHANGE"
    | "OFFERING_CHANGE"
    | "ADD_OFFERING"
    | "REMOVE_OFFERING"
    | "CANCELLATION";
  status: 'SUCCESS' | 'FAILED' | 'REVIEW'
  errorMessage?: string;
  quote?: Quote;
  contract?: Contract;
  invoice?: Invoice;
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "action": {
      "type": "string",
      "enum": ["QUANTITY_CHANGE", "RATE_CHANGE", "OFFERING_CHANGE", "ADD_OFFERING", "REMOVE_OFFERING", "CANCELLATION"]
    },
    "status": {
      "type": "string",
      "enum": ["SUCCESS", "FAILED", "REVIEW"]
    },
    "errorMessage": {
      "type": "string"
    },
    "quote": {
      "$ref": "#/definitions/Quote"
    },
    "contract": {
      "$ref": "#/definitions/Contract"
    }
  },
  "required": ["action", "status", "quote", "contract"],
  "definitions": {
    "Quote": {
      "type": "object"
      // Refer to Quote in API Definition
    },
    "Contract": {
      "type": "object"
      // Refer to Contract in API Definition
    },
    "Invoice": {
      "type": "object"
      // Refer to Contract in API Definition
    }
  }
}