openapi: 3.2.0
info:
  title: Connect Events Subscriptions API
  description: RESTful API for working with BILL webhooks
  version: '1'
servers:
- url: https://gateway.stage.bill.com/connect-events
  description: sandbox
tags:
- name: Subscriptions
paths:
  /v3/subscriptions:
    get:
      tags:
      - Subscriptions
      summary: Get list of subscriptions
      description: 'Get a list of all your created subscriptions.


        By default, you get 20 results on one page of results. Set `max` in your request to get up to 100 results on one page.


        **Note**: In this list operation, pagination is available only in one direction. The `nextPage` value is available in the response for you to retrieve the next page of results. However, you cannot retrieve the previous page of results.


        See Webhooks in the Guides section for more information, sample requests, and notification payloads for BILL events.'
      operationId: getAllSubscriptions
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key sent to you by BILL when you create a developer account. Set `sessionId` and `devKey` for organization-level BILL v3 API webhook events.
          example: '{{developer_key}}'
      - name: appKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Application key sent to you by BILL when you create a partner account. Set `sessionId` and `appKey` for partner-level BILL v3 API webhook events.
          example: '{{app_key}}'
      - name: apiToken
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Access token for Spend & Expense API authentication. Set `apiToken`  for Spend & Expense webhook events.
          example: '{{api_token}}'
      - name: max
        in: query
        schema:
          maximum: 100
          minimum: 1
          type:
          - integer
          - 'null'
          description: Maximum number of results
          format: int32
          example: 10
      - name: page
        in: query
        schema:
          type:
          - string
          - 'null'
          description: 'Next page of results.


            When a list has multiple pages, the `nextPage` value in the response enables you to navigate to the next page of results. Set `page` as the `nextPage` value for navigation.'
      responses:
        '200':
          description: getAllSubscriptions 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSubscriptionResponseDto'
    post:
      tags:
      - Subscriptions
      summary: Create a subscription
      description: 'Create a new event subscription. You can subscribe to multiple events with a single request. You can create up to 10 webhook subscriptions per organization.


        BILL provides a full catalog of all the events that you can subscribe to with `GET /v3/events/catalog`. See Get events catalog in the API reference for more information.


        See Webhooks in the Guides section for more information, sample requests, and notification payloads for BILL events.'
      operationId: createSubscription
      parameters:
      - name: X-Idempotent-Key
        in: header
        description: Idempotency key. The key must be in the UUID4 format.
        required: true
        schema:
          type: string
        example: '{{webhook_idempotency_key}}'
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key sent to you by BILL when you create a developer account. Set `sessionId` and `devKey` for organization-level BILL v3 API webhook events.
          example: '{{developer_key}}'
      - name: appKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Application key sent to you by BILL when you create a partner account. Set `sessionId` and `appKey` for partner-level BILL v3 API webhook events.
          example: '{{app_key}}'
      - name: apiToken
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Access token for Spend & Expense API authentication. Set `apiToken`  for Spend & Expense webhook events.
          example: '{{api_token}}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequestDto'
        required: true
      responses:
        '200':
          description: createSubscription 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionWithSecurityKeyResponseDto'
  /v3/subscriptions/{subscriptionId}:
    get:
      tags:
      - Subscriptions
      summary: Get subscription details
      description: Get details about an existing subscription.
      operationId: getSubscription
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key sent to you by BILL when you create a developer account. Set `sessionId` and `devKey` for organization-level BILL v3 API webhook events.
          example: '{{developer_key}}'
      - name: appKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Application key sent to you by BILL when you create a partner account. Set `sessionId` and `appKey` for partner-level BILL v3 API webhook events.
          example: '{{app_key}}'
      - name: apiToken
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Access token for Spend & Expense API authentication. Set `apiToken`  for Spend & Expense webhook events.
          example: '{{api_token}}'
      - name: subscriptionId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the subscription
          example: '{{webhook_subscription_id}}'
      responses:
        '200':
          description: getSubscription 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponseDto'
    put:
      tags:
      - Subscriptions
      summary: Replace a subscription
      description: 'Update the events that you are subscribed to.


        You can use the PUT operation to add, remove, or replace events in a subscription. For example, you can replace the `bill.created` event with `bill.updated` in your subscription.'
      operationId: replaceSubscription
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key sent to you by BILL when you create a developer account. Set `sessionId` and `devKey` for organization-level BILL v3 API webhook events.
          example: '{{developer_key}}'
      - name: appKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Application key sent to you by BILL when you create a partner account. Set `sessionId` and `appKey` for partner-level BILL v3 API webhook events.
          example: '{{app_key}}'
      - name: apiToken
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Access token for Spend & Expense API authentication. Set `apiToken`  for Spend & Expense webhook events.
          example: '{{api_token}}'
      - name: subscriptionId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the subscription
          example: '{{webhook_subscription_id}}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequestDto'
        required: true
      responses:
        '200':
          description: replaceSubscription 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponseDto'
    delete:
      tags:
      - Subscriptions
      summary: Delete a subscription
      description: Delete an existing subscription.
      operationId: deleteSubscription
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key sent to you by BILL when you create a developer account. Set `sessionId` and `devKey` for organization-level BILL v3 API webhook events.
          example: '{{developer_key}}'
      - name: appKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Application key sent to you by BILL when you create a partner account. Set `sessionId` and `appKey` for partner-level BILL v3 API webhook events.
          example: '{{app_key}}'
      - name: apiToken
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Access token for Spend & Expense API authentication. Set `apiToken`  for Spend & Expense webhook events.
          example: '{{api_token}}'
      - name: subscriptionId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the subscription
          example: '{{webhook_subscription_id}}'
      responses:
        '200':
          description: deleteSubscription 200 response
    patch:
      tags:
      - Subscriptions
      summary: Update a subscription
      description: 'Update details about a subscription.


        You can use the PATCH operation to modify existing subscription details, such as `name`, `status`, and `notificationUrl`.'
      operationId: updateSubscription
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key sent to you by BILL when you create a developer account. Set `sessionId` and `devKey` for organization-level BILL v3 API webhook events.
          example: '{{developer_key}}'
      - name: appKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Application key sent to you by BILL when you create a partner account. Set `sessionId` and `appKey` for partner-level BILL v3 API webhook events.
          example: '{{app_key}}'
      - name: apiToken
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Access token for Spend & Expense API authentication. Set `apiToken`  for Spend & Expense webhook events.
          example: '{{api_token}}'
      - name: subscriptionId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the subscription
          example: '{{webhook_subscription_id}}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionUpdateRequestDto'
        required: true
      responses:
        '200':
          description: updateSubscription 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponseDto'
  /v3/subscriptions/{subscriptionId}/security_key:
    post:
      tags:
      - Subscriptions
      summary: Create a security key
      description: 'Create a new security key for your subscription.


        When you create a new subscription, a one-time `securityKey` is one of the generated values in the response. All event notifications sent to your `notificationUrl` are signed with this key using the HMAC-SHA256 algorithm. The key is sent as the `x-bill-sha-signature` header value in the notification.


        You can use the security key to verify all notifications sent to you. It is good practice to keep the security key for your subscription updated in a timely manner. You can use this endpoint to generate a new security key based on your desired frequency.


        See Webhooks in the Guides section for more information, sample requests, and notification payloads for BILL events.'
      operationId: createNewSecurityKey
      parameters:
      - name: X-Idempotent-Key
        in: header
        description: Idempotency key. The key must be in the UUID4 format.
        required: true
        schema:
          type: string
        example: '{{webhook_idempotency_key}}'
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key sent to you by BILL when you create a developer account. Set `sessionId` and `devKey` for organization-level BILL v3 API webhook events.
          example: '{{developer_key}}'
      - name: appKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Application key sent to you by BILL when you create a partner account. Set `sessionId` and `appKey` for partner-level BILL v3 API webhook events.
          example: '{{app_key}}'
      - name: apiToken
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Access token for Spend & Expense API authentication. Set `apiToken`  for Spend & Expense webhook events.
          example: '{{api_token}}'
      - name: subscriptionId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the subscription
          example: '{{webhook_subscription_id}}'
      responses:
        '200':
          description: createNewSecurityKey 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityKeyDto'
  /v3/subscriptions/{subscriptionId}/test:
    post:
      tags:
      - Subscriptions
      summary: Generate a test event notification
      description: 'Generate a new test event notification. After you create a subscription, use this endpoint for BILL to send a test event notification to your specified notification URL.


        In your request, all the fields are optional. To see specific information in the test event notification, you can set `eventType`, `version`, and any details. You can get the BILL events catalog with `GET /v3/events/catalog`.


        **Note**: All the fields in the test event notification are test values. You cannot use any of the test values for any other operation.


        See Webhooks in the Guides section for more information, sample requests, and notification payloads for BILL events.'
      operationId: sendTestEvent
      parameters:
      - name: sessionId
        in: header
        schema:
          type:
          - string
          - 'null'
          description: API session ID generated with `/v3/login`
          example: '{{session_id}}'
      - name: devKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Developer key sent to you by BILL when you create a developer account. Set `sessionId` and `devKey` for organization-level BILL v3 API webhook events.
          example: '{{developer_key}}'
      - name: appKey
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Application key sent to you by BILL when you create a partner account. Set `sessionId` and `appKey` for partner-level BILL v3 API webhook events.
          example: '{{app_key}}'
      - name: apiToken
        in: header
        schema:
          type:
          - string
          - 'null'
          description: Access token for Spend & Expense API authentication. Set `apiToken`  for Spend & Expense webhook events.
          example: '{{api_token}}'
      - name: subscriptionId
        in: path
        required: true
        schema:
          minLength: 1
          type: string
          description: BILL-generated ID of the subscription
          example: '{{webhook_subscription_id}}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendTestEventRequestDto'
        required: true
      responses:
        '200':
          description: sendTestEvent 200 response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventDto'
