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 NameLineItemParameter DescriptionOptional/Required
RowIDAn ID from an external system that is associated with the row and that Everyware can store.Optional
DescriptionThe name of the line item, which is the product or service you are charging for. It will appear on the receipt.Required
QuantityThe number of Items *Required
AmountEachThe price per item*Required
SubtotalTotal 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.

  1. 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.

  2. 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"
}