Conga Custom Plan Template API

openapi: 3.2.0
info:
  title: Billing Management Custom Plan Template API
  version: 1.0.0
  description: The  CustomPlanTemplate (also called BillingPlanTemplate) Controller
servers:
- url: https://rls.congacloud.com/api/billing/v1
security:
- Bearer: []
tags:
- name: Custom Plan Template
  description: The  CustomPlanTemplate (also called BillingPlanTemplate) Controller
paths:
  /custom-plan-templates:
    patch:
      tags:
      - Custom Plan Template
      summary: Edit custom plan template
      description: Edit multiple custom plan template records along with template line items and returns the updated custom plan template record IDs.
      requestBody:
        description: The list of plan template and plan template line item records to update
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CustomPlanTemplateRequest'
            example: "[\n  {\n    \"Id\": \"Id-1\",\n    \"Name\": \"Monthly Billing Plan\",\n    \"PeriodsNeeded\": false,\n    \"NumberOfInstallments\": 1,\n    \"ComputationMethod\": \"Custom\",\n    \"StartDateBasedOn\": \"Custom\",\n    \"Description\": \"Example plan for 12-month billing\",\n    \"Items\": [\n      {\n        \"Id\": \"LineItemId-1\",\n        \"Name\": \"Initial Payment\",\n        \"OffsetType\": \"Months\",\n        \"OffsetNumber\": 1,\n        \"Percent\": 100,\n        \"PaymentTerm\": {\n          \"Id\": \"PaymentTermId\",\n          \"Name\": \"Net 30 Days\"\n        }\n      }\n    ]\n  }\n]"
          text/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CustomPlanTemplateRequest'
            example: "[\n  {\n    \"Id\": \"Id-1\",\n    \"Name\": \"Monthly Billing Plan\",\n    \"PeriodsNeeded\": false,\n    \"NumberOfInstallments\": 1,\n    \"ComputationMethod\": \"Custom\",\n    \"StartDateBasedOn\": \"Custom\",\n    \"Description\": \"Example plan for 12-month billing\",\n    \"Items\": [\n      {\n        \"Id\": \"LineItemId-1\",\n        \"Name\": \"Initial Payment\",\n        \"OffsetType\": \"Months\",\n        \"OffsetNumber\": 1,\n        \"Percent\": 100,\n        \"PaymentTerm\": {\n          \"Id\": \"PaymentTermId\",\n          \"Name\": \"Net 30 Days\"\n        }\n      }\n    ]\n  }\n]"
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CustomPlanTemplateRequest'
            example: "[\n  {\n    \"Id\": \"Id-1\",\n    \"Name\": \"Monthly Billing Plan\",\n    \"PeriodsNeeded\": false,\n    \"NumberOfInstallments\": 1,\n    \"ComputationMethod\": \"Custom\",\n    \"StartDateBasedOn\": \"Custom\",\n    \"Description\": \"Example plan for 12-month billing\",\n    \"Items\": [\n      {\n        \"Id\": \"LineItemId-1\",\n        \"Name\": \"Initial Payment\",\n        \"OffsetType\": \"Months\",\n        \"OffsetNumber\": 1,\n        \"Percent\": 100,\n        \"PaymentTerm\": {\n          \"Id\": \"PaymentTermId\",\n          \"Name\": \"Net 30 Days\"\n        }\n      }\n    ]\n  }\n]"
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
        '207':
          description: Multi-Status
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
        '500':
          description: Internal Server Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorApiResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorApiResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ErrorApiResponse'
    post:
      tags:
      - Custom Plan Template
      summary: Create a custom plan template with  line items
      description: "This API allows you to create one or multiple custom billing plan templates in a single request. Each template can include \nits own set of line items (installments or milestones), and the API validates all input before committing any records. \nThis endpoint is bulkified, so you can efficiently create several templates at once, and it provides detailed feedback for each record in the batch."
      requestBody:
        description: The list of plan template and plan template line item records to create
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CustomPlanTemplateRequest'
            example: "[\n  {\n    \"Name\": \"Monthly Billing Plan\",\n    \"PeriodsNeeded\": false,\n    \"NumberOfInstallments\": 1,\n    \"ComputationMethod\": \"Custom\",\n    \"StartDateBasedOn\": \"Custom\",\n    \"Description\": \"Example plan for 12-month billing\",\n    \"PlanType\": \"MileStone\",\n    \"BasedOn\": \"Percentage\",\n    \"Items\": [\n      {\n        \"Name\": \"Initial Payment\",\n        \"OffsetType\": \"Months\",\n        \"OffsetNumber\": 1,\n        \"Percent\": 100,\n        \"PaymentTerm\": {\n          \"Name\": \"Net 30 Days\"\n        }\n      }\n    ]\n  }\n]"
          text/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CustomPlanTemplateRequest'
            example: "[\n  {\n    \"Name\": \"Monthly Billing Plan\",\n    \"PeriodsNeeded\": false,\n    \"NumberOfInstallments\": 1,\n    \"ComputationMethod\": \"Custom\",\n    \"StartDateBasedOn\": \"Custom\",\n    \"Description\": \"Example plan for 12-month billing\",\n    \"PlanType\": \"MileStone\",\n    \"BasedOn\": \"Percentage\",\n    \"Items\": [\n      {\n        \"Name\": \"Initial Payment\",\n        \"OffsetType\": \"Months\",\n        \"OffsetNumber\": 1,\n        \"Percent\": 100,\n        \"PaymentTerm\": {\n          \"Name\": \"Net 30 Days\"\n        }\n      }\n    ]\n  }\n]"
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CustomPlanTemplateRequest'
            example: "[\n  {\n    \"Name\": \"Monthly Billing Plan\",\n    \"PeriodsNeeded\": false,\n    \"NumberOfInstallments\": 1,\n    \"ComputationMethod\": \"Custom\",\n    \"StartDateBasedOn\": \"Custom\",\n    \"Description\": \"Example plan for 12-month billing\",\n    \"PlanType\": \"MileStone\",\n    \"BasedOn\": \"Percentage\",\n    \"Items\": [\n      {\n        \"Name\": \"Initial Payment\",\n        \"OffsetType\": \"Months\",\n        \"OffsetNumber\": 1,\n        \"Percent\": 100,\n        \"PaymentTerm\": {\n          \"Name\": \"Net 30 Days\"\n        }\n      }\n    ]\n  }\n]"
      responses:
        '201':
          description: Created
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
        '207':
          description: Multi-Status
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
        '500':
          description: Internal Server Error
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorApiResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorApiResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ErrorApiResponse'
  /custom-plan-templates/activate:
    patch:
      tags:
      - Custom Plan Template
      summary: Activate or deactivate a list of custom plan templates
      description: "This API is used to activate or deactivate one or more custom Plan Templates in bulk. \nYou provide a list of template IDs along with the desired active status (true for activate, false for deactivate). The API processes each request individually, \nvalidates prerequisites (such as template existence and readiness), and returns a batch response indicating the success or failure for each template."
      requestBody:
        description: Contains the list of custom plan template id and true/false to activate or deactivate the custom plan template.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CustomPlanToggleActiveRequest'
          text/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CustomPlanToggleActiveRequest'
          application/*+json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CustomPlanToggleActiveRequest'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
        '207':
          description: Multi-Status
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
  /custom-plan-templates/{planTemplateId}:
    get:
      tags:
      - Custom Plan Template
      summary: Retrieve a custom plan template record
      description: This API endpoint allows you to retrieve a specific custom Plan Template by its unique identifier (planTemplateId).
      parameters:
      - name: planTemplateId
        in: path
        description: The identifier of the custom plan template
        required: true
        schema:
          type: string
      - name: includes
        in: query
        description: Optional related entities to include
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/PlanTemplate'
            application/json:
              schema:
                $ref: '#/components/schemas/PlanTemplate'
            text/json:
              schema:
                $ref: '#/components/schemas/PlanTemplate'
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ErrorApiResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorApiResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/ErrorApiResponse'
  /custom-plan-templates/{planTemplateId}/activate:
    patch:
      tags:
      - Custom Plan Template
      summary: Activate or deactivate a custom plan template
      description: "This API allows you to activate or deactivate a specific custom plan template by passing its unique identifier (planTemplateId) \nin the route and the desired status (active=true or active=false) as a query parameter. The API processes the request and updates the \ntemplate’s active status accordingly."
      parameters:
      - name: planTemplateId
        in: path
        description: Custom plan template id
        required: true
        schema:
          type: string
      - name: active
        in: query
        description: Active flag value
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
        '400':
          description: Bad Request
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
            text/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBatchResponse'
components:
  schemas:
    ErrorApiResponse:
      type: object
      properties:
        Errors:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ApiError'
      additionalProperties: false
    ApiError:
      type: object
      properties:
        Source:
          type:
          - string
          - 'null'
        Title:
          type:
          - string
          - 'null'
        Detail: {}
        Help:
          type:
          - string
          - 'null'
      additionalProperties: false
    BaseResponse:
      type: object
      properties:
        Id:
          type:
          - string
          - 'null'
        RecordIndex:
          type: integer
          format: int32
        IsSuccess:
          type: boolean
        Errors:
          type:
          - array
          - 'null'
          items:
            type: string
        ErrorMessage:
          type:
          - string
          - 'null'
          deprecated: true
      additionalProperties: false
    CustomPlanTemplateRequest:
      type: object
      properties:
        Id:
          type:
          - string
          - 'null'
          description: Indicates Id for Plan Template.
        Name:
          type:
          - string
          - 'null'
          description: Indicates Name for Plan Template to be created/updated.
        PeriodsNeeded:
          type:
          - boolean
          - 'null'
          description: If True, Billing is “Period specific” hence the line items must have non-overlapping Period Start Date and Period End Dates.If False, Billing is not dependent on periods so there’s no need for the user to enter the Periods at the line item level.
        NumberOfInstallments:
          type: integer
          description: The number of installments (i.e., the number of milestones/intended billing events.)
          format: int32
        ComputationMethod:
          type:
          - string
          - 'null'
          description: Indicates whether the user wants to define the custom or even distribution of the percentages/amounts across the installments.
        StartDateBasedOn:
          type:
          - string
          - 'null'
          description: Indicates the source from where the “Start Date” must be picked from.
        Description:
          type:
          - string
          - 'null'
        PlanType:
          type:
          - string
          - 'null'
          description: Indicates whether the intended billing plan should be a “Milestone” or “Term based” plan.
        BasedOn:
          type:
          - string
          - 'null'
          description: Indicates whether the user wants to enter the Fee directly (“Amount”) or as a “Percentage” of the ”Total Price”
        Items:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CustomPlanTemplateLineItemRequest'
          description: List of billing plan template line items associated with a billing plan template.
      additionalProperties: false
      description: 'Represents a request to create or update a custom billing plan template, including its configuration,

        computation method, and associated line items.'
    CustomPlanToggleActiveRequest:
      type: object
      properties:
        Active:
          type: boolean
          description: The flag contains whether the transaction has been successful or failed
        Id:
          type:
          - string
          - 'null'
          description: Created/Updated record Id on processed in a transaction
      additionalProperties: false
      description: CustomPlanToggleActiveRequest
    PlanTemplate:
      type: object
      properties:
        Id:
          type:
          - string
          - 'null'
        Name:
          type:
          - string
          - 'null'
        CreatedBy:
          $ref: '#/components/schemas/LookupObject'
        CreatedDate:
          type: string
          format: date-time
        ModifiedBy:
          $ref: '#/components/schemas/LookupObject'
        ModifiedDate:
          type: string
          format: date-time
        ExternalId:
          type:
          - string
          - 'null'
        ETag:
          type:
          - string
          - 'null'
        Description:
          type:
          - string
          - 'null'
        PlanType:
          type:
          - string
          - 'null'
        PeriodsNeeded:
          type: boolean
        NumberOfInstallments:
          type: integer
          format: int32
        BasedOn:
          type:
          - string
          - 'null'
        ComputationMethod:
          type:
          - string
          - 'null'
        StartDateBasedOn:
          type:
          - string
          - 'null'
        Active:
          type: boolean
        Items:
          type: array
          items:
            $ref: '#/components/schemas/PlanTemplateLineItem'
          description: Child collection of PlanTemplateLineItem (included when 'Items' is requested via the includes parameter).
      additionalProperties: {}
    BaseResponseBatchResponse:
      type: object
      properties:
        Summary:
          type:
          - string
          - 'null'
        Results:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/BaseResponse'
      additionalProperties: false
    LookupObject:
      type: object
      properties:
        Id:
          type:
          - string
          - 'null'
        Name:
          type:
          - string
          - 'null'
      additionalProperties: false
    CustomPlanTemplateLineItemRequest:
      type: object
      properties:
        Id:
          type:
          - string
          - 'null'
          description: Indicates Id for Plan Template line item to be updated.
        Name:
          type:
          - string
          - 'null'
          description: Indicates name for Plan Template Line Item to be created/updated.
        OffsetType:
          type:
          - string
          - 'null'
          description: Indicates the value based on which the offset to be calculated.
        OffsetNumber:
          type:
          - integer
          - 'null'
          description: Indicates the time to be elapsed between the billing periods.
          format: int32
        Percent:
          type:
          - number
          - 'null'
          description: Indicates the percentage of the total price to be computed for the installment.
          format: double
        PaymentTerm:
          $ref: '#/components/schemas/LookupObject'
      additionalProperties: false
      description: CustomPlanTemplateLineItemRequest
    PlanTemplateLineItem:
      type: object
      properties:
        Id:
          type:
          - string
          - 'null'
        Name:
          type:
          - string
          - 'null'
        CreatedBy:
          $ref: '#/components/schemas/LookupObject'
        CreatedDate:
          type: string
          format: date-time
        ModifiedBy:
          $ref: '#/components/schemas/LookupObject'
        ModifiedDate:
          type: string
          format: date-time
        ExternalId:
          type:
          - string
          - 'null'
        ETag:
          type:
          - string
          - 'null'
        PlanTemplate:
          $ref: '#/components/schemas/LookupObject'
        OffsetType:
          type:
          - string
          - 'null'
        OffsetNumber:
          type:
          - integer
          - 'null'
          format: int32
        Percent:
          type:
          - number
          - 'null'
          format: double
        PaymentTerm:
          $ref: '#/components/schemas/LookupObject'
        TemplateLineNumber:
          type:
          - string
          - 'null'
      additionalProperties: {}
  securitySchemes:
    Bearer:
      type: apiKey
      description: Please insert JWT with Bearer into field
      name: Authorization
      in: header