List Invoices

List invoices with pagination and status filtering

List Invoices

List invoices with pagination and status filtering

List invoices

1 import { Gwop } from "@gwop/sdk";
2 
3 const gwop = new Gwop({
4   merchantApiKey: process.env.GWOP_MERCHANT_API_KEY,
5 });
6 
7 const { result } = await gwop.invoices.list();
8 
9 for (const invoice of result.invoices) {
10   console.log(invoice.publicInvoiceId, invoice.status, invoice.amountUsdc);
11 }
12 
13 console.log(result.pagination); // { total, limit, offset, hasMore }

Response

1 {
2   "invoices": [
3     {
4       "id": "ef147e47-a983-4a4c-bd6d-756377705bde",
5       "publicInvoiceId": "inv_af95ad98fadb4599aab6373ac812842e",
6       "status": "OPEN",
7       "amountUsdc": 1025000,
8       "currency": "USDC",
9       "description": "Docs audit probe",
10       "metadata": {
11         "fee_usdc": 25000,
12         "base_amount_usdc": 1000000,
13         "fee_basis_points": 250,
14         "total_amount_usdc": 1025000
15       },
16       "expiresAt": "2026-04-08T22:55:04.088Z",
17       "createdAt": "2026-04-08T22:40:04.122Z"
18     },
19     {
20       "id": "70be0720-a5f0-4a57-829f-9af70424158c",
21       "publicInvoiceId": "inv_b8d22e32425343958182533aa7994e35",
22       "status": "PAID",
23       "amountUsdc": 1025,
24       "currency": "USDC",
25       "description": "Weekly Access subscription",
26       "metadata": {
27         "source": "agentrouter-demo",
28         "fee_usdc": 25,
29         "offerKey": "weekly",
30         "durationDays": 7,
31         "base_amount_usdc": 1000,
32         "fee_basis_points": 250,
33         "total_amount_usdc": 1025
34       },
35       "expiresAt": "2026-04-08T03:39:04.601Z",
36       "createdAt": "2026-04-08T03:24:04.624Z",
37       "paidAt": "2026-04-08T03:24:17.508Z",
38       "paidTxHash": "0x165de7bdf1e3803280388ef37683a2767ffecd098842feea7d03c39eb795e978",
39       "paymentChain": "base"
40     },
41     {
42       "id": "2491c796-17d8-495d-8812-4fdaaa370257",
43       "publicInvoiceId": "inv_b55f439ba1764b71aeeccbc76ec5bbb9",
44       "status": "EXPIRED",
45       "amountUsdc": 1025000,
46       "currency": "USDC",
47       "description": "Docs audit probe",
48       "metadata": {
49         "fee_usdc": 25000,
50         "base_amount_usdc": 1000000,
51         "fee_basis_points": 250,
52         "total_amount_usdc": 1025000
53       },
54       "expiresAt": "2026-04-08T19:59:58.151Z",
55       "createdAt": "2026-04-08T19:44:58.173Z"
56     }
57   ],
58   "pagination": {
59     "total": 265,
60     "limit": 20,
61     "offset": 0,
62     "hasMore": true
63   }
64 }

Parameters

Field	Type	Required	Default	Description
`limit`	`number`	No	`20`	Number of invoices per page (max 100)
`offset`	`number`	No	`0`	Number of invoices to skip
`status`	`string`	No	—	Filter by status: `OPEN`, `PAYING`, `PAID`, `EXPIRED`, `CANCELED`

Pagination

Results are ordered newest-first. Use offset and limit to page through results:

1 let offset = 0;
2 const limit = 20;
3 const allInvoices = [];
4 
5 while (true) {
6   const { result } = await gwop.invoices.list({ limit, offset });
7   allInvoices.push(...result.invoices);
8 
9   if (!result.pagination.hasMore) break;
10   offset += limit;
11 }

The pagination object tells you where you are:

Field	Type	Description
`total`	`number`	Total invoices matching the filter
`limit`	`number`	Page size used
`offset`	`number`	Current offset
`hasMore`	`boolean`	`true` if more pages exist

Filter by status

Pass status to return only invoices in a specific state:

1 // Get all paid invoices
2 const { result: paid } = await gwop.invoices.list({ status: "PAID" });
3 
4 // Get open invoices (awaiting payment)
5 const { result: open } = await gwop.invoices.list({ status: "OPEN" });

Valid statuses:

Status	Meaning
`OPEN`	Awaiting payment
`PAYING`	Payment detected, confirming on-chain
`PAID`	Payment confirmed and settled
`EXPIRED`	Invoice TTL reached without payment
`CANCELED`	Merchant canceled the invoice

Invoice list item shape

Each item in the invoices array is a summary — lighter than the full invoice from get().

