Invoices#

Inventory Preflight#

Evaluate the complete candidate Invoice against current branch availability without saving the
Invoice or changing inventory.

Endpoint#

Without invoiceId, the caller needs invoices.create; merchant scope is resolved the same way as
Create. With invoiceId, the caller needs invoices.manage; the server loads the Invoice inside
the authenticated tenant/merchant scope. Do not send merchantId in the body. An inaccessible Edit
Invoice returns the normal non-disclosing 404 NOT_FOUND, while a permission failure returns
403 FORBIDDEN.

Request#

{
  "invoiceLocationType": "online",
  "lineItems": [
    {
      "lineId": "li_1",
      "productId": "c126128b-7447-414f-80a9-61582fd8a608",
      "quantity": 8,
      "stockLocationId": "2d8b4e17-ec2e-41f2-b6e9-6a32c5fd1780"
    }
  ]
}

Unknown top-level or line fields are rejected with 400 VALIDATION_ERROR, including attempted
client authority such as availability, policy, tracking state, branch names, tenant, or merchant.
Blank/duplicate line IDs, malformed quantities, more than 200 lines, and Products unavailable in
the resolved merchant scope also return the normal validation envelope.

Response#

200 OK returns { "success": true, "data": { "lines": [], "blockingErrors": [], "advisories": [] } } even when blockingErrors is nonempty:

Each issue contains type (missing_location, inactive_location, or insufficient_stock),
severity (error or warning), lineIds, productId, productName, nullable locationId and
locationName, requestedQuantity, availableQuantity, and reservedQuantity.

Every active physical branch is returned, including branches with zero balance. For Edit,
availableQuantity adds back only that Invoice's own active holds before evaluating the candidate;
other Invoices' reservations remain unavailable. Duplicate Product lines sharing a branch are
grouped for issues and allocated in stable lineId order, so expectedReservedQuantity,
shortfallQuantity, and availableAfterOtherDraftLines are deterministic.

missing_location, inactive_location, and insufficient stock with zero-stock selling disabled
are blocking errors. Insufficient stock with zero-stock selling enabled is a warning advisory;
short branches remain selectable and the expected quantity is bounded by current Available.
Issues include affected lineIds plus Product, branch, Requested, Available, and Reserved facts.

Preflight is advisory, not a reservation or approval. It performs no Invoice, balance,
reservation, or Activity write, and its expectedReservedQuantity is not committed stock. A later
Create, Send, or Edit remains authoritative and may observe newer inventory.

Create an Invoice#

Endpoint#

Request#

curl -X POST https://uat.auxcore.net/api/v1/invoices \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "6f1c2a9e-3b7d-4e21-9a55-0c8f1d2b7e40",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "customerPhone": "5551234567",
    "lineItems": [
      {
        "id": "li_1",
        "name": "Web Design Services",
        "description": "Homepage redesign",
        "quantity": 10,
        "unit": "hour",
        "unitPrice": 150.00,
        "taxRate": 8
      },
      {
        "id": "li_2",
        "name": "Hosting (Annual)",
        "quantity": 1,
        "unitPrice": 299.00,
        "discount": 10,
        "discountType": "percent"
      }
    ],
    "issueDate": "2026-10-01",
    "dueDate": "2026-10-15",
    "discountAmount": 29.90,
    "allowPartialPayment": true,
    "minimumPaymentType": "percent",
    "minimumPaymentValue": 25,
    "notes": "Payment due within 15 days",
    "poNumber": "PO-456",
    "invoiceLocationType": "physical",
    "stockLocationId": "2d8b4e17-ec2e-41f2-b6e9-6a32c5fd1780",
    "metadata": { "location": "Headquarters" }
  }'

Body Parameters#

Line Item Fields#

See Writable and response-only line location fields
for the server-derived fields that can appear when the Invoice is read.

amount, taxAmount, subtotal and totalAmount are always calculated by the server; any values you send are overwritten. Totals: totalAmount = subtotal − discountAmount + taxAmount + freightAmount + convenienceFee, where subtotal is quantity × unit price before any discount.

Line discounts must also be counted in discountAmount. A line's discount lowers that line's taxable base, but the invoice total only subtracts the invoice-level discountAmount. Send discountAmount as the sum of all line discounts plus any invoice-level discount (the example above: 10% of 299.00 = 29.90), otherwise the line discount is not taken off the total.

Response#

201 Created with the invoice:

