Official Python SDK for the CoCart REST API.
Important
This SDK is still in development and not yet ready for production use. Provide feedback if you experience a bug.
- Add SDK docs to documentation site
- Add support for Cart API extras
- Add Checkout API support
- Python 3.9+
requestslibrary
See SUPPORT.md for our versioning policy, supported Python versions, and support lifecycle.
- Full cart management (add, update, remove, clear items)
- Batch requests — single round-trip for multiple sub-requests (CoCart Plus)
- Guest customer support with automatic cart key tracking
- Authenticated user support (Basic Auth & JWT)
- JWT token lifecycle (login, 2FA verification, refresh, validate, auto-refresh)
- Session management and cart transfer on login
- Fetch products easily, search and filter results
- Sessions management (admin)
- Customer account access (profile, orders, downloads, reviews)
- Multiple storage adapters for cart key and token persistence
- Multiple HTTP adapters (
requestsdefault,httpxoptional) typing.Protocolinterfaces for easy mocking in tests- ETag conditional requests for reduced bandwidth (enabled by default)
- Legacy CoCart plugin support with version-aware endpoint guards
- Comprehensive error handling with typed exceptions
- Iterator-based pagination with Python
forloop support - Fluent interface — all setters return
selffor chaining - Currency formatting and timezone utilities
| Guide | Description |
|---|---|
| Installation | Requirements, pip install, HTTP adapters, configuration options |
| Authentication | Guest sessions, Basic Auth, JWT (login/refresh/validate/auto-refresh), consumer keys, white-labelling |
| Cart | Add/update/remove items, batch requests, coupons, customer details, shipping, fees, totals |
| Products | List/search/filter products, pagination, variations, categories, tags, attributes, reviews |
| Account | Authenticated customer profile, password change, order history, downloads, reviews (supported now, awaiting a CoCart plugin release) |
| Sessions | Admin sessions API, SessionManager, storage adapters, cart transfer on login |
| Error Handling | Exception hierarchy, catching errors, HTTP status mapping, response error helpers |
| Utilities | Currency and timezone utility helpers that operate on data already returned by the API |
pip install cocartfromcocartimportCoCart# Initialize the clientclient=CoCart("https://your-store.com")
# Browse productsproducts=client.products().all()
print(products.to_dict())
# Add item to cartresponse=client.cart().add_item(42, quantity=2)
print(f"Cart key: {response.get_cart_key()}")
# Get cartcart=client.cart().get()
print(f"Items: {cart.get_item_count()}")
print(f"Total: {cart.get_totals().get('total')}")# Basic Authclient=CoCart("https://your-store.com", username="user@email.com", password="password")
# JWT Authclient=CoCart("https://your-store.com")
client.login("user@email.com", "password")
# WooCommerce API keys (admin)client=CoCart("https://your-store.com", consumer_key="ck_xxx", consumer_secret="cs_xxx")client=CoCart("https://your-store.com",
cart_key="existing_cart_key", # Guest sessionusername="customer@email.com", # Basic Authpassword="password",
jwt_token="your-jwt-token", # JWT Authjwt_refresh_token="your-refresh-token",
consumer_key="ck_xxxxx", # Admin (Sessions API)consumer_secret="cs_xxxxx",
auth_header_name="Authorization", # Custom auth header for proxiestimeout=30, # HTTP settingsverify_ssl=True,
rest_prefix="wp-json", # Custom REST prefixnamespace="cocart", # Custom namespace (WhiteLabel add-on)main_plugin="basic", # "basic" (default) or "legacy"etag=True, # ETag conditional requests (default True)max_retries=2, # Retry transient failures (429, 503)
)We have different channels at your disposal where you can find information about the CoCart project, discuss it and get involved:
- 📖 Documentation: this is the place to learn how to use CoCart API. Get started!
- 👪 Community: use our Discord chat room to share any doubts, feedback and meet great people. This is your place too to share how are you planning to use CoCart!
- 🐞 GitHub: we use GitHub for bugs and pull requests, doubts are solved with the community.
- 🐦 Social media: a more informal place to interact with CoCart users, reach out to us on X/Twitter.
Website cocartapi.com · GitHub @cocart-headless · X/Twitter @cocartapi · Facebook · Instagram
MIT