> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://beta-docs.payabli.com/api-reference/bill/add-bill/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta-docs.payabli.com/_mcp/server. # Create bill POST https://api-sandbox.payabli.com/api/Bill/single/{entry} Content-Type: application/json Creates a bill in an entrypoint. Reference: https://beta-docs.payabli.com/api-reference/bill/add-bill ## Authentication - `requestToken` header (required) — API Key authentication via header ## Servers - `https://api-sandbox.payabli.com/api` (Sandbox, default) - `https://api.payabli.com/api` (Production) ## Request ### Path parameters - `entry` (string, required) — The paypoint's entrypoint identifier. [Learn more](/api-reference/api-overview#entrypoint-vs-entry) ### Headers - `idempotencyKey` (string, optional) — _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 is not generated in Payabli, you must generate it yourself. ### Body (application/json) This endpoint expects a BillOutData. - `accountingField1` (string, optional) — Optional custom field. - `accountingField2` (string, optional) — Optional custom field. - `AdditionalData` (string, optional) — 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" } } ``` - `attachments` (list of FileContent, optional) — An arry 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 an fURL to a public file. The maximum file size for image uploads is 30 MB. - `billDate` (date, optional) — Date of bill. Accepted formats: YYYY-MM-DD, MM/DD/YYYY. - `billItems` (list of BillItem, optional) — Array of `LineItems` contained in bill. - `billNumber` (string, optional) — Unique identifier for the bill. Required when adding a bill. - `comments` (string, optional) — Any comment or description. - `dueDate` (date, optional) — Due date of bill. Accepted formats: YYYY-MM-DD, MM/DD/YYYY. - `endDate` (date, optional) — End Date for scheduled bills. Applied only in `Mode` = 1. Accepted formats: YYYY-MM-DD, MM/DD/YYYY - `frequency` (enum, optional) — Frequency for scheduled bills. Applied only in `Mode` = 1. - Allowed values: `one-time`, `weekly`, `every2weeks`, `every6months`, `monthly`, `every3months`, `annually` - `mode` (integer, optional) — Bill mode: value `0` for one-time bills, `1` for scheduled bills. - `netAmount` (string, optional) — Net Amount owed in bill. Required when adding a bill. - `status` (integer, optional) — 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 " - `terms` (string, optional) — Description of payment terms. - `vendor` (VendorData, optional) — 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. ## Response ### 200 Success - `isSuccess` (boolean, optional) — Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure. - `pageidentifier` (string, optional) — Auxiliary validation used internally by payment pages and components. - `responseCode` (integer, optional) — Code for the response. Learn more in [API Response Codes](/api-reference/api-responses). - `responseData` (Responsedatanonobject, optional) — If `isSuccess` = true, this contains the bill identifier. If `isSuccess` = false, this contains the reason for the error. - `responseText` (string, optional) — Response text for operation: 'Success' or 'Declined'. ## Errors ### 400 Bad Request Error Bad request/ invalid data - `any` ### 401 Unauthorized Error Unauthorized request. - `any` ### 500 Internal Server Error Internal API Error - `any` ### 503 Service Unavailable Error Database connection error - `isSuccess` (boolean, optional) — Boolean indicating whether the operation was successful. A `true` value indicates success. A `false` value indicates failure. - `responseData` (map from string to any, optional) — The object containing the response data. - `responseText` (string, optional) — Response text for operation: 'Success' or 'Declined'. ## Types ### FileContent Contains details about a file. See See [fileObject Object Model](/api-reference/schemas/filecontent) for a complete reference. Max upload size is 30 MB. - `fContent` (string, optional) — Content of file, Base64-encoded Ignored if furl is specified. Max upload size is 30 MB. - `filename` (string, optional) — The name of the attached file. - `ftype` (enum, optional) — The MIME type of the file (if content is provided) - Allowed values: `pdf`, `doc`, `docx`, `jpg`, `jpeg`, `png`, `gif`, `txt` - `furl` (string, optional) — Optional url provided to show or download the file remotely ### BillItem - `itemCost` (double, required) — Item or product price per unit. - `itemCategories` (list of string, optional) — Array of tags classifying item or product. - `itemCommodityCode` (string, optional) — Item or product commodity code. Max length of 250 characters. - `itemDescription` (string, optional) — Item or product description. Max length of 250 characters. - `itemMode` (integer, optional) — Internal class of item or product: value '0' is only for invoices , '1' for bills and, '2' common for both. - `itemProductCode` (string, optional) — Item or product code. Max length of 250 characters. - `itemProductName` (string, optional) — Item or product name. Max length of 250 characters. - `itemQty` (integer, optional) — Quantity of item or product. - `itemTaxAmount` (double, optional) — Tax amount applied to item or product. - `itemTaxRate` (double, optional) — Tax rate applied to item or product. - `itemTotalAmount` (double, optional) — Total amount in item or product. - `itemUnitOfMeasure` (string, optional) — Unit of measurement. Max length of 100 characters. ### VendorData - `vendorNumber` (string, optional) — Custom number identifying the vendor. Must be unique in paypoint. - `AdditionalData` (map from string to map from string to any, optional) — Custom dictionary of key:value pairs. You can use this field to store any data related to the object or for your system. If you are using [custom identifiers](/developer-guides/entities-custom-identifiers), pass those in this object. Example usage: ```json { "additionalData": { "key1": "value1", "key2": "value2", "key3": "value3" } } ``` - `address1` (string, optional) — Vendor's address - `address2` (string, optional) — Additional line for vendor's address. - `billingData` (BillingData, optional) — Object containing vendor's bank information. - `city` (string, optional) — Vendor's city. - `contacts` (list of Contacts, optional) — Array of objects describing the vendor's contacts. - `country` (string, optional) — Vendor's country. - `customerVendorAccount` (string, optional) — Account number of paypoint in the vendor side. - `ein` (string, optional) — EIN/Tax ID for vendor. - `email` (string, optional) — Vendor's email address. Required for vCard. - `internalReferenceId` (long, optional) — Internal identifier for global vendor account. - `locationCode` (string, optional) — Additional location code used to identify the vendor. - `mcc` (string, optional) — Business Merchant Category Code (MCC). [This resource](https://github.com/greggles/mcc-codes/blob/main/mcc_codes.csv) lists MCC codes. - `name1` (string, optional) — Primary name for vendor. Required for new vendor. - `name2` (string, optional) — Secondary name for vendor. - `payeeName1` (string, optional) — Alternative name used to receive paper check. - `payeeName2` (string, optional) — Alternative name used to receive paper check. - `paymentMethod` (VendorPaymentMethod, optional) — Object containing details about the payment method to use for the payout. - `phone` (string, optional) — Vendor's phone number. Phone number can't contain non-digit characters like hyphens or parentheses. - `remitAddress1` (string, optional) — Remittance address. Used for mailing paper checks. - `remitAddress2` (string, optional) — Remittance address additional line. Used for mailing paper checks. - `remitCity` (string, optional) — Remittance address city. Used for mailing paper checks. - `remitCountry` (string, optional) — Remittance address country. Used for mailing paper checks. - `remitState` (string, optional) — Remittance address state. Used for mailing paper checks. - `remitZip` (string, optional) — Remittance address ZIP code. Used for mailing paper checks. - `state` (string, optional) — Vendor's state. Must be a 2 character state code. - `vendorStatus` (integer, optional) — Vendor's status. Allowed status: - 0 Inactive - 1 Active - `zip` (string, optional) — Vendor's zip code. ### Responsedatanonobject The response data. ### BillingData - `accountNumber` (string, optional) — Account number for bank account. - `bankAccountFunction` (integer, optional) — Describes whether the bank account is used for deposits or withdrawals in Payabli: - `0`: Deposit - `1`: Withdrawal - `2`: Deposit and withdrawal - `bankAccountHolderName` (string, optional) — The accountholder's name. - `bankAccountHolderType` (enum, optional) — Describes whether the bank is a personal or business account. - Allowed values: `Personal`, `Business` - `bankName` (string, optional) — Name of bank for account. - `id` (integer, optional) — The bank's ID in Payabli. - `routingAccount` (string, optional) — Routing number of bank account. - `typeAccount` (enum, optional) — Type of bank account: Checking or Savings. - Allowed values: `Checking`, `Savings` ### Contacts - `contactEmail` (string, optional) — Contact email address. - `contactName` (string, optional) — Contact name. - `contactPhone` (string, optional) — Contact phone number. - `contactTitle` (string, optional) — Contact title. ### VendorPaymentMethod Object containing details about the payment method to use for the payout. - `method` (enum, optional) — Payment method to use for payout. Leave empty for managed payables. - Allowed values: `managed`, `vcard`, `ach`, `check` ## Examples **Request** ```json { "accountingField1": "MyInternalId", "attachments": [ { "filename": "my-doc.pdf", "ftype": "pdf", "furl": "https://mysite.com/my-doc.pdf" } ], "billDate": "2024-07-01", "billItems": [ { "itemCost": 5, "itemCategories": [ "deposits" ], "itemCommodityCode": "010", "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": -99, "terms": "NET30", "vendor": { "vendorNumber": "1234-A" } } ``` **Response** ```json { "isSuccess": true, "responseCode": 1, "responseData": 6101, "responseText": "Success" } ``` **SDK Code** ```python CreateBill import requests url = "https://api-sandbox.payabli.com/api/Bill/single/8cfec329267" payload = { "accountingField1": "MyInternalId", "attachments": [ { "filename": "my-doc.pdf", "ftype": "pdf", "furl": "https://mysite.com/my-doc.pdf" } ], "billDate": "2024-07-01", "billItems": [ { "itemCost": 5, "itemCategories": ["deposits"], "itemCommodityCode": "010", "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": -99, "terms": "NET30", "vendor": { "vendorNumber": "1234-A" } } headers = { "requestToken": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript CreateBill const url = 'https://api-sandbox.payabli.com/api/Bill/single/8cfec329267'; const options = { method: 'POST', headers: {requestToken: '', 'Content-Type': 'application/json'}, body: '{"accountingField1":"MyInternalId","attachments":[{"filename":"my-doc.pdf","ftype":"pdf","furl":"https://mysite.com/my-doc.pdf"}],"billDate":"2024-07-01","billItems":[{"itemCost":5,"itemCategories":["deposits"],"itemCommodityCode":"010","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":-99,"terms":"NET30","vendor":{"vendorNumber":"1234-A"}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go CreateBill package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api-sandbox.payabli.com/api/Bill/single/8cfec329267" payload := strings.NewReader("{\n \"accountingField1\": \"MyInternalId\",\n \"attachments\": [\n {\n \"filename\": \"my-doc.pdf\",\n \"ftype\": \"pdf\",\n \"furl\": \"https://mysite.com/my-doc.pdf\"\n }\n ],\n \"billDate\": \"2024-07-01\",\n \"billItems\": [\n {\n \"itemCost\": 5,\n \"itemCategories\": [\n \"deposits\"\n ],\n \"itemCommodityCode\": \"010\",\n \"itemDescription\": \"Deposit for materials\",\n \"itemMode\": 0,\n \"itemProductCode\": \"M-DEPOSIT\",\n \"itemProductName\": \"Materials deposit\",\n \"itemQty\": 1,\n \"itemTaxAmount\": 7,\n \"itemTaxRate\": 0.075,\n \"itemTotalAmount\": 123,\n \"itemUnitOfMeasure\": \"SqFt\"\n }\n ],\n \"billNumber\": \"ABC-123\",\n \"comments\": \"Deposit for materials\",\n \"dueDate\": \"2024-07-01\",\n \"endDate\": \"2024-07-01\",\n \"frequency\": \"monthly\",\n \"mode\": 0,\n \"netAmount\": \"3762.87\",\n \"status\": -99,\n \"terms\": \"NET30\",\n \"vendor\": {\n \"vendorNumber\": \"1234-A\"\n }\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("requestToken", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby CreateBill require 'uri' require 'net/http' url = URI("https://api-sandbox.payabli.com/api/Bill/single/8cfec329267") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["requestToken"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"accountingField1\": \"MyInternalId\",\n \"attachments\": [\n {\n \"filename\": \"my-doc.pdf\",\n \"ftype\": \"pdf\",\n \"furl\": \"https://mysite.com/my-doc.pdf\"\n }\n ],\n \"billDate\": \"2024-07-01\",\n \"billItems\": [\n {\n \"itemCost\": 5,\n \"itemCategories\": [\n \"deposits\"\n ],\n \"itemCommodityCode\": \"010\",\n \"itemDescription\": \"Deposit for materials\",\n \"itemMode\": 0,\n \"itemProductCode\": \"M-DEPOSIT\",\n \"itemProductName\": \"Materials deposit\",\n \"itemQty\": 1,\n \"itemTaxAmount\": 7,\n \"itemTaxRate\": 0.075,\n \"itemTotalAmount\": 123,\n \"itemUnitOfMeasure\": \"SqFt\"\n }\n ],\n \"billNumber\": \"ABC-123\",\n \"comments\": \"Deposit for materials\",\n \"dueDate\": \"2024-07-01\",\n \"endDate\": \"2024-07-01\",\n \"frequency\": \"monthly\",\n \"mode\": 0,\n \"netAmount\": \"3762.87\",\n \"status\": -99,\n \"terms\": \"NET30\",\n \"vendor\": {\n \"vendorNumber\": \"1234-A\"\n }\n}" response = http.request(request) puts response.read_body ``` ```java CreateBill import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api-sandbox.payabli.com/api/Bill/single/8cfec329267") .header("requestToken", "") .header("Content-Type", "application/json") .body("{\n \"accountingField1\": \"MyInternalId\",\n \"attachments\": [\n {\n \"filename\": \"my-doc.pdf\",\n \"ftype\": \"pdf\",\n \"furl\": \"https://mysite.com/my-doc.pdf\"\n }\n ],\n \"billDate\": \"2024-07-01\",\n \"billItems\": [\n {\n \"itemCost\": 5,\n \"itemCategories\": [\n \"deposits\"\n ],\n \"itemCommodityCode\": \"010\",\n \"itemDescription\": \"Deposit for materials\",\n \"itemMode\": 0,\n \"itemProductCode\": \"M-DEPOSIT\",\n \"itemProductName\": \"Materials deposit\",\n \"itemQty\": 1,\n \"itemTaxAmount\": 7,\n \"itemTaxRate\": 0.075,\n \"itemTotalAmount\": 123,\n \"itemUnitOfMeasure\": \"SqFt\"\n }\n ],\n \"billNumber\": \"ABC-123\",\n \"comments\": \"Deposit for materials\",\n \"dueDate\": \"2024-07-01\",\n \"endDate\": \"2024-07-01\",\n \"frequency\": \"monthly\",\n \"mode\": 0,\n \"netAmount\": \"3762.87\",\n \"status\": -99,\n \"terms\": \"NET30\",\n \"vendor\": {\n \"vendorNumber\": \"1234-A\"\n }\n}") .asString(); ``` ```php CreateBill request('POST', 'https://api-sandbox.payabli.com/api/Bill/single/8cfec329267', [ 'body' => '{ "accountingField1": "MyInternalId", "attachments": [ { "filename": "my-doc.pdf", "ftype": "pdf", "furl": "https://mysite.com/my-doc.pdf" } ], "billDate": "2024-07-01", "billItems": [ { "itemCost": 5, "itemCategories": [ "deposits" ], "itemCommodityCode": "010", "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": -99, "terms": "NET30", "vendor": { "vendorNumber": "1234-A" } }', 'headers' => [ 'Content-Type' => 'application/json', 'requestToken' => '', ], ]); echo $response->getBody(); ``` ```csharp CreateBill using RestSharp; var client = new RestClient("https://api-sandbox.payabli.com/api/Bill/single/8cfec329267"); var request = new RestRequest(Method.POST); request.AddHeader("requestToken", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"accountingField1\": \"MyInternalId\",\n \"attachments\": [\n {\n \"filename\": \"my-doc.pdf\",\n \"ftype\": \"pdf\",\n \"furl\": \"https://mysite.com/my-doc.pdf\"\n }\n ],\n \"billDate\": \"2024-07-01\",\n \"billItems\": [\n {\n \"itemCost\": 5,\n \"itemCategories\": [\n \"deposits\"\n ],\n \"itemCommodityCode\": \"010\",\n \"itemDescription\": \"Deposit for materials\",\n \"itemMode\": 0,\n \"itemProductCode\": \"M-DEPOSIT\",\n \"itemProductName\": \"Materials deposit\",\n \"itemQty\": 1,\n \"itemTaxAmount\": 7,\n \"itemTaxRate\": 0.075,\n \"itemTotalAmount\": 123,\n \"itemUnitOfMeasure\": \"SqFt\"\n }\n ],\n \"billNumber\": \"ABC-123\",\n \"comments\": \"Deposit for materials\",\n \"dueDate\": \"2024-07-01\",\n \"endDate\": \"2024-07-01\",\n \"frequency\": \"monthly\",\n \"mode\": 0,\n \"netAmount\": \"3762.87\",\n \"status\": -99,\n \"terms\": \"NET30\",\n \"vendor\": {\n \"vendorNumber\": \"1234-A\"\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift CreateBill 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": [ [ "itemCost": 5, "itemCategories": ["deposits"], "itemCommodityCode": "010", "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": -99, "terms": "NET30", "vendor": ["vendorNumber": "1234-A"] ] 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() ``` > If you're a software company, you're a payments company™