Python SDK - Perkstar Developers

The official synchronous SDK supports Python 3.9 and newer. It covers every operation in the public v1 API and is suited to Odoo modules, POS middleware, scheduled syncs, and backend services.

Install

Install the signed-off, versioned wheel directly from Perkstar:

python -m pip install \
  https://dashboard.perkstar.co.uk/developer-downloads/perkstar-0.1.0-py3-none-any.whl

The wheel has no compiled extensions, so the same file works on Linux, macOS, and Windows.

PyPI publishing requires a one-time registry verification. Until that is completed, the Perkstar-hosted wheel above is the official distribution.

Create a client

import os

from perkstar import Perkstar

with Perkstar(
    api_key=os.environ["PERKSTAR_API_KEY"],
    user_agent="MyOdooConnector/1.0",
) as perkstar:
    context = perkstar.marketplace.ping()
    print(context["data"]["organization"]["name"])

Pass oauth_access_token= instead of api_key= when your integration uses OAuth. Pass exactly one credential type.

Post a POS transaction

result = perkstar.marketplace.accrue(
    {
        "identifier": {"external_ref": "odoo:4:partner:981"},
        "card_id": "card_123",
        "transaction": {
            "type": "STAMP",
            "delta": 1,
            "external_transaction_id": "odoo:4:pos_order:94721",
        },
    },
    idempotency_key="odoo:4:pos_order:94721:loyalty",
)

print(result["enrollment"]["balance"])

The SDK generates an idempotency key for a new POST and preserves it across automatic retries. Supply your own stable key when a durable job may restart in a different process.

Pagination

for customer in perkstar.customers.list(limit=100):
    sync_customer(customer)

Requests are lazy and follow next_cursor until the API reports no more rows. An empty or repeated cursor stops with an error instead of looping forever.

Typed errors

from perkstar import PerkstarError, PerkstarRateLimitError

try:
    post_loyalty()
except PerkstarRateLimitError as error:
    schedule_retry(error.retry_after)
except PerkstarError as error:
    print(error.code, error.request_id)

Network failures, 408, 429, and retryable 5xx responses are retried up to three times by default. The client honours Retry-After and keeps the API error code, HTTP status, request ID, and API version on the raised exception.

Verify webhooks

from perkstar import verify_webhook_signature

event = verify_webhook_signature(
    raw_request_body,
    request.headers["X-Perkstar-Signature"],
    webhook_secret,
)

Pass the exact raw str or bytes body. The helper uses constant-time HMAC comparison and rejects timestamps outside a five-minute replay window.

Verify the download

curl --fail --remote-name \
  https://dashboard.perkstar.co.uk/developer-downloads/perkstar-0.1.0-py3-none-any.whl
curl --fail --remote-name \
  https://dashboard.perkstar.co.uk/developer-downloads/SHA256SUMS
sha256sum --check SHA256SUMS --ignore-missing

The source distribution is also available for inspection and local builds.

​Install

​Create a client

​Post a POS transaction

​Pagination

​Typed errors

​Verify webhooks

​Verify the download

Install

Create a client

Post a POS transaction

Pagination

Typed errors

Verify webhooks

Verify the download