Recoup

Get started with Recoup.

Try Our Platform

Use Recoup’s AI tools for your artists, releases, and catalog.

Build Your Platform

Our team builds custom AI software for your business.

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. Invoices are merged across every Stripe customer tagged with the account id, so a card saved on one customer and an invoiced plan on another appear in one list. 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 tagged Stripe customer or no invoices yet. startingAfter is an invoice id from a previous page; the next page holds invoices created before it. 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.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

Kept in this browser tab only and cleared when it closes.

cURL for this request
curl --request GET \
  --url 'https://api.recoupable.dev/api/accounts/{id}/payments'

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.

Example: "550e8400-e29b-41d4-a716-446655440000"

format: uuid

paymentsarray<AccountPayment>required

Invoices, newest first, merged across every Stripe customer tagged with the account id. Empty when the account has no tagged Stripe customer or no invoices.

Item properties for payments
idstringrequired

Stripe invoice id; use as startingAfter to page.

Example: "in_1U5xj400JObOnOb5BE0CmxCt"

createdAtstringrequired

When the invoice was created.

Example: "2026-09-04T14:33:00Z"

format: date-time

descriptionstringrequired

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

Example: "Pro, monthly"

amountCentsintegerrequired

Amount due in the smallest currency unit.

Example: 9900

currencystringrequired

ISO 4217 currency code, lowercase.

Example: "usd"

statusstring · enumrequired

Stripe invoice status.

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

Example: "paid"

urlstringrequirednullable

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

Example: "https://invoice.stripe.com/i/acct_123/test_456"

format: uri

hasMorebooleanrequired

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

Example: false

400Bad request - invalid id, limit, or startingAfter

application/json

errorstringrequired

Human-readable error message.

Example: "Account not found"

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

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

Example: "Account not found"

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.

Example: "Account not found"

Full specification

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

Download accounts.json
View operation source
json
{
  "operationId": "getAccountsByIdPayments",
  "description": "List the invoices paid or owed by an account, newest first: subscription renewals, credit purchases, and invoiced enterprise plans alike. Invoices are merged across every Stripe customer tagged with the account id, so a card saved on one customer and an invoiced plan on another appear in one list. 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 tagged Stripe customer or no invoices yet. `startingAfter` is an invoice id from a previous page; the next page holds invoices created before it. `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"
          }
        }
      }
    }
  }
}