Billing

This endpoint group exposes billing, subscription, payment, and metered-usage operations for the billing plugin. It includes user-scoped retrieval methods, subscription and plan management actions, payment recharge flows, usage reservation/commit workflows, and administrative billing controls. Some methods explicitly depend on subscription or user context, while others are intended for administrative or scheduler-driven use based on their descriptions and in-method checks.

Endpoints

POST /api/rpc (Method: BillingRpc.associatePlan)

• Description: Associates a target user or subscription with a billing plan.

• Request Body:

  {
    "method": "BillingRpc.associatePlan",
    "params": {
      "targetType": "subscription",
      "targetId": "string",
      "planId": "string"
    }
  }

• Parameters:

  Name	Type	Required	Description
  targetType	String	Yes	The target type to associate with the plan. Accepted values are subscription and user.
  targetId	String	Yes	The identifier of the target.
  planId	String	Yes	The billing plan identifier.

• Response:

  {
    "success": true,
    "data": "service-defined result"
  }

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "BillingRpc.associatePlan",
      "params": {
        "targetType": "subscription",
        "targetId": "string",
        "planId": "string"
      }
    }'

POST /api/rpc (Method: BillingRpc.migratePlan)

• Description: Migrates a target's subscription to a new plan.

• Request Body:

  {
    "method": "BillingRpc.migratePlan",
    "params": {
      "targetId": "string",
      "newPlanId": "string",
      "proration": true
    }
  }

• Parameters:

  Name	Type	Required	Description
  targetId	String	Yes	The target subscription identifier.
  newPlanId	String	Yes	The destination plan identifier.
  proration	Boolean	No	Whether proration is applied. Defaults to true.

• Response:

  {
    "success": true,
    "data": "service-defined result"
  }

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "BillingRpc.migratePlan",
      "params": {
        "targetId": "string",
        "newPlanId": "string",
        "proration": true
      }
    }'

POST /api/rpc (Method: BillingRpc.applyServicePack)

• Description: Applies a service pack add-on to a target's subscription.

• Request Body:

  {
    "method": "BillingRpc.applyServicePack",
    "params": {
      "targetId": "string",
      "packId": "string"
    }
  }

• Parameters:

  Name	Type	Required	Description
  targetId	String	Yes	The target identifier.
  packId	String	Yes	The service pack identifier.

• Response:

  {
    "success": true,
    "data": "service-defined result"
  }

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "BillingRpc.applyServicePack",
      "params": {
        "targetId": "string",
        "packId": "string"
      }
    }'

POST /api/rpc (Method: BillingRpc.applyDiscount)

• Description: Applies a discount code to a target's subscription.

• Request Body:

  {
    "method": "BillingRpc.applyDiscount",
    "params": {
      "targetId": "string",
      "discountCode": "string"
    }
  }

• Parameters:

  Name	Type	Required	Description
  targetId	String	Yes	The target identifier.
  discountCode	String	Yes	The discount code to apply.

• Response:

  {
    "success": true,
    "data": "service-defined result"
  }

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "BillingRpc.applyDiscount",
      "params": {
        "targetId": "string",
        "discountCode": "string"
      }
    }'

POST /api/rpc (Method: BillingRpc.getBillingInfoForCurrentUser)

• Description: Retrieves the complete billing profile for the currently logged-in user's subscription.

• Request Body:

  {
    "method": "BillingRpc.getBillingInfoForCurrentUser",
    "params": {}
  }

• Parameters:

  This method does not accept request parameters. It requires context.subscriptionId and throws an error if the subscription context is missing.

• Response:

  {
    "success": true,
    "data": "billing profile object with an added serviceCode when available"
  }

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "BillingRpc.getBillingInfoForCurrentUser",
      "params": {}
    }'

POST /api/rpc (Method: BillingRpc.getChargeRecordsForCurrentUser)

• Description: Retrieves charge records for the currently logged-in user's subscription.

• Request Body:

  {
    "method": "BillingRpc.getChargeRecordsForCurrentUser",
    "params": {
      "page": 1,
      "pageSize": 25
    }
  }

• Parameters:

  Name	Type	Required	Description
  page	Number	No	Page number. Defaults to 1. Must be a positive integer.
  pageSize	Number	No	Page size. Defaults to 25. Must be a positive integer.

• Response:

  {
    "success": true,
    "data": "service-defined paginated charge record result"
  }

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "BillingRpc.getChargeRecordsForCurrentUser",
      "params": {
        "page": 1,
        "pageSize": 25
      }
    }'

POST /api/rpc (Method: BillingRpc.getCurrentUserBillingInfo)

• Description: Retrieves the billing information for the currently authenticated user.

• Request Body:

  {
    "method": "BillingRpc.getCurrentUserBillingInfo",
    "params": {}
  }

• Parameters:

  This method does not accept request parameters. It requires context.subscriptionId.

• Response:

  {
    "success": true,
    "data": "billing profile object"
  }

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "BillingRpc.getCurrentUserBillingInfo",
      "params": {}
    }'

POST /api/rpc (Method: BillingRpc.listMyInvoices)

• Description: Lists invoices for the currently authenticated user.

• Request Body:

  {
    "method": "BillingRpc.listMyInvoices",
    "params": {
      "limit": 10
    }
  }

• Parameters:

  Name	Type	Required	Description
  limit	Number	No	Maximum number of invoices to return. Defaults to 10. Must be a positive integer.

• Response:

  {
    "success": true,
    "data": "service-defined invoice list result"
  }

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "BillingRpc.listMyInvoices",
      "params": {
        "limit": 10
      }
    }'

POST /api/rpc (Method: BillingRpc.canReserve)

• Description: Checks whether a target has enough balance or allowance to proceed with a metered action without creating a reservation.

• Request Body:

  {
    "method": "BillingRpc.canReserve",
    "params": {
      "targetId": "string",
      "featureKey": "string",
      "units": 1,
      "billerConfigOverride": {}
    }
  }

• Parameters:

  Name	Type	Required	Description
  targetId	String	Yes	The target identifier.
  featureKey	String	Yes	The metered feature key.
  units	Number	Yes	The number of units to evaluate.
  billerConfigOverride	Record<String, any>	No	Optional billing configuration overrides.

• Response:

  {
    "success": true,
    "data": {
      "canProceed": true
    }
  }

  When the underlying check rejects with a billing-specific error, the method returns:

  {
    "success": true,
    "data": {
      "canProceed": false,
      "reason": "string",
      "details": {}
    }
  }

• Example (cURL):

  curl -X POST "${