Track Payment Status on Opportunity Products

Every product line on an opportunity carries a payment status. Set it by hand when you take payment outside an accounting tool, or connect Xero to let it update automatically when you send and collect invoices. This article covers the status concept and the manual flow — see Create and Send Invoices via Xero if you're using the Xero integration.

The Four Statuses

• Unpaid — default state; no invoice raised yet.
• Deposit Invoiced — a deposit invoice has been sent.
• Invoiced — a full or balance invoice has been sent.
• Paid — payment received.

Each status shows as a small coloured pill beside the product name on the Products card of the opportunity. At a glance you can see exactly which line items still need chasing and which are settled.

Forward-only for automation, free-form for manual. Xero-driven updates only move a status up the ladder (a deposit invoice won't overwrite Paid). Manual edits can move in either direction — handy for correcting mistakes.

Set a Payment Status Manually

Useful for cash, bank transfers, offline invoicing, or any billing that happens outside your accounting tool.

1. Open an opportunity and find the Products card.
2. Click the edit icon on any product line to open the Edit Deal Product modal.
3. Open the Payment tab.
4. Scroll to Payment Status at the bottom of the tab. Pick Unpaid, Deposit Invoiced, Invoiced, or Paid.
5. Click Save. The pill on the Products card updates immediately.

Who Can See and Change It

Payment status is gated by a dedicated Invoices role scope, separate from the general CRM access. This lets you keep revenue figures private from team members who need the CRM but shouldn't see who's paid what.

• invoices:read — can see the status pills and the Invoices section on opportunities.
• invoices:write — can change the status and send invoices.
• Users with neither see no pills, no Invoices section, and a read-only payment status selector in the Edit modal.

Workspace admins set these scopes per role at https://app.trustpager.com/settings/permissions. The Admin, Editor, and Viewer preset roles already include the right mix — admins and editors can write, viewers can read.

Using the API or MCP

Payment status is available on the opportunity products endpoints:

• GET /opportunities/:id/products — returns payment_status on every line (requires invoices:read or it's stripped from the response). The path /deals/:id/products also works for legacy callers.
• PATCH /opportunities/:id/products/:id — accepts payment_status as one of the four values (requires invoices:write, returns 403 otherwise). The /deals/:id/products/:id alias continues to work.
• MCP tools get_opportunity_products, update_opportunity_product, and add_opportunity_product expose payment_status from version 1.2.18. The legacy tool names get_deal_products, update_deal_product, and add_deal_product still work as aliases.

Existing API keys don't auto-grant new scopes. If you have existing keys (or AI agents using OAuth tokens) and want them to see or change payment status, edit the key at https://app.trustpager.com/settings/api-keys and add the Invoices scopes.

Automating It with Xero

If your workspace has Xero connected, the Invoices section on the opportunity page lets you send invoices directly to Xero. When you do, the matching product lines automatically move to Deposit Invoiced or Invoiced. When Xero marks an invoice as PAID, clicking Sync Invoices pulls that status back into TrustPager and flips the relevant products to Paid.

Full walkthrough: How to Create and Send Invoices via Xero.

Troubleshooting

I can't change the payment status. Your role lacks the invoices:write scope. Ask a workspace admin to update your permissions at https://app.trustpager.com/settings/permissions.

I can't see any pills or the Invoices section. Your role lacks the invoices:read scope, or no line item on the opportunity has a non-unpaid status yet. Pills are hidden for Unpaid to keep the Products card quiet.

An AI agent gets a 403 setting payment_status. Add invoices:write to the agent's API key at https://app.trustpager.com/settings/api-keys.