# MySale API SDK
A comprehensive Python SDK for integrating with the MySale Marketplace API. This SDK provides both synchronous and asynchronous clients with full support for all MySale API endpoints including SKUs, Products, Orders, Returns, Taxonomy, and Shipping management.
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Authentication](#authentication)
- [Usage Examples](#usage-examples)
- [API Reference](#api-reference)
- [Error Handling](#error-handling)
- [Rate Limiting](#rate-limiting)
- [Development](#development)
- [License](#license)
## Features
- **Complete API Coverage**: Support for all MySale API endpoints
- **Async/Sync Support**: Both synchronous and asynchronous clients
- **Type Safety**: Full type hints with Pydantic models
- **Rate Limiting**: Built-in rate limiting to respect API limits
- **Error Handling**: Comprehensive error handling with specific exception types
- **Pagination**: Automatic pagination support for list endpoints
- **Validation**: Request/response validation using Pydantic models
- **Retry Logic**: Automatic retry for rate-limited and server error responses
### Supported Resources
- **SKUs**: Create, read, update, and manage product SKUs
- **Products**: Product management and grouping
- **Orders**: Order lifecycle management (new, acknowledged, shipped, cancelled)
- **Returns**: Returns and refunds management
- **Shipping**: Shipping policies and configuration
- **Taxonomy**: Product categorization and taxonomy
## Installation
```bash
pip install mysale-api-sdk
```
### Development Installation
```bash
git clone https://github.com/DuneRaccoon/mysale-api-sdk.git
cd mysale-api-sdk
pip install -e .
```
## Quick Start
```python
from mysale_api import MySaleClient, MySaleAsyncClient
# Synchronous client
client = MySaleClient(api_token="your_api_token_here")
# Get all new orders
new_orders = client.orders.list_new_orders()
print(f"Found {len(new_orders)} new orders")
# Get a specific SKU
sku = client.skus.get_by_merchant_id("your-sku-id")
print(f"SKU: {sku.name}")
# Asynchronous client
import asyncio
async def main():
async_client = MySaleAsyncClient(api_token="your_api_token_here")
# Get orders asynchronously
orders = await async_client.orders.list_new_orders_async()
print(f"Found {len(orders)} new orders")
await async_client.close()
asyncio.run(main())
```
## Authentication
The MySale API uses Bearer token authentication. You'll need to obtain an API token from your MySale merchant dashboard.
```python
from mysale_api import MySaleClient
client = MySaleClient(
api_token="your_api_token_here",
base_url="https://api.mysale.com", # Optional: defaults to MySale API URL
timeout=60.0, # Optional: request timeout in seconds
max_retries=5 # Optional: maximum retry attempts
)
```
## Usage Examples
### SKU Management
```python
from mysale_api import MySaleClient
from mysale_api.models import SKUCreateWrite, Weight
from uuid import uuid4
client = MySaleClient(api_token="your_token")
# Create a new SKU
sku_data = SKUCreateWrite(
merchant_sku_id="MY-SKU-001",
name="Premium T-Shirt",
description="High quality cotton t-shirt",
country_of_origin="AU",
weight=Weight(value=0.3, unit="kg"),
taxonomy_id=uuid4(), # Use actual taxonomy ID
)
new_sku = client.skus.create_sku(sku_data)
print(f"Created SKU: {new_sku.merchant_sku_id}")
# Update SKU pricing
from mysale_api.models import SKUPrices, SKUPrice, PriceValue
price_data = SKUPrices(
prices=SKUPrice(
cost=PriceValue(currency="AUD", value=10.00),
sell=PriceValue(currency="AUD", value=25.00),
rrp=PriceValue(currency="AUD", value=30.00)
)
)
client.skus.upload_prices("MY-SKU-001", price_data)
# List all SKUs with pagination
skus_page = client.skus.list_skus(offset=0, limit=50, paginated=True)
print(f"Total SKUs: {skus_page.total_count}")
for sku in skus_page.items:
print(f"- {sku.merchant_sku_id}: {sku.name}")
```
### Order Management
```python
# Get new orders that need processing
new_orders = client.orders.list_new_orders(limit=100)
for order_item in new_orders:
# Get full order details
order = client.orders.get_order(str(order_item.order_id))
print(f"Order {order.customer_order_reference}:")
print(f" Customer: {order.recipient.name}")
print(f" Items: {len(order.order_items)}")
print(f" Total: {order.order_shipping_price.currency} {order.order_shipping_price.amount}")
# Acknowledge an order
from mysale_api.models import OrderAcknowledgement
acknowledgement = OrderAcknowledgement(
merchant_order_id="MY-ORDER-001",
order_items=[] # Optional: can specify merchant order item IDs
)
client.orders.acknowledge_order(str(order.order_id), acknowledgement)
# Create a shipment
from mysale_api.models import ShipmentCreate, ShipmentItem
from datetime import datetime
shipment_data = ShipmentCreate(
merchant_shipment_id="SHIP-001",
tracking_number="TR123456789",
carrier="Australia Post",
carrier_shipment_method="Express",
dispatch_date=datetime.now(),
shipment_items=[
ShipmentItem(
merchant_sku_id="MY-SKU-001",
sku_id=order.order_items[0].sku_id,
sku_qty=1
)
]
)
shipment_id = client.orders.create_shipment(str(order.order_id), shipment_data)
print(f"Created shipment: {shipment_id}")
```
### Returns Management
```python
# Get pending returns
pending_returns = client.returns.list_pending_returns()
for return_item in pending_returns:
# Get full return details
return_detail = client.returns.get_return(str(return_item.id))
print(f"Return {return_detail.ran}:")
print(f" Customer: {return_detail.customer.name}")
print(f" Reason: {return_detail.reason_for_return}")
print(f" Amount: {return_detail.total_amount.currency if return_detail.total_amount else 'N/A'}")
# Approve a return
approved_return = client.returns.approve_return(str(return_detail.id))
print(f"Approved return: {approved_return.ran}")
# Process partial refund
from mysale_api.models import PartialRefund, Price
partial_refund = PartialRefund(
amount_to_refund=Price(currency="AUD", amount=15.50)
)
client.returns.partial_refund_return(str(return_detail.id), partial_refund)
```
### Product Management
```python
# Create a product
from mysale_api.models import ProductCreateWrite, ProductSKU
product_data = ProductCreateWrite(
merchant_product_id="PROD-001",
name="T-Shirt Collection",
description="Premium cotton t-shirts in various colors",
skus=[
ProductSKU(merchant_sku_id="MY-SKU-001"),
ProductSKU(merchant_sku_id="MY-SKU-002")
]
)
product = client.products.create_product(product_data)
print(f"Created product: {product.name}")
```
### Shipping Policies
```python
# Get all shipping policies
policies = client.shipping.list_policies()
for policy in policies:
print(f"Policy: {policy.name}")
print(f" Enabled: {policy.enabled}")
print(f" Default: {policy.is_default}")
print(f" Locations: {len(policy.dispatch_location_ids)}")
# Get shipping coverage analysis
coverage = client.shipping.analyze_shipping_coverage()
print(f"Total policies: {coverage['total_policies']}")
print(f"Enabled policies: {coverage['enabled_policies']}")
```
### Taxonomy Navigation
```python
# Get root categories
root_branches = client.taxonomy.get_root_branches()
for branch in root_branches:
print(f"Category: {branch.name}")
# Get child categories
children = client.taxonomy.get_child_branches(str(branch.branch_id))
for child in children:
print(f" - {child.name}")
# Search for categories
search_results = client.taxonomy.search_branches("clothing")
for result in search_results:
print(f"Found: {result.name} (Level {result.level})")
```
### Async Usage
```python
import asyncio
from mysale_api import MySaleAsyncClient
async def process_orders():
client = MySaleAsyncClient(api_token="your_token")
try:
# Get new orders
new_orders = await client.orders.list_new_orders_async(limit=50)
# Process each order
for order_item in new_orders:
order = await client.orders.get_order_async(str(order_item.order_id))
print(f"Processing order: {order.customer_order_reference}")
# Acknowledge the order
await client.orders.acknowledge_order_async(
str(order.order_id),
{"merchant_order_id": f"INTERNAL-{order.customer_order_reference}"}
)
finally:
await client.close()
# Run async function
asyncio.run(process_orders())
```
## API Reference
### Client Classes
#### MySaleClient (Synchronous)
```python
MySaleClient(
api_token: str,
base_url: str = "https://api.mysale.com",
timeout: float = 60.0,
max_retries: int = 5
)
```
#### MySaleAsyncClient (Asynchronous)
```python
MySaleAsyncClient(
api_token: str,
base_url: str = "https://api.mysale.com",
timeout: float = 60.0,
max_retries: int = 5
)
```
### Resource Endpoints
#### SKUs (`client.skus`)
- `get_by_merchant_id(merchant_sku_id)` - Get SKU by merchant ID
- `create_sku(data)` - Create new SKU
- `update_by_merchant_id(merchant_sku_id, data)` - Update SKU
- `list_skus(offset, limit, exclude_archived, paginated)` - List SKUs
- `upload_prices(merchant_sku_id, prices)` - Update SKU pricing
- `upload_inventory(merchant_sku_id, inventory)` - Update inventory
- `upload_images(merchant_sku_id, images)` - Upload images
- `enable(merchant_sku_id)` - Enable SKU for sale
- `disable(merchant_sku_id)` - Disable SKU
#### Orders (`client.orders`)
- `list_new_orders(offset, limit, paginated)` - Get new orders
- `list_acknowledged_orders(offset, limit, paginated)` - Get acknowledged orders
- `list_inprogress_orders(offset, limit, paginated)` - Get in-progress orders
- `list_completed_orders(offset, limit, paginated)` - Get completed orders
- `get_order(order_id)` - Get specific order
- `acknowledge_order(order_id, acknowledgement)` - Acknowledge order
- `create_shipment(order_id, shipment)` - Create shipment
- `get_shipments(order_id)` - Get order shipments
- `create_cancellation(order_id, cancellation)` - Cancel order items
#### Returns (`client.returns`)
- `list_pending_returns(offset, limit, paginated)` - Get pending returns
- `list_awaiting_returns(offset, limit, paginated)` - Get approved returns
- `get_return(return_id)` - Get specific return
- `approve_return(return_id)` - Approve return
- `decline_return(return_id)` - Decline return
- `receive_return(return_id)` - Mark return as received
- `partial_refund_return(return_id, refund_data)` - Process partial refund
- `full_refund_return(return_id)` - Process full refund
#### Products (`client.products`)
- `get_by_merchant_id(merchant_product_id)` - Get product by merchant ID
- `create_product(data)` - Create new product
- `update_by_merchant_id(merchant_product_id, data)` - Update product
- `list_products(offset, limit, paginated)` - List products
#### Shipping (`client.shipping`)
- `list_policies(paginated)` - Get shipping policies
- `get_policy(shipping_policy_id)` - Get specific policy
- `get_enabled_policies()` - Get enabled policies only
- `analyze_shipping_coverage()` - Analyze shipping coverage
#### Taxonomy (`client.taxonomy`)
- `get_branch(branch_id)` - Get taxonomy branch
- `list_branches(offset, limit, paginated)` - List all branches
- `search_branches(keyword)` - Search branches by keyword
- `get_root_branches()` - Get root categories
- `get_child_branches(parent_branch_id)` - Get child categories
## Error Handling
The SDK provides specific exception types for different error scenarios:
```python
from mysale_api import (
MySaleAPIError,
AuthenticationError,
ValidationError,
NotFoundError,
RateLimitError,
ServerError
)
try:
client = MySaleClient(api_token="invalid_token")
orders = client.orders.list_new_orders()
except AuthenticationError:
print("Invalid API token")
except RateLimitError as e:
print(f"Rate limited. Retry after: {e.retry_after} seconds")
except NotFoundError:
print("Resource not found")
except ValidationError as e:
print(f"Validation error: {e.message}")
except ServerError:
print("Server error occurred")
except MySaleAPIError as e:
print(f"API error: {e.message}")
```
### Exception Types
- `MySaleAPIError` - Base exception for all API errors
- `AuthenticationError` - Invalid credentials (401)
- `ForbiddenError` - Access forbidden (403)
- `NotFoundError` - Resource not found (404)
- `ValidationError` - Request validation failed (422)
- `RateLimitError` - Rate limit exceeded (429)
- `ServerError` - Server error (5xx)
- `ConflictError` - Resource conflict (409)
## Rate Limiting
The SDK automatically handles MySale's rate limits:
- **Burst**: 90 hits/second over 5-second period
- **Average**: 60 hits/second over 2-minute period
The SDK uses conservative limits (50 calls per 5 seconds) and will automatically wait when limits are approached.
```python
# Rate limiting is handled automatically
client = MySaleClient(api_token="your_token")
# These calls will be automatically throttled
for i in range(100):
client.skus.get_statistics() # Will respect rate limits
```
## Development
### Setting up Development Environment
```bash
git clone https://github.com/DuneRaccoon/mysale-api-sdk.git
cd mysale-api-sdk
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run linting
black mysale_api/
isort mysale_api/
flake8 mysale_api/
# Type checking
mypy mysale_api/
```
### Testing
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=mysale_api
# Run specific test file
pytest tests/test_orders.py
```
### Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Links
- [MySale API Documentation](https://apacsale.atlassian.net/wiki/spaces/MPS/pages/2109931778/API+Documentation)
- [PyPI Package](https://pypi.org/project/mysale-api-sdk/)
- [GitHub Repository](https://github.com/DuneRaccoon/mysale-api-sdk)
- [Issue Tracker](https://github.com/DuneRaccoon/mysale-api-sdk/issues)
## Support
For support, please:
1. Check the [documentation](https://github.com/DuneRaccoon/mysale-api-sdk)
2. Search [existing issues](https://github.com/DuneRaccoon/mysale-api-sdk/issues)
3. Create a [new issue](https://github.com/DuneRaccoon/mysale-api-sdk/issues/new) if needed
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history and changes.
Raw data
{
"_id": null,
"home_page": "https://github.com/DuneRaccoon/mysale-api-sdk",
"name": "mysale-api-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mysale, ozsale, marketplace, api, sdk, ecommerce",
"author": "Benjamin Herro",
"author_email": "benjamincsherro@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/6f/e6/b26beb58ae69cd9404687aa2010345aea486be798e85c97b0fc1c83bb35b/mysale_api_sdk-0.1.2.tar.gz",
"platform": null,
"description": "# MySale API SDK\n\nA comprehensive Python SDK for integrating with the MySale Marketplace API. This SDK provides both synchronous and asynchronous clients with full support for all MySale API endpoints including SKUs, Products, Orders, Returns, Taxonomy, and Shipping management.\n\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Authentication](#authentication)\n- [Usage Examples](#usage-examples)\n- [API Reference](#api-reference)\n- [Error Handling](#error-handling)\n- [Rate Limiting](#rate-limiting)\n- [Development](#development)\n- [License](#license)\n\n## Features\n\n- **Complete API Coverage**: Support for all MySale API endpoints\n- **Async/Sync Support**: Both synchronous and asynchronous clients\n- **Type Safety**: Full type hints with Pydantic models\n- **Rate Limiting**: Built-in rate limiting to respect API limits\n- **Error Handling**: Comprehensive error handling with specific exception types\n- **Pagination**: Automatic pagination support for list endpoints\n- **Validation**: Request/response validation using Pydantic models\n- **Retry Logic**: Automatic retry for rate-limited and server error responses\n\n### Supported Resources\n\n- **SKUs**: Create, read, update, and manage product SKUs\n- **Products**: Product management and grouping\n- **Orders**: Order lifecycle management (new, acknowledged, shipped, cancelled)\n- **Returns**: Returns and refunds management\n- **Shipping**: Shipping policies and configuration\n- **Taxonomy**: Product categorization and taxonomy\n\n## Installation\n\n```bash\npip install mysale-api-sdk\n```\n\n### Development Installation\n\n```bash\ngit clone https://github.com/DuneRaccoon/mysale-api-sdk.git\ncd mysale-api-sdk\npip install -e .\n```\n\n## Quick Start\n\n```python\nfrom mysale_api import MySaleClient, MySaleAsyncClient\n\n# Synchronous client\nclient = MySaleClient(api_token=\"your_api_token_here\")\n\n# Get all new orders\nnew_orders = client.orders.list_new_orders()\nprint(f\"Found {len(new_orders)} new orders\")\n\n# Get a specific SKU\nsku = client.skus.get_by_merchant_id(\"your-sku-id\")\nprint(f\"SKU: {sku.name}\")\n\n# Asynchronous client\nimport asyncio\n\nasync def main():\n async_client = MySaleAsyncClient(api_token=\"your_api_token_here\")\n \n # Get orders asynchronously\n orders = await async_client.orders.list_new_orders_async()\n print(f\"Found {len(orders)} new orders\")\n \n await async_client.close()\n\nasyncio.run(main())\n```\n\n## Authentication\n\nThe MySale API uses Bearer token authentication. You'll need to obtain an API token from your MySale merchant dashboard.\n\n```python\nfrom mysale_api import MySaleClient\n\nclient = MySaleClient(\n api_token=\"your_api_token_here\",\n base_url=\"https://api.mysale.com\", # Optional: defaults to MySale API URL\n timeout=60.0, # Optional: request timeout in seconds\n max_retries=5 # Optional: maximum retry attempts\n)\n```\n\n## Usage Examples\n\n### SKU Management\n\n```python\nfrom mysale_api import MySaleClient\nfrom mysale_api.models import SKUCreateWrite, Weight\nfrom uuid import uuid4\n\nclient = MySaleClient(api_token=\"your_token\")\n\n# Create a new SKU\nsku_data = SKUCreateWrite(\n merchant_sku_id=\"MY-SKU-001\",\n name=\"Premium T-Shirt\",\n description=\"High quality cotton t-shirt\",\n country_of_origin=\"AU\",\n weight=Weight(value=0.3, unit=\"kg\"),\n taxonomy_id=uuid4(), # Use actual taxonomy ID\n)\n\nnew_sku = client.skus.create_sku(sku_data)\nprint(f\"Created SKU: {new_sku.merchant_sku_id}\")\n\n# Update SKU pricing\nfrom mysale_api.models import SKUPrices, SKUPrice, PriceValue\n\nprice_data = SKUPrices(\n prices=SKUPrice(\n cost=PriceValue(currency=\"AUD\", value=10.00),\n sell=PriceValue(currency=\"AUD\", value=25.00),\n rrp=PriceValue(currency=\"AUD\", value=30.00)\n )\n)\n\nclient.skus.upload_prices(\"MY-SKU-001\", price_data)\n\n# List all SKUs with pagination\nskus_page = client.skus.list_skus(offset=0, limit=50, paginated=True)\nprint(f\"Total SKUs: {skus_page.total_count}\")\n\nfor sku in skus_page.items:\n print(f\"- {sku.merchant_sku_id}: {sku.name}\")\n```\n\n### Order Management\n\n```python\n# Get new orders that need processing\nnew_orders = client.orders.list_new_orders(limit=100)\n\nfor order_item in new_orders:\n # Get full order details\n order = client.orders.get_order(str(order_item.order_id))\n \n print(f\"Order {order.customer_order_reference}:\")\n print(f\" Customer: {order.recipient.name}\")\n print(f\" Items: {len(order.order_items)}\")\n print(f\" Total: {order.order_shipping_price.currency} {order.order_shipping_price.amount}\")\n\n# Acknowledge an order\nfrom mysale_api.models import OrderAcknowledgement\n\nacknowledgement = OrderAcknowledgement(\n merchant_order_id=\"MY-ORDER-001\",\n order_items=[] # Optional: can specify merchant order item IDs\n)\n\nclient.orders.acknowledge_order(str(order.order_id), acknowledgement)\n\n# Create a shipment\nfrom mysale_api.models import ShipmentCreate, ShipmentItem\nfrom datetime import datetime\n\nshipment_data = ShipmentCreate(\n merchant_shipment_id=\"SHIP-001\",\n tracking_number=\"TR123456789\",\n carrier=\"Australia Post\",\n carrier_shipment_method=\"Express\",\n dispatch_date=datetime.now(),\n shipment_items=[\n ShipmentItem(\n merchant_sku_id=\"MY-SKU-001\",\n sku_id=order.order_items[0].sku_id,\n sku_qty=1\n )\n ]\n)\n\nshipment_id = client.orders.create_shipment(str(order.order_id), shipment_data)\nprint(f\"Created shipment: {shipment_id}\")\n```\n\n### Returns Management\n\n```python\n# Get pending returns\npending_returns = client.returns.list_pending_returns()\n\nfor return_item in pending_returns:\n # Get full return details\n return_detail = client.returns.get_return(str(return_item.id))\n \n print(f\"Return {return_detail.ran}:\")\n print(f\" Customer: {return_detail.customer.name}\")\n print(f\" Reason: {return_detail.reason_for_return}\")\n print(f\" Amount: {return_detail.total_amount.currency if return_detail.total_amount else 'N/A'}\")\n\n# Approve a return\napproved_return = client.returns.approve_return(str(return_detail.id))\nprint(f\"Approved return: {approved_return.ran}\")\n\n# Process partial refund\nfrom mysale_api.models import PartialRefund, Price\n\npartial_refund = PartialRefund(\n amount_to_refund=Price(currency=\"AUD\", amount=15.50)\n)\n\nclient.returns.partial_refund_return(str(return_detail.id), partial_refund)\n```\n\n### Product Management\n\n```python\n# Create a product\nfrom mysale_api.models import ProductCreateWrite, ProductSKU\n\nproduct_data = ProductCreateWrite(\n merchant_product_id=\"PROD-001\",\n name=\"T-Shirt Collection\",\n description=\"Premium cotton t-shirts in various colors\",\n skus=[\n ProductSKU(merchant_sku_id=\"MY-SKU-001\"),\n ProductSKU(merchant_sku_id=\"MY-SKU-002\")\n ]\n)\n\nproduct = client.products.create_product(product_data)\nprint(f\"Created product: {product.name}\")\n```\n\n### Shipping Policies\n\n```python\n# Get all shipping policies\npolicies = client.shipping.list_policies()\n\nfor policy in policies:\n print(f\"Policy: {policy.name}\")\n print(f\" Enabled: {policy.enabled}\")\n print(f\" Default: {policy.is_default}\")\n print(f\" Locations: {len(policy.dispatch_location_ids)}\")\n\n# Get shipping coverage analysis\ncoverage = client.shipping.analyze_shipping_coverage()\nprint(f\"Total policies: {coverage['total_policies']}\")\nprint(f\"Enabled policies: {coverage['enabled_policies']}\")\n```\n\n### Taxonomy Navigation\n\n```python\n# Get root categories\nroot_branches = client.taxonomy.get_root_branches()\n\nfor branch in root_branches:\n print(f\"Category: {branch.name}\")\n \n # Get child categories\n children = client.taxonomy.get_child_branches(str(branch.branch_id))\n for child in children:\n print(f\" - {child.name}\")\n\n# Search for categories\nsearch_results = client.taxonomy.search_branches(\"clothing\")\nfor result in search_results:\n print(f\"Found: {result.name} (Level {result.level})\")\n```\n\n### Async Usage\n\n```python\nimport asyncio\nfrom mysale_api import MySaleAsyncClient\n\nasync def process_orders():\n client = MySaleAsyncClient(api_token=\"your_token\")\n \n try:\n # Get new orders\n new_orders = await client.orders.list_new_orders_async(limit=50)\n \n # Process each order\n for order_item in new_orders:\n order = await client.orders.get_order_async(str(order_item.order_id))\n print(f\"Processing order: {order.customer_order_reference}\")\n \n # Acknowledge the order\n await client.orders.acknowledge_order_async(\n str(order.order_id),\n {\"merchant_order_id\": f\"INTERNAL-{order.customer_order_reference}\"}\n )\n \n finally:\n await client.close()\n\n# Run async function\nasyncio.run(process_orders())\n```\n\n## API Reference\n\n### Client Classes\n\n#### MySaleClient (Synchronous)\n```python\nMySaleClient(\n api_token: str,\n base_url: str = \"https://api.mysale.com\",\n timeout: float = 60.0,\n max_retries: int = 5\n)\n```\n\n#### MySaleAsyncClient (Asynchronous)\n```python\nMySaleAsyncClient(\n api_token: str,\n base_url: str = \"https://api.mysale.com\", \n timeout: float = 60.0,\n max_retries: int = 5\n)\n```\n\n### Resource Endpoints\n\n#### SKUs (`client.skus`)\n- `get_by_merchant_id(merchant_sku_id)` - Get SKU by merchant ID\n- `create_sku(data)` - Create new SKU\n- `update_by_merchant_id(merchant_sku_id, data)` - Update SKU\n- `list_skus(offset, limit, exclude_archived, paginated)` - List SKUs\n- `upload_prices(merchant_sku_id, prices)` - Update SKU pricing\n- `upload_inventory(merchant_sku_id, inventory)` - Update inventory\n- `upload_images(merchant_sku_id, images)` - Upload images\n- `enable(merchant_sku_id)` - Enable SKU for sale\n- `disable(merchant_sku_id)` - Disable SKU\n\n#### Orders (`client.orders`)\n- `list_new_orders(offset, limit, paginated)` - Get new orders\n- `list_acknowledged_orders(offset, limit, paginated)` - Get acknowledged orders\n- `list_inprogress_orders(offset, limit, paginated)` - Get in-progress orders\n- `list_completed_orders(offset, limit, paginated)` - Get completed orders\n- `get_order(order_id)` - Get specific order\n- `acknowledge_order(order_id, acknowledgement)` - Acknowledge order\n- `create_shipment(order_id, shipment)` - Create shipment\n- `get_shipments(order_id)` - Get order shipments\n- `create_cancellation(order_id, cancellation)` - Cancel order items\n\n#### Returns (`client.returns`)\n- `list_pending_returns(offset, limit, paginated)` - Get pending returns\n- `list_awaiting_returns(offset, limit, paginated)` - Get approved returns\n- `get_return(return_id)` - Get specific return\n- `approve_return(return_id)` - Approve return\n- `decline_return(return_id)` - Decline return\n- `receive_return(return_id)` - Mark return as received\n- `partial_refund_return(return_id, refund_data)` - Process partial refund\n- `full_refund_return(return_id)` - Process full refund\n\n#### Products (`client.products`)\n- `get_by_merchant_id(merchant_product_id)` - Get product by merchant ID\n- `create_product(data)` - Create new product\n- `update_by_merchant_id(merchant_product_id, data)` - Update product\n- `list_products(offset, limit, paginated)` - List products\n\n#### Shipping (`client.shipping`)\n- `list_policies(paginated)` - Get shipping policies\n- `get_policy(shipping_policy_id)` - Get specific policy\n- `get_enabled_policies()` - Get enabled policies only\n- `analyze_shipping_coverage()` - Analyze shipping coverage\n\n#### Taxonomy (`client.taxonomy`)\n- `get_branch(branch_id)` - Get taxonomy branch\n- `list_branches(offset, limit, paginated)` - List all branches\n- `search_branches(keyword)` - Search branches by keyword\n- `get_root_branches()` - Get root categories\n- `get_child_branches(parent_branch_id)` - Get child categories\n\n## Error Handling\n\nThe SDK provides specific exception types for different error scenarios:\n\n```python\nfrom mysale_api import (\n MySaleAPIError,\n AuthenticationError,\n ValidationError,\n NotFoundError,\n RateLimitError,\n ServerError\n)\n\ntry:\n client = MySaleClient(api_token=\"invalid_token\")\n orders = client.orders.list_new_orders()\n \nexcept AuthenticationError:\n print(\"Invalid API token\")\nexcept RateLimitError as e:\n print(f\"Rate limited. Retry after: {e.retry_after} seconds\")\nexcept NotFoundError:\n print(\"Resource not found\")\nexcept ValidationError as e:\n print(f\"Validation error: {e.message}\")\nexcept ServerError:\n print(\"Server error occurred\")\nexcept MySaleAPIError as e:\n print(f\"API error: {e.message}\")\n```\n\n### Exception Types\n\n- `MySaleAPIError` - Base exception for all API errors\n- `AuthenticationError` - Invalid credentials (401)\n- `ForbiddenError` - Access forbidden (403)\n- `NotFoundError` - Resource not found (404)\n- `ValidationError` - Request validation failed (422)\n- `RateLimitError` - Rate limit exceeded (429)\n- `ServerError` - Server error (5xx)\n- `ConflictError` - Resource conflict (409)\n\n## Rate Limiting\n\nThe SDK automatically handles MySale's rate limits:\n- **Burst**: 90 hits/second over 5-second period\n- **Average**: 60 hits/second over 2-minute period\n\nThe SDK uses conservative limits (50 calls per 5 seconds) and will automatically wait when limits are approached.\n\n```python\n# Rate limiting is handled automatically\nclient = MySaleClient(api_token=\"your_token\")\n\n# These calls will be automatically throttled\nfor i in range(100):\n client.skus.get_statistics() # Will respect rate limits\n```\n\n## Development\n\n### Setting up Development Environment\n\n```bash\ngit clone https://github.com/DuneRaccoon/mysale-api-sdk.git\ncd mysale-api-sdk\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run linting\nblack mysale_api/\nisort mysale_api/\nflake8 mysale_api/\n\n# Type checking\nmypy mysale_api/\n```\n\n### Testing\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=mysale_api\n\n# Run specific test file\npytest tests/test_orders.py\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Run the test suite\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Links\n\n- [MySale API Documentation](https://apacsale.atlassian.net/wiki/spaces/MPS/pages/2109931778/API+Documentation)\n- [PyPI Package](https://pypi.org/project/mysale-api-sdk/)\n- [GitHub Repository](https://github.com/DuneRaccoon/mysale-api-sdk)\n- [Issue Tracker](https://github.com/DuneRaccoon/mysale-api-sdk/issues)\n\n## Support\n\nFor support, please:\n1. Check the [documentation](https://github.com/DuneRaccoon/mysale-api-sdk)\n2. Search [existing issues](https://github.com/DuneRaccoon/mysale-api-sdk/issues)\n3. Create a [new issue](https://github.com/DuneRaccoon/mysale-api-sdk/issues/new) if needed\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history and changes.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for MySale Marketplace API integration",
"version": "0.1.2",
"project_urls": {
"Bug Reports": "https://github.com/DuneRaccoon/mysale-api-sdk/issues",
"Documentation": "https://apacsale.atlassian.net/wiki/spaces/MPS/pages/2109931778/API+Documentation",
"Homepage": "https://github.com/DuneRaccoon/mysale-api-sdk",
"Repository": "https://github.com/DuneRaccoon/mysale-api-sdk"
},
"split_keywords": [
"mysale",
" ozsale",
" marketplace",
" api",
" sdk",
" ecommerce"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "92f2731561998d9b749a95b55e289afaf06289c9382413dd340a5027698d26ff",
"md5": "e046ed1af4fb576964a5ef7c0f9c8d6d",
"sha256": "ab967b318fc973013fc809329e8aecf33986b8fc6a11069b40cb4cdc589298e0"
},
"downloads": -1,
"filename": "mysale_api_sdk-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e046ed1af4fb576964a5ef7c0f9c8d6d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 40166,
"upload_time": "2025-07-10T02:36:13",
"upload_time_iso_8601": "2025-07-10T02:36:13.024815Z",
"url": "https://files.pythonhosted.org/packages/92/f2/731561998d9b749a95b55e289afaf06289c9382413dd340a5027698d26ff/mysale_api_sdk-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6fe6b26beb58ae69cd9404687aa2010345aea486be798e85c97b0fc1c83bb35b",
"md5": "343a063807ec309d630b5f6ef61e7d00",
"sha256": "836bf9c23b47cb61ec28f1199d90b89a4fc4d1231e0585a58d8074bb498fa23f"
},
"downloads": -1,
"filename": "mysale_api_sdk-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "343a063807ec309d630b5f6ef61e7d00",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 36749,
"upload_time": "2025-07-10T02:36:14",
"upload_time_iso_8601": "2025-07-10T02:36:14.617471Z",
"url": "https://files.pythonhosted.org/packages/6f/e6/b26beb58ae69cd9404687aa2010345aea486be798e85c97b0fc1c83bb35b/mysale_api_sdk-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 02:36:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DuneRaccoon",
"github_project": "mysale-api-sdk",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mysale-api-sdk"
}
JSON
