order add-invoice


`command`	`order.add-invoice`
Kind	Write
Needs	`MOSTRO_PUBKEY`, `RELAYS`, identity, the order’s local row, `--yes` in JSON mode
Publishes	One `add-invoice` request signed with the order’s trade key
Local write	Updates the order’s local status; never advances the trade index
Statuses	`ok`, `error`, `uncertain`
Schemas	`schemas/order.add-invoice.input.json`, `schemas/order.add-invoice.output.json`

Gives the node the buyer’s invoice for the sats, when it asked for one (next_step: add_invoice), or replaces it after a failed payment.

Input

Option	Required	Rule
`--order`	yes	UUID of an order in the local store
`--invoice`	yes	A BOLT-11 invoice (for exactly the order’s `sats_amount`, unless the node says otherwise) or a Lightning address
`--yes`	yes in JSON

Behavior

Looks the order up in the local orders table to get its trade key (order_unknown if missing; nothing sent), publishes the request, waits for the reply, updates the local status.

Success data: `OrderInvoiceData`

Field	Type	Meaning
`node_pubkey`	hex64	The node
`order_id`	uuid	The order
`result`	enum	What the node did, below
`order`	OrderRecord or null	The node’s order; present with `payment_accepted`, otherwise null
`trade_pubkey`	hex64	The order’s trade key

`result`	Node reply	Meaning	Next
`waiting_seller_payment`	`waiting-seller-to-pay`	Invoice stored; the seller has not locked the sats yet	Wait (watch `message list`)
`payment_accepted`	`hold-invoice-payment-accepted`	Invoice stored and the seller had already paid: the order is `active`	Pay the fiat, then `order fiat-sent`
`invoice_updated`	`invoice-updated`	A replacement invoice was stored	Wait for the payout

Outcomes

Case	status	code	Stages
Accepted, row updated	`ok`		published / accepted / applied
Accepted, nothing to record (`invoice_updated`)	`ok`		published / accepted / not_attempted
Accepted, row update failed	`ok` + `local_status_stale`		published / accepted / failed
Order not in store	`error`	`order_unknown`	not_attempted / unknown / not_attempted
Other local failure	`error`	its code	not_attempted / unknown / not_attempted
Refused	`error`	`node_refused` + `reason`	published / rejected / not_attempted
No / unusable reply, relay dropped wait	`uncertain`	`reply_timeout`, `reply_malformed`, `relay_read_failed`, `pow_required`	published / unknown / not_attempted
Ambiguous relays	`uncertain`	`request_rejected`	unknown / unknown / not_attempted

After uncertain: order info --order <id>; if the status moved past waiting-buyer-invoice, the invoice was taken.

invalid_arguments, configuration_*, relay_connection_failed, relay_read_failed, internal_error, identity_*, protocol_unsupported, pow_required, request_rejected, node_refused, order_declined (human prompt only), store_unwritable, order_unknown; uncertain: reply_timeout, reply_malformed, request_rejected, relay_read_failed, pow_required.

Warnings

local_status_stale, invalid_order_timestamp, invalid_event_timestamp, cleanup_incomplete.

Examples

A replacement invoice (for example after a failed payment) was stored

order.add-invoice/invoice_updated · status ok · exit 0 · fixture

mostro-cli --output json order add-invoice --order 00000000-0000-0000-0000-000000000001 --invoice lnbcrt150u1p... --yes

{
  "schema_version": "1",
  "command": "order.add-invoice",
  "status": "ok",
  "data": {
    "node_pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
    "order": null,
    "order_id": "00000000-0000-0000-0000-000000000001",
    "result": "invoice_updated",
    "trade_pubkey": "c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5"
  },
  "error": null,
  "warnings": [],
  "meta": {
    "publication": "published",
    "daemon_acceptance": "accepted",
    "persistence": "not_attempted",
    "snapshot": null
  }
}

Invoice accepted and the seller had already paid: the order is active

order.add-invoice/payment_accepted · status ok · exit 0 · fixture

mostro-cli --output json order add-invoice --order 00000000-0000-0000-0000-000000000001 --invoice lnbcrt150u1p... --yes

