---
title: "Create an invoice"
method: POST
path: "/invoices"
tags: ["Invoices"]
---

# Create an invoice

`POST /invoices`

Create a new invoice for an order.

## What happens

- Invoice record is created for the order
- Order status updates to `DELIVERED_UNPAID`
- Due date calculated from payment term if not provided

## Note

Each shipment can have only one AR invoice. Use `POST /shipments/{id}/invoice/generate`
to generate the invoice PDF document.

## Request body

- InvoiceInput
  - `orderId` string, uuid, required — Order to invoice
  - `invoiceDate` string, date, required — Invoice date
  - `dueDate` string, date — Payment due date
  - `amount` number, required — Invoice amount (typically calculated from order charges)
  - `reference` string — External reference number
  - `currency` string — Currency code (defaults to customer currency)
  - `paymentTermId` string, uuid — Payment term (defaults to customer default)

## Response `201`

Invoice created successfully

- Invoice
  - `id` string, uuid, required
  - `friendlyId` string, required — Human-readable invoice ID
  - `key` string, nullable — Client-defined key
  - `orderId` string, uuid — Associated order ID
  - `orderKey` string, nullable — Order friendly ID
  - `shipmentId` string, uuid — Associated shipment ID
  - `shipmentKey` string, nullable — Shipment friendly ID
  - `customer` CustomerReference — Enhanced reference to a customer resource (returned in responses). Includes full customer details in addition to id/key. Note: Does NOT include nested references (paymentTerm, contacts, etc.) to prevent recursion. Maximum nesting depth: 1 level.
    - `id` string, uuid, required — Customer UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `name` string, required — Customer company name
    - `friendlyId` string, required — Human-readable customer identifier
    - `status` 'PROSPECT' | 'ACTIVE' | 'INACTIVE' | 'CHURNED', required — Customer status
    - `phoneNumber` string, nullable — Primary phone number
    - `website` string, nullable — Customer website URL
    - `createdAt` string, date-time, required — When the customer was created
    - `updatedAt` string, date-time, required — When the customer was last updated
    - `deletedAt` string, date-time, nullable — When the customer was soft deleted (null if active)
  - `status` 'DRAFT' | 'AWAITING_PAYMENT' | 'PARTIALLY_PAID' | 'PAID' | 'VOIDED', required — Current status of the invoice. - `DRAFT`: Invoice record exists but not finalized - `AWAITING_PAYMENT`: Invoice finalized, awaiting payment - `PARTIALLY_PAID`: Some payments received, balance remains - `PAID`: Fully paid - `VOIDED`: Invoice cancelled/voided
  - `invoiceDate` string, date, required — Date invoice was issued
  - `dueDate` string, date, nullable — Payment due date
  - `amount` number, required — Total invoice amount
  - `currency` string, nullable — Currency code (USD, CAD)
  - `reference` string, nullable — External reference number
  - `amountPaid` number — Total payments received
  - `amountOwed` number — Outstanding balance
  - `creditsApplied` number, nullable — Total credits applied
  - `paymentTerm` PaymentTermReference — Enhanced reference to a payment term resource (returned in responses). Includes full payment term details in addition to id/key.
    - `id` string, uuid, required — Payment term UUID
    - `key` string, nullable — Client-defined reference ID if set
    - `name` string, required — Payment term name
    - `description` string, nullable — Payment term description or notes
    - `days` integer, nullable — Number of days until payment is due
    - `quickPayFee` number, float, nullable — Quick pay fee percentage (e.g., 0.05 for 5%)
    - `apOnly` boolean, nullable — Whether this payment term is for accounts payable only
    - `doNotUse` boolean, nullable — Flag to prevent using this payment term for new transactions
    - `createdAt` string, date-time, required — When the payment term was created
    - `updatedAt` string, date-time, required — When the payment term was last updated
    - `deletedAt` string, date-time, nullable — When the payment term was soft deleted (null if active)
  - `payments` InvoicePayment[] — Payments applied to this invoice
    - `id` string, uuid
    - `paymentGroupId` string, uuid
    - `amount` number — Amount applied to this invoice
    - `paymentDate` string, date
    - `reference` string, nullable — Check number, transaction ID, etc.
    - `paymentMethodType` string, nullable — Payment method (check, ach_wire, etc.)
  - `credits` InvoiceCredit[] — Credits applied to this invoice
    - `id` string, uuid
    - `creditMemoId` string, uuid
    - `creditMemoReference` string, nullable
    - `amount` number — Credit amount applied
    - `appliedAt` string, date-time
  - `factorName` 'DENIM' | 'HAULPAY' — Factoring provider for invoice financing. - `DENIM`: Denim factoring - `HAULPAY`: HaulPay factoring
  - `factorJobId` string, nullable — External factoring job ID
  - `factorStatus` string, nullable — Current factoring status
  - `qboId` string, nullable — QuickBooks Online invoice ID
  - `documentId` string, uuid, nullable — Generated invoice PDF document ID
  - `documentUrl` string, nullable — Download URL for invoice PDF
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, nullable

## Other responses

- `400` — Bad request - invalid input
- `401` — Unauthorized - invalid or missing access token
- `409` — Order already has an invoice
- `422` — Validation error - invalid field values

---

[API](https://skmtc.net/mvmnt/apis/mvmnt-api.md) · [All operations](https://skmtc.net/mvmnt/apis/mvmnt-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mvmnt/mvmnt-api/versions/c44e5e7a4256/schema)