> ## Documentation Index > Fetch the complete documentation index at: https://docs-beta.layerfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Create vendor payout > Creates a new vendor payout for a business or updates existing vendor payout. 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}/vendor-payouts openapi: 3.0.1 info: title: API version: latest servers: [] security: - BearerAuth: [] tags: [] externalDocs: url: / paths: /v1/businesses/{businessId}/vendor-payouts: post: tags: [] summary: Create vendor payout description: >- Creates a new vendor payout for a business or updates existing vendor payout. 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.vendor-payouts.post parameters: - name: businessId in: path description: The UUID of the business to create a vendor payout for required: true schema: type: string - name: Content-Type in: header description: Content-Type must be set to application/json schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateVendorPayoutParams' responses: '200': description: Vendor payout has been successfully updated or unchanged. headers: {} content: application/json: schema: $ref: '#/components/schemas/ApiVendorPayout' '201': description: Vendor payout successfully created. headers: {} content: application/json: schema: $ref: '#/components/schemas/ApiVendorPayout' '400': description: >- A vendor payout may be invalid if the bill payments, vendor refund payments, and other transactions do not total the payout amount, if the referenced payment or refund ids have different values than those in the payout creation parameters, or if duplicate payments or refunds are 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' deprecated: false components: schemas: CreateVendorPayoutParams: type: object properties: external_id: type: string nullable: true description: Unique ID of the vendor payout in your system for linking purposes. example: vendor-payout-1234 paid_out_amount: type: integer format: int64 description: >- The amount of the vendor payout, in cents. This amount can be negative if vendor refunds exceed bill payments. processor: $ref: '#/components/schemas/PaymentProcessor' nullable: true description: >- Processor used to make the payment. If not null, every bill payment or vendor refund payment associated with the vendor payout must have the same processor example: STRIPE completed_at: type: string format: date-time description: Timestamp of when the vendor payout was completed bill_payments: type: array items: $ref: '#/components/schemas/VendorPayoutPaymentInput' description: List of bill payments to associate with the vendor payout vendor_refund_payments: type: array items: $ref: '#/components/schemas/VendorPayoutRefundInput' description: List of vendor refund payments to associate with the vendor payout other_transactions: type: array items: $ref: '#/components/schemas/OtherVendorPayoutTransactionInput' description: A list of other transactions associated with the vendor payout tags: type: array items: $ref: '#/components/schemas/TagKeyValue' memo: type: string nullable: true description: >- Memo for any text you would like to associate with the vendor payout (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 payout. Can be used to filter when listing vendor payouts. ApiVendorPayout: type: object properties: id: type: string format: uuid description: Unique ID for the Vendor Payout. **Idempotency key.** external_id: type: string nullable: true description: Unique ID of the vendor payout in your system for linking purposes. example: vendor-payout-1234 business_id: type: string format: uuid description: ID of the Business that generated the vendor payout. paid_out_amount: type: integer format: int64 description: The amount of the vendor payout, in cents processor: $ref: '#/components/schemas/PaymentProcessor' nullable: true description: >- Processor used to make the payment, if any. If not null, every bill payment or vendor refund payment associated with the vendor payout must have the same processor example: STRIPE imported_at: type: string format: date-time description: Timestamp of when the vendor payout was imported completed_at: type: string format: date-time description: Timestamp of when the vendor payout was completed payments: type: array items: $ref: '#/components/schemas/ApiBillPayment' description: A list of bill payments associated with the vendor payout refunds: type: array items: $ref: '#/components/schemas/ApiVendorRefund' description: A list of vendor refund payments associated with the vendor payout other_transactions: type: array items: $ref: '#/components/schemas/ApiOtherVendorPayoutTransaction' description: A list of other transactions associated with the vendor payout transaction_tags: type: array items: $ref: '#/components/schemas/ApiTag' description: A list of tags associated with the vendor payout match: $ref: '#/components/schemas/ApiMatch' nullable: true description: The transaction match associated with the vendor payout suggested_matches: type: array items: $ref: '#/components/schemas/ApiSuggestedMatch' description: A list of suggested matches for the vendor payout memo: type: string nullable: true description: >- Memo for any text you would like to associate with the vendor payout (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 payout. Can be used to filter when listing vendor payouts. ApiError: type: object properties: {} example: '' description: '' PaymentProcessor: type: string enum: - STRIPE - PAYPAL - SHOPIFY - ADYEN - RAINFOREST VendorPayoutPaymentInput: type: object properties: bill_payment_id: type: string format: uuid nullable: true description: UUID of the bill payment to associate with the vendor payout bill_payment_external_id: type: string nullable: true description: External ID of the bill payment to associate with the vendor payout description: >- At least one of bill_payment_id or bill_payment_external_id must be specified VendorPayoutRefundInput: type: object properties: vendor_refund_payment_id: type: string format: uuid nullable: true description: >- UUID of the vendor refund payment to associate with the vendor payout vendor_refund_payment_external_id: type: string nullable: true description: >- External ID of the vendor refund payment to associate with the vendor payout description: >- At least one of vendor_refund_payment_id or vendor_refund_payment_external_id must be specified OtherVendorPayoutTransactionInput: type: object properties: amount: type: integer format: int64 description: >- Amount of the transaction, in cents. This amount must be a positive value. direction: $ref: '#/components/schemas/BankTransactionDirection' description: Direction of the transaction. account: $ref: '#/components/schemas/AccountIdentifier' description: Account identifier for the transaction. description: type: string description: Description of the transaction. external_id: type: string nullable: true description: External ID of the transaction in your system for linking purposes. 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: [] ApiBillPayment: type: object properties: id: type: string format: uuid description: Unique identifier for the payment external_id: type: string nullable: true description: External ID for the payment at: type: string format: date-time description: When the payment was made method: $ref: '#/components/schemas/PaymentMethod' description: Method used for payment amount: type: integer format: int64 description: Payment amount in cents processor: type: string nullable: true description: Payment processor used 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. imported_at: type: string format: date-time description: When the payment was imported allocations: type: array items: $ref: '#/components/schemas/ApiBillPaymentAllocation' description: How the payment is allocated across bills transaction_tags: type: array items: $ref: '#/components/schemas/ApiTag' description: Tags associated with the payment memo: type: string nullable: true description: >- Memo for any text you would like to associate with the bill 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 bill payment. Can be used to filter when listing bill payments. 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. ApiOtherVendorPayoutTransaction: type: object properties: id: type: string format: uuid description: Unique ID for the other vendor payout transaction. amount: type: integer format: int64 description: Amount of the transaction, in cents direction: $ref: '#/components/schemas/BankTransactionDirection' description: Direction of the transaction account: $ref: '#/components/schemas/AccountIdentifier' description: Account identifier for the transaction description: type: string description: Description of the transaction external_id: type: string nullable: true description: External ID of the transaction 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 ApiMatch: type: object properties: id: type: string format: uuid description: Layer's UUID for the match match_type: $ref: '#/components/schemas/MatchType' description: Type of the object to match bank_transaction: $ref: '#/components/schemas/ApiBankTransactionInterface' details: $ref: '#/components/schemas/ApiMatchDetails' ApiSuggestedMatch: type: object properties: id: type: string format: uuid description: Layer's identifier for the suggested match matchType: $ref: '#/components/schemas/MatchType' description: 'Type of the matched object. ' details: $ref: '#/components/schemas/ApiMatchDetails' description: Details of the suggested match BankTransactionDirection: type: string enum: - CREDIT - DEBIT 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 PaymentMethod: type: string enum: - CASH - CHECK - CREDIT_CARD - ACH - CREDIT_BALANCE - OTHER 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 ApiBillPaymentAllocation: type: object properties: id: type: string format: uuid description: Unique identifier for the allocation bill_id: type: string format: uuid description: ID of the bill payment_id: type: string format: uuid description: ID of the payment amount: type: integer format: int64 description: Amount allocated in cents transaction_tags: type: array items: $ref: '#/components/schemas/ApiTag' description: Tags associated with the allocation memo: type: string nullable: true description: >- Memo for any text you would like to associate with the bill payment 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 bill payment allocation. 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. MatchType: type: string enum: - TRANSFER - INVOICE_PAYMENT - PAYOUT ApiBankTransactionInterface: type: object required: - id - amount - date properties: id: type: string format: uuid description: Layer's UUID for the bank transaction business_id: type: string format: uuid description: UUID of the business the transaction is for source: $ref: '#/components/schemas/TransactionSource' description: Source of the bank transaction. source_transaction_id: type: string description: >- External transaction ID from the source platform (e.g, Plaid transaction ID) example: g4DlKyjXqGH3Kp5XlaWMtwLRrE4Z9AiE8B4Ko source_account_id: type: string description: External account ID from the source platform (e.g, Plaid account ID) example: Aaoy8G7VXZHVeqNoL1GvcmkPdqpLRWi9NArdG imported_at: type: string format: date-time description: Timestamp when the transaction was imported. date: type: string format: date-time description: Timestamp when the transaction was created. direction: $ref: '#/components/schemas/BankTransactionDirection' description: Direction of the transaction. amount: type: integer format: int64 description: Amount of the transaction, in cents. counterparty_name: type: string nullable: true description: Name of the transaction counterparty example: WeWork description: type: string nullable: true description: Description of the transaction. example: WeWork monthly rent payment account_name: type: string nullable: true description: Name of the bank account example: Plaid Checking categorizationStatus: $ref: '#/components/schemas/CategorizationStatus' description: The status of the transaction’s categorization in Layer’s systems. memo: type: string nullable: true description: >- Memo for any text you would like to associate with the bank transaction (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 bank transaction. Can be used to filter when listing bank transactions. ApiMatchDetails: type: object required: - id - amount - date properties: id: type: string format: uuid description: Layer's ID for the match amount: type: integer format: int64 description: Monetary amount of the matched transaction, in cents date: type: string format: date-time description: Date that the matched transaction occurred description: type: string nullable: true description: Description of the match example: Transfer from SavingsAccount to CheckingAccount AccountId: type: object properties: type: type: string description: Resource type. Value will be `AccountId`. example: AccountId id: type: string format: uuid description: ID of the account AccountStableName: type: object properties: type: type: string description: Resource type. Value will be `StableName`. example: StableName stable_name: type: string example: CURRENT_ASSETS description: Stable name of the account 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 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' TransactionSource: type: string enum: - UNIT - PLAID - API - STRIPE - CUSTOM CategorizationStatus: type: string enum: - PENDING - READY_FOR_INPUT - CATEGORIZED - SPLIT - LAYER_REVIEW - JOURNALING - MATCHED 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 ````