Skip to main content

opencollective-py

A Python client for the OpenCollective GraphQL API.

Installation

# Basic installation
pip install git+https://github.com/MaxGhenis/opencollective-py.git

# With PDF conversion support (for HTML receipts)
pip install "opencollective[pdf] @ git+https://github.com/MaxGhenis/opencollective-py.git"

Quick start

Authentication

First, create an OAuth2 application at https://opencollective.com/applications.

from opencollective import OAuth2Handler, OpenCollectiveClient

# Set up OAuth2 handler
auth = OAuth2Handler(
    client_id="your_client_id",
    client_secret="your_client_secret",
    token_file="~/.config/opencollective/token.json"  # Optional: persist token
)

# Get authorization URL (redirect user here)
auth_url = auth.get_authorization_url(scope="expenses")

# After user authorizes, exchange code for token
token_data = auth.exchange_code(authorization_code)

# Create client with access token
client = OpenCollectiveClient(access_token=token_data["access_token"])

Submitting expenses

Reimbursement vs invoice: when to use which

Type Use when... Receipt required?
Reimbursement You paid out-of-pocket and need to be paid back Yes
Invoice You're billing for services/work rendered No (optional)

Examples:

  • Membership dues you paid → Reimbursement (you have a receipt)
  • Conference registration → Reimbursement (you have a receipt)
  • Monthly consulting fee → Invoice (you're billing for work)
  • Software development work → Invoice (you're billing for work)

Use this when you paid for something and need to be reimbursed:

expense = client.submit_reimbursement(
    collective_slug="policyengine",
    description="NASI Membership Dues 2026",
    amount_cents=32500,  # $325.00
    receipt_file="/path/to/receipt.pdf",  # or .png, .jpg, .html
    tags=["membership", "professional development"]
)
print(f"Created: https://opencollective.com/policyengine/expenses/{expense['legacyId']}")

Features:

  • Auto-detects your account from the OAuth token
  • Auto-selects your first payout method
  • Converts HTML receipts to PDF automatically (requires opencollective[pdf])
  • Uploads receipt and attaches it to the expense

Submit an invoice

Use this when billing for services (no receipt needed):

expense = client.submit_invoice(
    collective_slug="policyengine",
    description="January 2026 Consulting",
    amount_cents=500000,  # $5,000.00
    tags=["consulting"]
)

Low-level expense creation

For more control, use the lower-level create_expense() method:

# First upload receipt if needed
file_info = client.upload_file("/path/to/receipt.pdf")

# Create expense with full control
expense = client.create_expense(
    collective_slug="policyengine",
    payee_slug="max-ghenis",
    description="Cloud services - January 2026",
    amount_cents=10000,
    expense_type="RECEIPT",  # or "INVOICE"
    payout_method_id="your-payout-method-id",
    attachment_urls=[file_info["url"]],
    tags=["cloud", "infrastructure"],
)

Managing expenses

# Get your account info
me = client.get_me()
print(f"Logged in as: {me['name']} (@{me['slug']})")

# Get your payout methods
methods = client.get_payout_methods(me['slug'])
for m in methods:
    print(f"  {m['type']}: {m['id']}")

# Get recent expenses
expenses = client.get_expenses("policyengine", limit=50)
print(f"Found {expenses['totalCount']} expenses")

# Get pending expenses only
pending = client.get_pending_expenses("policyengine")

# Approve an expense (requires admin permissions)
client.approve_expense(expense_id="abc123")

# Reject an expense with a message
client.reject_expense(expense_id="xyz789", message="Missing receipt")

# Delete your own draft/pending expense
client.delete_expense(expense_id="abc123")

File uploads

Upload files for expense attachments:

# Upload from file path
file_info = client.upload_file(
    "/path/to/receipt.pdf",
    kind="EXPENSE_ITEM"  # or EXPENSE_INVOICE, EXPENSE_ATTACHED_FILE
)
print(f"Uploaded to: {file_info['url']}")

# Upload from file-like object
from io import BytesIO
file_obj = BytesIO(pdf_bytes)
file_info = client.upload_file(file_obj, filename="receipt.pdf")

Supported formats: PNG, JPEG, GIF, WebP, PDF, CSV

Get collective info

collective = client.get_collective("policyengine")
print(f"Name: {collective['name']}")
print(f"Currency: {collective['currency']}")

CLI

The package includes a command-line interface for common operations.

Setup

# Authenticate (get credentials at https://opencollective.com/applications)
oc auth

Commands

# Submit a reimbursement
oc reimbursement "NASI Dues 2026" 325.00 receipt.pdf -c policyengine -t membership

# Submit an invoice
oc invoice "January Consulting" 5000.00 -c policyengine

# List expenses
oc expenses -c policyengine --pending
oc expenses -c policyengine --mine

# Delete an expense
oc delete abc123-def456

# Show current user
oc me

MCP server (for Claude Code)

The package includes an MCP server so Claude Code can submit expenses directly.

Setup

Add to your Claude Code MCP config (~/.claude/mcp.json):

{
  "mcpServers": {
    "opencollective": {
      "command": "python",
      "args": ["-m", "opencollective.mcp_server"]
    }
  }
}

Make sure you've authenticated first with oc auth.

Available tools

  • submit_reimbursement - Submit a reimbursement with receipt
  • submit_invoice - Submit an invoice for services
  • list_expenses - List expenses for a collective
  • delete_expense - Delete a draft/pending expense
  • get_me - Get current user info
  • get_collective - Get collective info

Example usage in Claude Code

"Submit my NASI receipt at /tmp/nasi_receipt.html as a $325 reimbursement to policyengine with tags membership and professional-development"

Development

# Clone the repository
git clone https://github.com/MaxGhenis/opencollective-py.git
cd opencollective-py

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
ruff check --fix .

License

MIT

Metadata

Release files for opencollective 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opencollective 0.2.1
File Size Uploaded Provenance Actions
opencollective-0.2.1.tar.gz 98.1 kB Without provenance Details for opencollective-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opencollective 0.2.1
File Interpreter ABI Platform Actions
opencollective-0.2.1-py3-none-any.whl Python 3 none any Details for opencollective-0.2.1-py3-none-any.whl

Total release size: 115.2 kB

Release files / opencollective-0.2.1.tar.gz

Download URL opencollective-0.2.1.tar.gz
Size 98.1 kB
Tags Source
SHA-256 checksum
How to use checksums
703e651b8b7979e15b30ea40767d19825d3e85e42d3eb3af19a968a973d477dc
BLAKE2b-256 checksum
How to use checksums
ab20b1a32686eb08dee8b830dd5bef33a1822ad1ff2723de36ed18c11eb2f404
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.11

Release files / opencollective-0.2.1-py3-none-any.whl

Download URL opencollective-0.2.1-py3-none-any.whl
Size 17.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e0a38942d6746b46e1745f5375d2e7a2e13ba0228a509a5de932e9fb8a0a9f56
BLAKE2b-256 checksum
How to use checksums
8c4b0abcd0816af7d30cdee4fa934d9ba3b94d41663ffb1dafc49abbf88693ff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.11

Security for opencollective 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page