MX Invoice

PCE Invoice lets you create professional invoices and collect payments fast through a secure pay link. Choose a customer, add line items, enable card and/or ACH, and send. Customers receive an email (and optionally SMS) with a link to view and pay. A receipt is issued automatically on successful payment.

Prerequisites & limitations

Prerequisites: API credentials, a live or sandbox merchant (merchantId), and at least one configured payment method (card and/or ACH).
Limitations: Taxes are applied at line level via taxes or taxCategory. Invoice-level isTaxExempt overrides taxes where permitted. Discount stacking depends on isExclusive. ACH availability is region/gateway dependent.

Create invoice

POST https://sandbox.api.mxmerchant.com/checkout/v3/invoice?echo=true

Use this endpoint to create a new invoice with optional click-to-pay.

Query parameter

Name	Type	Required	Example	Description
`echo`	boolean	No	`true`	Returns the created invoice object in the response.

Top-level body fields

Field	Type / Enum	Required	Notes
`invoiceDate`	string (ISO 8601)	No	If omitted, server time is used.
`merchantId`	integer	Yes	Merchant creating the invoice.
`status`	enum: `Unpaid`	`Paid`	`Void`	No	Defaults to `Unpaid` on create.
`isClick2PayEnabled`	boolean	No	Enables pay link on the invoice.
`allowCreditCard`	boolean	No	Allow card payments.
`allowACH`	boolean	No	Allow ACH payments.
`terms`	enum (e.g., `OnReceipt`)	No	Used to calculate `dueDate`.
`dueDate`	string (ISO 8601)	No	Derived from `terms` if omitted.
`memo`	string	No	Free-form note shown on the invoice.
`isTaxExempt`	boolean	No	Invoice-level tax exemption.
`purchases`	`array<PurchaseItem>`	Yes	At least one line item required.
`shippingAddress`	`Address`	No	Shipping address snapshot.
`billingAddress`	`Address`	No	Billing address snapshot.
`customer`	`Customer`	Yes	Customer being invoiced.

`PurchaseItem` (line item)

Field	Type / Enum	Required	Notes
`productName`	string	Yes	Item title shown on the invoice.
`description`	string	No	Additional detail.
`price`	number	Yes	Unit price.
`quantity`	integer	Yes	Defaults to `1` if omitted.
`discount`	number	No	Amount discount at line level.
`discounts[]`	`array<Discount>`	No	Structured discounts applied to the line.
`taxes[]`	`array<Tax>`	No	Explicit tax entries.
`taxCategory`	`TaxCategory`	No	Category that determines applicable taxes.
`totalAmount`	string/number	No	Calculated (read-only on create).

`Discount`

Field	Type / Enum	Notes
`discountType`	enum: `Item`	`Invoice`	Scope of discount.
`discountRateType`	enum: `Amount`	`Percent`	Calculation method.
`rate`	string/number	Amount or percent (e.g., `20`).
`code`	string	Optional promo code.
`isExclusive`	boolean	If true, cannot stack with other discounts.

`Tax`

Field	Type	Notes
`id`	integer	Tax ID.
`name`	string	Display name.
`rate`	string	Decimal (e.g., `0.07` for 7%).
`taxCode`	string	Matches tax category code.

`TaxCategory`

Field	Type	Notes
`id`	integer	Tax category ID.
`code`	string	Category code (e.g., `Georgia`).
`display`	string	Human-readable label (e.g., `7.000 % - Georgia`).

`Address`

Field	Type	Notes
`address1`	string	Street line 1.
`city`	string	City.
`state`	string	State/Province.
`zip`	string	Postal/ZIP code.
`country`	string	ISO country code (e.g., `US`).

`Customer`

Field	Type	Notes
`id`	integer	Customer ID.
`name`	string	Full name.
`email`	string	Billing email for invoice delivery.
`mobile`	string	Optional; may be used for SMS notices.
`customerNumber`	string	Merchant’s external customer number.
`isTaxExempt`	boolean	Customer-level tax exemption.

Response (201 Created)

Common response fields after successful create:

Field	Type / Example	Description
`id`	`239998`	Internal invoice identifier.
`invoiceNumber`	`1047`	Human-readable invoice number.
`receiptNumber`	`PTFOO01174PV`	Receipt reference.
`accessCode`	`FVF745`	Code embedded in the pay link.
`status`	`Unpaid`	Current invoice status.
`terms`	`OnReceipt`	Payment terms.
`dueDate`	`2020-10-14T04:00:00Z`	Payment due date.
`invoiceDate`	`2020-10-14T04:00:00Z`	Invoice date.
`allowCreditCard`	`true`	Card payments allowed.
`allowACH`	`false`	ACH payments allowed.
`barCode`	base64 string	Encoded barcode image data.
`purchases[]`	array	Normalized line items with taxes/discounts applied.
`customer`	object	Customer summary (id, name, email, mobile).
`billingAddress`	object	Billing address snapshot.
`shippingAddress`	object	Shipping address snapshot.
`totalAmount`	string/number	Invoice total.
`subTotalAmount`	string/number	Subtotal before tax/discounts.
`taxAmount`	string/number	Total tax applied.
`discountAmount`	string/number	Total discounts applied.
`balance`	string/number	Amount due (total – paid).
`paidAmount`	string/number	Amount paid to date.
`sourceType`	e.g., `MXM`	Originating source.

Tip: Add ?echo=true to return the full invoice object in the create response.

Send invoice receipt

Send a copy of the invoice receipt via email and/or SMS.

POST https://sandbox.api.mxmerchant.com/checkout/v3/invoicereceipt?id={{invoiceId}}&contact={{email}}%2C{{phoneNumber}}

Parameters

Name	Location	Required	Example	Description
`id`	query	Yes	`239998`	Invoice ID to send a receipt for.
`contact`	query	Yes	`[email protected],15551234567`	Comma-separated list of email(s) and/or E.164 phone(s).

Get tax & tax category information

If you don’t know the tax or tax category IDs, fetch them first.

GET https://api.mxmerchant.com/checkout/v3/tax?merchantId={{merchantId}}

Request parameter

Name	Type	Required	Description
`merchantId`	integer	Yes	Merchant ID to scope the tax catalog.

Response (200 OK)

Path	Type	Description
`records[].id`	integer	Tax ID used on items.
`records[].name`	string	Tax name.
`records[].rate`	string	Decimal tax rate (e.g., `0.07`).
`records[].taxCategories[].id`	integer	Tax Category ID (e.g., `2584`).
`records[].taxCategories[].name`	string	Category name (e.g., `Georgia`).
`records[].taxCategories[].code`	string	Category code.
`records[].taxCategories[].isPrimary`	boolean	Indicates primary category for the tax.

Apply taxes effectively • Prefer setting a taxCategory on each line item. • Use explicit taxes[] to target a specific tax ID. • Set isTaxExempt at the invoice or customer level where allowed.