> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://beta-docs.payabli.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta-docs.payabli.com/_mcp/server. # Create invoice POST https://api-sandbox.payabli.com/api/Invoice/{entry} Content-Type: application/json Creates an invoice in an entrypoint. Reference: https://beta-docs.payabli.com/api-reference/invoice/add-invoice ## 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) ### Query parameters - `forceCustomerCreation` (boolean, optional) — When `true`, the request creates a new customer record, regardless of whether customer identifiers match an existing customer. Defaults to `false`. ### 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 an InvoiceData. - `customerData` (PayorData, optional) — Object describing the customer/payor. Required for POST requests. Which fields are required depends on the paypoint's custom identifier settings. See [PayorData Object Model](/api-reference/schemas/payordata) for a complete reference. - `invoiceData` (BillData, optional) — Object describing the invoice. Required for POST requests. - `scheduledOptions` (BillOptions, optional) — Object with options for scheduled invoices. ## 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 identifier of the invoice. If `isSuccess` = false, this contains the reason for the failure. - `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 ### PayorData Customer information. May be required, depending on the paypoint's settings. Required for subscriptions. See [PayorData object Model](/api-reference/schemas/payordata) for a complete reference. - `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" } } ``` - `billingAddress1` (string, optional) — Billing address. - `billingAddress2` (string, optional) — Additional line for the billing address. - `billingCity` (string, optional) — Billing city. - `billingCountry` (string, optional) — Billing address country. - `billingEmail` (string, optional) — Email address. - `billingPhone` (string, optional) — Phone number. - `billingState` (string, optional) — Billing state. Must be 2-letter state code for address in US. - `billingZip` (string, optional) — Customer's billing ZIP code. For Pay In functions, this field supports 5-digit and 9-digit ZIP codes and alphanumeric Canadian postal codes. For example: "37615-1234" or "37615". - `company` (string, optional) — Customer's company name. - `customerId` (long, optional) — The Payabli-generated unique ID for the customer. - `customerNumber` (string, optional) — User-provided unique identifier for the customer. This is typically the customer ID from your own system. - `firstName` (string, optional) — Customer/Payor first name. - `identifierFields` (list of string, optional) — List of fields acting as customer identifiers, to be used instead of CustomerNumber. - `lastName` (string, optional) — Customer/Payor last name. - `shippingAddress1` (string, optional) — The shipping address. - `shippingAddress2` (string, optional) — Additional line for shipping address. - `shippingCity` (string, optional) — Shipping city. - `shippingCountry` (string, optional) — Shipping address country. - `shippingState` (string, optional) — Shipping state or province. - `shippingZip` (string, optional) — Shipping ZIP code. For Pay In functions, this field supports 5-digit and 9-digit ZIP codes and alphanumeric Canadian postal codes. For example: "37615-1234" or "37615". ### BillData - `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) — Array of `fileContent` objects with attached documents. Max upload size is 30 MB. - `company` (string, optional) — Company name of the recipient of the invoice. - `discount` (double, optional) — Discount applied to the invoice. - `dutyAmount` (double, optional) — Duty amount. - `firstName` (string, optional) — First name of the recipient of the invoice. - `freightAmount` (double, optional) — Freight/shipping amount. - `frequency` (enum, optional) — Frequency of scheduled invoice. - Allowed values: `one-time`, `weekly`, `every2weeks`, `every6months`, `monthly`, `every3months`, `annually` - `invoiceAmount` (double, optional) — Invoice total amount. - `invoiceDate` (date, optional) — Invoice date in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY. - `invoiceDueDate` (date, optional) — Invoice due date in one of the accepted formats: YYYY-MM-DD, MM/DD/YYYY. - `invoiceEndDate` (date, optional) — Indicate the date to finish a scheduled invoice cycle (`invoiceType`` = 1) in any of the accepted formats: YYYY-MM-DD, MM/DD/YYYY. - `invoiceNumber` (string, optional) — Invoice number. Identifies the invoice under a paypoint. - `invoiceStatus` (integer, optional) — Status for invoice. The accepted status values are: - 0 draft - 1 active - 2 partially paid - 4 paid/complete - 99 cancelled - `invoiceType` (integer, optional) — Type of invoice. Only `0` for one-time invoices is currently supported. - `items` (list of BillItem, optional) — Array of line items included in the invoice. - `lastName` (string, optional) — Last name of the recipient of the invoice. - `notes` (string, optional) — Notes included in the invoice. - `paymentTerms` (enum, optional) — Payment terms for invoice. If no terms are defined, then reponse data for this field defaults to `N30`. - Allowed values: `PIA`, `CIA`, `UR`, `NET10`, `NET20`, `NET30`, `NET45`, `NET60`, `NET90`, `EOM`, `MFI`, `5MFI`, `10MFI`, `15MFI`, `20MFI`, `2/10NET30`, `UF`, `10UF`, `20UF`, `25UF`, `50UF` - `purchaseOrder` (string, optional) — Purchase order number. - `shippingAddress1` (string, optional) — The shipping address. - `shippingAddress2` (string, optional) — Additional line for shipping address. - `shippingCity` (string, optional) — Shipping city. - `shippingCountry` (string, optional) — Shipping address country. - `shippingEmail` (string, optional) — Shipping recipient's contact email address. - `shippingFromZip` (string, optional) — Sender shipping ZIP code. - `shippingPhone` (string, optional) — Recipient phone number. - `shippingState` (string, optional) — Shipping state or province. - `shippingZip` (string, optional) — Shipping ZIP code. For Pay In functions, this field supports 5-digit and 9-digit ZIP codes and alphanumeric Canadian postal codes. For example: "37615-1234" or "37615". - `summaryCommodityCode` (string, optional) — Commodity code. - `tax` (double, optional) — Tax rate in percent applied to the invoice. - `termsConditions` (string, optional) — Custom terms and conditions included in the invoice. ### BillOptions - `includePaylink` (boolean, optional) — Flag to indicate if the scheduled invoice would include a paymentlink - `includePdf` (boolean, optional) — Flag to indicate if the scheduled invoice would include a PDF version of invoice ### Responsedatanonobject The response data. ### 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. ## Examples **Request** ```json { "customerData": { "customerNumber": "3", "firstName": "Tamara", "lastName": "Bagratoni" }, "invoiceData": { "discount": 10, "frequency": "one-time", "invoiceAmount": 982.37, "invoiceDate": "2025-10-19", "invoiceNumber": "INV-3", "invoiceStatus": 1, "invoiceType": 0, "items": [ { "itemCost": 100, "itemDescription": "Consultation for Georgian tours", "itemMode": 1, "itemProductName": "Adventure Consult", "itemQty": 1 }, { "itemCost": 882.37, "itemDescription": "Deposit for trip planning", "itemProductName": "Deposit ", "itemQty": 1 } ] } } ``` **Response** ```json { "isSuccess": true, "responseCode": 1, "responseData": 3625, "responseText": "Success" } ``` **SDK Code** ```python AddInvoice import requests url = "https://api-sandbox.payabli.com/api/Invoice/8cfec329267" payload = { "customerData": { "customerNumber": "3", "firstName": "Tamara", "lastName": "Bagratoni" }, "invoiceData": { "discount": 10, "frequency": "one-time", "invoiceAmount": 982.37, "invoiceDate": "2025-10-19", "invoiceNumber": "INV-3", "invoiceStatus": 1, "invoiceType": 0, "items": [ { "itemCost": 100, "itemDescription": "Consultation for Georgian tours", "itemMode": 1, "itemProductName": "Adventure Consult", "itemQty": 1 }, { "itemCost": 882.37, "itemDescription": "Deposit for trip planning", "itemProductName": "Deposit ", "itemQty": 1 } ] } } headers = { "requestToken": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript AddInvoice const url = 'https://api-sandbox.payabli.com/api/Invoice/8cfec329267'; const options = { method: 'POST', headers: {requestToken: '', 'Content-Type': 'application/json'}, body: '{"customerData":{"customerNumber":"3","firstName":"Tamara","lastName":"Bagratoni"},"invoiceData":{"discount":10,"frequency":"one-time","invoiceAmount":982.37,"invoiceDate":"2025-10-19","invoiceNumber":"INV-3","invoiceStatus":1,"invoiceType":0,"items":[{"itemCost":100,"itemDescription":"Consultation for Georgian tours","itemMode":1,"itemProductName":"Adventure Consult","itemQty":1},{"itemCost":882.37,"itemDescription":"Deposit for trip planning","itemProductName":"Deposit ","itemQty":1}]}}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go AddInvoice package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api-sandbox.payabli.com/api/Invoice/8cfec329267" payload := strings.NewReader("{\n \"customerData\": {\n \"customerNumber\": \"3\",\n \"firstName\": \"Tamara\",\n \"lastName\": \"Bagratoni\"\n },\n \"invoiceData\": {\n \"discount\": 10,\n \"frequency\": \"one-time\",\n \"invoiceAmount\": 982.37,\n \"invoiceDate\": \"2025-10-19\",\n \"invoiceNumber\": \"INV-3\",\n \"invoiceStatus\": 1,\n \"invoiceType\": 0,\n \"items\": [\n {\n \"itemCost\": 100,\n \"itemDescription\": \"Consultation for Georgian tours\",\n \"itemMode\": 1,\n \"itemProductName\": \"Adventure Consult\",\n \"itemQty\": 1\n },\n {\n \"itemCost\": 882.37,\n \"itemDescription\": \"Deposit for trip planning\",\n \"itemProductName\": \"Deposit \",\n \"itemQty\": 1\n }\n ]\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 AddInvoice require 'uri' require 'net/http' url = URI("https://api-sandbox.payabli.com/api/Invoice/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 \"customerData\": {\n \"customerNumber\": \"3\",\n \"firstName\": \"Tamara\",\n \"lastName\": \"Bagratoni\"\n },\n \"invoiceData\": {\n \"discount\": 10,\n \"frequency\": \"one-time\",\n \"invoiceAmount\": 982.37,\n \"invoiceDate\": \"2025-10-19\",\n \"invoiceNumber\": \"INV-3\",\n \"invoiceStatus\": 1,\n \"invoiceType\": 0,\n \"items\": [\n {\n \"itemCost\": 100,\n \"itemDescription\": \"Consultation for Georgian tours\",\n \"itemMode\": 1,\n \"itemProductName\": \"Adventure Consult\",\n \"itemQty\": 1\n },\n {\n \"itemCost\": 882.37,\n \"itemDescription\": \"Deposit for trip planning\",\n \"itemProductName\": \"Deposit \",\n \"itemQty\": 1\n }\n ]\n }\n}" response = http.request(request) puts response.read_body ``` ```java AddInvoice import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api-sandbox.payabli.com/api/Invoice/8cfec329267") .header("requestToken", "") .header("Content-Type", "application/json") .body("{\n \"customerData\": {\n \"customerNumber\": \"3\",\n \"firstName\": \"Tamara\",\n \"lastName\": \"Bagratoni\"\n },\n \"invoiceData\": {\n \"discount\": 10,\n \"frequency\": \"one-time\",\n \"invoiceAmount\": 982.37,\n \"invoiceDate\": \"2025-10-19\",\n \"invoiceNumber\": \"INV-3\",\n \"invoiceStatus\": 1,\n \"invoiceType\": 0,\n \"items\": [\n {\n \"itemCost\": 100,\n \"itemDescription\": \"Consultation for Georgian tours\",\n \"itemMode\": 1,\n \"itemProductName\": \"Adventure Consult\",\n \"itemQty\": 1\n },\n {\n \"itemCost\": 882.37,\n \"itemDescription\": \"Deposit for trip planning\",\n \"itemProductName\": \"Deposit \",\n \"itemQty\": 1\n }\n ]\n }\n}") .asString(); ``` ```php AddInvoice request('POST', 'https://api-sandbox.payabli.com/api/Invoice/8cfec329267', [ 'body' => '{ "customerData": { "customerNumber": "3", "firstName": "Tamara", "lastName": "Bagratoni" }, "invoiceData": { "discount": 10, "frequency": "one-time", "invoiceAmount": 982.37, "invoiceDate": "2025-10-19", "invoiceNumber": "INV-3", "invoiceStatus": 1, "invoiceType": 0, "items": [ { "itemCost": 100, "itemDescription": "Consultation for Georgian tours", "itemMode": 1, "itemProductName": "Adventure Consult", "itemQty": 1 }, { "itemCost": 882.37, "itemDescription": "Deposit for trip planning", "itemProductName": "Deposit ", "itemQty": 1 } ] } }', 'headers' => [ 'Content-Type' => 'application/json', 'requestToken' => '', ], ]); echo $response->getBody(); ``` ```csharp AddInvoice using RestSharp; var client = new RestClient("https://api-sandbox.payabli.com/api/Invoice/8cfec329267"); var request = new RestRequest(Method.POST); request.AddHeader("requestToken", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"customerData\": {\n \"customerNumber\": \"3\",\n \"firstName\": \"Tamara\",\n \"lastName\": \"Bagratoni\"\n },\n \"invoiceData\": {\n \"discount\": 10,\n \"frequency\": \"one-time\",\n \"invoiceAmount\": 982.37,\n \"invoiceDate\": \"2025-10-19\",\n \"invoiceNumber\": \"INV-3\",\n \"invoiceStatus\": 1,\n \"invoiceType\": 0,\n \"items\": [\n {\n \"itemCost\": 100,\n \"itemDescription\": \"Consultation for Georgian tours\",\n \"itemMode\": 1,\n \"itemProductName\": \"Adventure Consult\",\n \"itemQty\": 1\n },\n {\n \"itemCost\": 882.37,\n \"itemDescription\": \"Deposit for trip planning\",\n \"itemProductName\": \"Deposit \",\n \"itemQty\": 1\n }\n ]\n }\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift AddInvoice import Foundation let headers = [ "requestToken": "", "Content-Type": "application/json" ] let parameters = [ "customerData": [ "customerNumber": "3", "firstName": "Tamara", "lastName": "Bagratoni" ], "invoiceData": [ "discount": 10, "frequency": "one-time", "invoiceAmount": 982.37, "invoiceDate": "2025-10-19", "invoiceNumber": "INV-3", "invoiceStatus": 1, "invoiceType": 0, "items": [ [ "itemCost": 100, "itemDescription": "Consultation for Georgian tours", "itemMode": 1, "itemProductName": "Adventure Consult", "itemQty": 1 ], [ "itemCost": 882.37, "itemDescription": "Deposit for trip planning", "itemProductName": "Deposit ", "itemQty": 1 ] ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api-sandbox.payabli.com/api/Invoice/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() ```