{
  "success": true,
  "data": {
    "id": "0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10",
    "invoiceNumber": "INV-2026-000123",
    "displayInvoiceNumber": "INV-2026-000123",
    "linkId": "INV-1790812800000-A1B2C3D4",
    "shortLink": "https://uat.auxcore.net/s/Ab12Cd",
    "merchantId": "6f1c2a9e-3b7d-4e21-9a55-0c8f1d2b7e40",
    "type": "standard",
    "status": "sent",
    "customerId": "3d7f0c1e-8a2b-4f6d-b9c3-1e5a7d2f8b04",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "lineItems": [ ... ],
    "subtotal": 1799.00,
    "discountAmount": 29.90,
    "taxAmount": 120.00,
    "convenienceFee": 0,
    "totalAmount": 1889.10,
    "amountPaid": 0,
    "amountDue": 1889.10,
    "currency": "USD",
    "allowPartialPayment": true,
    "minimumPaymentType": "percent",
    "minimumPaymentValue": 25,
    "issueDate": "2026-10-01",
    "dueDate": "2026-10-15",
    "invoiceLocationType": "physical",
    "stockLocationId": "2d8b4e17-ec2e-41f2-b6e9-6a32c5fd1780",
    "stockLocationName": "Headquarters",
    "inventoryVersion": 0,
    "metadata": { "location": "Headquarters" },
    "createdAt": "2026-10-01T09:00:00.000Z"
  }
}

Money fields (subtotal, discountAmount, taxAmount, convenienceFee, totalAmount, amountPaid, amountDue, minimumPaymentValue) are numbers in this create response but decimal strings (e.g. "1889.10") whenever the invoice is read back (get, list, lookup); write responses can mix both (e.g. after a payment amountPaid / amountDue are numbers while totalAmount is a string). Parse them before doing arithmetic. Amounts inside paymentHistory entries are numbers.

The customer pays at shortLink, or at {host}/pay/invoice/{linkId} when no short link was minted.

Errors#

Send an Invoice#

Send invoice via email or SMS. See Sending & Delivery for all delivery endpoints.

Endpoint#

curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{ "method": "email", "to": "john@example.com" }'

method (email or sms) and to are both required, but to is only checked for presence: the invoice is always delivered to its stored customerEmail / customerPhone. To send to a different address, edit the invoice first.

When a draft first enters sent, the server validates the explicit physical fulfillment location
and reserves each tracked Product line atomically before delivery. A failed validation or
insufficient-stock result leaves the Invoice draft, balances, reservations, and Activity
unchanged. A later notification-delivery failure does not undo a reservation that the server has
already committed.

An insufficient-stock Send returns this structured error when zero-stock selling is disabled:

{
  "success": false,
  "error": {
    "code": "INVOICE_INVENTORY_INSUFFICIENT",
    "message": "Inventory is not available for this invoice.",
    "details": {
      "violations": [
        {
          "productId": "c126128b-7447-414f-80a9-61582fd8a608",
          "productName": "Widget",
          "requestedQuantity": 5,
          "availableQuantity": 3,
          "locationId": "2d8b4e17-ec2e-41f2-b6e9-6a32c5fd1780",
          "locationName": "Warehouse East"
        }
      ]
    }
  }
}

Record a Payment#

Record money that has already been collected against an invoice (full or partial). This endpoint does not charge a card — see Invoice Payments.

Endpoint#

curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/payment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500.00,
    "paymentMethod": "card",
    "transactionId": "TXN-20261001-8F3A2C",
    "notes": "First installment"
  }'

Response: the updated invoice, e.g. "status": "partial", "amountPaid": 500, "amountDue": 1389.1, with the payment appended to paymentHistory.

Get Invoice#

Endpoint#

curl https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response: the full invoice object (same shape as create), including paymentHistory,
deliveryHistory, editHistory, viewCount, sentAt, viewedAt, paidAt, and these
server-derived detail additions:

• fulfillmentLocationLocked and fulfillmentLocationLockReason (first_payment or null)
• inventoryReservation.state: none, active, partial, converted_to_sale, or released
• inventoryReservation.lines[]: Product, physical location, requested/reserved/unreserved
  quantities, persisted line state, and updatedAt
• inventoryActivity[]: server-recorded reservation and settlement quantities; clients must not
  infer Activity from balance totals
