Python SDK — installation and usage

Overview

Install: pip install merch-sdk. OAuth 2.0, async client, typed responses, retry/backoff, webhook signature verification. Python 3.9+. The SDK is open-source (MIT) and follows semantic versioning. It abstracts OAuth 2.0 token management, retries with exponential backoff, idempotency keys for write operations, and webhook signature verification.

Requirements

• Python 3.9 or newer
• An active client_id and client_secret from the customer portal
• (Optional) webhook_secret if you receive webhooks

Installation

pip install merch-sdk

Authentication and client setup

from merch_sdk import Client

client = Client(
    client_id="your_client_id",
    client_secret="your_client_secret",
    region="eu",  # or "me", "cis"
)
# OAuth 2.0 client_credentials grant runs automatically

List open quotes

quotes = client.quotes.list(status="open", limit=50)
for q in quotes:
    print(q.id, q.total_landed_usd, q.lead_time_days)

Create an order from a quote

order = client.orders.create(
    quote_id="qt_a1b2c3",
    delivery_address={
        "name": "Acme HR",
        "line1": "123 Oxford St",
        "city": "London",
        "country": "GB",
        "postal_code": "W1A 1AA",
    },
    payment_terms="net30",
)
print(order.id, order.expected_delivery)

Verify and handle a webhook

from merch_sdk.webhooks import verify

def handler(request):
    payload = request.body
    sig = request.headers["X-Merch-Signature"]
    event = verify(payload, sig, secret="whsec_...")
    if event.type == "order.shipped":
        update_internal_status(event.data.order_id, "shipped")
    return 200

Error handling

The SDK raises typed exceptions for common error cases: AuthenticationError, RateLimitError, ValidationError, NotFoundError, ServerError. Network errors are retried automatically with exponential backoff (up to 5 attempts by default). 429 responses respect the Retry-After header.

Idempotency

Write operations (orders.create, quotes.accept) accept an idempotency key. The SDK generates one automatically per call; pass your own to safely retry across process boundaries.

Pagination

List endpoints return paginated results. The SDK exposes both an iterator interface (preferred) and explicit cursor handling for advanced use cases. Page size defaults to 50, max 200.

Logging and observability

The SDK integrates with your standard logging library. Set log_level=DEBUG (or equivalent) to see HTTP requests, retries, and rate-limit handling. Sensitive headers (Authorization, webhook secrets) are automatically redacted.

Testing

A sandbox environment is available at https://sandbox.api.merch.am. Sandbox client credentials are issued separately; sandbox state resets weekly. Test webhooks with client.webhooks.test_send() (or the equivalent in your language).

Versioning and upgrades

The SDK follows semantic versioning. Major versions may include breaking changes; minor and patch versions are backwards-compatible. Deprecation notices appear in CHANGELOG.md with a minimum 6-month removal window. Subscribe to GitHub releases for notifications.

Source code

SDK source on GitHub: github.com/merch (placeholder — public access enabled at GA in Q1 2027). Issues and PRs welcome.

Support

Email developers@merch.am with SDK questions. Production-impacting issues escalate to same-day response for clients with active MSA.