TrackOfferz Python SDK
Official, zero-dependency Python client for the TrackOfferz reporting API.
- Typed — dataclass results, ships with
py.typed. - Zero dependencies — standard library only.
- Resilient — automatic retries on 429 (honours
Retry-After) and transient 5xx. - Network-scoped — every call is limited to your network by the API key.
Install
pip install trackofferz
Authenticate
Create a key in the panel under Settings → API keys (format tofz_sk_…).
from trackofferz import TrackOfferz
client = TrackOfferz(api_key="tofz_sk_...")
Reporting
# Summary (defaults to the last 30 days)
s = client.reports.summary(from_="2026-06-01", to="2026-06-30")
print(s.clicks, s.conversions, s.revenue_cents)
# Breakdown by publisher
for row in client.reports.breakdown(by="publisher"):
print(row.label, row.conversions, row.payout_cents)
# One page of conversions for a campaign
page = client.reports.conversions(campaign_id=5, page=1, page_size=100)
print(page.total, page.has_next)
for c in page.rows:
print(c.transaction_id, c.payout_cents, c.status)
# Stream EVERY click across all pages (auto-pagination)
for click in client.reports.iter_clicks(from_="2026-06-01", to="2026-06-30"):
print(click.transaction_id, click.country_code, click.is_unique)
Money fields are integers in cents (
payout_cents=1250→$12.50). Date params areYYYY-MM-DD.from_has a trailing underscore (fromis a Python keyword) and maps to thefromquery parameter.
Conversions (ingest)
Record a conversion server-to-server for a click your link already tracked —
the basis of "Track from CMS". The transaction_id is the click id captured on
your landing page.
res = client.conversions.create(
transaction_id="click_abc123", # the click id (a.k.a. tid)
event_type="purchase", # default; also: lead, install, refund, …
payout=12.50, # decimal, or payout_cents=1250
sale_amount=199.00,
currency="USD",
custom_data={"order_id": "SO-9001"},
)
print(res.status, res.conversion_id, res.duplicate)
Idempotent. Re-sending the same
transaction_idreturns the existing conversion withduplicate=True— it never double-counts. Retries on429/5xxare therefore safe and automatic.The key is bound to your network: you can only convert your own clicks. A
404(click_not_found) means no click matched thetransaction_idwithin the attribution window.
Errors
from trackofferz import (
AuthenticationError, ValidationError, RateLimitError, APIError, TrackOfferzError,
)
try:
client.reports.summary(from_="not-a-date")
except ValidationError as e:
print("bad input:", e.message)
except RateLimitError as e:
print("slow down; retry after", e.retry_after, "s")
except TrackOfferzError as e: # base class — catches all of the above
print(e.status, e.code, e.message)
Configuration
TrackOfferz(
api_key="tofz_sk_...",
base_url="https://trackofferz.com/api/v1", # override for self-hosted
timeout=30.0,
max_retries=2,
)
Full API reference: https://trackofferz.com/docs
TrackOfferz is a product by SPTSPL (S. P. Techno Solution Private Limited).
Metadata
Release files for trackofferz 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| trackofferz-0.2.0.tar.gz | 8.1 kB | Without provenance | Details for trackofferz-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| trackofferz-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for trackofferz-0.2.0-py3-none-any.whl |
Total release size: 18.3 kB
Release files / trackofferz-0.2.0.tar.gz
| Download URL | trackofferz-0.2.0.tar.gz |
|---|---|
| Size | 8.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f9757a2f815efd1918e99482d6045e9637e7870feec2a51adbab4ee664c497e7
|
|
BLAKE2b-256 checksum How to use checksums |
73129707e80403d29395a93bdb879cf57cbbc40cc7de9dc869e78f32d5fa101a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.5
|
Release files / trackofferz-0.2.0-py3-none-any.whl
| Download URL | trackofferz-0.2.0-py3-none-any.whl |
|---|---|
| Size | 10.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ab828338ac39b49e7656b8702b1e0f0fa0a035464039d3603fe411719796533a
|
|
BLAKE2b-256 checksum How to use checksums |
1777b92dbeb860a3e93d52bf505423474d67937269e2f69edfb10888636ca6a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.5
|
Security for trackofferz 0.2.0
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.