Invoices

TIP

The invoice ID will be set to the following fields on a transaction when paid:

• Order ID
• PO number

This will allow you to look up a transaction by an invoice ID and vice versa. If you set the invoice number field on an invoice, then the transaction order ID field will be this invoice number in place of the invoice ID.

Create Invoice

Create a new invoice.

Request Method: POST

URL Endpoint: /api/invoice

Name	Type	Default	Description	Required
currency	string literal		Currency that invoice amounts should be in ("USD", etc.)	*
company_name	string		Name of company issuing the invoice
company_logo_url	string		Hosted location of logo image to include on invoice
customer_number	string		Optional identifier for the invoiced customer to match merchant records
customer_id	string		ID of the saved customer being invoiced (must be a valid customer id if included)
invoice_number	string		Optional identifier for the invoice to match merchant records
payable_to	object		object containing details for the person the invoice is being paid to	*
payable_to     .id	string		ID of the stored address you want to make the invoice payable to
payable_to     .first_name	string		First name
payable_to     .last_name	string		Last name
payable_to     .company	string		Company name
payable_to     .address_line_1	string		Address line 1	*
payable_to     .address_line_2	string		Address line 2
payable_to     .city	string		City	*
payable_to     .state	string literal		State, in 2-character format ("KS", "QC", etc.))	*
payable_to     .postal_code	string		Postal code (must be a valid postal code for the country provided)	*
payable_to     .country	string literal		Country, in 2-character format ("US", "CA", "MX", etc.)	*
payable_to     .phone	string		Phone number
payable_to     .fax	string		Fax number
payable_to     .email	string		Email address (must be valid email format, "example@mail.com")
bill_to	object		object containing details for the person the invoice is being billed to	*
bill_to     .id	string		ID of the stored address you want to make the invoice billable to
bill_to     .first_name	string		First name
bill_to     .last_name	string		Last name
bill_to     .company	string		Company name
bill_to     .address_line_1	string		Address line 1	*
bill_to     .address_line_2	string		Address line 2
bill_to     .city	string		City	*
bill_to     .state	string literal		State, in 2-character ("KS", "QC", etc.)format	*
bill_to     .postal_code	string		Postal (must be a valid postal code for the country provided) code	*
bill_to     .country	string literal		Country, in 2-character ("US", "CA", "MX", etc.) format	*
bill_to     .phone	string		Phone number
bill_to     .fax	string		Fax number
bill_to     .email	string		Email address (must be valid email format, "example@mail.com")
date_due	datetime string		Date the invoice is due ("2021-02-13T06:00:00.000Z")by	*
items[#]	object array		array containing line items included in the invoice	*
items[#]     .status	string literal		"pending" or "paid"	*
items[#]     .type	string	""	Type of item
items[#]     .name	string	""	Name of item
items[#]     .description	string	""	Description of item
items[#]     .unit_price	integer		Unit price of item	*
items[#]     .quantity	integer		Quantity of item	*
items[#]     .quantity_shipped	integer	0	Quantity of items shipped to customer
items[#]     .product_code	string	""	Product Code of item
items[#]     .commodity_code	string	""	Commodity Code of item
items[#]     .unit_of_measure	string	""	Unit of measure of item ("lb", "kg", etc.)
items[#]     .alternate_tax_identifier	string	""	Alternate tax ID for item
items[#]     .taxable	boolean	false	Whether local and national tax should be applied at the item level rather than the invoice level
items[#]     .local_tax_rate	string	""	Local tax rate for item ("1.000")
items[#]     .local_tax	integer	0	Local tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .national_tax_rate	string	""	National tax rate for item ("1.000")
items[#]     .national_tax	integer	0	National tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .tax_rate	string	""	Combined tax rate for item (local tax + national tax)
items[#]     .tax_amount	integer	0	Tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .discount_amount	integer	0	Discount to take off the item's total amount, expressed in cents (100 = $1.00))
items[#]     .freight_amount	integer	0	Freight amount to add to the item's total, expressed in cents (100 = $1.00)
advanced_fields	boolean	false	Whether or not to include additional fields for line items (advanced fields include quantity_shipped, freight_amount, unit_of_measure, taxable, local_tax_rate, local_tax, national_tax_rate, national_tax)
enable_tax	boolean	false	Whether or not to enable tax (if enabled, tax applied at the invoice level will override taxes applied at the item level)
enable_shipping	boolean	false	Whether or not to enable shipping
require_shipping_details	boolean	false	Whether or not to require shipping details
require_billing_details_on_payment_only	boolean	false	Whether or not to require billing details only at time of payment
tax_percent	string		Tax rate to apply to invoice total if enable_tax is true. A rate of "0.000" will cause tax to be read as a flat amount.	*
tax	integer	calculated amount	Total tax amount of the invoice, expressed in cents (100 = $1.00). If tax_percent is included and is not "0", this field will be overridden with the calculated amount.
shipping	integer	calculated amount	Shipping amount of the invoice, expressed in cents (100 = $1.00)
amount_paid	integer	calculated amount	Amount of the invoice that has already been paid, expressed in cents (100 = $1.00)
service_fees_paid	integer	calculated amount	Service fee amount that has already been paid, expressed in cents (100 = $1.00)
surcharge_paid	integer	calculated amount	Surcharge amount that has already been paid, expressed in cents (100 = $1.00)
discount_credited	integer	calculated amount	Discount amount that has already been credited, expressed in cents (100 = $1.00)
adjustment	integer	0	Apply a payment adjustment to the total amount of the invoice, expressed in cents (100 = $1.00)
allow_partial_payment	boolean	false	Whether or not to allow partial payment of the amount due
transaction_type	string literal	"sale"	"sale" or "authorize"
payment_methods[#]	string array		Allowable payment method types ("card", "ach", and/or "mail")	*
card_processor_id (can be "")	string		ID of the payment processor to use for credit card payments	*
ach_processor_id (can be "")	string		ID of the payment processor to use for ACH payments	*
message	string		Message for customers viewing the invoice
send_via	string literal		How to send invoice notifications ("email", "text", "both", or "none")	*
email_to	string		Email address (must be valid email format, "xxxxx@xxxxx.xxx")

Get Invoice By ID

Retrieve details for the specified invoice.

Request Method: GET

URL Endpoint: /api/invoice/{ invoice id }

{
  "status": "success",
  "msg": "success",
  "data": {
    "id": "bhi9vado3hogrne0u4tg",
    "currency": "USD",
    "company_name": "ACME Inc.",
    "company_logo_url": "",
    "customer_number": "123Customer",
    "payable_to": {
      "id": "",
      "first_name": "First",
      "last_name": "Last",
      "company": "Merchant Business",
      "address_line_1": "123 Some St",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somewebsite.com"
    },
    "bill_to": {
      "id": "",
      "first_name": "First",
      "last_name": "Last",
      "company": "Some Business",
      "address_line_1": "123 Drury Lane",
      "address_line_2": "",
      "city": "Some City",
      "state": "IL",
      "postal_code": "60000",
      "country": "US",
      "phone": "5555555555",
      "fax": "5555555555",
      "email": "info@somesite.com"
    },
    "created_at": "2019-02-13T22:52:26Z",
    "date_due": "2019-02-13T06:00:00Z",
    "items": [
      {
        "id": "bhi9vado3hogrne0u4t0",
        "name": "Widget",
        "description": "A widget for processors",
        "quantity": 1,
        "quantity_shipped": 0,
        "unit_of_measure": "",
        "unit_price": 100,
        "discount": 0,
        "discount_type": "$",
        "taxable": false,
        "local_tax": "0",
        "national_tax": "0",
        "tax_rate": "0",
        "tax_amount": 0,
        "amount": 100,
        "status": "pending"
      }
    ],
    "advanced_fields": false,
    "subtotal": 100,
    "tax_percent": "0.00",
    "tax": 0,
    "total": 100,
    "amount_paid": 0,
    "adjustment": 0,
    "amount_due": 100,
    "payment_methods": ["card"],
    "card_processor_id": "bhi5qa5o3hogms88jojg",
    "ach_processor_id": "",
    "status": "pending",
    "message": "Thank you for your business!",
    "reject_message": "",
    "send_via": "none",
    "last_sent_at": "0001-01-01T00:00:00Z",
    "updated_at": "2019-02-13T23:15:43Z",
    "public_url": "d038ea94-3f4f-4703-9e94-74792605944e",
    "hosted_url": "http://localhost:8080/invoice/d038ea94-3f4f-4703-9e94-74792605944e"
  }
}

Search Invoices

Retrieve details for all invoices that match provided search criteria.

Request Method: POST

URL Endpoint: /api/invoices/search

Name	Type	Description
id	object	Object containing details for searching by id
id     .operator	string literal	"=" or "!="
id     .value	string	invoice id to match or exclude
amount_due	object	Object containing details for searching by amount_due
amount_due     .operator	string literal	"=", "!=", "<", or ">"
amount_due     .value	integer	amount to match or exclude
date_due	object	Object containing details for searching by date_due
date_due     .start_date	date string	Searches by date_due between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ")
date_due     .end_date	date string	Searches by date_due between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ")
limit	integer	Maximum records to return (0-100)
offset	integer	Number of records to offset the return by

Update Invoice

Update an existing invoice.

Request Method: POST

URL Endpoint: /api/invoice/{ invoice id }

Name	Type	Default	Description	Required
currency	string literal		Currency that invoice amounts should be in ("USD", etc.)	*
company_name	string		Name of company issuing the invoice
company_logo_url	string		Hosted location of logo image to include on invoice
customer_number	string		Optional identifier for the invoiced customer to match merchant records
customer_id	string		ID of the saved customer being invoiced (must be a valid customer id if included)
invoice_number	string		Optional identifier for the invoice to match merchant records
payable_to	object		object containing details for the person the invoice is being paid to	*
payable_to     .id	string		ID of the stored address you want to make the invoice payable to
payable_to     .first_name	string		First name
payable_to     .last_name	string		Last name
payable_to     .company	string		Company name
payable_to     .address_line_1	string		Address line 1	*
payable_to     .address_line_2	string		Address line 2
payable_to     .city	string		City	*
payable_to     .state	string literal		State, in 2-character format ("KS", "QC", etc.))	*
payable_to     .postal_code	string		Postal code (must be a valid postal code for the country provided)	*
payable_to     .country	string literal		Country, in 2-character format ("US", "CA", "MX", etc.)	*
payable_to     .phone	string		Phone number
payable_to     .fax	string		Fax number
payable_to     .email	string		Email address (must be valid email format, "example@mail.com")
bill_to	object		object containing details for the person the invoice is being billed to	*
bill_to     .id	string		ID of the stored address you want to make the invoice billable to
bill_to     .first_name	string		First name
bill_to     .last_name	string		Last name
bill_to     .company	string		Company name
bill_to     .address_line_1	string		Address line 1	*
bill_to     .address_line_2	string		Address line 2
bill_to     .city	string		City	*
bill_to     .state	string literal		State, in 2-character ("KS", "QC", etc.)format	*
bill_to     .postal_code	string		Postal (must be a valid postal code for the country provided) code	*
bill_to     .country	string literal		Country, in 2-character ("US", "CA", "MX", etc.) format	*
bill_to     .phone	string		Phone number
bill_to     .fax	string		Fax number
bill_to     .email	string		Email address (must be valid email format, "example@mail.com")
date_due	datetime string		Date the invoice is due ("2021-02-13T06:00:00.000Z")by	*
items[#]	object array		array containing line items included in the invoice	*
items[#]     .status	string literal		"pending" or "paid"	*
items[#]     .type	string	""	Type of item
items[#]     .name	string	""	Name of item
items[#]     .description	string	""	Description of item
items[#]     .unit_price	integer		Unit price of item	*
items[#]     .quantity	integer		Quantity of item	*
items[#]     .quantity_shipped	integer	0	Quantity of items shipped to customer
items[#]     .product_code	string	""	Product Code of item
items[#]     .commodity_code	string	""	Commodity Code of item
items[#]     .unit_of_measure	string	""	Unit of measure of item ("lb", "kg", etc.)
items[#]     .alternate_tax_identifier	string	""	Alternate tax ID for item
items[#]     .taxable	boolean	false	Whether local and national tax should be applied at the item level rather than the invoice level
items[#]     .local_tax_rate	string	""	Local tax rate for item ("1.000")
items[#]     .local_tax	integer	0	Local tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .national_tax_rate	string	""	National tax rate for item ("1.000")
items[#]     .national_tax	integer	0	National tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .tax_rate	string	""	Combined tax rate for item (local tax + national tax)
items[#]     .tax_amount	integer	0	Tax amount to be added to the item's total, expressed in cents (100 = $1.00)
items[#]     .discount_amount	integer	0	Discount to take off the item's total amount, expressed in cents (100 = $1.00))
items[#]     .freight_amount	integer	0	Freight amount to add to the item's total, expressed in cents (100 = $1.00)
advanced_fields	boolean	false	Whether or not to include additional fields for line items (advanced fields include quantity_shipped, freight_amount, unit_of_measure, taxable, local_tax_rate, local_tax, national_tax_rate, national_tax)
enable_tax	boolean	false	Whether or not to enable tax (if enabled, tax applied at the invoice level will override taxes applied at the item level)
enable_shipping	boolean	false	Whether or not to enable shipping
require_shipping_details	boolean	false	Whether or not to require shipping details
require_billing_details_on_payment_only	boolean	false	Whether or not to require billing details only at time of payment
tax_percent	string		Tax rate to apply to invoice total if enable_tax is true. A rate of "0.000" will cause tax to be read as a flat amount.	*
tax	integer	calculated amount	Total tax amount of the invoice, expressed in cents (100 = $1.00). If tax_percent is included and is not "0", this field will be overridden with the calculated amount.
shipping	integer	calculated amount	Shipping amount of the invoice, expressed in cents (100 = $1.00)
amount_paid	integer	calculated amount	Amount of the invoice that has already been paid, expressed in cents (100 = $1.00)
service_fees_paid	integer	calculated amount	Service fee amount that has already been paid, expressed in cents (100 = $1.00)
surcharge_paid	integer	calculated amount	Surcharge amount that has already been paid, expressed in cents (100 = $1.00)
discount_credited	integer	calculated amount	Discount amount that has already been credited, expressed in cents (100 = $1.00)
adjustment	integer	0	Apply a payment adjustment to the total amount of the invoice, expressed in cents (100 = $1.00)
amount_due	integer	calculated amount	Amount of the invoice that remains due, expressed in cents (100 = $1.00)
allow_partial_payment	boolean	false	Whether or not to allow partial payment of the amount due
transaction_type	string literal	"sale"	"sale" or "authorize"
payment_methods[#]	string array		Allowable payment method types ("card", "ach", and/or "mail")	*
card_processor_id (can be "")	string		ID of the payment processor to use for credit card payments	*
ach_processor_id (can be "")	string		ID of the payment processor to use for ACH payments	*
message	string		Message for customers viewing the invoice
send_via	string literal		How to send invoice notifications ("email", "text", "both", or "none")	*
email_to	string		Email address (must be valid email format, "xxxxx@xxxxx.xxx")

Delete Invoice

Delete the specified invoice.

Request Method: DELETE

URL Endpoint: /api/invoice/{ invoice id }

{
  "status": "success",
  "msg": "success"
}