> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nymblecommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoices API Reference for Nymble Commerce

> REST API reference for Nymble Commerce invoice management — list, create, issue, pay, refund, discount, void, and cancel invoices for B2B orders.

The Invoices API manages the complete invoice lifecycle — from creation and issuance through payment collection, discounts, refunds, and voids. Invoices are always associated with an order and a customer, and track exactly how much has been billed, paid, and remains outstanding.

***

## Invoice states

Invoices move through a defined set of states. Understanding which state an invoice is in determines which actions you can take on it.

| State           | Description                                                                             |
| --------------- | --------------------------------------------------------------------------------------- |
| `Draft`         | Invoice has been created but not yet sent. Still editable. Not yet payable.             |
| `Issued`        | Invoice has been issued to the customer and is now payable.                             |
| `PartiallyPaid` | One or more payments have been recorded, but a balance remains.                         |
| `Paid`          | The invoice has been paid in full (balance = 0).                                        |
| `Voided`        | Removed from accounts receivable. Only possible from `Draft` or `Issued`. Irreversible. |
| `Cancelled`     | Administratively cancelled. The record is preserved for audit purposes. Irreversible.   |

<Warning>
  Voiding and cancelling are both irreversible. A voided invoice is removed from AR; a cancelled invoice retains its record. Use void for erroneous invoices and cancel for legitimate business cancellations.
</Warning>

***

## The invoice object

<ResponseField name="id" type="string">
  Unique identifier for the invoice (GUID).
</ResponseField>

<ResponseField name="organizationId" type="string">
  The tenant organization this invoice belongs to.
</ResponseField>

<ResponseField name="orderId" type="string">
  The ID of the order this invoice is associated with.
</ResponseField>

<ResponseField name="orderNumber" type="string">
  Human-readable order number.
</ResponseField>

<ResponseField name="invoiceNumber" type="string">
  Human-readable invoice number (e.g. `INV-00892`). Supply your own on import to preserve existing numbers.
</ResponseField>

<ResponseField name="externalId" type="string">
  Your system's identifier for this invoice.
</ResponseField>

<ResponseField name="status" type="string">
  Current invoice state: `Draft`, `Issued`, `PartiallyPaid`, `Paid`, `Voided`, or `Cancelled`.
</ResponseField>

<ResponseField name="invoiceDate" type="string (ISO 8601)">
  The date the invoice was created.
</ResponseField>

<ResponseField name="dueDate" type="string (ISO 8601)">
  The payment due date.
</ResponseField>

<ResponseField name="terms" type="string">
  Payment terms (e.g. `Net30`).
</ResponseField>

<ResponseField name="currencyCode" type="string">
  ISO 4217 currency code (e.g. `USD`).
</ResponseField>

<ResponseField name="poNumber" type="string">
  Customer's purchase order number.
</ResponseField>

<ResponseField name="notes" type="string">
  Free-text notes on the invoice.
</ResponseField>

<ResponseField name="customer" type="object">
  Customer details. Includes `customerNumber`, `companyName`, `companyEmail`, `companyPhone`, `billingAddress`, and `shippingAddress`.
</ResponseField>

<ResponseField name="primarySalesRep" type="object">
  Sales rep details. Includes `repNumber`, `firstName`, `lastName`, `fullName`, `email`, `phoneNumber`.
</ResponseField>

<ResponseField name="items" type="array">
  Invoice line items.

  <Expandable title="item fields" />
</ResponseField>

<ResponseField name="payments" type="array">
  Payment records attached to this invoice.

  <Expandable title="payment fields" />
</ResponseField>

***

## Endpoints

### List invoices

Returns a paginated list of invoices. Filter by customer, order, or status using query parameters.

#### Query parameters

<ParamField query="customerId" type="string">
  Filter invoices by customer ID.
</ParamField>

<ParamField query="orderId" type="string">
  Filter invoices by order ID. Use this to retrieve all invoices for a specific order.
</ParamField>

<ParamField query="status" type="string">
  Filter by invoice status: `Draft`, `Issued`, `PartiallyPaid`, `Paid`, `Voided`, or `Cancelled`.
</ParamField>

<ParamField query="page" type="integer">
  Page number. Defaults to `1`.
</ParamField>

<ParamField query="pageSize" type="integer">
  Results per page. Defaults to `25`.
</ParamField>

#### Example request

```bash theme={null}
# List all invoices for a specific order
curl "https://api.achievemomentum.com/api/invoices?orderId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer <token>"
```

```bash theme={null}
# List all unpaid (Issued) invoices
curl "https://api.achievemomentum.com/api/invoices?status=Issued&page=1&pageSize=50" \
  -H "Authorization: Bearer <token>"
```

#### Response

```json theme={null}
{
  "items": [ /* array of invoice objects */ ],
  "totalCount": 124,
  "pageNumber": 1,
  "pageSize": 25,
  "totalPages": 5
}
```