Field	Type	Present	Description
`id`	`string`	Always	Merchant-side UUID
`publicInvoiceId`	`string`	Always	Payer-facing `inv_*` identifier
`status`	`string`	Always	Current status
`amountUsdc`	`number`	Always	Total amount including fees (6 decimals)
`currency`	`string`	Always	Always `"USDC"`
`description`	`string`	If set	Invoice description
`metadata`	`object`	If set	Includes fee breakdown
`createdAt`	`Date`	Always	Creation timestamp
`expiresAt`	`Date`	Always	Expiry timestamp
`paidAt`	`Date`	Paid only	Settlement timestamp
`paidTxHash`	`string`	Paid only	Transaction hash (Base58 for Solana, hex for Base)
`paymentChain`	`string`	Paid only	`"solana"` or `"base"`

Payment fields (paidAt, paidTxHash, paymentChain) are only present on paid invoices. They are undefined for open, expired, and canceled invoices.

Next step

Get Invoice

Full public checkout view with payment methods and settlement details

Cancel Invoice

Cancel an open invoice before payment arrives

List invoices

1 import { Gwop } from "@gwop/sdk";
2 
3 const gwop = new Gwop({
4   merchantApiKey: process.env.GWOP_MERCHANT_API_KEY,
5 });
6 
7 const { result } = await gwop.invoices.list();
8 
9 for (const invoice of result.invoices) {
10   console.log(invoice.publicInvoiceId, invoice.status, invoice.amountUsdc);
11 }
12 
13 console.log(result.pagination); // { total, limit, offset, hasMore }

Response

1 {
2   "invoices": [
3     {
4       "id": "ef147e47-a983-4a4c-bd6d-756377705bde",
5       "publicInvoiceId": "inv_af95ad98fadb4599aab6373ac812842e",
6       "status": "OPEN",
7       "amountUsdc": 1025000,
8       "currency": "USDC",
9       "description": "Docs audit probe",
10       "metadata": {
11         "fee_usdc": 25000,
12         "base_amount_usdc": 1000000,
13         "fee_basis_points": 250,
14         "total_amount_usdc": 1025000
15       },
16       "expiresAt": "2026-04-08T22:55:04.088Z",
17       "createdAt": "2026-04-08T22:40:04.122Z"
18     },
19     {
20       "id": "70be0720-a5f0-4a57-829f-9af70424158c",
21       "publicInvoiceId": "inv_b8d22e32425343958182533aa7994e35",
22       "status": "PAID",
23       "amountUsdc": 1025,
24       "currency": "USDC",
25       "description": "Weekly Access subscription",
26       "metadata": {
27         "source": "agentrouter-demo",
28         "fee_usdc": 25,
29         "offerKey": "weekly",
30         "durationDays": 7,
31         "base_amount_usdc": 1000,
32         "fee_basis_points": 250,
33         "total_amount_usdc": 1025
34       },
35       "expiresAt": "2026-04-08T03:39:04.601Z",
36       "createdAt": "2026-04-08T03:24:04.624Z",
37       "paidAt": "2026-04-08T03:24:17.508Z",
38       "paidTxHash": "0x165de7bdf1e3803280388ef37683a2767ffecd098842feea7d03c39eb795e978",
39       "paymentChain": "base"
40     },
41     {
42       "id": "2491c796-17d8-495d-8812-4fdaaa370257",
43       "publicInvoiceId": "inv_b55f439ba1764b71aeeccbc76ec5bbb9",
44       "status": "EXPIRED",
45       "amountUsdc": 1025000,
46       "currency": "USDC",
47       "description": "Docs audit probe",
48       "metadata": {
49         "fee_usdc": 25000,
50         "base_amount_usdc": 1000000,
51         "fee_basis_points": 250,
52         "total_amount_usdc": 1025000
53       },
54       "expiresAt": "2026-04-08T19:59:58.151Z",
55       "createdAt": "2026-04-08T19:44:58.173Z"
56     }
57   ],
58   "pagination": {
59     "total": 265,
60     "limit": 20,
61     "offset": 0,
62     "hasMore": true
63   }
64 }

Parameters

Field	Type	Required	Default	Description
`limit`	`number`	No	`20`	Number of invoices per page (max 100)
`offset`	`number`	No	`0`	Number of invoices to skip
`status`	`string`	No	—	Filter by status: `OPEN`, `PAYING`, `PAID`, `EXPIRED`, `CANCELED`

Pagination

Results are ordered newest-first. Use offset and limit to page through results:

1 let offset = 0;
2 const limit = 20;
3 const allInvoices = [];
4 
5 while (true) {
6   const { result } = await gwop.invoices.list({ limit, offset });
7   allInvoices.push(...result.invoices);
8 
9   if (!result.pagination.hasMore) break;
10   offset += limit;
11 }

The pagination object tells you where you are:

Field	Type	Description
`total`	`number`	Total invoices matching the filter
`limit`	`number`	Page size used
`offset`	`number`	Current offset
`hasMore`	`boolean`	`true` if more pages exist

Filter by status

Pass status to return only invoices in a specific state:

1 // Get all paid invoices
2 const { result: paid } = await gwop.invoices.list({ status: "PAID" });
3 
4 // Get open invoices (awaiting payment)
5 const { result: open } = await gwop.invoices.list({ status: "OPEN" });

