Skip to content

Invoices, payments & cards

Contents 26 pages

What the web app's Invoices, Payments and Payment methods pages do, as operations. Reading needs payments:read. Paying an invoice and changing a card need payments:write, which only an owner or admin can grant.

Nothing here charges a card or takes a card number:

  • Paying an invoice answers Stripe's page for what is owed now. The person pays there; the invoice shows paid once Stripe confirms it.
  • Adding a card, or allowing API bookings on one, happens on the web app's Payment methods page, signed in. The API answers a link to it.

A change to a card acts as the person behind the key (who connected the AI app, or made the key), within the key's scopes; a key with nobody behind it acts as your organization's API identity. The person who saved a card, or an owner or admin, may change it.

A Shopify store pays through Shopify: it lists its Shopify charges with GET /payments, and every other operation here answers not_available_for_shopify.

List invoices#

GET/api/v1/invoicesScope payments:read

Newest first, with what is still owed on each, read from Stripe now. status is all, open, overdue or paid; q finds an INV- number. An organization that pays by card has none.

Request
curl "https://app.shipeasyco.com/api/v1/invoices?status=overdue" \
  -H "Authorization: Bearer $SHIPEASY_API_KEY"
Response
{
	"object": "list",
	"data": [
		{
			"object": "invoice",
			"id": "cm7inv01…",
			"reference": "INV-2026-0142",
			"status": "OVERDUE",
			"period_start": "2026-10-01",
			"period_end": "2026-10-31",
			"issued_at": "2026-11-01T14:00:00.000Z",
			"due_at": "2026-11-15T14:00:00.000Z",
			"total_usd": "4812.40",
			"balance_usd": "4812.40",
			"web_url": "https://app.shipeasyco.com/portal/invoices/cm7inv01…"
		}
	],
	"has_more": false,
	"next_cursor": null
}

Read an invoice#

GET/api/v1/invoices/{invoiceId}Scope payments:read

Its lines, tax, what was paid and whether it can be paid now (payable).

Download an invoice#

GET/api/v1/invoices/{invoiceId}/pdfScope payments:read

The PDF, drawn from what Stripe confirms now and never stored. While Stripe does not answer it is upstream_unavailable; try again shortly.

Pay an invoice#

POST/api/v1/invoices/{invoiceId}/payScope payments:write

Stripe's page for the balance, recomputed on the server. Asking again within the hour gives the same page, so there is never a second charge to take. A retry with the same Idempotency-Key answers pay_url: null: the link is never stored, so ask again for it.

JSON
{
	"object": "invoice_pay_link",
	"invoice_id": "cm7inv01…",
	"amount_due_usd": "4812.40",
	"pay_url": "https://checkout.stripe.com/c/pay/cs_live_…",
	"expires_at": "2026-11-19T16:00:00.000Z"
}

Nothing owed, or a bank payment still clearing, is validation_failed with the reason.

List payments#

GET/api/v1/paymentsScope payments:read

Booking payments, newest first, 25 a page (page, from 1). view is all, issues (booked nothing, or our team is working on it) or refunded; q finds a CHG- or SHP- code; range (30d, 90d, 12m, all) is an organization's only. Each row says where it stands (state, label, explanation) and which shipment it paid for. A store's rows are its Shopify charges, without the order's name.

GET/api/v1/payment_methods/setupScope payments:write

The web app's Payment methods page. A signed-in person adds a card there on Stripe's form, or allows API bookings on one; that permission is always given by a person, never through the API (see Payment methods & mandates).

Rename or share a card#

PATCH/api/v1/payment_methods/{cardId}Scope payments:write

Send nickname (an empty string clears it), visibility (organization or private), or both. Answers the card. A card the acting person cannot see or change is card_not_available.

Remove a card#

DELETE/api/v1/payment_methods/{cardId}Scope payments:write

Removed at Stripe first, so nothing can charge it afterwards; bookings already paid with it are untouched. If Stripe does not answer, nothing changes and the answer is upstream_unavailable.