Invoices API Reference for Nymble Commerce

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.

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.

The invoice object

string

Unique identifier for the invoice (GUID).

organizationId

string

The tenant organization this invoice belongs to.

orderId

string

The ID of the order this invoice is associated with.

orderNumber

string

Human-readable order number.

invoiceNumber

string

Human-readable invoice number (e.g. INV-00892). Supply your own on import to preserve existing numbers.

externalId

string

Your system’s identifier for this invoice.

status

string

Current invoice state: Draft, Issued, PartiallyPaid, Paid, Voided, or Cancelled.

invoiceDate

string (ISO 8601)

The date the invoice was created.

dueDate

string (ISO 8601)

The payment due date.

terms

string

Payment terms (e.g. Net30).

currencyCode

string

ISO 4217 currency code (e.g. USD).

poNumber

string

Customer’s purchase order number.

notes

string

Free-text notes on the invoice.

customer

object

Customer details. Includes customerNumber, companyName, companyEmail, companyPhone, billingAddress, and shippingAddress.

primarySalesRep

object

Sales rep details. Includes repNumber, firstName, lastName, fullName, email, phoneNumber.

items

array

Invoice line items.

Show item fields

payments

array

Payment records attached to this invoice.

Show payment fields

Endpoints

List invoices

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

Query parameters

customerId

string

Filter invoices by customer ID.

orderId

string

Filter invoices by order ID. Use this to retrieve all invoices for a specific order.

status

string

Filter by invoice status: Draft, Issued, PartiallyPaid, Paid, Voided, or Cancelled.

page

integer

Page number. Defaults to 1.

pageSize

integer

Results per page. Defaults to 25.

Example request

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

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

Response

{
  "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

invoiceId

string

required

The unique identifier (GUID) of the invoice.

Example request

curl https://api.achievemomentum.com/api/invoices/inv-uuid-00892 \
  -H "Authorization: Bearer <token>"

Response

Returns 200 OK with the full 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.

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.

Request body

orderId

string

required

The ID of the order this invoice is for.

orderNumber

string

The order number. Optional — used for display purposes.

invoiceNumber

string

Supply an existing invoice number to import it. When omitted, Nymble Commerce generates one automatically.

customer

object

required

Customer details for the invoice.

Show customer fields

billingAddress

object

Billing address. Fields: address1, address2, city, stateProvince, zipPostalCode, country.

shippingAddress

object

Shipping address. Same fields as billingAddress.

primarySalesRep

object

required

Sales rep details.

Show salesRep fields

poNumber

string

Customer’s purchase order number.

invoiceDate

string (ISO 8601)

required

The invoice date.

dueDate

string (ISO 8601)

required

The payment due date.

terms

string

required

Payment terms (e.g. Net30, Net60).

currencyCode

string

required

ISO 4217 currency code (e.g. USD).

notes

string

Free-text notes.

items

array

required

Invoice line items.

Show item fields

tax

number

Tax amount to apply.

discount

object

Order-level discount. Fields: code, type (Percentage or Amount), value, description.

importedInvoiceTotal

number

Authoritative total from an external system. When supplied, overrides the computed line-item total.

importedBalance

number

Outstanding balance from an external system. Supply alongside importedInvoiceTotal — Nymble Commerce derives the amount paid as importedInvoiceTotal − importedBalance.

active

boolean

Set to false to soft-delete the matching invoice on import. Defaults to true.

Example request

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": "[email protected]",
      "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

invoices

array

required

An array of invoice objects. Each follows the same shape as POST /api/invoices.

Example request

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

invoiceId

string

required

The unique identifier of the invoice to update.

Request body

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

Example request

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

invoiceId

string

required

The unique identifier of the invoice to issue.

Example request

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

invoiceId

string

required

The unique identifier of the invoice being paid.

Request body

amount

number

required

Payment amount.

currencyCode

string

required

ISO 4217 currency code (e.g. USD).

method

string

required

Payment method (e.g. EFT, Check, Wire, Cash).

paymentDate

string (ISO 8601)

required

Date the payment was received.

reference

string

External reference number (e.g. cheque number, wire reference, bank trace ID).

notes

string

Internal notes about this payment.

paymentProfileId

string

If paid using a saved card on file, the payment profile ID.

cardType

string

Card brand if applicable (e.g. Visa, Mastercard).

last4Digits

string

Last four digits of the card if applicable.

status

string

Payment status to record. Defaults to Completed.

Example request

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.

Path parameters

invoiceId

string

required

The unique identifier of the invoice.

paymentId

string

required

The ID of the pending payment record to complete.

Example request

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

invoiceId

string

required

The unique identifier of the invoice.

paymentId

string

required

The ID of the payment to refund.

Request body

amount

number

required

Amount to refund. Must not exceed the payment’s net amount.

reference

string

Refund reference number.

notes

string

Reason or notes for the refund.

Example request

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

invoiceId

string

required

The unique identifier of the invoice.

Example request

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

invoiceId

string

required

The unique identifier of the invoice.

Request body

discount

object

required

The discount to apply.

Show discount fields

type

string

required

Discount type: Percentage or Amount.

value

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.

code

string

Optional discount or promo code for reference.

description

string

Human-readable description (e.g. Loyalty discount).

Example request

# 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"
    }
  }'

# 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

invoiceId

string

required

The unique identifier of the invoice.

Example request

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.

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

Path parameters

invoiceId

string

required

The unique identifier of the invoice to void.

Example request

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).

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

Path parameters

invoiceId

string

required

The unique identifier of the invoice to cancel.

Example request

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

invoiceId

string

required

The unique identifier of the draft invoice to delete.

Example request

curl -X DELETE https://api.achievemomentum.com/api/invoices/inv-uuid-00892 \
  -H "Authorization: Bearer <token>"

Response

Returns 204 No Content on success.

​Invoice states

​The invoice object

​Endpoints

​List invoices

​Query parameters

​Example request

​Response

​Get an invoice

​Path parameters

​Example request

​Response

​Create an invoice

​Request body

​Example request

​Response

​Bulk create invoices

​Request body

​Example request

​Update an invoice

​Path parameters

​Request body

​Example request

​Response

​Issue an invoice

​Path parameters

​Example request

​Response

​Record an offline payment

​Path parameters

​Request body

​Example request

​Response

​Complete a hosted payment

​Path parameters

​Example request

​Response

​Refund a payment

​Path parameters

​Request body

​Example request

​Response

​Mark a payment as failed

​Path parameters

​Example request

​Response

​Apply a discount

​Path parameters

​Request body

​Example request

​Response

​Remove a discount

​Path parameters

​Example request

​Response

​Void an invoice

​Path parameters

​Example request

​Response

​Cancel an invoice

​Path parameters

​Example request

​Response

​Delete an invoice

​Path parameters

​Example request

​Response

Invoice states

The invoice object

Endpoints

List invoices

Query parameters

Example request

Response

Get an invoice

Path parameters

Example request

Response

Create an invoice

Request body

Example request

Response

Bulk create invoices

Request body

Example request

Update an invoice

Path parameters

Request body

Example request

Response

Issue an invoice

Path parameters

Example request

Response

Record an offline payment

Path parameters

Request body

Example request

Response

Complete a hosted payment

Path parameters

Example request

Response

Refund a payment

Path parameters

Request body

Example request

Response

Mark a payment as failed

Path parameters

Example request

Response

Apply a discount

Path parameters

Request body

Example request

Response

Remove a discount

Path parameters

Example request

Response

Void an invoice

Path parameters

Example request

Response

Cancel an invoice

Path parameters

Example request

Response

Delete an invoice

Path parameters

Example request

Response