Skip to main content

Invoice API

Create, read, update, and delete invoices using the NetSuite REST API.

Endpoints​

MethodEndpointDescription
GET/record/v1/invoiceList all invoices
GET/record/v1/invoice/{id}Get specific invoice
POST/record/v1/invoiceCreate new invoice
PATCH/record/v1/invoice/{id}Update invoice
DELETE/record/v1/invoice/{id}Delete invoice

Key Fields​

Header Fields​

FieldTypeDescriptionRequired
idstringInternal ID (read-only)-
tranIdstringInvoice numberAuto-generated
entityobjectCustomer referenceYes
tranDatestringInvoice date (ISO 8601)Yes
dueDatestringPayment due dateAuto-calculated
statusobjectInvoice statusRead-only
subsidiaryobjectSubsidiaryYes (OneWorld)

Financial Fields​

FieldTypeDescription
currencyobjectTransaction currency
exchangeRatenumberExchange rate
subTotalnumberSubtotal (read-only)
taxTotalnumberTotal tax (read-only)
totalnumberGrand total (read-only)
amountPaidnumberAmount paid (read-only)
amountRemainingnumberBalance due (read-only)
termsobjectPayment terms

Billing & Shipping​

FieldTypeDescription
billAddr1stringBilling address line 1
billCitystringBilling city
billStatestringBilling state
billZipstringBilling ZIP
shipAddr1stringShipping address line 1
shipCitystringShipping city
shipStatestringShipping state
shipZipstringShipping ZIP

Other Fields​

FieldTypeDescription
salesRepobjectSales representative
memostringMemo/notes
messageobjectMessage to customer
otherRefNumstringReference number
createdFromobjectSource transaction (e.g., Sales Order)

Sublists​

FieldTypeDescription
itemcollectionLine items

Example: Create Invoice from Sales Order​

POST /record/v1/invoice
Content-Type: application/json
{
  "entity": {
    "id": "456"
  },
  "tranDate": "2025-12-25",
  "createdFrom": {
    "id": "1001"
  },
  "subsidiary": {
    "id": "1"
  },
  "currency": {
    "id": "1"
  },
  "item": {
    "items": [
      {
        "item": { "id": "789" },
        "quantity": 10,
        "rate": 99.99
      }
    ]
  }
}
Auto-Fill from Sales Order

When you provide createdFrom with a sales order ID, NetSuite auto-fills customer, items, prices, and addresses from the sales order.

Example: Create Standalone Invoice​

POST /record/v1/invoice
Content-Type: application/json
{
  "entity": {
    "id": "456"
  },
  "tranDate": "2025-12-25",
  "dueDate": "2026-01-24",
  "subsidiary": {
    "id": "1"
  },
  "currency": {
    "id": "1"
  },
  "terms": {
    "id": "2"
  },
  "memo": "Professional services - December 2025",
  "item": {
    "items": [
      {
        "item": { "id": "999" },
        "quantity": 40,
        "rate": 150.00,
        "description": "Consulting hours",
        "amount": 6000.00
      }
    ]
  }
}

Example: Update Invoice​

PATCH /record/v1/invoice/5001
Content-Type: application/json
{
  "memo": "Updated: Payment plan agreed",
  "dueDate": "2026-02-28"
}

Invoice Statuses​

StatusDescription
OPENUnpaid or partially paid
PAID_IN_FULLFully paid
PENDING_APPROVALAwaiting approval (if workflow enabled)
VOIDEDVoided/cancelled

Query Filters​

Find Open Invoices​

GET /record/v1/invoice?q=status='OPEN'

Find Overdue Invoices​

GET /record/v1/invoice?q=dueDate < SYSDATE AND status='OPEN'

Find by Customer​

GET /record/v1/invoice?q=entity='456'

Find by Date Range​

GET /record/v1/invoice?q=tranDate BETWEEN '2025-01-01' AND '2025-12-31'

Find High-Value Invoices​

GET /record/v1/invoice?q=total > 50000

Payment Tracking​

Check Payment Status​

const invoice = await getInvoice(5001);
console.log(`Total: ${invoice.total}`);
console.log(`Paid: ${invoice.amountPaid}`);
console.log(`Remaining: ${invoice.amountRemaining}`);

Apply Payment​

Payments are applied via Customer Payment records:

{
  "customer": { "id": "456" },
  "payment": 1000.00,
  "apply": {
    "items": [
      {
        "doc": { "id": "5001" },
        "apply": true,
        "amount": 1000.00
      }
    ]
  }
}

Important Notes​

Accounting Impact​

Creating an invoice:

  • Debit: Accounts Receivable
  • Credit: Revenue/Income accounts (per line item)
  • Credit: Sales Tax Payable (if applicable)

Revenue Recognition​

  • Revenue is recognized when invoice is created (not when paid)
  • Use revenue recognition features for deferred revenue

Voiding vs Deleting​

  • Void: Reverses accounting impact, keeps audit trail
  • Delete: Only allowed if no payments applied and period unlocked

Credit Limit Check​

NetSuite checks customer credit limit when creating invoices. If exceeded:

  • Invoice can still be created
  • Warning appears in UI
  • May require approval

See Also​