***

### Get an invoice

Retrieves a single invoice by its ID, including all line items and payment history.

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier (GUID) of the invoice.
</ParamField>

#### Example request

```bash theme={null}
curl https://api.achievemomentum.com/api/invoices/inv-uuid-00892 \
  -H "Authorization: Bearer <token>"
```

#### Response

Returns `200 OK` with the full [invoice object](#the-invoice-object).

***

### Create an invoice

Creates a new invoice in `Draft` status. Invoices are normally created automatically when an order ships, but you can use this endpoint to create them manually or to import invoices from another system.

<Tip>
  Supply `invoiceNumber` to preserve an existing invoice number on import. Supply both `importedInvoiceTotal` and `importedBalance` when importing invoices whose payment history is tracked in another system — Nymble Commerce will use those values directly rather than computing them from line items.
</Tip>

#### Request body

<ParamField body="orderId" type="string" required>
  The ID of the order this invoice is for.
</ParamField>

<ParamField body="orderNumber" type="string">
  The order number. Optional — used for display purposes.
</ParamField>

<ParamField body="invoiceNumber" type="string">
  Supply an existing invoice number to import it. When omitted, Nymble Commerce generates one automatically.
</ParamField>

<ParamField body="customer" type="object" required>
  Customer details for the invoice.

  <Expandable title="customer fields">
    <ParamField body="billingAddress" type="object">
      Billing address. Fields: `address1`, `address2`, `city`, `stateProvince`, `zipPostalCode`, `country`.
    </ParamField>

    <ParamField body="shippingAddress" type="object">
      Shipping address. Same fields as `billingAddress`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="primarySalesRep" type="object" required>
  Sales rep details.

  <Expandable title="salesRep fields" />
</ParamField>

<ParamField body="poNumber" type="string">
  Customer's purchase order number.
</ParamField>

<ParamField body="invoiceDate" type="string (ISO 8601)" required>
  The invoice date.
</ParamField>

<ParamField body="dueDate" type="string (ISO 8601)" required>
  The payment due date.
</ParamField>

<ParamField body="terms" type="string" required>
  Payment terms (e.g. `Net30`, `Net60`).
</ParamField>

<ParamField body="currencyCode" type="string" required>
  ISO 4217 currency code (e.g. `USD`).
</ParamField>

<ParamField body="notes" type="string">
  Free-text notes.
</ParamField>

<ParamField body="items" type="array" required>
  Invoice line items.

  <Expandable title="item fields" />
</ParamField>

<ParamField body="tax" type="number">
  Tax amount to apply.
</ParamField>

<ParamField body="discount" type="object">
  Order-level discount. Fields: `code`, `type` (`Percentage` or `Amount`), `value`, `description`.
</ParamField>

<ParamField body="importedInvoiceTotal" type="number">
  Authoritative total from an external system. When supplied, overrides the computed line-item total.
</ParamField>

<ParamField body="importedBalance" type="number">
  Outstanding balance from an external system. Supply alongside `importedInvoiceTotal` — Nymble Commerce derives the amount paid as `importedInvoiceTotal − importedBalance`.
</ParamField>

<ParamField body="active" type="boolean">
  Set to `false` to soft-delete the matching invoice on import. Defaults to `true`.
</ParamField>

#### Example request

```bash theme={null}
curl -X POST https://api.achievemomentum.com/api/invoices \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "orderNumber": "ORD-00412",
    "customer": {
      "customerNumber": "CUST-1042",
      "companyName": "Brightfield Supply Co.",
      "companyEmail": "ap@brightfieldsupply.com",
      "billingAddress": {
        "address1": "300 Commerce Blvd",
        "city": "Portland",
        "stateProvince": "OR",
        "zipPostalCode": "97201",
        "country": "US"
      }
    },
    "primarySalesRep": {
      "repNumber": "REP-007",
      "firstName": "Jordan",
      "lastName": "Avery"
    },
    "poNumber": "PO-88412",
    "invoiceDate": "2024-03-15T00:00:00Z",
    "dueDate": "2024-04-14T00:00:00Z",
    "terms": "Net30",
    "currencyCode": "USD",
    "items": [
      {
        "sku": "WDG-BLU-L",
        "productName": "Widget Blue Large",
        "quantity": 24,
        "price": 12.50
      }
    ],
    "tax": 28.80
  }'
```

#### Response

Returns `201 Created` with the new invoice object in `Draft` status.

***

### Bulk create invoices

Creates multiple invoices in a single request. Follows the same rules as the single create endpoint. Use `invoiceNumber` on each entry to make the import idempotent.

#### Request body

<ParamField body="invoices" type="array" required>
  An array of invoice objects. Each follows the same shape as `POST /api/invoices`.
</ParamField>

#### Example request

```bash theme={null}
curl -X POST https://api.achievemomentum.com/api/invoices/bulk \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "invoices": [
      {
        "orderId": "ord-uuid-001",
        "invoiceNumber": "INV-2023-001",
        "customer": { "customerNumber": "CUST-0055", "companyName": "Apex Distributors" },
        "primarySalesRep": { "repNumber": "REP-003" },
        "invoiceDate": "2023-06-15T00:00:00Z",
        "dueDate": "2023-07-15T00:00:00Z",
        "terms": "Net30",
        "currencyCode": "USD",
        "items": [
          { "sku": "PART-A1", "productName": "Part A1", "quantity": 100, "price": 4.25 }
        ],
        "importedInvoiceTotal": 425.00,
        "importedBalance": 0.00
      }
    ]
  }'
```

***

### Update an invoice

Updates an existing invoice. You can update most fields while the invoice is in `Draft` status.

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the invoice to update.
</ParamField>

#### Request body

Accepts the same fields as `POST /api/invoices`. Only supply fields you want to change.

#### Example request

```bash theme={null}
curl -X PUT https://api.achievemomentum.com/api/invoices/inv-uuid-00892 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "dueDate": "2024-05-01T00:00:00Z",
    "notes": "Extended due date per customer request."
  }'
```

#### Response

Returns `200 OK` with the updated invoice object.

***

### Issue an invoice

Transitions an invoice from `Draft` to `Issued`. Once issued, the invoice is payable and visible to the customer. You cannot issue an already-issued, paid, voided, or cancelled invoice.

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the invoice to issue.
</ParamField>

#### Example request

```bash theme={null}
curl -X POST https://api.achievemomentum.com/api/invoices/inv-uuid-00892/issue \
  -H "Authorization: Bearer <token>"
```

#### Response

Returns `200 OK` with the updated invoice object in `Issued` status.

***

### Record an offline payment

Records a payment made outside the hosted payment flow — such as a bank transfer (EFT), cheque, or wire transfer. The invoice status updates automatically to `PartiallyPaid` or `Paid` based on the resulting balance.

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the invoice being paid.
</ParamField>

#### Request body

<ParamField body="amount" type="number" required>
  Payment amount.
</ParamField>

<ParamField body="currencyCode" type="string" required>
  ISO 4217 currency code (e.g. `USD`).
</ParamField>

<ParamField body="method" type="string" required>
  Payment method (e.g. `EFT`, `Check`, `Wire`, `Cash`).
</ParamField>

<ParamField body="paymentDate" type="string (ISO 8601)" required>
  Date the payment was received.
</ParamField>

<ParamField body="reference" type="string">
  External reference number (e.g. cheque number, wire reference, bank trace ID).
</ParamField>

<ParamField body="notes" type="string">
  Internal notes about this payment.
</ParamField>

<ParamField body="paymentProfileId" type="string">
  If paid using a saved card on file, the payment profile ID.
</ParamField>

<ParamField body="cardType" type="string">
  Card brand if applicable (e.g. `Visa`, `Mastercard`).
</ParamField>

<ParamField body="last4Digits" type="string">
  Last four digits of the card if applicable.
</ParamField>

<ParamField body="status" type="string">
  Payment status to record. Defaults to `Completed`.
</ParamField>

#### Example request

```bash theme={null}
curl -X POST https://api.achievemomentum.com/api/invoices/inv-uuid-00892/payments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 479.30,
    "currencyCode": "USD",
    "method": "EFT",
    "paymentDate": "2024-04-10T00:00:00Z",
    "reference": "WIRE-TXN-884421",
    "notes": "Full payment received via wire transfer."
  }'
```

#### Response

Returns `200 OK` with the updated invoice object, now in `Paid` status.

***

### Complete a hosted payment

Marks a pending payment as complete after a successful hosted payment transaction (e.g. WorldPay). Nymble Commerce calls this internally after receiving the payment provider callback, but you can also call it directly if you need to complete a payment that was initiated via [`POST /api/payments/worldpay/transaction-setup`](/api-reference/payments#initiate-a-hosted-payment-session).

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the invoice.
</ParamField>

<ParamField path="paymentId" type="string" required>
  The ID of the pending payment record to complete.
</ParamField>

#### Example request

```bash theme={null}
curl -X POST https://api.achievemomentum.com/api/invoices/inv-uuid-00892/payments/pay-uuid-55512/complete \
  -H "Authorization: Bearer <token>"
```

#### Response

Returns `200 OK` with the updated invoice object.

***

### Refund a payment

Issues a partial or full refund against a specific payment on the invoice. The invoice balance and status update to reflect the refund. Multiple refunds can be applied to the same payment up to the original payment amount.

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the invoice.
</ParamField>

<ParamField path="paymentId" type="string" required>
  The ID of the payment to refund.
</ParamField>

#### Request body

<ParamField body="amount" type="number" required>
  Amount to refund. Must not exceed the payment's net amount.
</ParamField>

<ParamField body="reference" type="string">
  Refund reference number.
</ParamField>

<ParamField body="notes" type="string">
  Reason or notes for the refund.
</ParamField>

#### Example request

```bash theme={null}
curl -X POST https://api.achievemomentum.com/api/invoices/inv-uuid-00892/payments/pay-uuid-55512/refund \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "notes": "Partial refund for returned goods — 8 units of WDG-BLU-L."
  }'
```

#### Response

Returns `200 OK` with the updated invoice object, including the new refund record.

***

### Mark a payment as failed

Marks a pending payment attempt as failed. Use this when the payment provider reports a declined or failed transaction that was initiated through the hosted payment flow.

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the invoice.
</ParamField>

#### Example request

```bash theme={null}
curl -X POST https://api.achievemomentum.com/api/invoices/inv-uuid-00892/payments/fail \
  -H "Authorization: Bearer <token>"
```

#### Response

Returns `200 OK`. The payment record is updated to `Failed` status; the invoice balance is unchanged.

***

### Apply a discount

Applies an order-level discount to an invoice. You can apply a fixed amount or a percentage. Applying a discount to an invoice that already has one replaces the existing discount.

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the invoice.
</ParamField>

#### Request body

<ParamField body="discount" type="object" required>
  The discount to apply.

  <Expandable title="discount fields">
    <ParamField body="type" type="string" required>
      Discount type: `Percentage` or `Amount`.
    </ParamField>

    <ParamField body="value" type="number" required>
      Discount value. For `Percentage`, supply a value between `0` and `100` (e.g. `10` for 10% off). For `Amount`, supply the monetary amount to deduct.
    </ParamField>

    <ParamField body="code" type="string">
      Optional discount or promo code for reference.
    </ParamField>

    <ParamField body="description" type="string">
      Human-readable description (e.g. `Loyalty discount`).
    </ParamField>
  </Expandable>
</ParamField>

#### Example request

```bash theme={null}
# Apply a 10% discount
curl -X POST https://api.achievemomentum.com/api/invoices/inv-uuid-00892/discount \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "discount": {
      "type": "Percentage",
      "value": 10,
      "code": "LOYAL10",
      "description": "Loyalty programme discount"
    }
  }'
```

```bash theme={null}
# Apply a fixed $25 discount
curl -X POST https://api.achievemomentum.com/api/invoices/inv-uuid-00892/discount \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "discount": {
      "type": "Amount",
      "value": 25.00,
      "description": "Goodwill adjustment"
    }
  }'
```

#### Response

Returns `200 OK` with the updated invoice object reflecting the new `discountAmount` and `invoiceTotal`.

***

### Remove a discount

Removes the order-level discount from an invoice. Line-item discounts are not affected.

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the invoice.
</ParamField>

#### Example request

```bash theme={null}
curl -X DELETE https://api.achievemomentum.com/api/invoices/inv-uuid-00892/discount \
  -H "Authorization: Bearer <token>"
```

#### Response

Returns `200 OK` with the updated invoice object.

***

### Void an invoice

Voids an invoice that is in `Draft` or `Issued` status. Voiding removes the invoice from accounts receivable. You cannot void an invoice that has recorded payments — refund all payments first.

<Warning>
  Voiding is irreversible. Once voided, an invoice cannot be reinstated. Use void for invoices that were created in error.
</Warning>

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the invoice to void.
</ParamField>

#### Example request

```bash theme={null}
curl -X POST https://api.achievemomentum.com/api/invoices/inv-uuid-00892/void \
  -H "Authorization: Bearer <token>"
```

#### Response

Returns `200 OK` with the invoice object in `Voided` status.

***

### Cancel an invoice

Cancels an invoice. Unlike voiding, cancellation retains the full invoice record for audit and reporting purposes. Use cancel for legitimate business cancellations (e.g. order cancelled by customer).

<Warning>
  Cancellation is irreversible. The invoice record is preserved but no further actions can be taken on it.
</Warning>

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the invoice to cancel.
</ParamField>

#### Example request

```bash theme={null}
curl -X POST https://api.achievemomentum.com/api/invoices/inv-uuid-00892/cancel \
  -H "Authorization: Bearer <token>"
```

#### Response

Returns `200 OK` with the invoice object in `Cancelled` status.

***

### Delete an invoice

Permanently deletes a `Draft` invoice. You cannot delete an invoice that has been issued or has any payment history — void or cancel it instead.

#### Path parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the draft invoice to delete.
</ParamField>

#### Example request

```bash theme={null}
curl -X DELETE https://api.achievemomentum.com/api/invoices/inv-uuid-00892 \
  -H "Authorization: Bearer <token>"
```

#### Response

Returns `204 No Content` on success.