API REFERENCE

List Account Payments

On this page

GET/api/accounts/{id}/payments

List the invoices paid or owed by an account, newest first: subscription renewals, credit purchases, and invoiced enterprise plans alike. Non-draft rows carry the hosted invoice URL for the receipt; url is null for drafts. Returns an empty list (not 404) when the account has no Stripe customer or no invoices yet. id may be the authenticated account or an organization the caller belongs to.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --url 'https://api.recoupable.dev/api/accounts/YOUR_ID/payments' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Parameters

Path parameters

idstringrequired

The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.

Query parameters

limitinteger

Maximum rows to return.

Default: 20

startingAfterstring

Cursor for the next page: the id of the last payment from the previous response.

Responses

200Payments retrieved successfully

application/json

account_idstringrequired

The account these payments belong to.

format: uuid

paymentsarray<AccountPayment>required

Invoices, newest first. Empty when the account has no Stripe customer or no invoices.

Item properties

idstringrequired

Stripe invoice id; use as startingAfter to page.

createdAtstringrequired

When the invoice was created.

format: date-time

descriptionstringrequired

What was billed: the first line item's description, or the plan name.

amountCentsintegerrequired

Amount due in the smallest currency unit.

currencystringrequired

ISO 4217 currency code, lowercase.

statusstring · enumrequired

Stripe invoice status.

Values: "draft", "open", "paid", "uncollectible", "void"

urlstringrequirednullable

Hosted invoice page (receipt). Null for draft invoices.

format: uri

hasMorebooleanrequired

True when another page exists; pass the last id as startingAfter.

400Bad request - invalid id, limit, or startingAfter

application/json

errorstringrequired

Human-readable error message.

400 example

{
  "error": "limit must be between 1 and 100"
}

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

401 example

{
  "error": "Unauthorized"
}

403Forbidden - the account is not the caller's and not an organization they belong to (an unknown id also returns 403, never 404)

application/json

errorstringrequired

Human-readable error message.

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download accounts.json

View operation source

json

{
  "description": "List the invoices paid or owed by an account, newest first: subscription renewals, credit purchases, and invoiced enterprise plans alike. Non-draft rows carry the hosted invoice URL for the receipt; `url` is null for drafts. Returns an empty list (not 404) when the account has no Stripe customer or no invoices yet. `id` may be the authenticated account or an organization the caller belongs to.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "name": "limit",
      "in": "query",
      "description": "Maximum rows to return.",
      "required": false,
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 20
      }
    },
    {
      "name": "startingAfter",
      "in": "query",
      "description": "Cursor for the next page: the `id` of the last payment from the previous response.",
      "required": false,
      "schema": {
        "type": "string"
      },
      "example": "in_1U5xj400JObOnOb5BE0CmxCt"
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Payments retrieved successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentsResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - invalid `id`, `limit`, or `startingAfter`",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentsErrorResponse"
          },
          "example": {
            "error": "limit must be between 1 and 100"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - invalid or missing authentication",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentsErrorResponse"
          },
          "example": {
            "error": "Unauthorized"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - the account is not the caller's and not an organization they belong to (an unknown id also returns 403, never 404)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentsErrorResponse"
          }
        }
      }
    }
  }
}