> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md # Create bill POST https://api-sandbox.payabli.com/api/Bill/single/{entry} Content-Type: application/json Creates a bill in an entrypoint. Reference: https://docs.payabli.com/developers/api-reference/bill/add-bill ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: payabliApi-oas version: 1.0.0 paths: /Bill/single/{entry}: post: operationId: AddBill summary: Add bill description: Creates a bill in an entrypoint. tags: - Bill parameters: - name: entry in: path description: >- The paypoint's entrypoint identifier. [Learn more](/developers/api-reference/api-overview#entrypoint-vs-entry) required: true schema: type: string - name: requestToken in: header description: > Long-lived API token sent in the `requestToken` header. See [API token authentication](/developers/api-tokens). required: true schema: type: string - name: idempotencyKey in: header description: >- _Optional but recommended_ A unique ID that you can include to prevent duplicating objects or transactions in the case that a request is sent more than once. This key isn't generated in Payabli, you must generate it yourself. This key persists for 2 minutes. After 2 minutes, you can reuse the key if needed. required: false schema: $ref: '#/components/schemas/IdempotencyKey' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BillResponse' '400': description: Bad request / invalid data. content: application/json: schema: $ref: '#/components/schemas/PayabliErrorBody' '401': description: Unauthorized request. content: application/json: schema: $ref: '#/components/schemas/PayabliErrorBody' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/PayabliErrorBody' '503': description: Database connection error. content: application/json: schema: $ref: '#/components/schemas/PayabliErrorBody' requestBody: content: application/json: schema: $ref: '#/components/schemas/BillOutData' servers: - url: https://api-sandbox.payabli.com/api description: Sandbox - url: https://api.payabli.com/api description: Production components: schemas: IdempotencyKey: type: string description: > _Optional but recommended._ A unique ID that you can include to prevent duplicating objects or transactions in the case that a request is sent more than once. This key isn't generated in Payabli; you must generate it yourself. The key persists for 2 minutes. After 2 minutes, you can reuse the key if needed. title: IdempotencyKey AccountingField: type: string description: Optional custom field. title: AccountingField AdditionalDataString: type: string description: > Custom dictionary of key:value pairs. You can use this field to store any data related to the object or for your system. Example usage: ```json { "additionalData": { "key1": "value1", "key2": "value2", "key3": "value3" } } ``` title: AdditionalDataString FileContentFtype: type: string enum: - pdf - doc - docx - jpg - jpeg - png - gif - txt description: The MIME type of the file (if content is provided). title: FileContentFtype FileContent: type: object properties: fContent: type: string description: | Content of file, Base64-encoded. Ignored if `furl` is specified. Max upload size is 30 MB. filename: type: string description: The name of the attached file. ftype: $ref: '#/components/schemas/FileContentFtype' furl: type: string description: Optional URL provided to show or download the file remotely. description: Contains details about a file. Max upload size is 30 MB. title: FileContent Attachments: type: array items: $ref: '#/components/schemas/FileContent' description: > Array of `fileContent` objects with attached documents. Max upload size is 30 MB. title: Attachments ItemCommodityCode: type: string description: Item or product commodity code. Max length of 250 characters. title: ItemCommodityCode ItemDescription: type: string description: Item or product description. Max length of 250 characters. title: ItemDescription ItemProductCode: type: string description: Item or product code. Max length of 250 characters. title: ItemProductCode ItemProductName: type: string description: Item or product name. Max length of 250 characters. title: ItemProductName ItemUnitofMeasure: type: string description: Unit of measurement. Max length of 100 characters. title: ItemUnitofMeasure BillItem: type: object properties: itemCategories: type: array items: type: string description: Array of tags classifying item or product. itemCommodityCode: $ref: '#/components/schemas/ItemCommodityCode' itemCost: type: number format: double description: Item or product price per unit. itemDescription: $ref: '#/components/schemas/ItemDescription' itemMode: type: integer description: > Internal class of item or product: value `0` is only for invoices, `1` for bills, and `2` is common for both. Required on invoice line items — invoice creation fails with `Invalid item data` if it's omitted. itemProductCode: $ref: '#/components/schemas/ItemProductCode' itemProductName: $ref: '#/components/schemas/ItemProductName' itemQty: type: integer description: Quantity of item or product. itemTaxAmount: type: number format: double description: Tax amount applied to item or product. itemTaxRate: type: number format: double description: Tax rate applied to item or product. itemTotalAmount: type: number format: double description: > Per-line total for this item (unit cost times quantity). Distinct from the invoice's overall total, `invoiceAmount`. Required on invoice line items. itemUnitOfMeasure: $ref: '#/components/schemas/ItemUnitofMeasure' title: BillItem Billitems: type: array items: $ref: '#/components/schemas/BillItem' description: Array of `LineItems` contained in bill. title: Billitems Comments: type: string description: Any comment or description. title: Comments Frequency: type: string enum: - onetime - weekly - every2weeks - every6months - monthly - every3months - annually - firstofmonth - fifteenthofmonth - endofmonth description: > Frequency for operation. The `firstofmonth`, `fifteenthofmonth`, and `endofmonth` values are only valid on subscriptions — they aren't accepted by other endpoints (such as invoice scheduling) that use this enum. title: Frequency BillOutDataScheduledOptions: type: object properties: storedMethodId: type: string description: The ID of the stored payment method to use for the bill. description: Options for scheduled bills. title: BillOutDataScheduledOptions Billstatus: type: integer description: | The bill's status. Values are: - `-99`: deleted or canceled - `1`: Active - `2`: Sent to approval - `5`: Partially approved - `11`: Rejected - `20`: Approved - `50`: Payment in transit - `100`: Paid title: Billstatus Terms: type: string enum: - PIA - CIA - UR - NET10 - NET20 - NET30 - NET45 - NET60 - NET90 - EOM - MFI - 5MFI - 10MFI - 15MFI - 20MFI - 2/10NET30 - UF - 10UF - 20UF - 25UF - 50UF description: > Payment terms for invoice. If no terms are defined, then response data for this field defaults to `NET30`. title: Terms VendorNumber: type: string description: > Custom number identifying the vendor. Must be unique in paypoint. Can't be blank. title: VendorNumber BillOutDataVendor: type: object properties: vendorNumber: $ref: '#/components/schemas/VendorNumber' description: | The vendor associated with the bill. Although you can create a vendor in a create bill request, Payabli recommends creating a vendor separately and passing a valid `vendorNumber` here. At minimum, the `vendorNumber` is required. title: BillOutDataVendor BillOutData: type: object properties: accountingField1: $ref: '#/components/schemas/AccountingField' accountingField2: $ref: '#/components/schemas/AccountingField' additionalData: $ref: '#/components/schemas/AdditionalDataString' attachments: $ref: '#/components/schemas/Attachments' description: > An array of bill images. Attachments aren't required, but we strongly recommend including them. Including a bill image can make payouts smoother and prevent delays. You can include either the Base64-encoded file content, or you can include a `furl` to a public file. The maximum file size for image uploads is 30 MB. When vendor enrichment is enabled and the first attachment is a PDF, the invoice is scanned and extracted vendor contact information and bill details (invoice number, amount due, due date) are merged into the request. Fields in the request body take precedence over extracted data. If the scan fails, bill creation proceeds with the original request data. See the [vendor enrichment guide](/guides/pay-out-vendor-enrichment-overview) for details. Contact Payabli to enable this feature. billDate: type: string format: date description: 'Date of bill. Accepted formats: YYYY-MM-DD, MM/DD/YYYY.' billItems: $ref: '#/components/schemas/Billitems' billNumber: type: string description: Unique identifier for the bill. Required when adding a bill. comments: $ref: '#/components/schemas/Comments' discount: type: number format: double description: Discount amount applied to the bill. dueDate: type: string format: date description: 'Due date of bill. Accepted formats: YYYY-MM-DD, MM/DD/YYYY.' endDate: type: string format: date description: | End date for scheduled bills. Applied only in `Mode` = 1. Accepted formats: YYYY-MM-DD, MM/DD/YYYY. frequency: $ref: '#/components/schemas/Frequency' lotNumber: type: string description: Lot number associated with the bill. mode: type: integer description: 'Bill mode: value `0` for one-time bills, `1` for scheduled bills.' netAmount: type: number format: double description: Net amount owed in bill. Required when adding a bill. scheduledOptions: $ref: '#/components/schemas/BillOutDataScheduledOptions' status: $ref: '#/components/schemas/Billstatus' terms: $ref: '#/components/schemas/Terms' totalAmount: type: number format: double description: Total amount of the bill. vendor: $ref: '#/components/schemas/BillOutDataVendor' description: > The vendor associated with the bill. Although you can create a vendor in a create bill request, Payabli recommends creating a vendor separately and passing a valid `vendorNumber` here. At minimum, the `vendorNumber` is required. description: Bill payload sent when creating or updating a bill. title: BillOutData Responsecode: type: integer description: | Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses). title: Responsecode PageIdentifier: type: string description: Auxiliary validation used internally by payment pages and components. title: PageIdentifier RoomIdNotInUse: type: integer format: int64 description: Field not in use on this endpoint. It always returns `0`. title: RoomIdNotInUse IsSuccess: type: boolean description: | Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure. title: IsSuccess ResponseText: type: string description: | Response text for operation: 'Success' or 'Declined'. title: ResponseText Responsedatanonobject: oneOf: - type: string - type: integer description: The response data. title: Responsedatanonobject BillResponse: type: object properties: responseCode: $ref: '#/components/schemas/Responsecode' pageIdentifier: oneOf: - $ref: '#/components/schemas/PageIdentifier' - type: 'null' roomId: $ref: '#/components/schemas/RoomIdNotInUse' isSuccess: $ref: '#/components/schemas/IsSuccess' responseText: $ref: '#/components/schemas/ResponseText' responseData: $ref: '#/components/schemas/Responsedatanonobject' description: | If `isSuccess` = true, this contains the bill identifier. If `isSuccess` = false, this contains the reason for the error. required: - responseText description: Response wrapper for bill operations. title: BillResponse PayabliErrorBodyResponseData: type: object properties: explanation: type: string description: Human-readable explanation of what happened. todoAction: type: string description: Suggested resolution. description: Object with detailed error context. title: PayabliErrorBodyResponseData PayabliErrorBody: type: object properties: isSuccess: type: boolean description: Always `false` for error responses. responseCode: type: integer description: | Code for the response. Learn more in [API Response Codes](/developers/api-reference/api-responses). responseText: type: string description: Error text describing what went wrong. responseData: $ref: '#/components/schemas/PayabliErrorBodyResponseData' description: Object with detailed error context. required: - isSuccess - responseText description: | Shape returned by every Payabli API error response. The `responseData` object carries human-readable error context. title: PayabliErrorBody securitySchemes: APIKeyAuth: type: apiKey in: header name: requestToken description: > Long-lived API token sent in the `requestToken` header. See [API token authentication](/developers/api-tokens). BearerAuth: type: http scheme: bearer description: > OAuth2 Bearer access token from the client-credentials flow. See [OAuth authentication](/developers/oauth-authentication). ``` ## Examples **Request** ```json { "accountingField1": "MyInternalId", "attachments": [ { "filename": "my-doc.pdf", "ftype": "pdf", "furl": "https://mysite.com/my-doc.pdf" } ], "billDate": "2024-07-01", "billItems": [ { "itemCategories": [ "deposits" ], "itemCommodityCode": "010", "itemCost": 5, "itemDescription": "Deposit for materials", "itemMode": 0, "itemProductCode": "M-DEPOSIT", "itemProductName": "Materials deposit", "itemQty": 1, "itemTaxAmount": 7, "itemTaxRate": 0.075, "itemTotalAmount": 123, "itemUnitOfMeasure": "SqFt" } ], "billNumber": "ABC-123", "comments": "Deposit for materials", "dueDate": "2024-07-01", "endDate": "2024-07-01", "frequency": "monthly", "mode": 0, "netAmount": 3762.87, "status": 1, "terms": "NET30", "vendor": { "vendorNumber": "VEN-123" } } ``` **Response** ```json { "responseText": "Success", "responseCode": 1, "pageIdentifier": null, "roomId": 0, "isSuccess": true, "responseData": 6101 } ``` **SDK Code** ```typescript import { PayabliClient } from "@payabli/sdk-node"; async function main() { const client = new PayabliClient({ apiKey: "YOUR_API_KEY_HERE", }); await client.bill.addBill("8cfec329267", { body: { accountingField1: "MyInternalId", attachments: [ { filename: "my-doc.pdf", ftype: "pdf", furl: "https://mysite.com/my-doc.pdf", }, ], billDate: "2024-07-01", billItems: [ { itemCategories: [ "deposits", ], itemCommodityCode: "010", itemCost: 5, itemDescription: "Deposit for materials", itemMode: 0, itemProductCode: "M-DEPOSIT", itemProductName: "Materials deposit", itemQty: 1, itemTaxAmount: 7, itemTaxRate: 0.075, itemTotalAmount: 123, itemUnitOfMeasure: "SqFt", }, ], billNumber: "ABC-123", comments: "Deposit for materials", dueDate: "2024-07-01", endDate: "2024-07-01", frequency: "monthly", mode: 0, netAmount: 3762.87, status: 1, terms: "NET30", vendor: { vendorNumber: "VEN-123", }, }, }); } main(); ``` ```python from payabli import payabli, FileContent, BillItem, BillOutDataVendor import datetime client = payabli( api_key="YOUR_API_KEY_HERE", ) client.bill.add_bill( entry="8cfec329267", accounting_field_1="MyInternalId", attachments=[ FileContent( filename="my-doc.pdf", ftype="pdf", furl="https://mysite.com/my-doc.pdf", ) ], bill_date=datetime.date.fromisoformat("2024-07-01"), bill_items=[ BillItem( item_categories=[ "deposits" ], item_commodity_code="010", item_cost=5, item_description="Deposit for materials", item_mode=0, item_product_code="M-DEPOSIT", item_product_name="Materials deposit", item_qty=1, item_tax_amount=7, item_tax_rate=0.075, item_total_amount=123, item_unit_of_measure="SqFt", ) ], bill_number="ABC-123", comments="Deposit for materials", due_date=datetime.date.fromisoformat("2024-07-01"), end_date=datetime.date.fromisoformat("2024-07-01"), frequency="monthly", mode=0, net_amount=3762.87, status=1, terms="NET30", vendor=BillOutDataVendor( vendor_number="VEN-123", ), ) ``` ```java package com.example.usage; import io.github.payabli.api.PayabliPayabliApiOasClient; import io.github.payabli.api.resources.bill.requests.AddBillRequest; import io.github.payabli.api.types.BillItem; import io.github.payabli.api.types.BillOutData; import io.github.payabli.api.types.BillOutDataVendor; import io.github.payabli.api.types.FileContent; import io.github.payabli.api.types.FileContentFtype; import io.github.payabli.api.types.Frequency; import io.github.payabli.api.types.Terms; import java.util.Arrays; import java.util.Optional; public class Example { public static void main(String[] args) { PayabliPayabliApiOasClient client = PayabliPayabliApiOasClient .builder() .apiKey("YOUR_API_KEY_HERE") .build(); client.bill().addBill( "8cfec329267", AddBillRequest .builder() .body( BillOutData .builder() .accountingField1("MyInternalId") .attachments( Arrays.asList( FileContent .builder() .filename("my-doc.pdf") .ftype(FileContentFtype.PDF) .furl("https://mysite.com/my-doc.pdf") .build() ) ) .billDate("2024-07-01") .billItems( Arrays.asList( BillItem .builder() .itemCategories( Optional.of( Arrays.asList("deposits") ) ) .itemCommodityCode("010") .itemCost(5.0) .itemDescription("Deposit for materials") .itemMode(0) .itemProductCode("M-DEPOSIT") .itemProductName("Materials deposit") .itemQty(1) .itemTaxAmount(7.0) .itemTaxRate(0.075) .itemTotalAmount(123.0) .itemUnitOfMeasure("SqFt") .build() ) ) .billNumber("ABC-123") .comments("Deposit for materials") .dueDate("2024-07-01") .endDate("2024-07-01") .frequency(Frequency.MONTHLY) .mode(0) .netAmount(3762.87) .status(1) .terms(Terms.NET_30) .vendor( BillOutDataVendor .builder() .vendorNumber("VEN-123") .build() ) .build() ) .build() ); } } ``` ```ruby require "payabli" client = Payabli::Client.new(api_key: "YOUR_API_KEY_HERE") client.bill.add_bill( entry: "8cfec329267", accounting_field_1: "MyInternalId", attachments: [{ filename: "my-doc.pdf", ftype: "pdf", furl: "https://mysite.com/my-doc.pdf" }], bill_date: "2024-07-01", bill_items: [{ item_categories: ["deposits"], item_commodity_code: "010", item_cost: 5, item_description: "Deposit for materials", item_mode: 0, item_product_code: "M-DEPOSIT", item_product_name: "Materials deposit", item_qty: 1, item_tax_amount: 7, item_tax_rate: 0.075, item_total_amount: 123, item_unit_of_measure: "SqFt" }], bill_number: "ABC-123", comments: "Deposit for materials", due_date: "2024-07-01", end_date: "2024-07-01", frequency: "monthly", mode: 0, net_amount: 3762.87, status: 1, terms: "NET30", vendor: { vendor_number: "VEN-123" } ) ``` ```csharp using PayabliPayabliApiOas; using System.Threading.Tasks; using System.Collections.Generic; using System; namespace Usage; public class Example { public async Task Do() { var client = new PayabliPayabliApiOasClient( apiKey: "YOUR_API_KEY_HERE" ); await client.Bill.AddBillAsync( "8cfec329267", new AddBillRequest { Body = new BillOutData { AccountingField1 = "MyInternalId", Attachments = new List(){ new FileContent { Filename = "my-doc.pdf", Ftype = FileContentFtype.Pdf, Furl = "https://mysite.com/my-doc.pdf" }, } , BillDate = DateOnly.Parse("2024-07-01"), BillItems = new List(){ new BillItem { ItemCategories = new List(){ "deposits", } , ItemCommodityCode = "010", ItemCost = 5, ItemDescription = "Deposit for materials", ItemMode = 0, ItemProductCode = "M-DEPOSIT", ItemProductName = "Materials deposit", ItemQty = 1, ItemTaxAmount = 7, ItemTaxRate = 0.075, ItemTotalAmount = 123, ItemUnitOfMeasure = "SqFt" }, } , BillNumber = "ABC-123", Comments = "Deposit for materials", DueDate = DateOnly.Parse("2024-07-01"), EndDate = DateOnly.Parse("2024-07-01"), Frequency = Frequency.Monthly, Mode = 0, NetAmount = 3762.87, Status = 1, Terms = Terms.Net30, Vendor = new BillOutDataVendor { VendorNumber = "VEN-123" } } } ); } } ``` ```go package example import ( context "context" payabli "github.com/payabli/sdk-go" client "github.com/payabli/sdk-go/client" option "github.com/payabli/sdk-go/option" ) func do() { client := client.NewClient( option.WithApiKey( "YOUR_API_KEY_HERE", ), ) request := &payabli.AddBillRequest{ Body: &payabli.BillOutData{ AccountingField1: payabli.String( "MyInternalId", ), Attachments: &payabli.Attachments{ &payabli.FileContent{ Filename: payabli.String( "my-doc.pdf", ), Ftype: payabli.FileContentFtypePdf.Ptr(), Furl: payabli.String( "https://mysite.com/my-doc.pdf", ), }, }, BillDate: payabli.Time( payabli.MustParseDate( "2024-07-01", ), ), BillItems: &payabli.Billitems{ &payabli.BillItem{ ItemCategories: []string{ "deposits", }, ItemCommodityCode: payabli.String( "010", ), ItemCost: payabli.Float64( 5, ), ItemDescription: payabli.String( "Deposit for materials", ), ItemMode: payabli.Int( 0, ), ItemProductCode: payabli.String( "M-DEPOSIT", ), ItemProductName: payabli.String( "Materials deposit", ), ItemQty: payabli.Int( 1, ), ItemTaxAmount: payabli.Float64( 7, ), ItemTaxRate: payabli.Float64( 0.075, ), ItemTotalAmount: payabli.Float64( 123, ), ItemUnitOfMeasure: payabli.String( "SqFt", ), }, }, BillNumber: payabli.String( "ABC-123", ), Comments: payabli.String( "Deposit for materials", ), DueDate: payabli.Time( payabli.MustParseDate( "2024-07-01", ), ), EndDate: payabli.Time( payabli.MustParseDate( "2024-07-01", ), ), Frequency: payabli.FrequencyMonthly.Ptr(), Mode: payabli.Int( 0, ), NetAmount: payabli.Float64( 3762.87, ), Status: payabli.Int( 1, ), Terms: payabli.TermsNet30.Ptr(), Vendor: &payabli.BillOutDataVendor{ VendorNumber: payabli.String( "VEN-123", ), }, }, } client.Bill.AddBill( context.TODO(), "8cfec329267", request, ) } ``` ```php bill->addBill( '8cfec329267', new AddBillRequest([ 'body' => new BillOutData([ 'accountingField1' => 'MyInternalId', 'attachments' => [ new FileContent([ 'filename' => 'my-doc.pdf', 'ftype' => FileContentFtype::Pdf->value, 'furl' => 'https://mysite.com/my-doc.pdf', ]), ], 'billDate' => new DateTime('2024-07-01'), 'billItems' => [ new BillItem([ 'itemCategories' => [ 'deposits', ], 'itemCommodityCode' => '010', 'itemCost' => 5, 'itemDescription' => 'Deposit for materials', 'itemMode' => 0, 'itemProductCode' => 'M-DEPOSIT', 'itemProductName' => 'Materials deposit', 'itemQty' => 1, 'itemTaxAmount' => 7, 'itemTaxRate' => 0.075, 'itemTotalAmount' => 123, 'itemUnitOfMeasure' => 'SqFt', ]), ], 'billNumber' => 'ABC-123', 'comments' => 'Deposit for materials', 'dueDate' => new DateTime('2024-07-01'), 'endDate' => new DateTime('2024-07-01'), 'frequency' => Frequency::Monthly->value, 'mode' => 0, 'netAmount' => 3762.87, 'status' => 1, 'terms' => Terms::Net30->value, 'vendor' => new BillOutDataVendor([ 'vendorNumber' => 'VEN-123', ]), ]), ]), ); ``` ```swift import Foundation let headers = [ "requestToken": "", "Content-Type": "application/json" ] let parameters = [ "accountingField1": "MyInternalId", "attachments": [ [ "filename": "my-doc.pdf", "ftype": "pdf", "furl": "https://mysite.com/my-doc.pdf" ] ], "billDate": "2024-07-01", "billItems": [ [ "itemCategories": ["deposits"], "itemCommodityCode": "010", "itemCost": 5, "itemDescription": "Deposit for materials", "itemMode": 0, "itemProductCode": "M-DEPOSIT", "itemProductName": "Materials deposit", "itemQty": 1, "itemTaxAmount": 7, "itemTaxRate": 0.075, "itemTotalAmount": 123, "itemUnitOfMeasure": "SqFt" ] ], "billNumber": "ABC-123", "comments": "Deposit for materials", "dueDate": "2024-07-01", "endDate": "2024-07-01", "frequency": "monthly", "mode": 0, "netAmount": 3762.87, "status": 1, "terms": "NET30", "vendor": ["vendorNumber": "VEN-123"] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/Bill/single/8cfec329267")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```