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

string

The tenant organization this invoice belongs to.

string

The ID of the order this invoice is associated with.

string

Human-readable order number.

string

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

string

Your system’s identifier for this invoice.

string

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

string (ISO 8601)

The date the invoice was created.

string (ISO 8601)

The payment due date.

string

Payment terms (e.g. Net30).

string

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

string

Customer’s purchase order number.

string

Free-text notes on the invoice.

object

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

object

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

array

Invoice line items.

Show item fields

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

string

Filter invoices by customer ID.

string

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

string

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

integer

Page number. Defaults to 1.

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

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

string

required

The ID of the order this invoice is for.

string

The order number. Optional — used for display purposes.

string

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

object

required

Customer details for the invoice.

Show customer fields

object

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

object

Shipping address. Same fields as billingAddress.

object

required

Sales rep details.

Show salesRep fields

string

Customer’s purchase order number.

string (ISO 8601)

required

The invoice date.

string (ISO 8601)

required

The payment due date.

string

required

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

string

required

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

string

Free-text notes.

array

required

Invoice line items.

Show item fields

number

Tax amount to apply.

object

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

number

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

number

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

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

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

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

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

string

required

The unique identifier of the invoice being paid.

Request body

number

required

Payment amount.

string

required

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

string

required

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

string (ISO 8601)

required

Date the payment was received.

string

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

string

Internal notes about this payment.

string

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

string

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

string

Last four digits of the card if applicable.

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

string

required

The unique identifier of the invoice.

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

string

required

The unique identifier of the invoice.

string

required

The ID of the payment to refund.

Request body

number

required

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

string

Refund reference number.

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

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

string

required

The unique identifier of the invoice.

Request body

object

required

The discount to apply.

Show discount fields

string

required

Discount type: Percentage or Amount.

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.

string

Optional discount or promo code for reference.

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

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

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

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

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