• Historical rows always include locationId. locationName is nullable when the row belongs to
  an earlier fulfillment location whose name is not available from the Invoice's current snapshot;
  clients must not display the UUID as though it were a branch name.

{
  "success": true,
  "data": {
    "id": "0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10",
    "invoiceNumber": "INV-2026-000123",
    "status": "partial",
    "totalAmount": "1889.10",
    "amountPaid": "500.00",
    "amountDue": "1389.10",
    "invoiceLocationType": "online",
    "stockLocationId": "2d8b4e17-ec2e-41f2-b6e9-6a32c5fd1780",
    "stockLocationName": "Warehouse East",
    "inventoryVersion": 0,
    "fulfillmentLocationLocked": true,
    "fulfillmentLocationLockReason": "first_payment",
    "inventoryReservation": {
      "state": "active",
      "lines": [
        {
          "lineId": "li_1",
          "productId": "c126128b-7447-414f-80a9-61582fd8a608",
          "productName": "Widget",
          "locationId": "2d8b4e17-ec2e-41f2-b6e9-6a32c5fd1780",
          "locationName": "Warehouse East",
          "requestedQuantity": 5,
          "reservedQuantity": 5,
          "unreservedQuantity": 0,
          "state": "active",
          "updatedAt": "2026-10-01T09:01:00.000Z"
        }
      ]
    },
    "inventoryActivity": [
      {
        "id": "c983fef5-37d8-4a2e-a766-c034220f3001",
        "type": "reservation_created",
        "productId": "c126128b-7447-414f-80a9-61582fd8a608",
        "locationId": "2d8b4e17-ec2e-41f2-b6e9-6a32c5fd1780",
        "locationName": "Warehouse East",
        "requestedQuantity": 5,
        "reservedQuantity": 5,
        "deductedQuantity": null,
        "notDeductedQuantity": 0,
        "reservationDelta": 5,
        "reservedAfter": 5,
        "createdAt": "2026-10-01T09:01:00.000Z"
      }
    ],
    "paymentHistory": [
      {
        "amount": 500.00,
        "paymentMethod": "card",
        "paidAt": "2026-10-02T17:00:00.000Z",
        "transactionId": "TXN-20261001-8F3A2C",
        "isExternal": false,
        "balanceAfter": 1389.10
      }
    ],
    "dueDate": "2026-10-15"
  }
}

Returns 404 NOT_FOUND when the invoice does not exist in your tenant.

List Invoices#

Endpoint#

Query Parameters#

curl "https://uat.auxcore.net/api/v1/invoices?status=overdue&limit=25" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": [ { "id": "0b8e6a3c-...", "invoiceNumber": "INV-2026-000123", "status": "overdue" } ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "statusCounts": { "all": 42, "sent": 10, "overdue": 1, "paid": 31 }
  }
}

Invoice Summary#

KPIs and status counts for the invoices dashboard.

Endpoint#

Optional query: merchantId.

{
  "success": true,
  "data": {
    "statusCounts": { "all": 42, "sent": 10, "overdue": 1, "paid": 31 },
    "outstandingTotal": 12500.00,
    "outstandingCount": 11,
    "overdueTotal": 1889.10,
    "overdueCount": 1,
    "paidMonthTotal": 8200.00,
    "paidMonthCount": 9,
    "avgTimeToPayDays": 6.4,
    "avgTimeToPaySampleSize": 31
  }
}

Update Invoice#

Update a draft invoice. Any other status returns 400 VALIDATION_ERROR ("Only draft invoices can be updated") — to change an invoice that has already been sent, viewed or partially paid, use Edit Invoice below, which rotates the payment link and re-sends the updated invoice.

Endpoint#

curl -X PUT https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "lineItems": [ ... ],
    "notes": "Updated payment terms"
  }'

Takes the create fields. When lineItems is sent, totals are recalculated, and a product whose
total quantity rises above its maxQuantity is refused with 400 QUANTITY_LIMIT_EXCEEDED (a
quantity already on the invoice before the limit was set or lowered is kept).

Saving a draft still has no inventory effect. If invoiceLocationType is physical,
stockLocationId must be that Invoice Location's active branch id even while draft.

Edit Invoice#

Edit an existing invoice in place — the same invoice id and invoice number are returned. The behaviour depends on the invoice's current status, which is re-checked in the API against the latest database row at the moment of the call:

• draft / sent / viewed → full edit. The payment link is rotated: the old linkId is invalidated (it now serves a "link no longer available" message) and a new linkId / shortLink is issued. Status is set to sent and the invoice is auto-resent via Email (when it has an email) and SMS (when it has a phone). Channels are chosen by the system — there is no channel picker.
• Full edit with "resend": false → the invoice is updated in place; the link, status and balance are kept and nothing is sent.
• partial → due date, notes and allowRescheduleNextPayment only. The existing link is kept, amounts and payment history are untouched, and nothing is resent. Any amount-affecting field in the body (lineItems, taxRate, discountAmount, convenienceFee, currency, totalAmount, amount, allowPartialPayment, minimumPaymentType, minimumPaymentValue) is rejected with 400.
• paid → 409 CONFLICT. cancelled / expired / overdue / pending → 400 VALIDATION_ERROR.

Endpoint#

Full edit (draft / sent / viewed)#

curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/edit \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "customerName": "Acme Corp",
    "customerEmail": "ap@acme.example",
    "customerPhone": "+15551234567",
    "lineItems": [
      { "id": "li_1", "name": "Consulting", "quantity": 2, "unitPrice": 125.00, "taxRate": 8.5 }
    ],
    "discountAmount": 0,
    "allowPartialPayment": true,
    "dueDate": "2026-10-31",
    "notes": "Updated scope"
  }'

Fields you omit keep their current value; metadata is merged into the existing metadata.
Before the first payment, changing tracked lines or stockLocationId on an issued Invoice causes
the server to reconcile the existing reservation atomically. After the first payment,
stockLocationId and invoiceLocationType are locked; a change returns
409 FULFILLMENT_LOCATION_LOCKED with error.details.reason: "first_payment".

Response (200): the same invoice with a new linkId, the rotated-out id in previousLinkId, and a meta.delivery block reporting the resend outcome (sent, failed or skipped per channel).

{
  "success": true,
  "data": {
    "id": "0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10",
    "invoiceNumber": "INV-2026-000123",
    "status": "sent",
    "linkId": "INV-1790899200000-NEW12345",
    "shortLink": "https://uat.auxcore.net/s/Xy98Zw",
    "previousLinkId": "INV-1790812800000-A1B2C3D4",
    "totalAmount": "271.25",
    "amountPaid": "0.00",
    "amountDue": "271.25",
    "dueDate": "2026-10-31"
  },
  "meta": { "delivery": { "email": "sent", "sms": "sent" } }
}

shortLink may be missing if the shortener was unavailable; fall back to {host}/pay/invoice/{linkId}. If a resend fails the invoice and the new link stay active (meta.delivery reports failed); call send-email / send-sms to retry delivery.

Partial edit (due date + notes only)#

curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/edit \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{ "dueDate": "2026-11-15", "notes": "Extended terms" }'

Response (200): the same invoice in place — linkId, amounts and payment history are all unchanged; only dueDate (and optionally notes) change. No resend is performed.

Old payment link after a full edit#

Once a full edit rotates the link, the old pay URL (/pay/invoice/{oldLinkId}) resolves to:

{
  "success": false,
  "error": {
    "code": "LINK_ROTATED",
    "message": "This invoice link is no longer available. Please use the latest invoice link."
  }
}

returned with HTTP 410 Gone. A link that was never issued still returns 404.

Errors#

Cancel Invoice#

Void an issued invoice. Only issued, unpaid invoices (sent, viewed) can be cancelled; there is no request body.

Endpoint#

curl -X POST https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/cancel \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response: the invoice with "status": "cancelled", cancelledAt and cancelledBy. The
server releases every active inventory reservation before committing the terminal status. The
void endpoint follows the same release rule.

Delete Invoice#

Soft-delete a draft or cancelled invoice. Response: { "success": true, "data": { "message": "Invoice deleted successfully" } }.

Any other status is refused, but the API currently reports it as 500 INTERNAL_ERROR ("Failed to delete invoice") rather than a 400; 404 NOT_FOUND when the invoice does not exist.

Endpoint#

curl -X DELETE https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Generate QR Code#

Get a QR code for the invoice's pay link.

Endpoint#

curl https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/qr-code \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
  }
}

Download PDF#

Get invoice as PDF (Content-Type: application/pdf, sent as an attachment).

Endpoint#

curl https://uat.auxcore.net/api/v1/invoices/0b8e6a3c-5d2f-4c71-9e1a-7f3b2c9d4e10/pdf \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -o invoice.pdf