{
  "schema_version": "1",
  "command": "order.add-invoice",
  "status": "ok",
  "data": {
    "node_pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
    "order": {
      "buyer_trade_pubkey": null,
      "created_at": "2026-10-16T00:00:00Z",
      "created_at_unix": "1792108800",
      "expires_at": "2026-10-17T00:00:00Z",
      "expires_at_unix": "1792195200",
      "fiat_amount": "15",
      "fiat_amount_max": null,
      "fiat_amount_min": null,
      "fiat_currency": "USD",
      "id": "00000000-0000-0000-0000-000000000001",
      "payment_method": "bank transfer",
      "premium_percent": "1",
      "sats_amount": "15000",
      "seller_trade_pubkey": null,
      "side": "sell",
      "status": "active"
    },
    "order_id": "00000000-0000-0000-0000-000000000001",
    "result": "payment_accepted",
    "trade_pubkey": "c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5"
  },
  "error": null,
  "warnings": [],
  "meta": {
    "publication": "published",
    "daemon_acceptance": "accepted",
    "persistence": "applied",
    "snapshot": null
  }
}

Accepted, but the local status could not be updated: ok with a warning

order.add-invoice/stale_status · status ok · exit 0 · fixture

mostro-cli --output json order add-invoice --order 00000000-0000-0000-0000-000000000001 --invoice lnbcrt150u1p... --yes

{
  "schema_version": "1",
  "command": "order.add-invoice",
  "status": "ok",
  "data": {
    "node_pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
    "order": null,
    "order_id": "00000000-0000-0000-0000-000000000001",
    "result": "waiting_seller_payment",
    "trade_pubkey": "c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5"
  },
  "error": null,
  "warnings": [
    {
      "code": "local_status_stale",
      "message": "The node accepted the invoice but the local order status could not be updated."
    }
  ],
  "meta": {
    "publication": "published",
    "daemon_acceptance": "accepted",
    "persistence": "failed",
    "snapshot": null
  }
}

Invoice accepted; the seller has not paid yet

order.add-invoice/waiting_seller_payment · status ok · exit 0 · fixture

mostro-cli --output json order add-invoice --order 00000000-0000-0000-0000-000000000001 --invoice lnbcrt150u1p... --yes

{
  "schema_version": "1",
  "command": "order.add-invoice",
  "status": "ok",
  "data": {
    "node_pubkey": "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798",
    "order": null,
    "order_id": "00000000-0000-0000-0000-000000000001",
    "result": "waiting_seller_payment",
    "trade_pubkey": "c6047f9441ed7d6d3045406e95c07cd85c778e4b8cef3ca7abac09b95c709ee5"
  },
  "error": null,
  "warnings": [],
  "meta": {
    "publication": "published",
    "daemon_acceptance": "accepted",
    "persistence": "applied",
    "snapshot": null
  }
}

A Lightning address sent; the relays dropped the wait afterwards

order.add-invoice/relay_read_failed_uncertain · status uncertain · relay_read_failed · exit 1 · authored

mostro-cli --output json order add-invoice --order 00000000-0000-0000-0000-000000000001 --invoice buyer@ln.example --yes

{
  "schema_version": "1",
  "command": "order.add-invoice",
  "status": "uncertain",
  "data": null,
  "error": {
    "code": "relay_read_failed",
    "message": "A configured relay failed during the public order read."
  },
  "warnings": [],
  "meta": {
    "publication": "published",
    "daemon_acceptance": "unknown",
    "persistence": "not_attempted",
    "snapshot": null
  }
}

An answer that could not be used

order.add-invoice/reply_malformed_uncertain · status uncertain · reply_malformed · exit 1 · fixture

mostro-cli --output json order add-invoice --order 00000000-0000-0000-0000-000000000001 --invoice lnbcrt150u1p... --yes

{
  "schema_version": "1",
  "command": "order.add-invoice",
  "status": "uncertain",
  "data": null,
  "error": {
    "code": "reply_malformed",
    "message": "The reply from the node could not be used."
  },
  "warnings": [],
  "meta": {
    "publication": "published",
    "daemon_acceptance": "unknown",
    "persistence": "not_attempted",
    "snapshot": null
  }
}

