> ## Documentation Index > Fetch the complete documentation index at: https://docs.layerfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Create vendor refund > Creates a new vendor refund for a business or updates existing vendor refund. This endpoint is idempotent using the `external_id` field as the idempotency key, so subsequent requests with the same `external_id` will update or no-op. ## OpenAPI ````yaml post /v1/businesses/{businessId}/bills/refunds openapi: 3.0.1 info: title: API version: latest servers: [] security: - BearerAuth: [] tags: [] externalDocs: url: / paths: /v1/businesses/{businessId}/bills/refunds: post: tags: - Vendor Refunds summary: Create vendor refund description: >- Creates a new vendor refund for a business or updates existing vendor refund. This endpoint is idempotent using the `external_id` field as the idempotency key, so subsequent requests with the same `external_id` will update or no-op. operationId: business.bills.refunds.post parameters: - name: businessId in: path description: The UUID of the business to create a vendor refund for. required: true schema: type: string format: uuid - name: Content-Type in: header description: Content-Type must be set to application/json. schema: type: string requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/SimpleVendorRefundCreateParams' - $ref: '#/components/schemas/ItemizedVendorRefundCreateParams' responses: '200': description: Vendor refund has been successfully updated or unchanged. content: application/json: schema: $ref: '#/components/schemas/ApiVendorRefund' '201': description: Vendor refund successfully created. content: application/json: schema: $ref: '#/components/schemas/ApiVendorRefund' '400': description: >- A vendor refund may be invalid if the bill does not exist, if the refund amount is greater than the bill amount, if the referenced bill id has a different value than that in the vendor refund creation parameters, or if a negative net value payload is specified. content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: >- Business id is not found. This indicates the business id is invalid or the business has been archived. content: application/json: schema: $ref: '#/components/schemas/ApiError' components: schemas: SimpleVendorRefundCreateParams: title: Simple Vendor Refund type: object properties: external_id: type: string nullable: true description: An external identifier for the vendor refund transaction. completed_at: type: string format: date-time description: The time the vendor refund was completed. bill_id: type: string format: uuid nullable: true description: The ID of the bill to refund. bill_external_id: type: string nullable: true description: The external ID of the bill to refund. bill_line_item_id: type: string format: uuid nullable: true description: The ID of the bill line item to refund. bill_line_item_external_id: type: string nullable: true description: The external ID of the bill line item to refund. bill_payment_id: type: string format: uuid nullable: true description: The ID of the bill payment to refund. bill_payment_external_id: type: string nullable: true description: The external ID of the bill payment to refund. refund_processing_fee: type: integer format: int64 default: 0 description: The fee charged to the business for processing the refund in cents. method: $ref: '#/components/schemas/PaymentMethod' description: The payment method used for the refund. processor: type: string nullable: true description: The payment processor used to process the refund. example: STRIPE tags: type: array items: $ref: '#/components/schemas/TagKeyValue' description: Tags to associate with the vendor refund. memo: type: string nullable: true description: >- Memo for any text you would like to associate with the vendor refund (for example, to display to end users). metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the vendor refund. Can be used to filter when listing vendor refunds. required: - completed_at - method description: >- Simple vendor refund creation parameters. The system will automatically calculate the refund amount based on the specified target (bill, line item, or payment). At least one target identifier must be provided. ItemizedVendorRefundCreateParams: title: Itemized Vendor Refund type: object properties: external_id: type: string nullable: true description: An external identifier for the vendor refund transaction. refunded_amount: type: integer format: int64 description: >- The total amount of the vendor refund in cents. This value must be positive and equal to the sum of all allocation amounts. completed_at: type: string format: date-time description: The time the vendor refund was completed. allocations: type: array items: $ref: '#/components/schemas/CreateVendorRefundAllocationParams' description: >- The targets of the vendor refund. Each allocation specifies how much of the refund should be applied to a specific bill, line item, payment, or vendor. payments: type: array items: $ref: '#/components/schemas/CreateVendorRefundPaymentParams' description: The payment methods and amounts used to process the vendor refund. tags: type: array items: $ref: '#/components/schemas/TagKeyValue' description: Tags to associate with the vendor refund. memo: type: string nullable: true description: >- Memo for any text you would like to associate with the vendor refund (for example, to display to end users). metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the vendor refund. Can be used to filter when listing vendor refunds. required: - refunded_amount - completed_at - allocations - payments description: >- Itemized vendor refund creation parameters. Provides full control over refund allocations and payments. The sum of allocation amounts must equal the refunded_amount. ApiVendorRefund: type: object properties: id: type: string format: uuid description: Unique identifier for the vendor refund. external_id: type: string nullable: true description: >- Unique ID of the vendor refund in your system for linking purposes. **Idempotency key**. example: vendor-refund-123 refunded_amount: type: integer format: int64 description: Amount refunded to the business in cents. status: type: string description: Status of the vendor refund. example: PAID completed_at: type: string format: date-time description: Time when the vendor refund was completed. allocations: type: array items: $ref: '#/components/schemas/ApiVendorRefundAllocation' description: Allocations associated with this vendor refund. payments: type: array items: $ref: '#/components/schemas/ApiVendorRefundPayment' description: Payments associated with this vendor refund. transaction_tags: type: array items: $ref: '#/components/schemas/ApiTag' memo: type: string nullable: true description: >- Memo for any text you would like to associate with the vendor refund (for example, to display to end users). metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the vendor refund. Can be used to filter when listing vendor refunds. description: >- A vendor refund represents a transaction where a vendor returns value to a business. A specific bill can be refunded or a general refund can be applied to a vendor. ApiError: type: object description: An error object returned in API error responses. properties: type: $ref: '#/components/schemas/ApiErrorType' description: >- A fixed category for the error, helpful for categorizing and processing errors. description: type: string description: A human-readable error description. error_enum: $ref: '#/components/schemas/ApiEnumErrorType' description: >- A stable, machine-readable identifier for programmatically handling specific error conditions. Only present for 4xx client errors—not included for 5xx server errors. Use this instead of parsing the description field, as enum values remain stable across API versions. nullable: true meta: type: object description: Optional additional information about the error. nullable: true required: - type - description PaymentMethod: type: string enum: - CASH - CHECK - CREDIT_CARD - ACH - CREDIT_BALANCE - OTHER TagKeyValue: type: object description: >- A TagKeyValue holds key=value data related to a tag. This is used when creating or updating taggable entities (transactions, invoices, etc.). properties: key: type: string description: The tag dimension key (e.g., "department", "project", "location"). example: department dimension_display_name: type: string nullable: true description: >- If the TagDimension doesn't exist, providing this value specifies the display name upon database insertion. Otherwise, it is left as null on the TagDimension. example: Department value: type: string description: The tag value (e.g., "sales", "marketing", "engineering"). example: sales value_display_name: type: string nullable: true description: >- If the TagValueDefinition doesn't exist, providing this value specifies the display name upon database insertion. Otherwise, it is left as null on the TagValueDefinition. example: Sales Department required: - key - value PlatformDefinedJson: type: object description: Arbitrary JSON data defined by the caller, with a 1KB size constraint. additionalProperties: true example: custom_field: value any valid json: below 1kb nested: meaning of life: 42 array: [] CreateVendorRefundAllocationParams: type: object properties: external_id: type: string nullable: true description: An external identifier for the vendor refund allocation. total_amount: type: integer format: int64 description: >- The total amount of this allocation in cents. Must equal the sum of all line item amounts. line_items: type: array items: $ref: '#/components/schemas/CreateVendorRefundAllocationLineItemParams' description: The line items that make up this allocation. bill_id: type: string format: uuid nullable: true description: The ID of the bill to refund. bill_external_id: type: string nullable: true description: The external ID of the bill to refund. bill_line_item_id: type: string format: uuid nullable: true description: The ID of the bill line item to refund. bill_line_item_external_id: type: string nullable: true description: The external ID of the bill line item to refund. bill_payment_id: type: string format: uuid nullable: true description: The ID of the bill payment to refund. bill_payment_external_id: type: string nullable: true description: The external ID of the bill payment to refund. vendor_id: type: string format: uuid nullable: true description: The ID of the vendor to refund. vendor_external_id: type: string nullable: true description: The external ID of the vendor to refund. tags: type: array items: $ref: '#/components/schemas/TagKeyValue' description: Tags to associate with the allocation. memo: type: string nullable: true description: >- Memo for any text you would like to associate with the vendor refund allocation. metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the vendor refund allocation. required: - total_amount - line_items description: >- Parameters for creating a vendor refund allocation. At least one target identifier (bill, line item, payment, or vendor) must be provided. CreateVendorRefundPaymentParams: type: object properties: external_id: type: string nullable: true description: >- Unique ID of the payment in your system for linking purposes. **Idempotency key**. example: payment-456 refunded_amount: type: integer format: int64 description: Amount refunded to the business in cents. refund_processing_fee: type: integer format: int64 nullable: true description: Fee charged to the business for processing the refund in cents. completed_at: type: string format: date-time description: Time when the payment was completed. method: $ref: '#/components/schemas/PaymentMethod' description: Payment method used for the refund. processor: type: string nullable: true description: >- Processor used to make the payment, if any. Any processor name can be provided and will be tracked. Supported processors (e.g. `STRIPE`) will have additional asset balance tracking. example: STRIPE payment_clearing_account_identifier: $ref: '#/components/schemas/AccountIdentifier' description: >- The the ledger account to use for the payment (overrides the default determined by the payment method). tags: type: array items: $ref: '#/components/schemas/TagKeyValue' description: Tags to associate with the payment. memo: type: string nullable: true description: >- Memo for any text you would like to associate with the vendor refund payment. metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the vendor refund payment. Can be used to filter when listing vendor refund payments. description: Parameters for creating a vendor refund payment. ApiVendorRefundAllocation: type: object properties: id: type: string format: uuid description: Unique identifier for the vendor refund allocation. bill_id: type: string format: uuid nullable: true description: ID of the bill this allocation is associated with. amount: type: integer format: int64 description: Amount of the allocation in cents. line_items: type: array items: $ref: '#/components/schemas/ApiVendorRefundAllocationLineItem' description: Line items that make up this allocation. bill_external_id: type: string nullable: true description: External ID of the bill this allocation is associated with. bill_line_item_id: type: string format: uuid nullable: true description: >- ID of the bill line item this allocation is associated with. If specified, must not refer to a different bill than `bill_id` or `bill_external_id`. bill_line_item_external_id: type: string nullable: true description: >- The external ID of the bill line item to refund. If specified alongside `bill_line_item_id`, they must refer to the same bill line item. bill_payment_id: type: string format: uuid nullable: true description: ID of the bill payment this allocation is associated with. bill_payment_external_id: type: string nullable: true description: External ID of the bill payment this allocation is associated with. vendor: $ref: '#/components/schemas/ApiVendorData' transaction_tags: type: array items: $ref: '#/components/schemas/ApiTag' memo: type: string nullable: true description: >- Memo for any text you would like to associate with the vendor refund allocation (for example, to display to end users). metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the vendor refund allocation. ApiVendorRefundPayment: type: object properties: id: type: string format: uuid description: Unique identifier for the payment. external_id: type: string nullable: true description: >- Unique ID of the payment in your system for linking purposes. **Idempotency key**. example: payment-456 refunded_amount: type: integer format: int64 description: Amount refunded to the business in cents. refund_processing_fee: type: integer format: int64 nullable: true description: Fee charged for the refund processing in cents. completed_at: type: string format: date-time description: Time when the payment was completed. method: type: string description: Method of the payment. example: ACH processor: type: string nullable: true description: Processor used for the payment. example: STRIPE payment_clearing_account: $ref: '#/components/schemas/SingleApiChartAccount' description: >- The the ledger account to use for the payment (overrides the default determined by the payment method), if specified. transaction_tags: type: array items: $ref: '#/components/schemas/ApiTag' memo: type: string nullable: true description: >- Memo for any text you would like to associate with the vendor refund payment (for example, to display to end users). metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the vendor refund payment. Can be used to filter when listing vendor refund payments. description: >- A payment represents a transaction that moves value from a vendor to a business. A specific bill can be refunded or a general refund can be applied to a vendor. ApiTag: type: object properties: id: type: string format: uuid description: ID for the tag. key: type: string description: Key for the tag. example: ExampleTagKey dimension_display_name: type: string nullable: true description: Display name for the tag dimension. value: type: string description: Value for the tag. example: ExampleTagValue value_display_name: type: string nullable: true description: Display name for the tag value definition. dimension_id: type: string format: uuid description: ID of the tag dimension this tag belongs to. definition_id: type: string format: uuid description: ID of the tag value definition. archived_at: type: string format: date-time nullable: true description: When the tag was archived. required: - id - key - value - dimension_id - definition_id ApiErrorType: type: string enum: - ResourceArchived - AuthFailure - Plaid - Stripe - InvalidState - ResourceNotFound - InvalidParameters - JsonSerialization - Unknown - BadRequest - PaginationCursor - Conflict - LedgerOperationFailed ApiEnumErrorType: type: string description: >- Stable enum values for programmatic error handling. Only present in 4xx error responses. enum: - AccessCodeInvalid - BalanceSheetDoesNotBalance - BalanceSheetMissingAccount - BankStatementParserError - BillStateError - BulkCategorizeFailure - BulkMatchFailure - BusinessTaskAlreadyCompleted - BusinessTaskDeleted - CalendlyOAuthError - CallBookingError - CantUpdateTransactionInCustomerPayout - CantUpdateTransactionInVendorPayout - CheckPayrollConfigNotFound - CheckPayrollServiceNotFound - ClerkUserAlreadyExists - ConflictingQueryParams - CustomAccountAlreadyExists - CustomTransactionCsvParsingError - CustomTransactionUploadFailure - CustomerPayoutInputFormatError - DoesNotMatchExistingEntity - EmptyBatchRequest - ExpenseParserError - ExternalAccountBalanceReconciliationError - ExternalIdConflict - InvalidCategory - InvalidEffectiveDate - InvalidLedgerOperation - InvalidMonthlyAverageRange - InvalidMultiPartRequest - InvalidPaginationCursor - InvalidPayload - InvoiceDeleted - InvoiceNotFound - InvoiceReferenceMismatch - InvoiceStateError - ManualRateLimit - MultipleTagKeyFiltersUnsupported - NoCognitoUserFound - NoOpeningBalanceFound - NotYetReconciled - OnePasswordApiError - OnePasswordItemNotFound - OnePasswordVaultNotFound - OpenAICategorizationError - PaymentLinkInvalid - PayrollStateError - PeriodIsClosed - PeriodNotClosed - PhoneNumberAlreadyRegistered - PlaidApiError - PlaidConnectionBroken - PlaidCreateLinkTokenError - PlaidCredentialsNotConfigured - PlaidExchangePublicTokenError - PlaidGetInstitutionByIdError - PlaidGetItemError - PlaidInvalidEnvironment - PlaidItemAlreadyExists - PlaidItemNotFound - PlaidProcessorApiError - PlaidUnlinkItemError - QueryParamFormat - QueryParamMissing - QuickbooksBrokenConnection - QuickbooksConnectionAlreadyExists - QuickbooksConnectionAlreadySyncing - QuickbooksConnectionMissing - QuickbooksConnectionNotActivated - QuickbooksInvalidRequest - QuickbooksInvalidState - QuickbooksNoMatchingAccount - QuickbooksNonPostingAccountType - QuickbooksNotConfigured - QuickbooksOAuthCallbackInvalid - QuickbooksOAuthError - QuickbooksTokenExpired - ResourceArchived - ScheduleCNotConfigured - SmsNotEnabled - SpecifiedBadRequest - SpecifiedIdNotFound - SplitTransactionError - StepEvaluationBadRequest - StripeConnectAccountIdNotFound - StripeCredentialsNotConfigured - StripeGetBalanceForConnectAccountFailure - StripeRedirectOrRefreshUrlNotConfigured - TagFilterNotFound - UnexpectedQueryParam - UnitAccountsInUse - WrongAnswerType CreateVendorRefundAllocationLineItemParams: type: object properties: external_id: type: string nullable: true description: An external identifier for the line item. amount: type: integer format: int64 description: The amount of this line item in cents. account_identifier: $ref: '#/components/schemas/AccountIdentifier' description: Identifier of the ledger account for this line item. prepayment_account_identifier: $ref: '#/components/schemas/AccountIdentifier' nullable: true description: Identifier of the prepayment ledger account for this line item. tags: type: array items: $ref: '#/components/schemas/TagKeyValue' description: Tags to associate with the line item. memo: type: string nullable: true description: Memo for any text you would like to associate with the line item. metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the vendor refund allocation line item. required: - amount - account_identifier description: Parameters for creating a vendor refund allocation line item. AccountIdentifier: oneOf: - $ref: '#/components/schemas/AccountId' description: ID of the account. title: Account ID - $ref: '#/components/schemas/AccountStableName' description: Stable name associated with the account. title: Account Stable Name ApiVendorRefundAllocationLineItem: type: object properties: external_id: type: string nullable: true description: External identifier for the line item. amount: type: integer format: int64 description: Amount of the line item in cents. ledger_account: $ref: '#/components/schemas/SingleApiChartAccount' nullable: true description: The ledger account associated with this line item. prepayment_account: $ref: '#/components/schemas/SingleApiChartAccount' nullable: true description: >- The prepayment account associated with this line item, if applicable. transaction_tags: type: array items: $ref: '#/components/schemas/ApiTag' memo: type: string nullable: true description: Memo for any text you would like to associate with the line item. metadata: $ref: '#/components/schemas/PlatformDefinedJson' nullable: true description: Arbitrary custom metadata in JSON format with a size limit of 1KB. reference_number: type: string nullable: true description: >- Any (typically user-visible) identifier you would like to associate with the vendor refund allocation line item. ApiVendorData: type: object properties: id: type: string format: uuid description: Unique identifier for the vendor. external_id: type: string description: >- Unique ID of the vendor in your system for linking purposes. **Idempotency key**. individual_name: type: string nullable: true description: Full name of the individual vendor or contact at a corporate vendor. company_name: type: string nullable: true description: Name of the company vendor. email: type: string nullable: true description: Email address of the vendor. mobile_phone: type: string nullable: true description: Mobile phone number of the vendor. office_phone: type: string nullable: true description: Office phone number of the vendor. address_string: type: string nullable: true description: Address of the vendor. memo: type: string nullable: true description: >- Memo for any text you would like to associate with the vendor (for example, to display to end users). status: type: string enum: - ACTIVE - ARCHIVED description: Status of the vendor. transaction_tags: type: array items: $ref: '#/components/schemas/ApiTag' SingleApiChartAccount: type: object properties: id: $ref: '#/components/schemas/AccountIdentifier' name: type: string description: Name of the account. example: Current Assets account_number: type: string nullable: true description: Account number if configured. example: '4000' stable_name: $ref: '#/components/schemas/AccountStableName' normality: $ref: '#/components/schemas/BankTransactionDirection' account_type: $ref: '#/components/schemas/ApiLedgerAccountType' account_subtype: $ref: '#/components/schemas/ApiLedgerAccountSubtype' description: A single ledger account without nested children. AccountId: type: object required: - type - id properties: type: type: string enum: - AccountId description: Resource type. Value will be `AccountId`. example: AccountId id: type: string format: uuid description: ID of the account. AccountStableName: type: object required: - type - stable_name properties: type: type: string enum: - StableName description: Resource type. Value will be `StableName`. example: StableName stable_name: type: string example: CURRENT_ASSETS description: Stable name of the account. BankTransactionDirection: type: string enum: - CREDIT - DEBIT ApiLedgerAccountType: type: object properties: value: $ref: '#/components/schemas/LedgerAccountType' description: Type of the account. display_name: type: string description: Display name of the account type. example: Asset ApiLedgerAccountSubtype: type: object properties: value: $ref: '#/components/schemas/LedgerAccountSubtype' display_name: type: string description: Display name of the account subtype. example: Current Assets LedgerAccountType: type: string enum: - ASSET - LIABILITY - EQUITY - REVENUE - COGS - EXPENSE LedgerAccountSubtype: type: string enum: - BANK_ACCOUNTS - ACCOUNTS_RECEIVABLE - INVENTORY - PAYMENT_PROCESSOR_CLEARING_ACCOUNT - FIXED_ASSET - ACCUMULATED_DEPRECIATION - CASH - UNDEPOSITED_FUNDS - CURRENT_ASSET - NON_CURRENT_ASSET - PREPAID_EXPENSES - DEVELOPMENT_COSTS - LOANS_RECEIVABLE - INTANGIBLE_ASSET - ACCOUNTS_PAYABLE - CREDIT_CARD - TAXES_PAYABLE - INCOME_TAXES_PAYABLE - SALES_TAXES_PAYABLE - OTHER_TAXES_PAYABLE - PAYROLL_TAXES_PAYABLE - UNEARNED_REVENUE - PAYROLL_LIABILITY - PAYROLL_CLEARING - LINE_OF_CREDIT - TIPS - REFUND_LIABILITIES - UNDEPOSITED_OUTFLOWS - OUTGOING_PAYMENT_CLEARING_ACCOUNT - OTHER_CURRENT_LIABILITY - LOANS_PAYABLE - NOTES_PAYABLE - SHAREHOLDER_LOAN - NON_CURRENT_LIABILITY - CONTRIBUTIONS - DISTRIBUTIONS - COMMON_STOCK - PREFERRED_STOCK - ADDITIONAL_PAID_IN_CAPITAL - RETAINED_EARNINGS - ACCUMULATED_ADJUSTMENTS - OPENING_BALANCE_EQUITY - OTHER_EQUITY - SALES - UNCATEGORIZED_REVENUE - RETURNS_ALLOWANCES - DIVIDEND_INCOME - INTEREST_INCOME - OTHER_INCOME - COGS - OPERATING_EXPENSES - PAYROLL - TAXES_LICENSES - UNCATEGORIZED_EXPENSE - CHARITABLE_CONTRIBUTIONS - LOAN_EXPENSES - FINANCE_COSTS - INTEREST_EXPENSES - DEPRECIATION - AMORTIZATION - BAD_DEBT - OTHER_EXPENSES securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````