Valid statuses:

Status	Meaning
`OPEN`	Awaiting payment
`PAYING`	Payment detected, confirming on-chain
`PAID`	Payment confirmed and settled
`EXPIRED`	Invoice TTL reached without payment
`CANCELED`	Merchant canceled the invoice

Invoice list item shape

Each item in the invoices array is a summary — lighter than the full invoice from get().

Field	Type	Present	Description
`id`	`string`	Always	Merchant-side UUID
`publicInvoiceId`	`string`	Always	Payer-facing `inv_*` identifier
`status`	`string`	Always	Current status
`amountUsdc`	`number`	Always	Total amount including fees (6 decimals)
`currency`	`string`	Always	Always `"USDC"`
`description`	`string`	If set	Invoice description
`metadata`	`object`	If set	Includes fee breakdown
`createdAt`	`Date`	Always	Creation timestamp
`expiresAt`	`Date`	Always	Expiry timestamp
`paidAt`	`Date`	Paid only	Settlement timestamp
`paidTxHash`	`string`	Paid only	Transaction hash (Base58 for Solana, hex for Base)
`paymentChain`	`string`	Paid only	`"solana"` or `"base"`

Payment fields (paidAt, paidTxHash, paymentChain) are only present on paid invoices. They are undefined for open, expired, and canceled invoices.

Next step

Get Invoice

Full public checkout view with payment methods and settlement details

Cancel Invoice

Cancel an open invoice before payment arrives

1	import { Gwop } from "@gwop/sdk";
2
3	const gwop = new Gwop({
4	merchantApiKey: process.env.GWOP_MERCHANT_API_KEY,
5	});
6
7	const { result } = await gwop.invoices.list();
8
9	for (const invoice of result.invoices) {
10	console.log(invoice.publicInvoiceId, invoice.status, invoice.amountUsdc);
11	}
12
13	console.log(result.pagination); // { total, limit, offset, hasMore }

1	{
2	"invoices": [
3	{
4	"id": "ef147e47-a983-4a4c-bd6d-756377705bde",
5	"publicInvoiceId": "inv_af95ad98fadb4599aab6373ac812842e",
6	"status": "OPEN",
7	"amountUsdc": 1025000,
8	"currency": "USDC",
9	"description": "Docs audit probe",
10	"metadata": {
11	"fee_usdc": 25000,
12	"base_amount_usdc": 1000000,
13	"fee_basis_points": 250,
14	"total_amount_usdc": 1025000
15	},
16	"expiresAt": "2026-04-08T22:55:04.088Z",
17	"createdAt": "2026-04-08T22:40:04.122Z"
18	},
19	{
20	"id": "70be0720-a5f0-4a57-829f-9af70424158c",
21	"publicInvoiceId": "inv_b8d22e32425343958182533aa7994e35",
22	"status": "PAID",
23	"amountUsdc": 1025,
24	"currency": "USDC",
25	"description": "Weekly Access subscription",
26	"metadata": {
27	"source": "agentrouter-demo",
28	"fee_usdc": 25,
29	"offerKey": "weekly",
30	"durationDays": 7,
31	"base_amount_usdc": 1000,
32	"fee_basis_points": 250,
33	"total_amount_usdc": 1025
34	},
35	"expiresAt": "2026-04-08T03:39:04.601Z",
36	"createdAt": "2026-04-08T03:24:04.624Z",
37	"paidAt": "2026-04-08T03:24:17.508Z",
38	"paidTxHash": "0x165de7bdf1e3803280388ef37683a2767ffecd098842feea7d03c39eb795e978",
39	"paymentChain": "base"
40	},
41	{
42	"id": "2491c796-17d8-495d-8812-4fdaaa370257",
43	"publicInvoiceId": "inv_b55f439ba1764b71aeeccbc76ec5bbb9",
44	"status": "EXPIRED",
45	"amountUsdc": 1025000,
46	"currency": "USDC",
47	"description": "Docs audit probe",
48	"metadata": {
49	"fee_usdc": 25000,
50	"base_amount_usdc": 1000000,
51	"fee_basis_points": 250,
52	"total_amount_usdc": 1025000
53	},
54	"expiresAt": "2026-04-08T19:59:58.151Z",
55	"createdAt": "2026-04-08T19:44:58.173Z"
56	}
57	],
58	"pagination": {
59	"total": 265,
60	"limit": 20,
61	"offset": 0,
62	"hasMore": true
63	}
64	}

1	let offset = 0;
2	const limit = 20;
3	const allInvoices = [];
4
5	while (true) {
6	const { result } = await gwop.invoices.list({ limit, offset });
7	allInvoices.push(...result.invoices);
8
9	if (!result.pagination.hasMore) break;
10	offset += limit;
11	}

1	// Get all paid invoices
2	const { result: paid } = await gwop.invoices.list({ status: "PAID" });
3
4	// Get open invoices (awaiting payment)
5	const { result: open } = await gwop.invoices.list({ status: "OPEN" });