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#
/api/v1/invoicesScope payments:readNewest 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.
curl "https://app.shipeasyco.com/api/v1/invoices?status=overdue" \
-H "Authorization: Bearer $SHIPEASY_API_KEY"{
"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#
/api/v1/invoices/{invoiceId}Scope payments:readIts lines, tax, what was paid and whether it can be paid now (payable).
Download an invoice#
/api/v1/invoices/{invoiceId}/pdfScope payments:readThe 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#
/api/v1/invoices/{invoiceId}/payScope payments:writeStripe'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.
{
"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#
/api/v1/paymentsScope payments:readBooking 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 a link to add a card#
/api/v1/payment_methods/setupScope payments:writeThe 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#
/api/v1/payment_methods/{cardId}Scope payments:writeSend 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#
/api/v1/payment_methods/{cardId}Scope payments:writeRemoved 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.