Billing Operations Management
The Billing Operations Management service encompasses all functionalities related to managing billing processes within the system. This includes subscription handling, payment management, and coupon applications, providing a seamless experience for users managing their financial interactions with the service.

This service is divided into three primary categories:

  • Subscription management

    Manage various aspects of subscriptions, including retrieving payment histories, handling proration details during plan changes, and performing actions such as deleting, reactivating, and updating subscriptions. This ensures users maintain complete control over their subscription lifecycles.


  • Customer payment management

    Access and manage payment methods associated with customer accounts, ensuring users can easily view and maintain their payment information for smooth billing operations.


  • Coupon management

    Retrieve details of available coupons and apply them to customer accounts, allowing for promotional discounts and effective management of customer incentives.


Together, these functionalities streamline billing processes, enhance user experience, and ensure efficient management of all financial interactions within the platform.
ENDPOINTS
Expand all
  • Subscription management
    GET/subscription/{id}/payments
    GET/subscription/{id}/proration/{product_id}
    GET/plan/{plan}/{version}/limits
    DELETE/subscription/{id}
    PUT/subscription/{id}
    PATCH/subscription/{id}
    POST/organisation/purchase-info
    PUT/organisation/plan
    GET/org/usage
  • Customer payment management
  • Coupon management
Get Subscription Payment History
This API endpoint retrieves the details of a subscription and its associated payments. You must provide the subscription ID in the path parameter to retrieve the information.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will return the subscription details, including its status, plan, and a list of payments with detailed information.
  • If the request fails, an appropriate error message will be returned.
Path Parameters
  • id string
    The unique subscription ID to retrieve.
JavaScript
Response codes
const axios = require('axios');

const url = 'https://payment-query.api.pinghome.io/v1/subscription/{id}/payments';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Get Subscription Proration Details
This API endpoint retrieves proration details for a subscription when switching between plans. The proration amount is calculated based on the remaining time on the current plan and the cost of the new plan. You must provide both the subscription ID and product ID as path parameters.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will return the proration details, including the current plan, the new plan, and the proration difference.
  • If the request fails, an appropriate error message will be returned.
Path Parameters
  • id string
    The unique subscription ID to retrieve.
  • product_id string
JavaScript
Response codes
const axios = require('axios');

const url = 'https://payment-query.api.pinghome.io/v1/subscription/{id}/proration/{product_id}';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Get Plan Limits by Version
This API endpoint retrieves the limits for a specific plan version. It supports plan and version as path parameters to specify the plan and version being queried. The response provides the limits organized by modules such as monitoring and statuspage.

Authorization: Bearer YOUR_TOKEN



Expected Behavior:


  • On success, the system will return the plan limits organized by module, including key, value, title, and other metadata.
  • If the request is unauthorized, the system will respond with an authentication error message.
Path Parameters
  • plan string
    The plan identifier, such as 'team', 'developer', or 'business'. Example: 'team'
  • version string
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-query.api.pinghome.io/v1/plan/team/v1/limits";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Delete Subscription
This API endpoint allows you to delete a subscription by its unique ID. The user must provide the subscription ID in the path parameter and authenticate with a valid token.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will cancel the subscription and return a success message.
  • If the request is invalid or the subscription cannot be deleted, the system will return an error message detailing the issue.
Path Parameters
  • id string
    The unique ID of the subscription to delete.
JavaScript
Response codes
const axios = require('axios');

const url = 'https://payment-cmd.api.pinghome.io/v1/subscription/{id}';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Reactivate Subscription
This API endpoint allows reactivating a subscription by its unique ID. You must provide the subscription ID in the path parameter.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will reactivate the subscription and return a success message.
  • If the request is invalid or the subscription cannot be reactivated, the system will return an error message detailing the issue.
Path Parameters
  • id string
    The unique ID of the subscription to reactivate.
JavaScript
Response codes
const axios = require('axios');

const url = 'https://payment-cmd.api.pinghome.io/v1/subscription/{id}';

axios.put(url, {}, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Update Subscription
This API endpoint allows updating a subscription by its unique ID. You must provide the subscription ID in the path parameter and a valid price ID in the request body.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will update the subscription and return a success message.
  • If the request is invalid or the subscription cannot be updated, the system will return an error message detailing the issue.
Path Parameters
  • id string
    The unique ID of the subscription to update.
Request Body Parameters
  • price_id string
    The ID of the new price to update the subscription with.
JavaScript
Response codes
const axios = require('axios');

const url = 'https://payment-cmd.api.pinghome.io/v1/subscription/{id}';
const data = {
  price_id: 'price_1MU7isEyoIQbyvYhiIpiQlw2'
};

axios.patch(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Create Organisation Purchase Info
This API endpoint allows creating a purchase information record for an organisation.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will create the purchase info and return a confirmation message.
  • If the request is unauthorized or invalid, the system will respond with an error message.
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/organisation/purchase-info";

axios.post(url, {}, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Update Organisation Plan
This API endpoint allows updating the plan of an organisation.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will update the organisation plan and return a confirmation message.
  • If the request is unauthorized or invalid, the system will respond with an error message.
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/organisation/plan";

axios.put(url, {}, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Retrieve Organisation Usage
This API endpoint retrieves usage data for a specific organisation. The response includes details on monitoring, team, and service limits, as well as the current usage for each category.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system returns detailed usage data for the organisation.
  • If the request is unauthorized, the system will return an authentication error.
JavaScript
Response codes
const axios = require('axios');

const url = 'https://customer-query.api.pinghome.io/v1/org/usage';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Get Account's Payment Method Information
This API endpoint retrieves the list of payment methods associated with the account. The response includes details of each payment method, such as the payment provider, type, and whether it is set as the default payment method.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will return the list of payment methods along with relevant details.
  • If the request fails, an appropriate error message will be returned.
JavaScript
Response codes
const axios = require('axios');

const url = 'https://payment-query.api.pinghome.io/v1/payment-methods';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Access Coupon Information
This API endpoint retrieves a coupon by its unique code. You must provide the coupon code in the path parameter.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will return the details of the coupon associated with the provided code.
  • If the coupon does not exist or the user is not authorized, an appropriate error message will be returned.
Path Parameters
  • code string
    The unique coupon code to retrieve. Example: '25OFF'.
JavaScript
Response codes
const axios = require('axios');

const url = 'https://payment-query.api.pinghome.io/v1/coupon/{code}';

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).
Apply Discount Voucher
This API endpoint allows applying a voucher code for a customer. The request body must contain the voucher code.

Authorization: Bearer YOUR_TOKEN


Expected Behavior:


  • On success, the system will apply the voucher and return a confirmation message.
  • If the request is unauthorized or invalid, the system will respond with an error message.
Request Body Parameters
  • code string
    The voucher code to be applied. Example: 'AAACCCBBDD-CSSSS1'
JavaScript
Response codes
const axios = require('axios');

const url = "https://customer-cmd.api.pinghome.io/v1/customer/applied-voucher";
const data = {
  "code": "AAACCCBBDD-CSSSS1"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});
ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).