Creating an Invoice
Access Endpoint URL: https://rest.everyware.com/api/Default/CreateInvoice [POST]
You can use the CreateInvoice method to generate an invoice with one or multiple line items that can be sent via text or email to the customer's specified mobile number and/or email address. Upon payment, the customer may also receive an email receipt and/or a thank you note via text.
Calculate Dollar Amounts First
Note: Dollar amounts must be calculated before entering. This API is not programmed to calculate amounts, only to display them on invoices as directed.
Partial Payments
Note: If additional fees are required, outside the normal purchase total, then partial payments are not permitted. Everyware supports partial payments, however the full balances due must be calculated and maintained by the individual business.
Fee & Tax Settings
Note: Fee and tax settings are editable in the Everyware portal, but not through this API.
Amount Formatting
For any dollar amount fields, format without dollar signs.
Ex: “5.00” = 5
Inbound Parameters
Parameters should be passed in a single JSON-body object. For individual line items, see the next table and code sample.
Parameter Name | Description | Optional/Required |
---|---|---|
LineItems | An array of Line Items (*see next table for Line Item parameters). | Required |
BusinessName | The name of the business billing the customer. It appears at the top of the invoice and email receipt. | Required |
BusinessID | An ID that Everyware can store for the business charging the customer. | Optional |
AccountNumber | A customer/business account number that can be stored by Everyware. | Optional |
AccountNumber2 | Another customer/business account number that can be stored by Everyware. | Optional |
Description | The description of the line items of the invoice. | Optional |
DiscountAmount | The amount that is to be discounted from the invoice. | Optional |
TotalAmountDue | The total dollar amount owed after the subtotal, taxes, and fees are calculated. | Required |
Subtotal | The total dollar amount for all line items excluding taxes and fees. | Required |
Tax | The dollar amount for the taxes to be charged. Settings for taxes can be adjusted in Portal. If left blank or at $0.00, it will not appear as a line item. | Optional |
ConvenienceFee | The dollar amount for an optional convenience fee. If left blank or at $0.00, it will not appear as a line item. | Optional |
OrderNumber | The unique identifier used to reference the invoice. It appears on the invoice and in the Payments Report in Portal. If left blank, Everyware will generate a number for you. Formerly named Invoice ID. | Optional |
StatementDate | The date of the billing statement. If left blank, we will auto-populate it with the date the invoice is sent/generated by email or text. | Optional |
BillToName | The first and last names of the customer being billed. | Optional |
BillToExternalId | A unique identifier for the invoice that is provided by you and stored by Everyware. | Optional |
BillToAddress1 | The first line of the billing address for the customer being billed. | Optional |
BillToAddress2 | The second line of the billing address for the customer being billed. | Optional |
BillToCity | The city corresponding to the billing address for the customer being billed. | Optional |
BillToState | The state code for the billing address of the customer being billed. Format: 2-letter code (TX, FL, etc.) | Optional |
BillToCountry | The country code for the billing address of the customer being billed. Example: United States = US | Optional |
BillToZip | The zip/postal code of the billing address for the customer being billed. | Required |
BillToCellPhone | The mobile phone number of the customer. Must be a valid, 10-digit max mobile number provided with no formatting or the transaction will be declined. Example: 3055551212 | Required |
BillToEmailAddress | The email address where you want to receive Pay By Email invoices. | Optional |
BusinessAddress1 | Address Line One for the business sending the invoice. This will appear at the bottom of the payment receipt. | Required |
BusinessAddress2 | Address Line Two for the business sending the invoice. This will appear at the bottom of the payment receipt. | Optional |
BusinessCity | The city corresponding to the address of the business sending the invoice. This will appear at the bottom of the payment receipt. | Required |
BusinessState | The state code for the address of the business sending the invoice. This will appear at the bottom of the payment receipt. | Required |
BusinessZip | The zip/postal code of the business sending the invoice. This will appear at the bottom of the payment receipt. | Required |
BusinessPhone | The main phone number (landline or mobile) of the business sending the invoice. It should be 10-digits max, with no formatting. This will appear at the bottom of the payment receipt received via email and in the business profile in Portal. Example: 3055551212 | Optional |
BusinessEmail | The email address for the business sending the invoice. It will appear in the payment receipt and can be configured to appear in the "From" line of email receipts. | Optional |
ScheduledDate | The date on which the invoice link should be generated. It is also the date for the invoice link to be sent to the customer if it is to be sent via SMS. If left blank, the Pay By Text message with the invoice link will be sent instantly the same day. | Optional |
ExpirationDate | The date the invoice link expires. If a customer clicks the invoice link after it expires, they will see a message asking them to contact the merchant. | Optional |
DueDate | The date by which the invoice must be paid. | Optional |
BatchId | A unique, external bill batch identifier for groups of invoices sent that need to be identified together. Everyware will also generate an Everyware BatchId which will appear in your response and in the "Batch Report" table in Portal. | Optional |
MessageExternalID | A unique identifier from an external system associated with the message that Everyware can store. | Optional |
SendSMSInvoice | True or False. If True, a text message with the invoice link will be sent. If False, a link will be generated and shown under Pending Payments in Portal. | Required |
SendEmailInvoice | True or False. If True, an email with the invoice link will be sent. | Required |
generateQRCode | True or False. If True, the response to the call will include a parameter called "QRCodeBase64" with a string as the value. Decoding the base64 encoded string will provide a QR code that, when scanned, will redirect the user to the invoice page. | Optional |
IsPartialPayment | True or False. If True, the customer will be allowed to make a partial payment. Partial payments will not be allowed if any fees are included. Note: Site Settings for the account must also toggle on/off "Allow Partial Payments" to show the option if set to True. | Required |
DeliveryFee | The dollar amount for the optional "Delivery Fee" line item, which can be activated and adjusted in Portal. If left blank or at $0.00, it will not appear as a line item. | Optional |
CustomFee1 | The dollar amount for an optional, custom line item. This fee type can be activated, labeled, and adjusted in the Everyware Portal. If left blank or at $0.00, it will not appear as a line item. | Optional |
CustomFee2 | The dollar amount for an optional, custom line item. This fee type can be activated, labeled, and adjusted in the Everyware Portal. If left blank or at $0.00, it will not appear as a line item. | Optional |
SendSMSReceipt | True or False. If true, a receipt will be sent to the customer via SMS upon paying the invoice. | Optional |
SendEmailReceipt | True or False. If true, a receipt will be sent to the customer via email upon paying the invoice. | Optional |
PreviousSMSID | The ID associated with the previous invoice sent to the customer. Used when a merchant wants to send a follow up invoice since it links the two invoices together. | Optional |
CustomerExternalID | A unique identifier from an external system for the customer that Everyware can store. | Optional |
ShippingAmount | The dollar amount added to the invoice for shipping costs. | Optional |
SalesRep | The sales representative sending the invoice. | Optional |
SMSMessage | The actual text sent with the invoice. A default message will be provided if left blank. | Optional |
Inbound Parameters - Per Line Item
LineItem Parameter Name | LineItemParameter Description | Optional/Required |
---|---|---|
RowID | An ID from an external system that is associated with the row and that Everyware can store. | Optional |
Description | The name of the line item, which is the product or service you are charging for. It will appear on the receipt. | Required |
Quantity | The number of Items * | Required |
AmountEach | The price per item* | Required |
Subtotal | Total amount charged for the line item before taxes and fees. | Required |
Sample CreateInvoice Use Case 1 : Create and Send an Invoice
For merchants who want to send an invoice by text and email containing a single line item, which does not allow for partial payment, and includes an invoice expiration date.
{
"BusinessName": "Hello Sunshine Automotive",
"LineItems": [
{
"Description": "Automotive Sample Line Item",
"Quantity": 1,
"AmountEach": "1.00",
"Total": "1.00"
}
],
"OrderNumber": "12345",
"BillToExternalId":"",
"Subtotal": "1.00",
"TotalAmountDue": "1.00",
"SendSMSInvoice": true,
"SendEmailInvoice": true,
"generateQRCode": true,
"IsPartialPayment": false,
"BillToCellPhone": "5125551212",
"BillToName": "John Doe",
"BillToAddress1": "100 Test Street",
"BillToAddress2": "",
"BillToCity": "Austin",
"BillToState": "TX",
"BillToZip": "78701",
"ScheduledDate": "10-13-2021",
"ExpirationDate": "12-31-2021",
"DueDate": "10-31-2021"
}
curl --location 'https://rest.everyware.com/api/Default/CreateInvoice' \
--header 'Authorization: Basic [xxx]' \
--header 'Content-Type: application/json' \
--data-raw ' {
"BusinessName": "Hello Sunshine Automotive",
"LineItems": [
{
"Description": "Automotive Sample Line Item",
"Quantity": 1,
"AmountEach": "1.00",
"Total": "1.00"
}
],
"OrderNumber": "12345",
"BillToExternalId":"",
"Subtotal": "1.00",
"TotalAmountDue": "1.00",
"SendSMSInvoice": true,
"SendEmailInvoice": true,
"IsPartialPayment": false,
"BillToCellPhone": "5125551212",
"BillToName": "John Doe",
"BillToAddress1": "100 Test Street",
"BillToAddress2": "",
"BillToCity": "Austin",
"BillToState": "TX",
"BillToZip": "78701",
"ScheduledDate": "10-13-2021",
"ExpirationDate": "12-31-2021",
"DueDate": "10-31-2021"
}'
{
"OrderNumber": "E486902247",
"SMSID": "1072248",
"QRCodeBase64": "iVBORw0KGgoAAAANSUhEUgAAAGQAAABkAQMAAABKLAcXAAAABlBMVEX///8AAABVwtN+AAAACXBIWXMAAA7EAAAOxAGVKw4bAAABOUlEQVQ4jZXUP87CIBQA8EcY2OACplyDoUmvhJuTsLnplUgceg2MF6gbA+F9D6ODwweU7deE9v0twM9xiDDbRzhrxNiUBSFnKMv1AKytI14ALK7Xw/LaKZVdMTAiFtRkzl1RZOqORfhvnIOi3CXlvl6/lfhXdBh6gPO3pINyeMH7rRj1XGVH+fTug8NUI2uIOgWz0klFQ1/YIU5hOR0kR9nRQahs6RJft450ojdPAj+RjUrRTPBtoj4IektLLNMDP4GLRu5SFIX7ydh3nC0dM7yCoxHVqU5WS1HQ1CF6Huq9ceXTNju93p5B9iRYra7ChLEpOioAWwssu1Tnmm860OZs0BTtCnBPfwao9RwX7aZcPCw3TKWv2T2wgMDYFXU3McTPvTHVfc8OBOUu26LcVbDFWPhUYlA/5w9thCpCSF81gwAAAABJRU5ErkJggg==",
"IsSuccess": true,
"Message": "Your Pay By Email invoice has been successfully created.",
"Data": "Do you want to use the card ending in 0483 for $1.00? Enter yes or no. https://pay.everyware.com/B930E609"
}
Sample CreateInvoice Use Case 2: Send & Accept Partial Payment on an Invoice
For merchants who need to send an invoice, allow the customer to make a partial payment toward the total amount due, and later when the customer clicks the original invoice link, they are redirect to an updated invoice displaying the remaining amount due.
-
The first CreateInvoice call results in an invoice for 3 line items that is texted and emailed to the customer. The invoice will allow for a partial payment.
-
After the customer pays a partial amount toward the total due on the first invoice, use the first invoice's SMSID in the second call's PreviousSMSID parameter.
{
"BusinessName": "Hello Sunshine Inc",
"LineItems": [
{
"Description": "January Bill $1.00 ",
"Quantity": "1",
"AmountEach": "1.00",
"Total": "1.00"
},
{
"Description": "Feb Bill",
"Quantity": "1",
"AmountEach": "1.00",
"Total": "1.00"
},
{
"Description": "March Bill",
"Quantity": "1",
"AmountEach": "1.00",
"Total": "1.00"
}
],
"Subtotal": "3.00",
"TotalAmountDue": "3.00",
"SendSMSInvoice": true,
"SendEmailInvoice": true,
"IsPartialPayment": true,
"OrderNumber": "11112021",
"BillToName": "Whit Testing",
"BilltoExternalID": "Test",
"BillToCellPhone": "5555555555",
"BillToEmailAddress": "[email protected]",
"ScheduledDate": "11-11-2021",
"ExpirationDate": "12-01-2021",
"DueDate": "11-30-2021",
"BusinessEmail": "[email protected]",
"BillToAddress1": "701 Brazos St",
"BusinessPhone": "5555555555",
"BillToAddress2": "",
"BillToCity": "Austin",
"BillToState": "TX",
"BillToZip": "78701",
"PreviousSMSID":""
}
{
"IsSuccess": true,
"Message": "Your Pay By Email invoice has been successfully created.",
"Data": "Do you want to use the card ending in 2159 for $3.00? Enter yes or no. https://mdpaybill.net/6C492AD6",
"OrderNumber": "11112021",
"SMSID": "479038"
}
{
"BusinessName": "Hello Sunshine Inc",
"LineItems": [
{
"Description": "PAID January Bill $1.00 ",
"Quantity": "1",
"AmountEach": "0.00",
"Total": "0.00"
},
{
"Description": "Feb Bill",
"Quantity": "1",
"AmountEach": "1.00",
"Total": "1.00"
},
{
"Description": "March Bill",
"Quantity": "1",
"AmountEach": "1.00",
"Total": "1.00"
}
],
"Subtotal": "2.00",
"TotalAmountDue": "2.00",
"SendSMSInvoice": false,
"SendEmailInvoice": false,
"IsPartialPayment": false,
"OrderNumber": "11112021",
"BillToName": "Whit Testing",
"BilltoExternalID": "Test",
"BillToCellPhone": "5555555555",
"BillToEmailAddress": "[email protected]",
"ScheduledDate": "11-11-2021",
"ExpirationDate": "12-01-2021",
"DueDate": "11-30-2021",
"BusinessEmail": "[email protected]",
"BillToAddress1": "701 Brazos St",
"BusinessPhone": "5555555555",
"BillToAddress2": "",
"BillToCity": "Austin",
"BillToState": "TX",
"BillToZip": "78701",
"PreviousSMSID":"479038"
}
{
"IsSuccess": true,
"Message": "Your Pay By Text invoice has been successfully created.",
"Data": "https://mdpaybill.net/E83CF150",
"OrderNumber": "11112021",
"SMSID": "479040"
}
Updated 5 months ago