components:
  schemas:
    VirtualCard:
      type: object
      properties:
        status:
          type: string
        remitEmail:
          type: string
        enrollDate:
          type: string
          format: date-time
        declineDate:
          type: string
          format: date-time
        alternatePayByType:
          type: string
      description: Vendor virtual card enrollment information.
    PaymentPayloadV1:
      type: object
      properties:
        id:
          type: string
        billIds:
          type: array
          items:
            type: string
        transactionNumber:
          type: string
        status:
          type: string
        createdBy:
          type: string
        createdTime:
          type: string
          format: date-time
        updatedTime:
          type: string
          format: date-time
        processDate:
          type: string
          format: date
        funding:
          $ref: '#/components/schemas/Funding'
        disbursement:
          $ref: '#/components/schemas/Disbursement'
        vendor:
          $ref: '#/components/schemas/Vendor'
        billingType:
          type: string
      description: Payload for Payment.
    ThreeDsChallengePayloadV1:
      type: object
      properties:
        merchantName:
          type: string
        merchantCategoryCode:
          type: string
        acsTransactionId:
          type: string
        userUuid:
          type: string
        occurredTime:
          type: string
          format: date-time
        amount:
          type: number
        cardUuid:
          type: string
        companyUuid:
          type: string
        currencyCode:
          type: string
      description: 3ds challenge transformed payload.
    VendorPayloadV1:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        shortName:
          type: string
        archived:
          type: boolean
        paymentNetworkId:
          type: string
        rppsId:
          type: string
        networkStatus:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        paymentInformation:
          $ref: '#/components/schemas/PaymentInformation'
        createdTime:
          type: string
          format: date-time
        updatedTime:
          type: string
          format: date-time
        accountNumber:
          type: string
        email:
          type: string
        phone:
          type: string
        recurringPayments:
          type: boolean
        billCurrency:
          type: string
        autoPay:
          $ref: '#/components/schemas/AutoPay'
        balance:
          $ref: '#/components/schemas/Balance'
        additionalInfo:
          $ref: '#/components/schemas/AdditionalInfo'
      description: Vendor transformed payload.
    AutoPay:
      type: object
      properties:
        enabled:
          type: boolean
      description: Vendor auto-pay information.
    Disbursement:
      type: object
      properties:
        amount:
          type: number
        currency:
          type: string
        arrivesByDate:
          type: string
        disbursementAccount:
          $ref: '#/components/schemas/DisbursementAccount'
      description: Payment disbursement information.
    CurrencyData:
      type: object
      properties:
        exchangeRate:
          type: number
        exponent:
          type: integer
          format: int64
        originalCurrencyAmount:
          type: string
        originalCurrencyCode:
          type: string
        symbol:
          type: string
      description: CurrencyData class for Spend \& Expense Transactions.
    CardAccountDefaults:
      type: object
      properties:
        payables:
          type: boolean
        receivables:
          type: boolean
        funding:
          type: boolean
        disbursement:
          type: boolean
      description: Card payment default values for BILL operations.
    Vendor:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
      description: Vendor information.
    SubscriptionEventDto:
      required:
      - type
      - version
      type: object
      properties:
        type:
          minLength: 1
          type: string
          description: Event type
        version:
          minLength: 1
          type: string
          description: Event type version
      description: Subscription events information.
    ReimbursementPayloadV1:
      type: object
      properties:
        uuid:
          type: string
        note:
          type: string
        merchantName:
          type: string
        amount:
          type: number
        status:
          $ref: '#/components/schemas/ReimbursementStatus'
        fulfillmentType:
          $ref: '#/components/schemas/FulfillmentType'
        budgetUuid:
          type: string
        companyUuid:
          type: string
        userUuid:
          type: string
        occurredTime:
          type: string
          format: date-time
        updatedTime:
          type: string
          format: date-time
        retiredTime:
          type: string
          format: date-time
        submittedTime:
          type: string
          format: date-time
      description: Spend reimbursement transformed payload.
    SubscriptionWithSecurityKeyResponseDto:
      type: object
      properties:
        id:
          type: string
          description: BILL-generated ID of the subscription
        name:
          type: string
          description: Subscription name
        organizationId:
          type: string
          description: BILL-generated ID of the organization. BILL sends you event notifications only for the BILL organization used to set up a subscription.
        status:
          allOf:
          - $ref: '#/components/schemas/SubscriptionStatusWithActorDto'
          - description: Subscription status information
        events:
          type: array
          description: Subscription events information. You can retrieve event `type` and `version` with `GET /v3/events/catalog`.
          items:
            $ref: '#/components/schemas/SubscriptionEventDto'
        notificationUrl:
          type: string
          description: Event notification URL. The URL must be HTTPS. BILL uses this URL to send you event notifications.
        createdTime:
          type: string
          description: Subscription created date and time
          format: date-time
        updatedTime:
          type: string
          description: Subscription updated date and time
          format: date-time
        securityKey:
          type: string
          description: 'BILL-generated security key.


            When you create a new subscription, a one-time `securityKey` is generated and all event notifications sent to your `notificationUrl` are signed with this key.'
      description: Subscription and security key information.
    InvoicePayloadV1:
      type: object
      properties:
        id:
          type: string
        customerId:
          type: string
        invoiceNumber:
          type: string
        archived:
          type: boolean
        totalAmount:
          type: number
        dueAmount:
          type: number
        scheduledAmount:
          type: number
        creditAmount:
          type: number
        invoiceDate:
          type: string
          format: date
        dueDate:
          type: string
          format: date
        createdBy:
          type: string
        createdTime:
          type: string
          format: date-time
        updatedTime:
          type: string
          format: date-time
        payToChartOfAccountId:
          type: string
        salesTaxPercentage:
          type: number
        salesTaxTotal:
          type: number
        status:
          type: string
      description: invoice transformed payload.
    SubscriptionStatusDto:
      type: object
      properties:
        enabled:
          type: boolean
          description: Set as `true` if the subscription is enabled. When you create a new subscription, this value is set as `true` by default.
        reason:
          type: string
          description: Reason for changing the subscription status. This field is used by BILL for informing you when the `enabled` field is set as `false`.
      description: Subscription status information.
    TransactionPayloadV1:
      type: object
      properties:
        uuid:
          type: string
        fees:
          type: number
        foreignExchangeFee:
          type: number
        transactionType:
          $ref: '#/components/schemas/TransactionType'
        parentTransactionUuid:
          type: string
        userUuid:
          type: string
        rawMerchantName:
          type: string
        merchantName:
          type: string
        budgetUuid:
          type: string
        originalAuthTransactionUuid:
          type: string
        occurredTime:
          type: string
          format: date-time
        updatedTime:
          type: string
          format: date-time
        authorizedTime:
          type: string
          format: date-time
        complete:
          type: boolean
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
        currencyData:
          $ref: '#/components/schemas/CurrencyData'
        amount:
          type: number
        receiptStatus:
          $ref: '#/components/schemas/ReceiptStatusType'
        cardUuid:
          type: string
        companyUuid:
          type: string
        merchantCategoryCode:
          type: string
        declineReason:
          type: string
        declineInternalReasonCode:
          type: string
      description: Spend Transaction transformed payload.
    PaymentInformation:
      type: object
      properties:
        payByType:
          type: string
        virtualCard:
          $ref: '#/components/schemas/VirtualCard'
        email:
          type: string
        payeeName:
          type: string
        lastPaymentDate:
          type: string
          format: date-time
      description: Vendor payment information.
    PaginationDto_SubscriptionResponseDto_:
      type: object
      properties:
        nextPage:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionResponseDto'
      description: Pagination information.
    BankAccountPayloadV1:
      type: object
      properties:
        id:
          type: string
        archived:
          type: boolean
        accountNumber:
          type: string
        nameOnAccount:
          type: string
        routingNumber:
          type: string
        bankName:
          type: string
        status:
          type: string
        createdBy:
          type: string
        type:
          type: string
        ownerType:
          type: string
        default:
          $ref: '#/components/schemas/BankAccountDefaults'
        createdTime:
          type: string
          format: date-time
        updatedTime:
          type: string
          format: date-time
      description: Bank Account transformed payload.
    TransactionType:
      type: string
      description: TransactionType.
      enum:
      - CLEAR
      - DECLINE
      - AUTHORIZATION
    Address:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        stateOrProvince:
          type: string
        zipOrPostalCode:
          type: string
        country:
          type: string
      description: Vendor address information.
    DisbursementAccount:
      type: object
      properties:
        type:
          type: string
        accountNumber:
          type: string
      description: Disbursement account details.
    CustomField:
      required:
      - name
      - note
      - selectedValues
      - uuid
      type: object
      properties:
        uuid:
          type: string
        name:
          type: string
        note:
          type: string
        selectedValues:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldValue'
      description: Custom field object used for custom field return values. Used on Transaction and Reimbursement returns
    SubscriptionUpdateRequestDto:
      type: object
      properties:
        name:
          type: string
          description: Subscription name
        status:
          allOf:
          - $ref: '#/components/schemas/SubscriptionStatusDto'
          - description: Subscription status information
        events:
          type: array
          description: Subscription events information. You can retrieve event `type` and `version` with `GET /v3/events/catalog`.
          items:
            $ref: '#/components/schemas/SubscriptionEventDto'
        notificationUrl:
          type: string
          description: Event notification URL. The URL must be HTTPS. BILL uses this URL to send you event notifications.
      description: Update a subscription (name updated)
      example:
        name: Manage bills
    SubscriptionResponseDto:
      type: object
      properties:
        id:
          type: string
          description: BILL-generated ID of the subscription
        name:
          type: string
          description: Subscription name
        organizationId:
          type: string
          description: BILL-generated ID of the organization. BILL sends you event notifications only for the BILL organization used to set up a subscription.
        status:
          allOf:
          - $ref: '#/components/schemas/SubscriptionStatusWithActorDto'
          - description: Subscription status information
        events:
          type: array
          description: Subscription events information. You can retrieve event `type` and `version` with `GET /v3/events/catalog`.
          items:
            $ref: '#/components/schemas/SubscriptionEventDto'
        notificationUrl:
          type: string
          description: Event notification URL. The URL must be HTTPS. BILL uses this URL to send you event notifications.
        createdTime:
          type: string
          description: Subscription created date and time
          format: date-time
        updatedTime:
          type: string
          description: Subscription updated date and time
          format: date-time
      description: Subscription response information.
    BillClassificationsDto:
      type: object
      properties:
        chartOfAccountId:
          type: string
        accountingClassId:
          type: string
        departmentId:
          type: string
        locationId:
          type: string
      description: General ledger classifications information for the bill.
    AdditionalInfo:
      type: object
      properties:
        taxId:
          type: string
        taxIdType:
          type: string
        track1099:
          type: boolean
        leadTimeInDays:
          type: integer
          format: int32
        combinePayments:
          type: boolean
        companyName:
          type: string
        paymentTermId:
          type: string
      description: Vendor additional information.
    RiskVerificationPayloadV1:
      type: object
      properties:
        decision:
          type: string
      description: Payload for Risk Verification.
    FulfillmentType:
      type: string
      description: Enum for fulfillment type.
      enum:
      - PAYROLL
      - ACH
      - UNSPECIFIED
    SecurityKeyDto:
      type: object
      properties:
        securityKey:
          type: string
          description: BILL-generated security key
      description: Security key used for signing outgoing messages.
    ListSubscriptionResponseDto:
      type: object
      description: The list of subscription response dto and next page.
      allOf:
      - $ref: '#/components/schemas/PaginationDto_SubscriptionResponseDto_'
    SubscriptionStatusWithActorDto:
      type: object
      properties:
        enabled:
          type: boolean
          description: Set as `true` if the subscription is enabled. When you create a new subscription, this value is set as `true` by default.
        reason:
          type: string
          description: Reason for changing the subscription status. This field is used by BILL for informing you when the `enabled` field is set as `false`.
        actor:
          allOf:
          - $ref: '#/components/schemas/SubscriptionActorDto'
          - description: Entity that set the subscription status
      description: Subscription status and change actor information.
    Balance:
      type: object
      properties:
        amount:
          type: number
        lastUpdatedDate:
          type: string
          format: date-time
      description: Vendor account balance information.
    CardAccountExpiration:
      type: object
      properties:
        year:
          type: string
        month:
          type: string
      description: Card expiration month and year.
    Funding:
      type: object
      properties:
        amount:
          type: number
        currency:
          type: string
        fundingAccount:
          $ref: '#/components/schemas/FundingAccount'
      description: Payment funding information.
    SubscriptionActorDto:
      type: string
      description: Subscription change actor information.
      enum:
      - CLIENT
      - SYSTEM
    FundingAccount:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
        name:
          type: string
        accountNumber:
          type: string
        last4:
          type: string
      description: Funding account details.
    BillPayloadV1:
      type: object
      properties:
        id:
          type: string
        vendorId:
          type: string
        vendorName:
          type: string
        invoice:
          $ref: '#/components/schemas/Invoice'
        amount:
          type: number
        createdBy:
          type: string
        createdTime:
          type: string
          format: date-time
        updatedTime:
          type: string
          format: date-time
        archived:
          type: boolean
        description:
          type: string
        dueDate:
          type: string
          format: date
        payFromChartOfAccountId:
          type: string
        paymentStatus:
          type: string
        classifications:
          $ref: '#/components/schemas/BillClassificationsDto'
        purchaseOrderNumber:
          type: string
      description: Bill transformed payload.
    CardAccountPayloadV1:
      type: object
      properties:
        id:
          type: string
        archived:
          type: boolean
        createdTime:
          type: string
          format: date-time
        createdBy:
          type: string
        updatedTime:
          type: string
          format: date-time
        nameOnAccount:
          type: string
        brand:
          type: string
        type:
          type: string
        status:
          type: string
        last4:
          type: string
        expiration:
          $ref: '#/components/schemas/CardAccountExpiration'
        default:
          $ref: '#/components/schemas/CardAccountDefaults'
      description: Card Account transformed payload.
    BankAccountDefaults:
      type: object
      properties:
        payables:
          type: boolean
        receivables:
          type: boolean
      description: Bank payment default values for BILL AP and AR operations.
    SubscriptionRequestDto:
      required:
      - events
      - name
      - notificationUrl
      - status
      type: object
      properties:
        name:
          minLength: 1
          type: string
          description: Subscription name
        status:
          allOf:
          - $ref: '#/components/schemas/SubscriptionStatusDto'
          - description: Subscription status information
        events:
          minItems: 1
          type: array
          description: Subscription events information. You can retrieve event `type` and `version` with `GET /v3/events/catalog`.
          items:
            $ref: '#/components/schemas/SubscriptionEventDto'
        notificationUrl:
          minLength: 1
          type: string
          description: Event notification URL. The URL must be HTTPS. BILL uses this URL to send you event notifications.
      description: Create a subscription
      example:
        name: Bill management
        status:
          enabled: true
        events:
        - type: bill.created
          version: '1'
        - type: bill.updated
          version: '1'
        - type: bill.archived
          version: '1'
        notificationUrl: '{{webhook_notification_url}}'
    ReimbursementStatus:
      type: string
      description: Enum for reimbursement status.
      enum:
      - UNSPECIFIED
      - CREATED
      - AWAITING_APPROVAL
      - APPROVAL_UNDONE
      - AWAITING_TIER2_APPROVAL
      - TIER2_APPROVAL_UNDONE
      - APPROVED
      - CANCEL_PAYMENT
      - FUNDING_RECEIVED
      - PAID
      - PAYMENT_FAILED
      - DENIED
      - DENIAL_UNDONE
      - DELETED
    Invoice:
      type: object
      properties:
        invoiceNumber:
          type: string
        invoiceDate:
          type: string
          format: date
      description: Invoice information.
    EventDto:
      type: object
      properties:
        id:
          type: string
          description: BILL-generated ID of the event
        type:
          type: string
          description: Event type
        version:
          type: string
          description: Event type version
        subscriptionId:
          type: string
          description: BILL-generated ID of the subscription
        payload:
          type: string
          description: Event payload. The payload is JSON escaped and presented as a string.
        createdTime:
          type: string
          description: Event created date and time
          format: date-time
        statusCode:
          type: integer
          description: HTTP status code received from the notification URL
          format: int32
      description: Event information.
    CustomFieldValue:
      required:
      - uuid
      - value
      type: object
      properties:
        uuid:
          type: string
        value:
          type: string
      description: Custom field value object representing the custom field value return on Custom fields for transactions and reimbursements.
    ReceiptStatusType:
      type: string
      description: ReceiptStatusType enum for Spend \& Expense Transactions.
      enum:
      - VALIDATED
      - NOT_VALIDATED
      - ATTACHED
      - MISSING
      - NOT_REQUIRED
      - NOT_ATTACHED
      - UNSPECIFIED
    SendTestEventRequestDto:
      type: object
      properties:
        eventType:
          type: string
          description: Event type. You can get the BILL events catalog with `GET /v3/events/catalog`.
        version:
          type: string
          description: Event type version
        vendor:
          allOf:
          - $ref: '#/components/schemas/VendorPayloadV1'
          - description: Test `vendor` event payload
        bill:
          allOf:
          - $ref: '#/components/schemas/BillPayloadV1'
          - description: Test `bill` event payload
        bank-account:
          allOf:
          - $ref: '#/components/schemas/BankAccountPayloadV1'
          - description: Test `bank-account` event payload
        card-account:
          allOf:
          - $ref: '#/components/schemas/CardAccountPayloadV1'
          - description: Test `card-account` event payload
        payment:
          allOf:
          - $ref: '#/components/schemas/PaymentPayloadV1'
          - description: Test `payment` event payload
        risk-verification:
          allOf:
          - $ref: '#/components/schemas/RiskVerificationPayloadV1'
          - description: Test `risk-verification` event payload
        invoice:
          allOf:
          - $ref: '#/components/schemas/InvoicePayloadV1'
          - description: Test `invoice` event payload
        transaction:
          allOf:
          - $ref: '#/components/schemas/TransactionPayloadV1'
          - description: Test `spend.transaction` event payload
        threeDsChallenge:
          allOf:
          - $ref: '#/components/schemas/ThreeDsChallengePayloadV1'
          - description: Test `spend.threeDsChallenge` event payload
        reimbursement:
          allOf:
          - $ref: '#/components/schemas/ReimbursementPayloadV1'
          - description: Test `spend.reimbursement` event payload
      description: Generate a test event notification
      example:
        eventType: bill.created
        version: '1'
        bill:
          id: test-bill-id
          vendorId: test-vendor-id
          amount: 100
x-provenance:
  method: searched
  source: https://developer.bill.com/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developer.bill.com/reference/createnewsecuritykey.md
  - https://developer.bill.com/reference/createsubscription.md
  - https://developer.bill.com/reference/deletesubscription.md
  - https://developer.bill.com/reference/getallsubscriptions.md
  - https://developer.bill.com/reference/geteventcatalog.md
  - https://developer.bill.com/reference/geteventsforsubscription.md
  - https://developer.bill.com/reference/getsubscription.md
  - https://developer.bill.com/reference/replacesubscription.md
  - https://developer.bill.com/reference/resendevent.md
  - https://developer.bill.com/reference/sendtestevent.md
  - https://developer.bill.com/reference/updatesubscription.md
  - https://developer.bill.com/reference/webhookgethealthcheck.md
  merge:
    pages: 12
    deduped: 19
    conflicts_kept_first: 0