# Subscription Management API Documentation The Subscription Management API allows users to manage their API subscriptions programmatically using API keys. This API supports creating new subscriptions, upgrading/downgrading existing plans, and canceling subscriptions. ### Authentication All API endpoints require authentication using one of the following headers: * `x-api-market-key: YOUR_API_KEY_HERE` ### Base URL * Base URL: `https://api.market/` * Clean, RESTful design * Consistent response format *** ## API Endpoints ### 1. Get Product Details with Pricing Plans Retrieves product information along with all available pricing plans. **Endpoint:** `GET /api/v1/product/{workspaceSlug}/{productSlug}` **Request:** ```bash curl -X GET \ 'https://api.market/api/v1/product/magicapi/upscaler' \ -H 'accept: application/json' \ -H 'x-api-market-key: YOUR_API_KEY_HERE' ``` **Response:** ````json { "product": { "id": "clst0xf230004jr0cdi7j6ttf", "slug": "upscaler", "title": "πŸ–ΌοΈβœ¨Image Upscale API | Streamlined Image Upscaling for Stunning Results", "name": "Image Upscaler", "description": "# πŸ–ΌοΈβœ¨Image Upscale API\n\n### πŸ”— [Documentation](https://docs.api.market/api.market-apis/image-upscale-api)\n\n**Image Upscale API: Unlock High-Resolution Visuals with Ease**\n\nThe **Image Upscale API** leverages advanced super-resolution models to enhance image quality by factors of 2Γ—, 4Γ—, or 8Γ—. Whether you're a developer, designer, or content creator, this service provides a convenient, cost-effective way to boost image resolution without sacrificing clarity or detail. Transform standard images into high-definition files suitable for printing, display, or machine learning datasets.\n\n- **Provider**: MagicAPI\n- **Category**: Image Processing, AI, Design\n- **Tags**: Image Upscaling, Super Resolution, Image Enhancement\n\n---\n\n## Features\n1. **Versatile Upscaling Factors** – Choose between 2Γ—, 4Γ—, or 8Γ— resolution increase.\n - 2Γ— consumes **1 API unit** per request.\n - 4Γ— consumes **2 API units** per request.\n - 8Γ— consumes **4 API units** per request.\n2. **High-Quality Output** – Retain sharpness and detail in a standard JPEG format.\n3. **Easy Integration** – Straightforward HTTP POST requests with JSON bodies.\n4. **Streamlined Workflows** – Automate your image enhancement, saving time and resources.\n5. **Use Anywhere** – Perfect for web design, digital marketing, e-commerce, or ML data.\n\n---\n\n## Use Cases\n- **Digital Media Platforms** – Improve photo quality for online galleries or social media.\n- **E-Commerce Listings** – Present product images in crisp, clear detail.\n- **Machine Learning Datasets** – Enhance image details to improve training accuracy.\n- **Marketing Materials** – Prepare images for high-resolution printing or large displays.\n- **Design & Photography** – Bring out the best in creative assets without manual editing.\n\n---\n\n## API Documentation\n\n### Endpoints\nEach endpoint accepts a JSON body containing the image URL to upscale:\n\n- **2Γ— Upscale**: `POST /upscale2x/` (1 API unit per API call)\n- **4Γ— Upscale**: `POST /upscale4x/` (2 API units per API call)\n- **8Γ— Upscale**: `POST /upscale8x/` (4 API units per API call)\n\n| Parameter | Type | Required | Description |\n|-----------|--------|----------|-----------------------------------|\n| `url` | string | Yes | The publicly accessible image URL |\n\n### cURL Example (2Γ— Upscale)\n```bash\ncurl -X 'POST' \\\n 'https://api.magicapi.dev/api/v1/magicapi/upscaler/upscale2x/' \\\n -H 'accept: image/jpeg' \\\n -H 'x-api-market-key: API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"url\": \"https://production-media.paperswithcode.com/datasets/Set5-0000002728-07a9793f_zA3bDjj.jpg\"\n}'\n```\n\n**Sample Output Image**\n\"Upscaled\n\n**Response Format**\n- **JPEG Image** – The upscaled image is returned directly in the response body.\n\n---\n\n## Status Codes\n\n| Code | Description |\n|------|-----------------------------------------------------------------|\n| 200 | The image was successfully upscaled and returned as a JPEG |\n| 400 | Bad request – possibly missing parameters or invalid image URL |\n| 500 | Internal server error – an unexpected error occurred |\n\n---\n\n## SEO Keywords\nimage upscaling, super-resolution, AI image enhancement, high-resolution, photo improvement, design tools, content creation\n\n---\n\n**Elevate your visuals with the Image Upscale API**β€”the quickest way to turn standard images into stunning, high-definition assets. Whether you're building a photo-editing tool, improving e-commerce product listings, or preparing content for high-res displays, our API ensures you get premium results with minimal effort. Unlock new creative possibilities and deliver top-tier visuals with every request.\n\n", "categories": [ "tools", "visual-recognition", "artificial-intelligence", "image-to-image" ], "workspace": { "slug": "magicapi", "name": "MagicAPI" } }, "pricingPlans": [ { "id": "cltivivul000clc0crn8momz5", "name": "Mega", "access": "public", "pricingPlanConfig": { "maxTPS": "100", "aPILimitType": "HARD", "apiCallLimit": "25000", "apiSoftLimitOverHead": 0.001, "subscriptionPricePerMonth": "89" } }, { "id": "cltivgy940008lc0ccgeger63", "name": "Ultra", "access": "public", "pricingPlanConfig": { "maxTPS": "100", "aPILimitType": "HARD", "apiCallLimit": "10000", "apiSoftLimitOverHead": 0.001, "subscriptionPricePerMonth": "45" } }, { "id": "cltive4k60004jm0c3yok8ig3", "name": "Pro", "access": "public", "pricingPlanConfig": { "maxTPS": "100", "aPILimitType": "HARD", "apiCallLimit": "1000", "apiSoftLimitOverHead": 0.001, "subscriptionPricePerMonth": "8" } }, { "id": "cltivkbfl000glc0chhfqt24z", "name": "Giga", "access": "public", "pricingPlanConfig": { "maxTPS": "100", "aPILimitType": "HARD", "apiCallLimit": "100000", "apiSoftLimitOverHead": 0.001, "subscriptionPricePerMonth": "199" } }, { "id": "clst0y61m0004jq0cwq4qvl7j", "name": "Free", "access": "public", "pricingPlanConfig": { "maxTPS": "100", "aPILimitType": "HARD", "apiCallLimit": "100", "apiSoftLimitOverHead": 0.001, "subscriptionPricePerMonth": 0 } } ] } ```` ### 2. Get Current Subscription Details Retrieves the current subscription status for a specific product. **Endpoint:** `GET /api/v1/subscription/{workspaceSlug}/{productSlug}` **Request:** ```bash curl -X GET \ 'https://api.market/api/v1/subscription/magicapi/upscaler' \ -H 'accept: application/json' \ -H 'x-api-market-key: YOUR_API_KEY_HERE' ``` **Response (Active Subscription):** ```json { "subscription": { "id": "cmfcerwmv0001le04krvsl2f8", "subscriptionStatus": "SUBSCRIBED", "currentPeriodStartDate": "2025-09-09T10:29:15.894Z", "endDate": null, "renewDate": "2025-10-09T10:29:15.894Z", "apiCallsMade": 0, "cancellationDate": null, "pricingPlan": { "id": "clsncx2d10004l10cjr09rj3w", "name": "Free", "pricingPlanConfig": { "maxTPS": "100", "aPILimitType": "HARD", "apiCallLimit": "100", "apiSoftLimitOverHead": 0.001, "subscriptionPricePerMonth": "0" } }, "product": { "slug": "faceswap", "title": "FaceSwap API" }, "workspace": { "slug": "magicapi" } } } ``` **Response (No Subscription):** ```json { "subscription": null, "message": "No active subscription found for this product" } ``` ### 3. Create/Upgrade/Downgrade Subscription Creates a new subscription or changes an existing subscription to a different pricing plan. **Endpoint:** `POST /api/v1/subscription/{workspaceSlug}/{productSlug}/{pricingPlanId}` **Request:** ```bash curl -X POST \ 'https://api.market/api/v1/subscription/magicapi/upscaler/cltivivul000clc0crn8momz5' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'x-api-market-key: YOUR_API_KEY_HERE' \ -d '{ "additionalData": "optional", "isDryRun": false }' ``` **Request Body Parameters:** * `additionalData` (optional): Additional information for the subscription * `isDryRun` (optional): Set to `true` to simulate the operation without making changes **Response (New Subscription):** ```json { "subscription": { "id": "cmeh11x2o0000p3vx3lbt174m", "subscriptionStatus": "SUBSCRIBED", "currentPeriodStartDate": "2025-08-18T11:24:16.942Z", "endDate": null, "renewDate": "2025-09-18T11:24:16.942Z", "pricingPlan": { "id": "cltivivul000clc0crn8momz5", "name": "Mega", "pricingPlanConfig": { "maxTPS": 100, "aPILimitType": "HARD", "apiCallLimit": "25000", "apiSoftLimitOverHead": 0.001, "subscriptionPricePerMonth": 89 } } }, "action": "subscribed" } ``` **Response (Upgrade/Downgrade):** ```json { "subscription": { "id": "cmeh11x2o0000p3vx3lbt174m", "subscriptionStatus": "SUBSCRIBED", "currentPeriodStartDate": "2025-08-18T11:24:16.942Z", "endDate": null, "renewDate": "2025-09-18T11:24:16.942Z", "pricingPlan": { "id": "cltivivul000clc0crn8momz5", "name": "Mega" } }, "action": "upgraded", "previousSubscription": { "id": "previous-subscription-id", "subscriptionStatus": "CANCELLED", "currentPeriodStartDate": "2025-07-18T11:24:16.942Z", "endDate": "2025-08-18T11:24:16.942Z", "renewDate": "2025-08-18T11:24:16.942Z", "apiCallsMade": 1250, "cancellationDate": "2025-08-18T11:24:16.942Z", "pricingPlan": { "id": "previous-plan-id", "name": "Ultra", "pricingPlanConfig": { "maxTPS": 100, "aPILimitType": "HARD", "apiCallLimit": "10000", "apiSoftLimitOverHead": 0.001, "subscriptionPricePerMonth": 45 } }, "product": { "slug": "upscaler", "name": "Image Upscaler" }, "workspace": { "slug": "magicapi" } } } ``` **Action Types:** * `subscribed`: First-time subscription * `resubscribed`: Re-subscribing to the same plan * `upgraded`: Moving to a higher-priced plan * `downgraded`: Moving to a lower-priced plan * `unchanged`: Same price, different plan * `changed`: Plan changed but price comparison failed ### 4. Cancel Subscription Cancels the current subscription for a product. **Endpoint:** `DELETE /api/v1/subscription/{workspaceSlug}/{productSlug}` **Request:** ```bash curl -X DELETE \ 'https://api.market/api/v1/subscription/magicapi/upscaler' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -H 'x-api-market-key: YOUR_API_KEY_HERE' \ -d '{ "cancelImmediately": false, "reason": "No longer needed" }' ``` **Request Body Parameters:** * `cancelImmediately` (optional): Set to `true` to cancel immediately, `false` to cancel at period end * `reason` (optional): Reason for cancellation **Response:** ```json { "subscription": { "id": "cmeh11x2o0000p3vx3lbt174m", "subscriptionStatus": "CANCELLED", "cancellationDate": "2025-08-18T11:26:59.422Z", "endDate": "2025-09-18T11:24:16.942Z", "pricingPlan": { "id": "cltivivul000clc0crn8momz5", "name": "Mega" }, "product": { "slug": "upscaler", "title": "Image Upscaler" }, "workspace": { "slug": "magicapi" } }, "message": "Subscription cancelled successfully", "cancelledImmediately": false } ``` *** ## Error Handling ### HTTP Status Codes * **200**: Success * **400**: Bad Request (missing parameters, invalid data) * **401**: Unauthorized (invalid or missing API key) * **403**: Forbidden (insufficient permissions) * **404**: Not Found (product, pricing plan, or subscription not found) * **405**: Method Not Allowed * **409**: Conflict (subscription already exists, invalid state transition) * **500**: Internal Server Error ### Error Response Format ```json { "error": "Error message description" } ``` *** ## Rate Limiting * API calls are subject to rate limiting based on your subscription plan * Rate limits are enforced per API key * Exceeding limits will result in 429 (Too Many Requests) responses *** ## Best Practices ### 1. Always Check Current Subscription Before making changes, retrieve the current subscription to understand the current state. ### 2. Use Dry Run for Testing Set `isDryRun: true` in the request body to simulate operations without making actual changes. ### 3. Handle Errors Gracefully Implement proper error handling for all API responses, especially for network failures. ### 4. Monitor Subscription Changes Track subscription changes in your application to provide users with real-time updates. *** ## Example Integration ```javascript class SubscriptionManager { constructor(apiKey, baseUrl = 'https://api.market') { this.apiKey = apiKey; this.baseUrl = baseUrl; } async getProductDetails(workspaceSlug, productSlug) { const response = await fetch( `${this.baseUrl}/api/v1/product/${workspaceSlug}/${productSlug}`, { headers: { 'x-api-market-key': this.apiKey, 'accept': 'application/json' } } ); return response.json(); } async getCurrentSubscription(workspaceSlug, productSlug) { const response = await fetch( `${this.baseUrl}/api/v1/subscription/${workspaceSlug}/${productSlug}`, { headers: { 'x-api-market-key': this.apiKey, 'accept': 'application/json' } } ); return response.json(); } async createSubscription(workspaceSlug, productSlug, pricingPlanId, options = {}) { const response = await fetch( `${this.baseUrl}/api/v1/subscription/${workspaceSlug}/${productSlug}/${pricingPlanId}`, { method: 'POST', headers: { 'x-api-market-key': this.apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ isDryRun: options.dryRun || false, additionalData: options.additionalData || '' }) } ); return response.json(); } async cancelSubscription(workspaceSlug, productSlug, options = {}) { const response = await fetch( `${this.baseUrl}/api/v1/subscription/${workspaceSlug}/${productSlug}`, { method: 'DELETE', headers: { 'x-api-market-key': this.apiKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ cancelImmediately: options.immediate || false, reason: options.reason || '' }) } ); return response.json(); } } // Usage const manager = new SubscriptionManager('your-api-key'); // Get product details const product = await manager.getProductDetails('magicapi', 'upscaler'); // Check current subscription const subscription = await manager.getCurrentSubscription('magicapi', 'upscaler'); // Create new subscription const newSubscription = await manager.createSubscription( 'magicapi', 'upscaler', 'cltivivul000clc0crn8momz5', { dryRun: false } ); // Cancel subscription const cancelResult = await manager.cancelSubscription( 'magicapi', 'upscaler', { reason: 'No longer needed', immediate: false } ); ``` *** ## Support For technical support or questions about the Subscription Management API: * **Documentation**: [docs.api.market](https://docs.api.market) * **API Status**: [status.api.market](https://status.api.market) * **Support Email**: