DealHub Billing API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Subskribe Billing API
servers:
- url: https://api.app.subskribe.com
security:
- ApiKeyAuth: []
tags:
- name: Billing
paths:
  /accountReceivableContact:
    get:
      tags:
      - Billing
      summary: Get the contact for accounts receivable
      description: Returns the details of the account receivable contact for your tenant
      operationId: getAccountReceivableContact
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountReceivableContactJson'
    put:
      tags:
      - Billing
      summary: Set the contact for accounts receivable
      description: Sets the details of the account receivable contact for your tenant
      operationId: putAccountReceivableContact
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountReceivableContactJson'
        description: contact details
      responses:
        default:
          description: successful operation
  /alias/subscriptionCharge/{aliasId}:
    get:
      tags:
      - Billing
      summary: Get the details of an alias
      description: Returns the details of the specified alias id including the subscription id and the charge id it is mapped to.
      operationId: getSubscriptionChargeAlias
      parameters:
      - name: aliasId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionChargeAlias'
    put:
      tags:
      - Billing
      summary: Create an alias for a subscription id/charge id pair
      description: This allows you to specify a string alias for a subscription id and a charge id. This can be useful when, for example, you want to upload usage statistics and would rather specify your own id (or another external id), rather than referring to Subskribe's internal ids.
      operationId: addSubscriptionChargeAlias
      parameters:
      - name: aliasId
        in: path
        description: alias to map to create the mapping for
        required: true
        schema:
          type: string
      - name: subscriptionId
        in: query
        description: the subscription id
        required: false
        schema:
          type: string
      - name: chargeId
        in: query
        description: the charge id
        required: false
        schema:
          type: string
      responses:
        default:
          description: successful operation
    delete:
      tags:
      - Billing
      summary: Delete the specified alias
      description: Deletes the specified alias mapping
      operationId: deleteSubscriptionChargeAlias
      parameters:
      - name: aliasId
        in: path
        required: true
        schema:
          type: string
      responses:
        default:
          description: successful operation
  /alias/subscriptionCharge:
    get:
      tags:
      - Billing
      summary: Get aliases for a subscription
      description: Returns all aliases for the specified subscription id.
      operationId: listAliasesForSubscription
      parameters:
      - name: subscriptionId
        in: query
        description: id of the subscription
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscriptionChargeAlias'
  /automatedInvoiceRules/{id}:
    get:
      tags:
      - Billing
      summary: Get automated invoice rule details
      description: Returns the details of the specified automated invoice rule
      operationId: getAutomatedInvoiceRule
      parameters:
      - name: id
        in: path
        description: Id of the automated invoice rule
        required: true
        schema:
          type: string
      responses:
        default:
          description: successful operation
    put:
      tags:
      - Billing
      summary: Update automated invoice rule details
      description: Updates the details of the specified automated invoice rule
      operationId: updateAutomatedInvoiceRule
      parameters:
      - name: id
        in: path
        description: id of the automated invoice rule
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/AutomatedInvoiceRuleRequestJson'
      responses:
        default:
          description: successful operation
  /automatedInvoiceRules/internal/{id}:
    get:
      tags:
      - Billing
      summary: Get automated invoice rule details via internal id
      description: Returns the details of the specified automated invoice rule
      operationId: getAutomatedInvoiceRuleByInternalId
      parameters:
      - name: id
        in: path
        description: Internal id of the automated invoice rule
        required: true
        schema:
          type: string
      responses:
        default:
          description: successful operation
      deprecated: true
    put:
      tags:
      - Billing
      operationId: updateAutomatedInvoiceRuleUsingInternalId
      parameters:
      - name: id
        in: path
        description: id of the automated invoice rule
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/AutomatedInvoiceRuleRequestJson'
      responses:
        default:
          description: successful operation
      deprecated: true
  /automatedInvoiceRules:
    get:
      tags:
      - Billing
      summary: Get automated invoice rules for a tenant
      description: Returns all the configured automated invoice rules for the tenant
      operationId: getAutomatedInvoiceRules
      responses:
        default:
          description: successful operation
    post:
      tags:
      - Billing
      summary: Create an automated invoice rule
      description: Creates an automated invoice rule with the specified parameters
      operationId: addAutomatedInvoiceRule
      requestBody:
        $ref: '#/components/requestBodies/AutomatedInvoiceRuleRequestJson'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomatedInvoiceRule'
  /dunning/sendInvoiceReminder/{invoiceNumber}:
    post:
      tags:
      - Billing
      summary: Send an Invoice Reminder
      description: Sends a reminder email for the specified invoice
      operationId: sendInvoiceReminder
      parameters:
      - name: invoiceNumber
        in: path
        description: number of the invoice
        required: true
        schema:
          type: string
      responses:
        default:
          description: successful operation
  /dunning/sendTestEmail/{reminderType}:
    post:
      tags:
      - Billing
      summary: Send a test email
      description: Sends a test email for dunning to the use associated with this API call. Note A user bound api key is required for this operation.
      operationId: sendTestDunningEmail
      parameters:
      - name: reminderType
        in: path
        description: type of the reminder
        required: true
        schema:
          type: string
          enum:
          - WEEK_BEFORE_DUE_DATE
          - DUE_DATE
          - WEEK_AFTER_DUE_DATE
          - TWO_WEEKS_AFTER_DUE_DATE
          - MONTH_AFTER_DUE_DATE
          - TWO_MONTHS_AFTER_DUE_DATE
      responses:
        default:
          description: successful operation
  /dunningSetting:
    get:
      tags:
      - Billing
      summary: Get dunning settings
      description: Returns the dunning settings for your tenant
      operationId: getDunningSetting
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DunningSettingJson'
    put:
      tags:
      - Billing
      summary: Update dunning settings
      description: Updates the dunning settings for your tenant
      operationId: updateDunningSetting
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DunningSettingJson'
        description: json representing the dunning settings
      responses:
        default:
          description: successful operation
  /invoices/bulk/{bulkInvoiceRunId}:
    get:
      tags:
      - Billing
      summary: Get bulk invoice run details
      description: Returns the details of the specified bulk invoice run
      operationId: getBulkInvoiceRun
      parameters:
      - name: bulkInvoiceRunId
        in: path
        description: id of the run
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkInvoiceRun'
  /invoices/bulk/{bulkInvoiceRunId}/runItems:
    get:
      tags:
      - Billing
      summary: Get items for bulk invoice run
      description: Returns the items associated with the specified bulk invoice run
      operationId: getBulkInvoiceRunItems
      parameters:
      - name: bulkInvoiceRunId
        in: path
        description: id of the run
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BulkInvoiceRunItem'
  /invoices/{number}/balance:
    get:
      tags:
      - Billing
      summary: Get invoice balance
      description: Returns the balance of the specified invoice number
      operationId: getInvoiceBalance
      parameters:
      - name: number
        in: path
        description: number of the invoice
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceBalanceJson'
  /invoices/{number}:
    get:
      tags:
      - Billing
      summary: Get invoice details
      description: Returns the details of the specified invoice number
      operationId: getInvoice
      parameters:
      - name: number
        in: path
        description: number of the invoice
        required: true
        schema:
          type: string
      - name: includeDeleted
        in: query
        description: include deleted invoice items
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceJson'
    put:
      tags:
      - Billing
      summary: Update invoice details
      description: Updates the details of the specified invoice.
      operationId: updateInvoice
      parameters:
      - name: number
        in: path
        description: number of the invoice
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInvoiceRequest'
        description: json representing invoice details
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceJson'
    delete:
      tags:
      - Billing
      summary: Delete invoice
      description: Deletes the specified invoice
      operationId: deleteInvoice
      parameters:
      - name: number
        in: path
        description: number of the invoice
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceJson'
  /invoices/generate:
    post:
      tags:
      - Billing
      summary: Generate subscription invoices
      description: Generates the invoices for the given subscription
      operationId: generateInvoice
      parameters:
      - name: subscriptionId
        in: query
        description: id of the subscription
        required: true
        schema:
          type: string
      - name: targetDate
        in: query
        description: Time in seconds since Epoch (GMT) to generate invoice from
        required: true
        schema:
          type: integer
          format: int64
      - name: invoiceDate
        in: query
        description: Time in seconds since Epoch (GMT) to set invoice date to
        required: false
        schema:
          type: integer
          format: int64
      - name: invoiceChargeInclusionOption
        in: query
        description: types of charges to include
        required: true
        schema:
          type: string
          enum:
          - INCLUDE_USAGE
          - EXCLUDE_USAGE
          - ONLY_USAGE
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InvoiceJson'
  /invoices/preview:
    get:
      tags:
      - Billing
      summary: Preview invoices
      description: Returns a preview of invoice for the specified order id OR subscription id
      operationId: previewInvoiceByOrderPeriod
      parameters:
      - name: orderId
        in: query
        description: id of order
        required: false
        schema:
          type: string
      - name: subscriptionId
        in: query
        description: id of subscription
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InvoicePreviewJson'
  /invoices/unbilledUsage:
    get:
      tags:
      - Billing
      summary: Get unbilled usage
      description: Returns the unbilled usage invoice items for the specified subscription
      operationId: previewInvoiceByOrderPeriod_1
      parameters:
      - name: subscriptionId
        in: query
        description: id of the subscription
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InvoiceItemJson'
  /invoices:
    get:
      tags:
      - Billing
      summary: Get all invoices for a subscription
      description: Returns all invoices for a subscription. The result is paginated. Use the cursor returned from a request in subsequent calls to retrieve all results.
      operationId: getInvoices
      parameters:
      - name: subscriptionId
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: status filter for invoices
        required: false
        schema:
          type: string
          enum:
          - DRAFT
          - POSTED
          - PAID
          - CONVERTED
          - VOIDED
      - name: cursor
        in: query
        description: used to iterate through all results
        required: false
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        description: number of items per page
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceJsonPaginationResponse'
  /invoices/{number}/voided:
    delete:
      tags:
      - Billing
      summary: Delete voided invoice
      description: Deletes the specified invoice
      operationId: deleteVoidedInvoice
      parameters:
      - name: number
        in: path
        description: number of the invoice
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceJson'
  /invoices/{number}/post:
    post:
      tags:
      - Billing
      summary: Mark invoice as posted
      description: Marks the specified invoice as posted
      operationId: postInvoice
      parameters:
      - name: number
        in: path
        description: number of the invoice
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceJson'
  /invoices/{number}/void:
    put:
      tags:
      - Billing
      summary: Mark invoice as voided
      description: Marks the specified invoice as voided
      operationId: voidInvoice
      parameters:
      - name: number
        in: path
        description: number of the invoice
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoidInvoiceRequest'
        description: json representing invoice details
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceJson'
  /invoices/{invoiceNumber}/pdf:
    get:
      tags:
      - Billing
      summary: Download invoice PDF
      description: Downloads the PDF for an invoice after it has been generated via a POST to /{invoiceNumber}/pdf. The data return will be the PDF document contents.
      operationId: getInvoiceDocumentPdf
      parameters:
      - name: invoiceNumber
        in: path
        description: number of the invoice
        required: true
        schema:
          type: string
      responses:
        default:
          description: successful operation
    post:
      tags:
      - Billing
      summary: Generate invoice PDF
      description: Generates a PDF version of the specified invoice. Once generated, PDF can be later fetched via a call to /{invoiceNumber}/pdf.
      operationId: createInvoiceDocument
      parameters:
      - name: invoiceNumber
        in: path
        required: true
        schema:
          type: string
      - name: force
        in: query
        description: Force regeneration of the PDF document even if there has been no changes. Defaults to false.
        required: false
        schema:
          type: boolean
      responses:
        default:
          description: successful operation
  /invoices/schedule/{id}:
    delete:
      tags:
      - Billing
      summary: Delete an existing billing schedule
      description: Billing schedules must be deleted in reverse chronological order.
      operationId: deleteBillingSchedule
      parameters:
      - name: id
        in: path
        description: billing schedule entry id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        default:
          description: successful operation
  /invoices/schedule:
    get:
      tags:
      - Billing
      summary: Get billing schedules for a subscription line item
      description: Retrieve all billing schedules for a subscription line item
      operationId: getBillingSchedules
      parameters:
      - name: subscriptionId
        in: query
        required: true
        schema:
          type: string
      - name: subscriptionChargeId
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BillingEventEntry'
    post:
      tags:
      - Billing
      summary: Add a new billing schedule for subscription line item
      description: Creates a new billing schedule entry for an event based charge
      operationId: addBillingSchedule
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingEventInput'
        description: new billing event
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: string
  /invoices/bulk/{bulkInvoiceRunId}/post:
    put:
      tags:
      - Billing
      summary: Posts invoices for a bulk run
      description: Marks all invoices associated with the specified bulk run as posted
      operationId: postInvoicesForBulkInvoiceRun
      parameters:
      - name: bulkInvoiceRunId
        in: path
        description: id of the run
        required: true
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/postInvoicesForBulkInvoiceRunBody'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkInvoiceRun'
  /invoices/bulk/email:
    post:
      tags:
      - Billing
      summary: Send emails for multiple invoices
      description: Trigger tasks for sending emails for the given list of invoice IDs
      operationId: sendBulkInvoiceEmail
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
        description: List of invoice numbers to email
        required: true
      responses:
        default:
          description: successful operation
  /invoices/sequence/{invoiceConfigId}:
    post:
      tags:
      - Billing
      summary: Update invoice sequence
      description: Updates the invoice sequence by invoice config id.
      operationId: updateInvoiceSequence
      parameters:
      - name: invoiceConfigId
        in: path
        description: invoice config id
        required: true
        schema:
          type: string
      - name: next invoice number
        in: query
        description: long integer value
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantInvoiceConfig'
  /invoices/previewAllInvoices:
    get:
      tags:
      - Billing
      summary: Preview all invoices
      description: Returns a preview of invoice for the specified order id OR subscription id
      operationId: previewAllInvoice
      parameters:
      - name: orderId
        in: query
        description: id of order
        required: false
        schema:
          type: string
      - name: subscriptionId
        in: query
        description: id of subscription
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InvoicePreviewJson'
  /invoices/usage:
    get:
      tags:
      - Billing
      summary: Get usage
      description: Returns the usage invoice items for the specified subscription and charge
      operationId: getUsageForSubscriptionCharge
      parameters:
      - name: subscriptionId
        in: query
        description: id of the subscription
        required: true
        schema:
          type: string
      - name: chargeId
        in: query
        description: id of the charge
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InvoiceItemJson'
  /invoices/{number}/canDelete:
    get:
      tags:
      - Billing
      summary: Check if invoice can be deleted
      description: Response contains flag to indicate if the invoice can be deleted and reason if it cannot be deleted
      operationId: getCanDeleteInvoice
      parameters:
      - name: number
        in: path
        description: number of the invoice
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceDeletableResponse'
  /invoices/{invoiceNumber}/documentJson:
    get:
      tags:
      - Billing
      summary: Get the invoice document JSON that is used to render invoice PDF
      description: Invoice document JSON that contains all details required to render full Invoice document
      operationId: getRawInvoiceDocumentJson
      parameters:
      - name: invoiceNumber
        in: path
        description: number of the invoice
        required: true
        schema:
          type: string
      responses:
        default:
          description: successful operation
  /invoices/{invoiceNumber}/email:
    post:
      tags:
      - Billing
      summary: Send invoice email to contacts
      description: Send the invoice to recipients via email with invoice PDF as attachment.
      operationId: emailInvoice
      parameters:
      - name: invoiceNumber
        in: path
        required: true
        schema:
          type: string
      responses:
        default:
          description: successful operation
  /invoices/bulk:
    post:
      tags:
      - Billing
      summary: Create a bulk invoice run
      description: Creates a bulk invoice run as specified by the input parameters. On success the id of the run is returned.
      operationId: createBulkInvoiceRun
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkInvoiceRunInput'
        description: json representing the run parameters
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: string
  /settlements/applicablePaymentBankAccounts:
    get:
      tags:
      - Billing
      summary: Get applicable payment bank accounts for invoice payment
      description: Returns a list of applicable payment bank accounts that can be used for payment for a given invoice number
      operationId: getApplicablePaymentBankAccountsForInvoicePayment
      parameters:
      - name: invoiceNumber
        in: query
        description: Invoice number
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentBankAccountJson'
  /settlements/{id}:
    get:
      tags:
      - Billing
      summary: Get settlement application details
      description: Gets the details of specified settlement application.
      operationId: getSettlementApplication
      parameters:
      - name: id
        in: path
        description: id of the settlement application
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettlementApplication'
  /settlements:
    get:
      tags:
      - Billing
      summary: Get settlement applications
      description: Returns the settlement applications for the specified invoice number or payment object.
      operationId: getSettlementApplications
      parameters:
      - name: invoiceNumber
        in: query
        description: number of the invoice
        required: false
        schema:
          type: string
      - name: paymentId
        in: query
        description: Id of payment
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SettlementApplication'
  /settlements/addAndApplyPayment:
    post:
      tags:
      - Billing
      summary: Apply a payment on a specific invoice
      description: Apply a payment per the specified parameters.
      operationId: addAndApplyPayment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyPaymentRequest'
        description: add and apply payment parameters in json
        required: true
      responses:
        default:
          description: successful operation
  /settlements/applyCreditMemo:
    post:
      tags:
      - Billing
      summary: Apply a credit memo
      description: Applies a credit memo per the specified parameters
      operationId: applyCreditMemo
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditMemoApplicationJson'
        description: application details in json
        required: true
      responses:
        default:
          description: successful operation
  /settlements/unapplyCreditMemo:
    post:
      tags:
      - Billing
      summary: Unapply a credit memo
      description: Unapplies a credit memo per the specified parameters
      operationId: unapplyCreditMemo
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreditMemoUnapplicationJson'
        description: application details in json
        required: true
      responses:
        default:
          description: successful operation
components:
  schemas:
    AutomatedInvoiceRuleRequestJson:
      type: object
      required:
      - cronExpression
      - firstExecutionDate
      - name
      properties:
        id:
          type: string
        entityIds:
          type: array
          uniqueItems: true
          items:
            type: string
        name:
          type: string
        description:
          type: string
        cronExpression:
          type: string
        firstExecutionDate:
          type: integer
          format: int64
        lastExecutionDate:
          type: integer
          format: int64
        targetDuration:
          type: integer
          format: int32
        invoiceDuration:
          type: integer
          format: int32
        includeUsageCharge:
          type: boolean
        includeNonUsageCharge:
          type: boolean
        autoPostInvoice:
          type: boolean
        autoEmailInvoice:
          type: boolean
        enabled:
          type: boolean
    PaymentBankAccountJson:
      type: object
      required:
      - currencyCode
      - entityIds
      - status
      properties:
        id:
          type: string
          readOnly: true
        entityIds:
          type: array
 

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dealhub/refs/heads/main/openapi/dealhub-billing-api-openapi.yml