Invoicing bills a customer with an itemized invoice — line items, taxes, a due date, and a pay-online link — then tracks it from Unpaid to Paid. Use it when you send a bill and let the customer pay, rather than charging a card yourself. For the full field list, jump to the Request reference.

Create an invoice with /checkout/v3/invoice. To charge a card yourself instead, use Sale; to bill automatically on a schedule, use Recurring Billing.

Common use cases

• Bill a client for a project or service with itemized line items
• Send a due-dated invoice a customer pays by card online
• Record an offline payment against an open invoice and send a receipt

Make your first invoice

The fastest way to see it work: bill an existing customer for a service. You'll need the customer's id first (see Create a customer). The full set of options is in the Request reference.

POST /checkout/v3/invoice

{
  "merchantId": 1000157980,
  "customer": { "id": 10000000803145 },
  "dueDate": "2026-02-28",
  "allowCreditCard": true,
  "purchases": [
    { "productName": "Consulting", "price": 250.00, "quantity": 2 }
  ],
  "billingAddress": { "address1": "2001 Westside Parkway", "city": "Alpharetta", "state": "GA", "zip": "30009" },
  "shippingAddress": { "address1": "2001 Westside Parkway", "city": "Alpharetta", "state": "GA", "zip": "30009" }
}

You'll get back a 200 OK with the created invoice, including its id, invoiceNumber, and an accessCode the customer uses to view and pay it online. The invoice starts Unpaid.

{
  "id": 260774,
  "merchantId": 1000157980,
  "invoiceNumber": 1044,
  "receiptNumber": "PTO6900CTU1Q",
  "accessCode": "OMGDES",
  "status": "Unpaid",
  "totalAmount": "500.00",
  "balance": "500.00",
  "paidAmount": "0",
  "dueDate": "2026-02-28T05:00:00Z",
  "created": "2026-01-06T14:08:50.37Z",
  "customer": { "id": 10000000803145 },
  "purchases": [
    { "id": 78629, "productName": "Consulting", "quantity": 2, "price": "250.00", "subTotalAmount": "500.00", "totalAmount": "500.00" }
  ],
  "allowCreditCard": true
}

The endpoint is documented in the API reference at POST /checkout/v3/invoice.

Scenarios

Every invoice is created the same way; what changes is the line items and how it gets paid. Pick the one that matches your job.

sequenceDiagram
    participant You as Your Application
    participant PCE as PCE
    participant Customer as Customer

    You->>PCE: POST /checkout/v3/invoice (status: Unpaid)
    PCE-->>You: 200 OK (id, invoiceNumber, accessCode)
    PCE->>Customer: Invoice / receipt (email)
    Customer->>PCE: Pays online with card
    PCE-->>You: Webhook (PaymentSuccess)
    Note over PCE: Invoice moves to Paid when the balance is cleared

Before you begin (all scenarios)

• The customer exists and you have their id (see Create a customer).

Scenario 1: Invoice a customer for a service

(single line item, pay online)

Use this for a straightforward bill: one or more line items, a due date, and card payment enabled so the customer can pay from the invoice.

You'll also need: the customer's id and the line items to bill.

Request

POST /checkout/v3/invoice

{
  "merchantId": 1000157980,
  "customer": { "id": 10000000803145 },
  "dueDate": "2026-02-28",
  "terms": "Net 30",
  "allowCreditCard": true,
  "purchases": [
    { "productName": "Website audit", "price": 750.00, "quantity": 1 }
  ],
  "billingAddress": { "name": "Alex Johnson", "address1": "2001 Westside Parkway", "city": "Alpharetta", "state": "GA", "zip": "30009" },
  "shippingAddress": { "name": "Alex Johnson", "address1": "2001 Westside Parkway", "city": "Alpharetta", "state": "GA", "zip": "30009" }
}

Response

{
  "id": 260780,
  "merchantId": 1000157980,
  "invoiceNumber": 1045,
  "accessCode": "K3D9ZP",
  "status": "Unpaid",
  "totalAmount": "750.00",
  "balance": "750.00",
  "dueDate": "2026-02-28T05:00:00Z",
  "customer": { "id": 10000000803145 },
  "allowCreditCard": true
}