No answer: the node may hold the invoice

order.add-invoice/reply_timeout_uncertain · status uncertain · reply_timeout · exit 1 · fixture

mostro-cli --output json order add-invoice --order 00000000-0000-0000-0000-000000000001 --invoice lnbcrt150u1p... --yes

{
  "schema_version": "1",
  "command": "order.add-invoice",
  "status": "uncertain",
  "data": null,
  "error": {
    "code": "reply_timeout",
    "message": "The node did not answer before the deadline."
  },
  "warnings": [],
  "meta": {
    "publication": "published",
    "daemon_acceptance": "unknown",
    "persistence": "not_attempted",
    "snapshot": null
  }
}

Refused with reason invalid_peer

order.add-invoice/node_refused · status error · node_refused · exit 1 · fixture

mostro-cli --output json order add-invoice --order 00000000-0000-0000-0000-000000000001 --invoice lnbcrt150u1p... --yes

{
  "schema_version": "1",
  "command": "order.add-invoice",
  "status": "error",
  "data": null,
  "error": {
    "code": "node_refused",
    "message": "The node refused the request.",
    "reason": "invalid_peer"
  },
  "warnings": [],
  "meta": {
    "publication": "published",
    "daemon_acceptance": "rejected",
    "persistence": "not_attempted",
    "snapshot": null
  }
}

Declined at the human prompt

order.add-invoice/order_declined · status error · order_declined · exit 1 · fixture

mostro-cli order add-invoice --order 00000000-0000-0000-0000-000000000001 --invoice lnbcrt150u1p...

{
  "schema_version": "1",
  "command": "order.add-invoice",
  "status": "error",
  "data": null,
  "error": {
    "code": "order_declined",
    "message": "The order was not confirmed, so nothing was sent."
  },
  "warnings": [],
  "meta": {
    "publication": "not_attempted",
    "daemon_acceptance": "unknown",
    "persistence": "not_attempted",
    "snapshot": null
  }
}

No local row for this order: nothing was sent

order.add-invoice/order_unknown · status error · order_unknown · exit 1 · fixture

mostro-cli --output json order add-invoice --order 00000000-0000-0000-0000-000000000009 --invoice lnbcrt150u1p... --yes

{
  "schema_version": "1",
  "command": "order.add-invoice",
  "status": "error",
  "data": null,
  "error": {
    "code": "order_unknown",
    "message": "No local order has this id, so nothing was sent."
  },
  "warnings": [],
  "meta": {
    "publication": "not_attempted",
    "daemon_acceptance": "unknown",
    "persistence": "not_attempted",
    "snapshot": null
  }
}

The removed addinvoice spelling

order.add-invoice/removed_spelling · status error · invalid_arguments · exit 2 · fixture

mostro-cli --output json addinvoice -o 00000000-0000-0000-0000-000000000001 -i lnbc...

{
  "schema_version": "1",
  "command": null,
  "status": "error",
  "data": null,
  "error": {
    "code": "invalid_arguments",
    "message": "The command arguments are invalid."
  },
  "warnings": [],
  "meta": {
    "publication": "not_attempted",
    "daemon_acceptance": "unknown",
    "persistence": "not_attempted",
    "snapshot": null
  }
}

JSON mode without –yes

order.add-invoice/yes_required · status error · invalid_arguments · exit 2 · fixture

mostro-cli --output json order add-invoice --order 00000000-0000-0000-0000-000000000001 --invoice lnbcrt150u1p...

{
  "schema_version": "1",
  "command": "order.add-invoice",
  "status": "error",
  "data": null,
  "error": {
    "code": "invalid_arguments",
    "message": "The command arguments are invalid."
  },
  "warnings": [],
  "meta": {
    "publication": "not_attempted",
    "daemon_acceptance": "unknown",
    "persistence": "not_attempted",
    "snapshot": null
  }
}

Buying as a taker · Buying as a maker

mostro-cli JSON Interface