Scenario 2: Invoice with multiple line items and a purchase order

(itemized bill with a PO reference)

Use this for itemized billing tied to a customer's purchase order. Add each product to purchases[] and set purchaseOrderNumber so it appears on the invoice.

You'll also need: each line item and the customer's PO number.

Request

POST /checkout/v3/invoice

{
  "merchantId": 1000157980,
  "customer": { "id": 10000000803145 },
  "purchaseOrderNumber": "PO-4471",
  "dueDate": "2026-03-15",
  "allowCreditCard": true,
  "purchases": [
    { "productName": "Onboarding", "price": 500.00, "quantity": 1 },
    { "productName": "Training seat", "price": 150.00, "quantity": 4 }
  ],
  "billingAddress": { "address1": "500 Market St", "city": "Atlanta", "state": "GA", "zip": "30301" },
  "shippingAddress": { "address1": "500 Market St", "city": "Atlanta", "state": "GA", "zip": "30301" }
}

Response

{
  "id": 260790,
  "merchantId": 1000157980,
  "invoiceNumber": 1046,
  "accessCode": "QW82LM",
  "status": "Unpaid",
  "purchaseOrderNumber": "PO-4471",
  "subTotalAmount": "1100.00",
  "totalAmount": "1100.00",
  "balance": "1100.00",
  "dueDate": "2026-03-15T04:00:00Z",
  "customer": { "id": 10000000803145 }
}

Scenario 3: Record an offline payment and send a receipt

(mark an invoice paid, then email the receipt)

Use this when a customer pays by check or cash. Record the payment against the invoice with /checkout/v3/invoicepayment, then send the receipt with /checkout/v3/invoicereceipt.

You'll also need: the invoice id and the amount received.

Request

POST /checkout/v3/invoicepayment

{
  "merchantId": 1000157980,
  "invoiceId": 260780,
  "amount": 750.00,
  "tenderType": "Check"
}

Then email the receipt:

POST /checkout/v3/invoicereceipt

{
  "merchantId": 1000157980,
  "invoiceId": 260780
}

Track the invoice

Read status and balance on the response for the immediate state. To follow an invoice afterwards:

• Retrieve it with GET /checkout/v3/invoice/{id}, or list invoices with /checkout/v3/invoice.
• Read its payments with GET /checkout/v3/invoicepayment.
• Read its returns with GET /checkout/v3/invoice/{id}/return, or a specific return with /checkout/v3/invoice/{id}/return/{returnId}.
• Read its history with GET /checkout/v3/invoicehistory/{id}.

When a customer pays online, the payment surfaces through the standard payment webhooks (PaymentSuccess / PaymentFail); the invoice moves to Paid once its balance reaches zero. See Webhook Event Types.

Manage an invoice

For reconciling exported invoices against settlement and deposits, see Reports & Reconciliation.

Request reference

The complete set of fields for the create-invoice request. Scenarios above use subsets of these.

Core parameters

Purchase line items

Each item in purchases[]:

Address fields

Used for both billingAddress and shippingAddress:

Validation

The prerequisites above are the validations, and PCE enforces them when you submit. merchantId, customer (with customer.id), purchases, billingAddress, and shippingAddress are required; each purchase needs productName, price, and quantity. If a check fails, the request returns an error and no invoice is created.

Statuses

An invoice starts Unpaid and moves to Paid when its balance reaches zero. Cancelled stops it.

Go live

The shared pre-production checklist is in Getting Started. Specific to invoicing, also confirm:

• Customers exist before you invoice them (you need customer.id).
• allowCreditCard is set as intended so customers can (or can't) pay online.
• You subscribe to PaymentSuccess to detect when an invoice is paid.
• Tax and discount handling match your business rules (see Sales Tax, Discounts).

Best practices

General practices are in Getting Started. Specific to invoicing:

Next steps

See also

• Recurring Billing: bill automatically on a schedule
• Sales Tax: apply tax to invoices
• Discounts: apply discounts to invoices
• Sale: charge a card directly instead of invoicing
• Payment Response Codes: resolve a declined online payment