Hi ${customerName},
\nManage your subscription:
\n Manage Subscription\nLink expires ${formatDate(response.tokenExpirationTime)}
\n`;\n```\n\n**SMS Notification:**\n```javascript\nconst { manageSubscriptionLink } = await getPortalLink(customerId);\nconst shortUrl = await shortenUrl(manageSubscriptionLink);\n\nawait sendSMS(customerPhone, \n `Your subscription ships tomorrow! Manage it here: ${shortUrl}`\n);\n```\n\n**Important Considerations:**\n\n**Token Expiration:**\n- Tokens expire after exactly 2 hours\n- Generate new token if expired\n- Don't store tokens long-term\n- Best practice: Generate on-demand\n\n**Domain Selection:**\n- Uses shop's `publicDomain` if configured\n- Falls back to Shopify domain (.myshopify.com)\n- Respects custom domain settings\n- Maintains brand consistency\n\n**Customer Lookup Errors:**\n- Email not found: Returns 400 error\n- Invalid customer ID: Returns error\n- No parameters provided: Returns 400\n- Both parameters provided: Uses customerId\n\n**Security Notes:**\n- Tokens cannot be used across different shops\n- Cannot be used for different customers\n- Tampering invalidates token\n- Consider rate limiting token generation\n\n**Best Practices:**\n\n1. **Generate On-Demand**: Create tokens when needed, not in advance\n2. **Use HTTPS**: Always serve links over HTTPS\n3. **Show Expiry**: Inform customers when link expires\n4. **URL Shortening**: Use URL shorteners for SMS/print materials\n5. **Track Usage**: Monitor which emails drive portal visits\n6. **Prefer Customer ID**: Use customerId when available for faster lookup\n\n**Comparison with /manage-subscription-link/{customerId}:**\n- This endpoint: Flexible lookup (ID or email)\n- Path parameter version: Customer ID only\n- Both generate identical tokens\n- Use this for email-based flows\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "getManageSubscriptionLinkv3", "parameters": [ { "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "customerId", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "in": "query", "name": "emailId", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "manageSubscriptionLink": "https://mystore.com/tools/recurring/customer_portal?token=eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21lcklkIjoxMjM0NSwic2hvcCI6Im15c3RvcmUubXlzaG9waWZ5LmNvbSIsInRpbWVzdGFtcCI6MTcwOTU2MjAwMH0.abc123xyz", "tokenExpirationTime": "2024-03-15T14:30:00Z" } } }, "schema": { "$ref": "#/components/schemas/TokenDetails" } } }, "description": "Successfully generated manage subscription link" }, "400": { "content": { "application/json": { "examples": { "Customer Not Found": { "description": "Customer Not Found", "value": { "detail": "Customer not found for the provided email: customer@example.com", "status": 400, "title": "Customer not found", "type": "https://example.com/errors/bad-request" } }, "Missing Parameters": { "description": "Missing Parameters", "value": { "detail": "Either customerId or emailId must be provided.", "status": 400, "title": "Missing required parameter", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Bad request - Missing parameters or customer not found" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "Customer does not belong to your shop", "status": 403, "title": "Access denied", "type": "https://example.com/errors/forbidden" } } }, "description": "Forbidden - Customer does not belong to authenticated shop" }, "500": { "content": { "application/json": { "example": { "detail": "Failed to generate customer portal token", "status": 500, "title": "Token generation failed", "type": "https://example.com/errors/internal-error" } } }, "description": "Internal server error" } }, "summary": "Generate customer portal access link by customer ID or email", "tags": [ "Customers", "Subscription Contracts" ] } }, "/api/external/v2/manage-subscription-link/{customerId}": { "get": { "description": "Generates a secure, time-limited link that allows customers to access their subscription management portal. This link provides customers with self-service capabilities to manage their subscriptions without requiring login credentials.\n\n**Key Features:**\n- Generates unique encrypted token for customer authentication\n- Token expires after 2 hours for security\n- Direct access to subscription management without password\n- Uses store's custom domain when available\n- Supports white-label customer portals\n\n**Token Security:**\n- Token contains encrypted customer ID, shop, and timestamp\n- Cannot be reused after expiration\n- Unique token generated for each request\n- Cryptographically secure encryption\n\n**Customer Portal Access:**\nOnce customers click the link, they can:\n- View all active subscriptions\n- Update payment methods\n- Change delivery addresses\n- Modify product quantities\n- Pause or cancel subscriptions\n- Update delivery schedules\n- Apply discount codes\n- View order history\n\n**Use Cases:**\n- Email campaigns with 'Manage Subscription' CTAs\n- Customer service providing quick access\n- Post-purchase email flows\n- Account management integrations\n- Reducing support ticket volume\n\n**URL Structure:**\nThe generated URL follows this pattern:\n`https://[store-domain]/[manage-subscription-path]?token=[encrypted-token]`\n\n**Important Notes:**\n- Links are single-use and expire after 2 hours\n- New link must be generated after expiration\n- Customer ID must be valid and active\n- Store must have customer portal configured\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "getManageSubscriptionLink", "parameters": [ { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Customer ID to generate portal link for. Provide the numeric ID without the gid:// prefix", "example": 987654321, "in": "path", "name": "customerId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "customerId": 987654321, "expiresInMinutes": 120, "manageSubscriptionLink": "https://store.example.com/pages/manage-subscriptions?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaG9wIjoic3RvcmUuZXhhbXBsZS5jb20iLCJjdXN0b21lcklkIjo5ODc2NTQzMjEsImNyZWF0ZWRBdCI6MTcxMDUxMjQwMDAwMH0.dGhpcyBpcyBhIHNhbXBsZSB0b2tlbiBmb3IgZG9jdW1lbnRhdGlvbg", "portalUrl": "https://store.example.com/pages/manage-subscriptions", "tokenExpirationTime": "2024-03-15T16:30:00.000Z" } } }, "schema": { "$ref": "#/components/schemas/TokenDetails" } } }, "description": "Manage subscription link successfully generated" }, "400": { "content": { "application/json": { "examples": { "Invalid Customer ID": { "description": "Invalid Customer ID", "value": { "detail": "Customer ID must be a positive number", "status": 400, "title": "Invalid customer ID", "type": "https://example.com/errors/bad-request" } }, "Portal Not Configured": { "description": "Portal Not Configured", "value": { "detail": "Store has not configured a manage subscriptions URL", "status": 400, "title": "Customer portal not configured", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to generate customer portal links", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "example": { "detail": "No customer found with ID 987654321", "status": 404, "title": "Customer not found", "type": "https://example.com/errors/not-found" } } }, "description": "Customer not found" }, "500": { "content": { "application/json": { "example": { "detail": "An error occurred while generating the secure token", "status": 500, "title": "Token generation failed", "type": "https://example.com/errors/internal-error" } } }, "description": "Internal server error" } }, "summary": "Generate customer portal link", "tags": [ "Customers", "Subscription Contracts" ] } }, "/api/external/v2/product-swaps": { "get": { "description": "Retrieves all configured product swap automations for the authenticated shop. Product swaps allow automatic replacement of products in subscription orders based on billing cycles or recurring schedules.\n\n**What are Product Swaps?**\nProduct swaps enable merchants to automatically replace products in subscription orders at specific billing cycles. This is useful for seasonal products, progression paths (e.g., beginner \u2192 intermediate \u2192 advanced), or variety subscriptions.\n\n**Key Features:**\n- View all configured swap automations\n- See source and destination product mappings\n- Check which billing cycles trigger swaps\n- Identify recurring vs one-time swaps\n- Review discount carry-forward settings\n\n**Swap Configuration Types:**\n- **One-Time Swap**: Occurs at a specific billing cycle\n- **Recurring Swap**: Occurs at every order\n- **Conditional Swap**: Based on billing cycle number\n\n**Use Cases:**\n- Seasonal product rotations (summer \u2192 fall \u2192 winter products)\n- Subscription progression (trial \u2192 full product)\n- Variety boxes with automatic product rotation\n- Product lifecycle management in subscriptions\n- A/B testing different products in subscriptions\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "getAllProductSwaps", "parameters": [ { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "ruleName", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "sourceVariants", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "destinationVariants", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": [ { "active": true, "carryDiscountForward": true, "checkForEveryRecurringOrder": false, "createdAt": "2024-01-15T10:30:00Z", "destinationVariants": "[{\"id\":67890,\"displayName\":\"Fall Blend Coffee\",\"imageSrc\":\"https://cdn.shopify.com/image2.jpg\",\"quantity\":2}]", "discountCarryForward": "PERCENTAGE", "forBillingCycle": 4, "id": 10782, "name": "Seasonal Coffee Rotation", "shop": "example-shop.myshopify.com", "sourceVariants": "[{\"id\":12345,\"displayName\":\"Summer Blend Coffee\",\"imageSrc\":\"https://cdn.shopify.com/image1.jpg\",\"quantity\":2}]", "stopSwapEmails": false, "updatedFirstOrder": false }, { "active": true, "carryDiscountForward": false, "checkForEveryRecurringOrder": true, "destinationVariants": "[{\"id\":33333,\"displayName\":\"Advanced Kit\",\"imageSrc\":\"https://cdn.shopify.com/kit2.jpg\",\"quantity\":1}]", "discountCarryForward": "NONE", "forBillingCycle": null, "id": 10783, "name": "Monthly Variety Swap", "shop": "example-shop.myshopify.com", "sourceVariants": "[{\"id\":22222,\"displayName\":\"Beginner Kit\",\"imageSrc\":\"https://cdn.shopify.com/kit1.jpg\",\"quantity\":1}]", "stopSwapEmails": true, "updatedFirstOrder": false } ] } }, "schema": { "$ref": "#/components/schemas/ProductSwapDTO" } } }, "description": "Successfully retrieved product swaps" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to view product swaps", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to view product swaps" } }, "summary": "Get all product swaps for a shop", "tags": [ "Product Catalog" ] }, "post": { "deprecated": true, "description": "Creates a new product swap automation rule for the authenticated shop. Product swaps automatically replace products in subscription orders based on billing cycles or recurring schedules.\n\n**Required Fields:**\n- **shop**: Your Shopify shop domain\n- **sourceVariants**: JSON string of variants to swap FROM (format: [{\"id\":12345,\"quantity\":2}])\n- **destinationVariants**: JSON string of variants to swap TO (format: [{\"id\":67890,\"quantity\":2}])\n- **name**: Descriptive name for this swap rule\n\n**Optional Fields:**\n- **forBillingCycle**: Specific cycle number when swap occurs (e.g., 4 = swap at 4th order). Leave null for recurring swaps.\n- **checkForEveryRecurringOrder**: If true, applies swap to every order (overrides forBillingCycle)\n- **updatedFirstOrder**: If true, can affect the first subscription order\n- **changeNextOrderDateBy**: Days to adjust next order date after swap (positive or negative integer)\n- **discountCarryForward**: How to handle discounts - NONE, PERCENTAGE, FIXED_AMOUNT, or PRICE\n- **carryDiscountForward**: Legacy boolean field (deprecated, use discountCarryForward instead)\n- **stopSwapEmails**: If true, suppresses customer notification emails about the swap\n- **ruleSequence**: Priority order when multiple swaps apply (lower number = higher priority)\n\n**Variant JSON Format:**\nThe API enriches your variant data with product details from Shopify. You only need to provide:\n```json\n[{\"id\": 12345, \"quantity\": 2}]\n```\nThe response will include enriched data: displayName, imageSrc, productTitle, etc.\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "createProductSwap", "parameters": [ { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "Request Example": { "description": "Request Example", "value": { "carryDiscountForward": false, "checkForEveryRecurringOrder": false, "destinationVariants": "[{\"id\":67890,\"quantity\":2}]", "discountCarryForward": "NONE", "forBillingCycle": 2, "name": "swap test", "shop": "example-shop", "sourceVariants": "[{\"id\":12345,\"quantity\":2}]", "stopSwapEmails": false, "updatedFirstOrder": false } } }, "schema": { "$ref": "#/components/schemas/ProductSwapDTO" } } }, "description": "ProductSwapDTO payload", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "carryDiscountForward": false, "changeNextOrderDateBy": null, "checkForEveryRecurringOrder": false, "destinationVariants": "[{\"id\":67890,\"displayName\":\"test-product\",\"imageSrc\":\"https://test.com/image.png\",\"quantity\":2}]", "discountCarryForward": "NONE", "forBillingCycle": 2, "id": 10782, "name": "swap test", "ruleSequence": 0, "shop": "example-shop", "sourceVariants": "[{\"id\":12345,\"displayName\":\"test-product\",\"imageSrc\":\"https://test.com/image.png\",\"quantity\":2}]", "stopSwapEmails": false, "updatedFirstOrder": false } } }, "schema": { "$ref": "#/components/schemas/ProductSwapDTO" } } }, "description": "Product swap created successfully" }, "400": { "content": { "application/json": { "examples": { "ID Exists": { "description": "ID Exists", "value": { "detail": "A new productSwap cannot already have an ID", "status": 400, "title": "A new productSwap cannot already have an ID", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request or product swap already has an ID" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to create product swaps", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to create product swap" }, "404": { "content": { "application/json": { "example": { "detail": "Resource not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "example": { "detail": "Cannot create product swap due to business rule violation", "status": 422, "title": "Business rule violation", "type": "https://example.com/errors/unprocessable-entity" } } }, "description": "Unprocessable entity - business rule violation" } }, "summary": "Create a new product swap automation", "tags": [ "Product Catalog" ] }, "put": { "deprecated": true, "description": "Updates an existing product swap automation rule for the authenticated shop. Use this endpoint to modify swap configurations, change source/destination products, adjust timing, or update discount handling.\n\n**Required Fields:**\n- **id**: The product swap ID to update\n- **shop**: Your Shopify shop domain (must match authenticated shop)\n\n**Updatable Fields:**\n- **sourceVariants**: JSON string of variants to swap FROM\n- **destinationVariants**: JSON string of variants to swap TO\n- **name**: Descriptive name for this swap rule\n- **forBillingCycle**: Specific cycle number when swap occurs (null for recurring)\n- **checkForEveryRecurringOrder**: If true, applies swap to every order\n- **updatedFirstOrder**: If true, can affect the first subscription order\n- **changeNextOrderDateBy**: Days to adjust next order date after swap\n- **discountCarryForward**: How to handle discounts (NONE, PERCENTAGE, FIXED_AMOUNT, PRICE)\n- **carryDiscountForward**: Legacy boolean field (use discountCarryForward instead)\n- **stopSwapEmails**: If true, suppresses customer notification emails\n- **ruleSequence**: Priority order (lower number = higher priority)\n\n**Impact of Updates:**\n- Changes apply to future orders immediately\n- Past orders and already-swapped products are not affected\n- If changing forBillingCycle, recalculates which subscriptions are affected\n- Variant data is automatically enriched from Shopify on update\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateProductSwap", "parameters": [ { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "Request Example": { "description": "Request Example", "value": { "carryDiscountForward": false, "checkForEveryRecurringOrder": false, "destinationVariants": "[{\"id\":67890,\"quantity\":2}]", "discountCarryForward": "NONE", "forBillingCycle": 2, "id": 10782, "name": "swap test", "shop": "example-shop", "sourceVariants": "[{\"id\":12345,\"quantity\":2}]", "stopSwapEmails": false, "updatedFirstOrder": false } } }, "schema": { "$ref": "#/components/schemas/ProductSwapDTO" } } }, "description": "ProductSwapDTO payload", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "carryDiscountForward": false, "changeNextOrderDateBy": null, "checkForEveryRecurringOrder": false, "destinationVariants": "[{\"id\":67890,\"displayName\":\"test-product\",\"imageSrc\":\"https://test.com/image.png\",\"quantity\":2}]", "discountCarryForward": "NONE", "forBillingCycle": 2, "id": 10782, "name": "swap test", "ruleSequence": 0, "shop": "example-shop", "sourceVariants": "[{\"id\":12345,\"displayName\":\"test-product\",\"imageSrc\":\"https://test.com/image.png\",\"quantity\":2}]", "stopSwapEmails": false, "updatedFirstOrder": false } } }, "schema": { "$ref": "#/components/schemas/ProductSwapDTO" } } }, "description": "Product swap updated successfully" }, "400": { "content": { "application/json": { "examples": { "ID Not Found": { "description": "ID Not Found", "value": { "detail": "Invalid id", "status": 400, "title": "Invalid id", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request or product swap not found" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to update product swaps", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to update product swap" }, "404": { "content": { "application/json": { "example": { "detail": "Resource not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Resource not found" }, "422": { "content": { "application/json": { "example": { "detail": "Cannot update product swap due to business rule violation", "status": 422, "title": "Business rule violation", "type": "https://example.com/errors/unprocessable-entity" } } }, "description": "Unprocessable entity - business rule violation" } }, "summary": "Update an existing product swap automation", "tags": [ "Product Catalog" ] } }, "/api/external/v2/product-swaps-by-variant-groups/{contractId}": { "post": { "description": "Retrieves product swap variant groups for the next 10 billing cycles of a specific subscription contract. This endpoint calculates and returns which products will be swapped to in future billing cycles based on configured swap automations.\n\n**Response Structure:**\nReturns a 2D array (`ListYou've received ${analytics.totalOrders} orders
\nTotal value: ${analytics.totalOrderRevenue}
\nNo shipment information available yet.
';\n}\n\nconst fulfillments = order.fulfillmentOrders?.edges || [];\nfulfillments.forEach(fo => {\n fo.node.fulfillments?.edges?.forEach(f => {\n const tracking = f.node.trackingInfo?.[0];\n if (tracking) {\n console.log(`Track with ${tracking.company}: ${tracking.number}`);\n console.log(`URL: ${tracking.url}`);\n }\n });\n});\n```\n\n**Best Practices:**\n\n1. **Cache Response**: Cache for 30-60 minutes to reduce Shopify API calls\n2. **Handle Nulls**: Always check for null/empty responses\n3. **Parse GraphQL**: Navigate edges/nodes structure carefully\n4. **Show All Tracking**: Display all fulfillments if multiple shipments\n5. **Link to Carrier**: Provide clickable tracking URLs\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "getSubscriptionFulfillmentsExternalV2", "parameters": [ { "description": "Contract ID", "in": "path", "name": "contractId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } }, "description": "Successfully retrieved fulfillment details (may be null if no orders exist)" }, "400": { "content": { "application/json": { "example": { "detail": "Contract ID must be a valid positive integer", "status": 400, "title": "Invalid contract ID", "type": "https://example.com/errors/bad-request" } } }, "description": "Bad request - Invalid contract ID" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "Contract does not belong to your shop", "status": 403, "title": "Access denied", "type": "https://example.com/errors/forbidden" } } }, "description": "Forbidden - Contract does not belong to authenticated shop" }, "502": { "content": { "application/json": { "example": { "detail": "Failed to retrieve fulfillment data from Shopify", "status": 502, "title": "Shopify API error", "type": "https://example.com/errors/bad-gateway" } } }, "description": "Bad gateway - Shopify API error" } }, "summary": "Get subscription fulfillment details for latest order", "tags": [ "Subscription Management", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contract-one-offs-by-contractId": { "get": { "description": "Retrieves all one-time products (add-ons) associated with a specific subscription contract across all billing attempts. One-time products are additional items that customers can add to their subscription orders on a non-recurring basis. Each one-time product is tied to a specific billing attempt and will only be included in that particular order.\n\n**Key Features:**\n- Returns ALL one-time products across all queued billing attempts\n- Each product includes the billing attempt ID to identify which order it belongs to\n- Includes product details: variant ID, quantity, title, image, and price\n- Products are automatically removed after the associated billing attempt is processed\n\n**Use Cases:**\n- Display all one-time products added to a subscription across all upcoming orders\n- Allow customers to review their one-time add-ons in customer portal\n- Enable merchants to see all one-time products for a contract\n- Integrate with external systems to manage subscription add-ons\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "getOneOffsForSubscriptionContractV2", "parameters": [ { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "example": "apst_your-api-key-here", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication. This key identifies your shop and must be included in the X-API-Key header.", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the subscription contract to retrieve one-time products for", "example": 98765, "in": "query", "name": "contractId", "required": true, "schema": { "description": "Must be a valid contract ID that belongs to the authenticated shop", "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": [ { "billingAttemptId": 11111, "contractId": 67890, "createdAt": "2024-01-15T10:30:00Z", "currencyCode": "USD", "id": 12345, "image": "https://cdn.shopify.com/s/files/1/0000/0000/products/filter.jpg", "price": "9.99", "productTitle": "Coffee Filters - Pack of 100", "quantity": 2, "shop": "example-shop.myshopify.com", "updatedAt": "2024-01-15T10:30:00Z", "variantId": 22222, "variantTitle": "Standard Size" }, { "billingAttemptId": 11112, "contractId": 67890, "createdAt": "2024-01-16T14:20:00Z", "currencyCode": "USD", "id": 12346, "image": "https://cdn.shopify.com/s/files/1/0000/0000/products/scoop.jpg", "price": "14.99", "productTitle": "Coffee Scoop", "quantity": 1, "shop": "example-shop.myshopify.com", "updatedAt": "2024-01-16T14:20:00Z", "variantId": 33333, "variantTitle": "Stainless Steel" } ] } }, "schema": { "items": { "$ref": "#/components/schemas/SubscriptionContractOneOffDTO" }, "type": "array" } } }, "description": "Successfully retrieved one-time products" }, "400": { "content": { "application/json": { "example": { "detail": "Contract does not belong to this shop", "status": 400, "title": "Invalid contract", "type": "https://example.com/errors/bad-request" } } }, "description": "Invalid contract ID or contract doesn't belong to authenticated shop" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to view one-time products", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to view one-time products" } }, "summary": "Get all one-time products for a subscription contract", "tags": [ "Subscription One-Time Products", "Product Catalog" ] } }, "/api/external/v2/subscription-contract-one-offs-by-contractId-and-billing-attempt-id": { "delete": { "description": "Removes a previously added one-time product from a specific subscription order. This permanently deletes the one-time product from the specified billing attempt. The operation is idempotent - attempting to delete a non-existent product will succeed without error.\n\n**Important Notes:**\n- Only removes the product from the specified billing attempt\n- Cannot remove products from billing attempts that are already processed\n- Activity logs are created for audit trails\n- Returns the updated list of all one-time products for the contract\n\n**Use Cases:**\n- Allow customers to remove unwanted add-ons before order processing\n- Clean up cart-like functionality in customer portals\n- Programmatically manage one-time product selections\n- Implement \"undo\" functionality for product additions\n\n**Business Rules:**\n- Contract must belong to the authenticated shop\n- The specific combination of contractId + billingAttemptId + variantId identifies the product to remove\n- No error is thrown if the product doesn't exist (idempotent operation)\n\n**Authentication:** Requires valid X-API-Key header that identifies the shop", "operationId": "deleteOneOffByV2", "parameters": [ { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "example": "apst_your-api-key-here", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication. This key identifies your shop and must be included in the X-API-Key header.", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the subscription contract", "example": 98765, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "The billing attempt ID that contains the product to remove", "example": 54321, "in": "query", "name": "billingAttemptId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "The Shopify product variant ID to remove from the one-time purchases", "example": 42549172011164, "in": "query", "name": "variantId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "All Products Removed": { "description": "Last one-time product was removed. Contract now has no one-time products.", "value": [] }, "Multiple Products Remain": { "description": "One product removed, multiple products remain across different billing attempts", "value": [ { "billingAttemptId": 54321, "id": 12347, "price": 14.99, "quantity": 1, "shop": "example-store.myshopify.com", "subscriptionContractId": 98765, "variantHandle": "seasonal-blend-250g", "variantId": 42549172011166 }, { "billingAttemptId": 54322, "id": 12348, "price": 39.99, "quantity": 1, "shop": "example-store.myshopify.com", "subscriptionContractId": 98765, "variantHandle": "coffee-grinder-manual", "variantId": 42549172011167 } ] }, "Product Didn't Exist": { "description": "Attempted to remove non-existent product. Operation succeeds, returns existing products.", "value": [ { "billingAttemptId": 54322, "id": 12346, "price": 8.99, "quantity": 1, "shop": "example-store.myshopify.com", "subscriptionContractId": 98765, "variantHandle": "coffee-filters-pack-100", "variantId": 42549172011165 } ] }, "Product Removed Successfully": { "description": "Product was removed. Response shows remaining one-time products.", "value": [ { "billingAttemptId": 54321, "id": 12345, "price": 19.99, "quantity": 2, "shop": "example-store.myshopify.com", "subscriptionContractId": 98765, "variantHandle": "premium-coffee-blend-500g", "variantId": 42549172011164 } ] } }, "schema": { "items": { "$ref": "#/components/schemas/SubscriptionContractOneOffDTO" }, "type": "array" } } }, "description": "Successfully removed the one-time product or product didn't exist. Returns all remaining one-time products for the contract." }, "400": { "content": { "application/json": { "examples": { "Invalid Parameter Format": { "description": "Invalid Parameter Format", "value": { "detail": "Failed to convert value of type 'java.lang.String' to required type 'java.lang.Long'; For input string: 'invalid'", "status": 400, "title": "Bad Request", "type": "https://example.com/probs/bad-request" } }, "Missing Required Parameter": { "description": "Missing Required Parameter", "value": { "detail": "Required request parameter 'variantId' for method parameter type Long is not present", "status": 400, "title": "Bad Request", "type": "https://example.com/probs/bad-request" } } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Invalid request parameters" }, "401": { "content": { "application/json": { "example": { "detail": "Full authentication is required to access this resource", "status": 401, "title": "Unauthorized", "type": "https://example.com/probs/unauthorized" }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "Access denied - contract does not belong to authenticated shop", "status": 403, "title": "Forbidden", "type": "https://example.com/probs/forbidden" }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Forbidden - contract belongs to different shop or insufficient permissions" } }, "summary": "Remove one-time product from subscription order", "tags": [ "Subscription One-Time Products" ] }, "put": { "deprecated": true, "description": "**Discontinued.** One-time products are no longer applied to the generated order or cleaned up afterward \u2014 this endpoint now always returns 400 and creates nothing. Do not build new integrations against it.", "operationId": "saveOneOffByV2", "parameters": [ { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "example": "apst_your-api-key-here", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication. This key identifies your shop and must be included in the X-API-Key header.", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the subscription contract", "example": 98765, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "The billing attempt ID to add the product to. If invalid or not QUEUED, the system will automatically use the next upcoming order.", "example": 54321, "in": "query", "name": "billingAttemptId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "The Shopify product variant ID to add as a one-time purchase", "example": 42549172011164, "in": "query", "name": "variantId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "The handle/slug of the product variant for URL-friendly identification", "example": "premium-coffee-blend-500g", "in": "query", "name": "variantHandle", "required": true, "schema": { "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "type": "string" } }, { "description": "The quantity of the product to add. Defaults to 1 if not specified.", "example": 2, "in": "query", "name": "quantity", "required": false, "schema": { "default": 1, "maximum": 999, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "First Product Added": { "description": "First one-time product added to this contract", "value": [ { "billingAttemptId": 54321, "id": 12351, "price": 34.99, "quantity": 3, "shop": "example-store.myshopify.com", "subscriptionContractId": 98765, "variantHandle": "limited-edition-roast", "variantId": 42549172011168 } ] }, "Product Added Successfully": { "description": "New product added to the list. Response includes all one-time products for the contract.", "value": [ { "billingAttemptId": 54321, "id": 12345, "price": 19.99, "quantity": 2, "shop": "example-store.myshopify.com", "subscriptionContractId": 98765, "variantHandle": "premium-coffee-blend-500g", "variantId": 42549172011164 }, { "billingAttemptId": 54321, "id": 12350, "price": 29.99, "quantity": 1, "shop": "example-store.myshopify.com", "subscriptionContractId": 98765, "variantHandle": "coffee-sampler-pack", "variantId": 42549172011167 } ] }, "Product Already Exists": { "description": "Product already exists in the billing attempt. No duplicate created. Returns existing list.", "value": [ { "billingAttemptId": 54321, "id": 12345, "price": 19.99, "quantity": 2, "shop": "example-store.myshopify.com", "subscriptionContractId": 98765, "variantHandle": "premium-coffee-blend-500g", "variantId": 42549172011164 } ] } }, "schema": { "items": { "$ref": "#/components/schemas/SubscriptionContractOneOffDTO" }, "type": "array" } } }, "description": "Successfully added one-time product or product already exists. Returns all one-time products for the contract." }, "400": { "content": { "application/json": { "examples": { "Contract Frozen": { "description": "Contract has minimum cycle requirements that prevent modifications", "value": { "detail": "Order modifications are frozen until minimum cycle requirements are met", "status": 400, "title": "Bad Request", "type": "https://example.com/probs/bad-request", "violations": { "field": "contractId", "message": "frozen_until_min_cycles" } } }, "Invalid Parameter Format": { "description": "Invalid Parameter Format", "value": { "detail": "Failed to convert value of type 'java.lang.String' to required type 'java.lang.Integer'; For input string: 'abc'", "status": 400, "title": "Bad Request", "type": "https://example.com/probs/bad-request" } }, "Missing Required Parameter": { "description": "Missing Required Parameter", "value": { "detail": "Required request parameter 'variantId' for method parameter type Long is not present", "status": 400, "title": "Bad Request", "type": "https://example.com/probs/bad-request" } }, "No Upcoming Orders": { "description": "No QUEUED billing attempts exist for this contract", "value": { "detail": "There is no upcoming order scheduled.", "status": 400, "title": "Bad Request", "type": "https://example.com/probs/bad-request", "violations": { "field": "data", "message": "idnull" } } } }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Bad request - validation failed or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Full authentication is required to access this resource", "status": 401, "title": "Unauthorized", "type": "https://example.com/probs/unauthorized" }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "Access denied - contract does not belong to authenticated shop", "status": 403, "title": "Forbidden", "type": "https://example.com/probs/forbidden" }, "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Forbidden - contract belongs to different shop or insufficient permissions" } }, "summary": "Add one-time product to subscription order", "tags": [ "Subscription One-Time Products" ] } }, "/api/external/v2/subscription-contracts-add-discount": { "put": { "description": "Creates and applies a custom manual discount to an existing subscription contract. This powerful endpoint supports multiple discount types and configurations for flexible pricing strategies.\n\n**Discount Types:**\n- **PERCENTAGE**: Percentage off the order (e.g., 10% off)\n- **FIXED**: Fixed amount off the order (e.g., $10 off)\n- **PRICE**: Override price (sets total to specific amount)\n\n**Key Features:**\n- Custom discount titles for easy identification\n- Cycle limits for time-bound promotions\n- Per-item or subtotal application options\n- Stacks with other discounts per Shopify rules\n- Automatic shipping price recalculation\n- Activity logging for audit trails\n\n**Application Methods:**\n- **Subtotal Discount** (appliesOnEachItem=false): Applied to order total after line item calculations\n- **Per-Item Discount** (appliesOnEachItem=true): Applied to each line item individually\n\n**Cycle Limits:**\n- Set recurringCycleLimit to apply discount for specific number of orders\n- Leave null for unlimited duration\n- Useful for '3 months at 20% off' promotions\n\n**Retention Campaigns:**\nThis endpoint integrates with cancellation retention workflows:\n- Can trigger merchant notifications\n- Tracks discount usage for retention analytics\n- Helps prevent churn with targeted offers\n\n**Important Notes:**\n- Discounts apply to future orders only\n- Cannot modify discounts once applied (must remove and re-add)\n- Some discount combinations may not be allowed by Shopify\n- Price overrides should be used carefully\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "addDiscountV2", "parameters": [ { "description": "Subscription contract ID to apply discount to. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Discount percentage (1-100). Required when discountType is PERCENTAGE", "example": 10, "in": "query", "name": "percentage", "required": false, "schema": { "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Custom title for the discount. If not provided, a default title will be generated", "example": "Loyalty Discount", "in": "query", "name": "discountTitle", "required": false, "schema": { "maxLength": 255, "type": "string" } }, { "description": "Number of billing cycles the discount applies to. Leave null for unlimited duration", "example": 3, "in": "query", "name": "recurringCycleLimit", "required": false, "schema": { "maximum": 9999, "minimum": 1, "type": "integer" } }, { "description": "Application method: true = apply to each line item individually, false = apply to order subtotal", "example": false, "in": "query", "name": "appliesOnEachItem", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Fixed discount amount in store currency. Required when discountType is FIXED or PRICE", "example": 10.99, "in": "query", "name": "amount", "required": false, "schema": { "format": "double", "maximum": 999999.99, "minimum": 0.01, "type": "number" } }, { "description": "Type of discount to apply", "example": "PERCENTAGE", "in": "query", "name": "discountType", "required": false, "schema": { "enum": [ "PERCENTAGE", "FIXED", "PRICE" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "customer": { "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "discounts": { "edges": [ { "node": { "id": "gid://shopify/SubscriptionManualDiscount/555555", "recurringCycleLimit": 3, "targetType": "ALL_LINES", "title": "Loyalty Discount", "type": "MANUAL", "value": { "percentage": 10.0 } } } ] }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "29.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "quantity": 1, "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "nextBillingDate": "2024-04-01T12:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Discount successfully added" }, "400": { "content": { "application/json": { "examples": { "Invalid Cycle Limit": { "description": "Invalid Cycle Limit", "value": { "detail": "Recurring cycle limit must be a positive integer", "status": 400, "title": "Invalid cycle limit", "type": "https://example.com/errors/bad-request" } }, "Invalid Discount Type": { "description": "Invalid Discount Type", "value": { "detail": "Discount type must be one of: PERCENTAGE, FIXED, PRICE", "status": 400, "title": "Invalid discount type", "type": "https://example.com/errors/bad-request" } }, "Invalid Percentage Value": { "description": "Invalid Percentage Value", "value": { "detail": "Percentage must be between 1 and 100", "status": 400, "title": "Invalid percentage value", "type": "https://example.com/errors/bad-request" } }, "Missing Required Parameter": { "description": "Missing Required Parameter", "value": { "detail": "Percentage is required when discountType is PERCENTAGE", "status": 400, "title": "Invalid discount parameters", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid parameters for discount creation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to modify subscription" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Conflicting Discounts": { "description": "Conflicting Discounts", "value": { "detail": "This discount cannot be combined with existing discounts on the subscription", "status": 422, "title": "Discount conflict", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Cannot modify subscription during active billing attempt", "status": 422, "title": "Unable to apply discount", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Discount parameters valid but cannot be applied" } }, "summary": "Add custom discount to subscription", "tags": [ "Subscription Contracts", "Subscription Discounts" ] } }, "/api/external/v2/subscription-contracts-add-line-item": { "put": { "description": "Adds a new product line item to an existing subscription contract. Can add either recurring products that will appear in each order or one-time products that appear only in the next order.\n\n**Key Features:**\n- Supports both recurring and one-time product additions\n- Automatically applies appropriate pricing policies based on discount carry-forward settings\n- Handles duplicate products by updating quantity (if enabled) or adding as new line\n- Calculates prices based on billing/delivery frequency multipliers\n- Sends email notifications to customers (unless suppressed)\n- Creates activity logs for audit trail\n\n**Pricing Policy Application:**\nThe system applies discounts based on the store's discount carry-forward setting:\n- **PRODUCT_PLAN**: Uses the discount from the product's selling plan\n- **EXISTING_PLAN**: Applies the discount structure from existing subscription items\n- **PRODUCT_THEN_EXISTING**: First attempts product plan, falls back to existing if not found\n\n**One-Time Products:**\nProducts added with `isOneTimeProduct=true` will:\n- Only appear in the next scheduled order\n- Be removed automatically after the next order bills successfully\n- Still attempt to match with appropriate selling plans\n- Can have subscription discounts applied if store setting allows\n\n**Duplicate Product Handling:**\nWhen adding a product that already exists in the subscription:\n- If store has 'updateExistingQuantityOnAddProduct' enabled and product is not one-time: Updates existing quantity\n- Otherwise: Adds as a new line item\n\n**Price Calculation:**\n- Base price is fetched considering contract currency and delivery country\n- Price is multiplied by fulfillment frequency ratio (billing interval / delivery interval)\n- Example: Monthly billing with weekly delivery = price \u00d7 4\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "addLineItemV2", "parameters": [ { "description": "Subscription contract ID to add product to. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Quantity of product to add. Must be a positive integer", "example": 2, "in": "query", "name": "quantity", "required": true, "schema": { "maximum": 999, "minimum": 1, "type": "integer" } }, { "description": "Shopify variant ID of the product to add. Can be provided as numeric ID or with gid:// prefix", "example": 42549172011164, "in": "query", "name": "variantId", "required": true, "schema": { "pattern": "^([0-9]+|gid://shopify/ProductVariant/[0-9]+)$", "type": "string" } }, { "description": "When true, product will only be included in the next order and automatically removed after that order bills successfully. When false, product will be included in all future orders until manually removed or subscription ends. One-time products are useful for samples, gifts, or limited-time additions", "example": false, "in": "query", "name": "isOneTimeProduct", "required": false, "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "billingPolicy": { "interval": "MONTH", "intervalCount": 1 }, "customer": { "email": "customer@example.com", "firstName": "John", "id": "gid://shopify/Customer/987654321", "lastName": "Doe" }, "deliveryPolicy": { "interval": "MONTH", "intervalCount": 1 }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "29.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "quantity": 2, "sellingPlanId": "gid://shopify/SellingPlan/123456", "sellingPlanName": "Deliver every month", "variantId": "gid://shopify/ProductVariant/42549172011164" } }, { "node": { "currentPrice": { "amount": "19.99", "currencyCode": "USD" }, "customAttributes": [ { "key": "_one_time_product", "value": "true" } ], "id": "gid://shopify/SubscriptionLine/222222", "quantity": 1, "variantId": "gid://shopify/ProductVariant/98765432101" } } ] }, "nextBillingDate": "2024-03-01T00:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Product successfully added to subscription" }, "400": { "content": { "application/json": { "examples": { "Build-a-Box Validation Error": { "description": "Build-a-Box Validation Error", "value": { "detail": "Adding this quantity would exceed the maximum allowed items for this build-a-box subscription", "status": 400, "title": "UserGeneratedError:Build-a-box quantity limit exceeded", "type": "https://example.com/errors/bad-request" } }, "Invalid Contract ID": { "description": "Invalid Contract ID", "value": { "detail": "No subscription contract found with ID: 123456789", "status": 400, "title": "UserGeneratedError:Subscription contract not found", "type": "https://example.com/errors/bad-request" } }, "Invalid Quantity": { "description": "Invalid Quantity", "value": { "detail": "Quantity must be greater than 0", "status": 400, "title": "UserGeneratedError:Invalid quantity", "type": "https://example.com/errors/bad-request" } }, "Product Variant Not Found": { "description": "Product Variant Not Found", "value": { "detail": "The specified product variant does not exist in the store", "status": 400, "title": "Product Variant not found for ID: 99999999999", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to modify subscription" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Draft Commit Error": { "description": "Draft Commit Error", "value": { "detail": "Unable to commit subscription changes: Billing attempt in progress", "status": 422, "title": "subscriptionDraftCommitError", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify GraphQL Error": { "description": "Shopify GraphQL Error", "value": { "detail": "Shopify API error: Product is not available for subscription", "status": 422, "title": "subscriptionDraftLineAddError", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Unable to process the request due to Shopify API constraints" } }, "summary": "Add product to subscription", "tags": [ "Subscription Products", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-add-line-items": { "put": { "description": "Adds multiple product line items to an existing subscription contract in a single request. This batch operation is more efficient than making multiple individual requests and ensures all products are added with consistent processing.\n\n**Key Features:**\n- Batch addition of multiple products in one API call\n- All products are added as recurring items (not one-time)\n- Automatic quantity defaulting (0 or null becomes 1)\n- Sequential processing with full validation for each item\n- Returns final subscription state after all additions\n- Same pricing and discount logic as single-item endpoint\n\n**Processing Behavior:**\n- Products are added sequentially, not in parallel\n- If any product fails, previous additions remain\n- Each product goes through full validation\n- Existing product handling follows store settings\n- Activity logs created for each product added\n\n**Duplicate Product Handling:**\nIf a product already exists in the subscription:\n- With 'updateExistingQuantityOnAddProduct' enabled: Updates quantity\n- Without setting: Adds as new line item\n- Setting applies to all products in the batch\n\n**Pricing and Discounts:**\nEach product receives:\n- Appropriate selling plan assignment\n- Discount carry-forward based on store settings\n- Currency and country-specific pricing\n- Fulfillment frequency multiplier application\n\n**Build-a-Box Validation:**\n- Applied if any product has _bb_id attribute\n- Validates total quantity after all additions\n- May fail entire batch if limits exceeded\n\n**Post-Processing:**\nAfter all products are added:\n- Build-a-Box discounts recalculated once\n- Product discounts synchronized\n- Single email notification sent\n- Shipping price updated once\n\n**Important Notes:**\n- Maximum recommended batch size: 10-20 products\n- Larger batches may timeout\n- All products become recurring items\n- Use single-item endpoint for one-time products\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "addLineItems", "parameters": [ { "description": "Subscription contract ID to add products to. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "Add Three Products": { "description": "Add Three Products", "value": { "42549172011164": 1, "42549172043932": 2, "42549172076700": 1 } }, "Build-a-Box Bundle": { "description": "Build-a-Box Bundle", "value": { "42549172011164": 2, "42549172043932": 2, "42549172076700": 2, "42549172109468": 1, "42549172142236": 1 } }, "With Default Quantities": { "description": "With Default Quantities", "value": { "42549172011164": 0, "42549172043932": null, "42549172076700": 3 } } }, "schema": { "type": "string" } } }, "description": "Map of variant IDs to quantities. Keys are variant IDs (numeric only, no gid:// prefix), values are quantities to add. Null or 0 quantities default to 1.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "billingPolicy": { "interval": "MONTH", "intervalCount": 1 }, "customer": { "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "deliveryPolicy": { "interval": "MONTH", "intervalCount": 1 }, "discounts": { "edges": [ { "node": { "id": "gid://shopify/SubscriptionManualDiscount/444444", "targetType": "ALL_LINES", "title": "BUILD_A_BOX_DISCOUNT_ABC123", "value": { "percentage": 20.0 } } } ] }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "59.98", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "quantity": 2, "sellingPlanId": "gid://shopify/SellingPlan/123456", "sellingPlanName": "Deliver every month", "title": "Premium Coffee - Dark Roast", "variantId": "gid://shopify/ProductVariant/42549172011164" } }, { "node": { "currentPrice": { "amount": "24.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/222222", "quantity": 1, "sellingPlanId": "gid://shopify/SellingPlan/123456", "sellingPlanName": "Deliver every month", "title": "Organic Tea - Green", "variantId": "gid://shopify/ProductVariant/42549172043932" } }, { "node": { "currentPrice": { "amount": "19.98", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/333333", "quantity": 2, "sellingPlanId": "gid://shopify/SellingPlan/123456", "sellingPlanName": "Deliver every month", "title": "Coffee Filters - 100 pack", "variantId": "gid://shopify/ProductVariant/42549172076700" } } ] }, "nextBillingDate": "2024-04-01T12:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Products successfully added to subscription" }, "400": { "content": { "application/json": { "examples": { "Build-a-Box Maximum Exceeded": { "description": "Build-a-Box Maximum Exceeded", "value": { "detail": "Adding these products would exceed Build-a-Box limits", "status": 400, "title": "UserGeneratedError:Maximum 12 quantity is required", "type": "https://example.com/errors/bad-request" } }, "Empty Request Body": { "description": "Empty Request Body", "value": { "detail": "Request body must contain at least one variant ID and quantity", "status": 400, "title": "Invalid request body", "type": "https://example.com/errors/bad-request" } }, "Invalid Quantity": { "description": "Invalid Quantity", "value": { "detail": "Quantities must be positive integers", "status": 400, "title": "Invalid quantity value", "type": "https://example.com/errors/bad-request" } }, "Invalid Variant ID": { "description": "Invalid Variant ID", "value": { "detail": "One or more product variants do not exist", "status": 400, "title": "Product Variant not found for ID: 99999999999", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to modify subscription" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Partial Success Warning": { "description": "Partial Success Warning", "value": { "addedVariants": [ "42549172011164", "42549172043932" ], "detail": "Some products were added successfully, but others failed", "failedVariants": [ { "error": "No selling plan available", "variantId": "42549172076700" } ], "status": 422, "title": "Partial success", "type": "https://example.com/errors/unprocessable-entity" } }, "Product Not Available for Subscription": { "description": "Product Not Available for Subscription", "value": { "detail": "One or more products are not configured for subscription sales", "status": 422, "title": "UserGeneratedError:Product is not available for subscription", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "One or more products cannot be added due to Shopify constraints" } }, "summary": "Add multiple products to subscription", "tags": [ "Subscription Products", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-apply-discount": { "put": { "description": "Applies a Shopify discount code to an existing subscription contract. The discount will be applied to future orders generated by this subscription.\n\n**Key Features:**\n- Validates discount code through Shopify's discount system\n- Prevents duplicate discount code applications\n- Uses database locking to prevent race conditions\n- Automatically recalculates shipping prices if needed\n- Creates audit trail through activity logs\n- Returns updated subscription with discount details\n\n**Discount Code Validation:**\n- Must be an active Shopify discount code in the store\n- Must be applicable to subscription orders\n- Cannot be applied if already active on the subscription\n- Subject to Shopify's discount rules and restrictions\n\n**Customer Portal Restrictions:**\nWhen called from customer portal context:\n- If 'enableAllowOnlyOneDiscountCode' is enabled, customers cannot apply additional codes\n- This restriction ensures single discount policy enforcement\n- External API calls bypass this restriction\n\n**Concurrency Protection:**\n- Uses database-level locking on the subscription contract\n- Prevents simultaneous discount applications\n- Ensures data consistency in high-traffic scenarios\n\n**Post-Application Effects:**\n- Discount applies to all future orders from the subscription\n- May trigger shipping price recalculation\n- Creates 'DISCOUNT_APPLIED' activity log entry\n- Updates subscription's discount collection\n\n**Important Notes:**\n- Discount codes are case-sensitive\n- Invalid or expired codes will return appropriate errors\n- Discounts stack according to Shopify's combination rules\n- Some discounts may not be compatible with subscriptions\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "applyDiscountCodeV2", "parameters": [ { "description": "Subscription contract ID to apply discount to. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Valid Shopify discount code to apply. Case-sensitive. Must be an active discount code in your Shopify store.", "example": "SAVE10", "in": "query", "name": "discountCode", "required": true, "schema": { "maxLength": 255, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "customer": { "email": "customer@example.com", "firstName": "John", "id": "gid://shopify/Customer/987654321", "lastName": "Doe" }, "discounts": { "edges": [ { "node": { "id": "gid://shopify/SubscriptionManualDiscount/888888", "targetType": "ALL_LINES", "title": "SAVE10", "value": { "percentage": 10.0 } } } ] }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "29.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "quantity": 2, "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "nextBillingDate": "2024-03-01T00:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Discount code successfully applied" }, "400": { "content": { "application/json": { "examples": { "Discount Already Applied": { "description": "Discount Already Applied", "value": { "detail": "The discount code SAVE10 is already active on this subscription", "status": 400, "title": "UserGeneratedError:Discount is already applied", "type": "https://example.com/errors/bad-request" } }, "Discount Not Applicable": { "description": "Discount Not Applicable", "value": { "detail": "This discount code is not configured for subscription orders", "status": 400, "title": "UserGeneratedError:Discount cannot be applied to subscriptions", "type": "https://example.com/errors/bad-request" } }, "Empty Discount Code": { "description": "Empty Discount Code", "value": { "detail": "Discount code cannot be empty", "status": 400, "title": "Invalid discount code", "type": "https://example.com/errors/bad-request" } }, "Invalid Discount Code": { "description": "Invalid Discount Code", "value": { "detail": "The discount code INVALID123 does not exist or has expired", "status": 400, "title": "UserGeneratedError:Discount code is invalid", "type": "https://example.com/errors/bad-request" } }, "Multiple Discounts Not Allowed": { "description": "Multiple Discounts Not Allowed", "value": { "detail": "Only one discount code is allowed per subscription", "status": 400, "title": "UserGeneratedError:Permission denied, Subscription cannot be modified", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to modify subscription" }, "404": { "content": { "application/json": { "example": { "detail": "No subscription contract found with ID 123456789", "status": 404, "title": "Subscription contract not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "409": { "content": { "application/json": { "example": { "detail": "Another operation is currently modifying this subscription. Please try again.", "status": 409, "title": "Subscription is being modified", "type": "https://example.com/errors/conflict" } } }, "description": "Concurrent modification conflict" }, "422": { "content": { "application/json": { "examples": { "Draft Commit Error": { "description": "Draft Commit Error", "value": { "detail": "Cannot modify subscription during active billing attempt", "status": 422, "title": "UserGeneratedError:Unable to commit subscription changes", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Discount code minimum purchase requirement not met", "status": 422, "title": "Unable to apply discount code", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Discount code exists but cannot be applied due to Shopify constraints" } }, "summary": "Apply discount code to subscription", "tags": [ "Subscription Contracts", "Subscription Discounts" ] } }, "/api/external/v2/subscription-contracts-bulk-update-line-item-attributes": { "put": { "description": "This API replaces all existing attributes for the specified line items within subscription contracts. Use carefully, as any attributes not included in the request will be removed.", "operationId": "updateMultipleContractsLineItemAttributesV2", "parameters": [ { "description": "API Key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Optional comma-separated list of subscription contract IDs to update. Example: 32665403611,3266540311,326654036123. Ignored if allSubscriptions=true.", "in": "query", "name": "contractIds", "required": false, "schema": { "type": "string" } }, { "description": "If true, updates all active subscriptions of the shop. If false (default), updates only the provided contractId or contractIds.", "in": "query", "name": "allSubscriptions", "required": false, "schema": { "default": false, "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "examples": { "Attributes Example": { "description": "Attributes Example", "value": [ { "key": "color", "value": "red" }, { "key": "size", "value": "M" } ] } }, "schema": { "items": { "$ref": "#/components/schemas/AttributeInfo" }, "type": "array" } } }, "description": "A JSON array of attributes. \u26a0\ufe0f Note: Providing this array will replace all existing attributes in the specified contract. Add or update attributes carefully, as any attributes not included in the request will be removed." }, "responses": { "200": { "content": { "*/*": { "schema": { "type": "string" } } }, "description": "OK" } }, "summary": "Replace all line item attributes in bulk across subscription contracts", "tags": [ "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-email-magic-link": { "get": { "description": "Sends an automated email to a customer containing a secure magic link for accessing their subscription management portal. The email is sent using the shop's configured email template and includes a time-limited authentication token.\n\n**What This Endpoint Does:**\n1. Validates customer exists and has subscriptions\n2. Generates secure portal access token\n3. Retrieves shop's email template configuration\n4. Sends personalized email with magic link\n5. Logs activity for audit trail\n\n**Magic Link Functionality:**\n\n**What is a Magic Link?**\nA magic link is a special URL containing an encrypted authentication token that allows customers to access their portal without entering a password. Clicking the link automatically logs them in.\n\n**Link Contents:**\n- Shop's portal URL\n- Encrypted customer token (2-hour expiration)\n- Direct access to subscription management\n- No password required\n\n**Security:**\n- Token expires in 2 hours\n- Single customer authentication\n- Cannot be used by others\n- Logged for security audit\n\n**Request Parameters:**\n\n**email (required):**\n- Customer's email address\n- Must exactly match email in Shopify\n- Customer must have at least one subscription\n- Case-sensitive in some systems\n\n**Email Template Configuration:**\n\n**Template Requirements:**\n- Email template must be configured in Appstle settings\n- Template type: SUBSCRIPTION_MANAGEMENT_LINK\n- Template must not be disabled\n- Template includes shop branding and customization\n\n**Email Content:**\n- Personalized greeting with customer name\n- Clickable magic link button/link\n- Expiration notice (link valid 2 hours)\n- Shop branding and footer\n- Optional custom messaging\n\n**Template Variables:**\n- `{customer_name}`: Customer's display name\n- `{magic_link}`: Portal URL with token\n- `{shop_name}`: Store name\n- `{expiration_time}`: Token expiry time\n\n**Use Cases:**\n\n**1. Customer Self-Service:**\n- \"Forgot password\" alternative\n- Quick portal access without account setup\n- Passwordless authentication flow\n- Reduce friction for customers\n\n**2. Subscription Management Prompts:**\n- \"Manage your subscription\" emails\n- Pre-billing reminders with management link\n- Post-purchase subscription setup\n- Re-engagement campaigns\n\n**3. Customer Support:**\n- Send portal access to customers\n- Enable self-service during support interactions\n- Provide instant portal access\n- Reduce support workload\n\n**4. Automated Workflows:**\n- Payment failure recovery emails\n- Subscription expiration notices\n- Pause/skip reminders\n- Renewal notifications\n\n**5. Marketing Campaigns:**\n- Subscription feature announcements\n- New product availability\n- Loyalty program invitations\n- Referral program links\n\n**Process Flow:**\n\n```\n1. API receives email parameter\n2. Searches subscription database for customer email\n3. If not found \u2192 Returns 400 error\n4. If found \u2192 Retrieves customer subscriptions\n5. Sorts subscriptions by status (active first)\n6. Checks email template configuration\n7. If disabled \u2192 Returns 400 error with instructions\n8. If enabled \u2192 Generates magic link token\n9. Prepares email with template\n10. Sends email via configured provider\n11. Logs activity (source: MERCHANT_EXTERNAL_API)\n12. Returns success message\n```\n\n**Response Format:**\n```json\n\"Email triggered successfully.\"\n```\n\n**Simple string response** confirming email queued for delivery.\n\n**Important Considerations:**\n\n**Customer Validation:**\n- Email MUST exist in subscription database\n- Customer MUST have at least one subscription\n- Customers without subscriptions cannot receive link\n- Returns error if customer not found\n\n**Email Template Disabled:**\n- If template disabled in settings: Returns error\n- Error message guides merchant to enable template\n- Path: \"More -> Notification Settings\"\n- Template must be explicitly enabled\n\n**Email Delivery:**\n- Email sent asynchronously\n- Success response doesn't guarantee delivery\n- Check email logs for delivery confirmation\n- Respects shop's email provider settings\n\n**Multiple Subscriptions:**\n- If customer has multiple subscriptions: Sorts by status\n- Active subscriptions shown first\n- Link provides access to ALL customer subscriptions\n- Portal displays all contracts\n\n**Activity Logging:**\n- All magic link emails logged\n- Source: MERCHANT_EXTERNAL_API\n- Includes timestamp and customer\n- Viewable in activity logs\n\n**Integration Examples:**\n\n**Webhook Trigger - Payment Failed:**\n```javascript\nasync function handlePaymentFailure(webhook) {\n const customerEmail = webhook.customer.email;\n \n // Send magic link to customer\n await fetch(\n `/api/external/v2/subscription-contracts-email-magic-link?email=${customerEmail}`,\n { headers: { 'X-API-Key': process.env.APPSTLE_API_KEY } }\n );\n \n console.log(`Magic link sent to ${customerEmail} for payment update`);\n}\n```\n\n**Customer Support Button:**\n```javascript\nasync function sendPortalAccess(customerEmail) {\n try {\n const response = await fetch(\n `/api/external/v2/subscription-contracts-email-magic-link?email=${encodeURIComponent(customerEmail)}`,\n { \n headers: { 'X-API-Key': apiKey },\n method: 'GET'\n }\n );\n \n if (response.ok) {\n alert('Portal access email sent to customer!');\n }\n } catch (error) {\n console.error('Failed to send magic link:', error);\n }\n}\n```\n\n**Best Practices:**\n\n1. **Validate Email**: Check email format before calling API\n2. **Rate Limiting**: Don't spam customers - limit frequency\n3. **Error Handling**: Handle customer not found gracefully\n4. **User Feedback**: Confirm email sent to user\n5. **Test Template**: Ensure email template configured and working\n6. **Monitor Logs**: Check activity logs for delivery issues\n\n**Common Errors:**\n\n**\"Customer Email does not exist\":**\n- Email not found in subscription database\n- Customer has no subscriptions\n- Email may be misspelled\n\n**\"Email template not found\":**\n- SUBSCRIPTION_MANAGEMENT_LINK template not configured\n- Contact Appstle support to set up template\n\n**\"Email is currently disabled\":**\n- Template disabled in Notification Settings\n- Navigate to More -> Notification Settings\n- Enable \"Subscription Management Link\" email\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "emailMagicLinkV2", "parameters": [ { "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } }, { "description": "Customer email", "in": "query", "name": "email", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": "Email triggered successfully.", "schema": { "type": "string" } } }, "description": "Email successfully queued for delivery" }, "400": { "content": { "application/json": { "examples": { "Customer Not Found": { "description": "Customer Not Found", "value": { "detail": "UserGeneratedError:Customer Email does not exist", "status": 400, "title": "Customer not found", "type": "https://example.com/errors/bad-request" } }, "Email Template Disabled": { "description": "Email Template Disabled", "value": { "detail": "UserGeneratedError:The Subscription Management Link email is currently disabled in Notification Settings. To enable it, go to More -> Notification Settings.", "status": 400, "title": "Email disabled", "type": "https://example.com/errors/bad-request" } }, "Email Template Not Found": { "description": "Email Template Not Found", "value": { "detail": "UserGeneratedError:Email template not found", "status": 400, "title": "Email template not configured", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Bad request - Customer not found or email template disabled" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "500": { "content": { "application/json": { "example": { "detail": "Failed to send magic link email", "status": 500, "title": "Email send failed", "type": "https://example.com/errors/internal-error" } } }, "description": "Internal server error - Email send failure" } }, "summary": "Send magic link email to customer for portal access", "tags": [ "Subscription Contracts", "Customer Portal" ] } }, "/api/external/v2/subscription-contracts-remove-discount": { "put": { "description": "Removes a specific discount from a subscription contract based on the discount ID. This will affect the pricing of all future orders generated by the subscription.\n\n**Key Features:**\n- Removes any type of discount: automatic, manual, or code-based\n- Uses Shopify's draft system for safe removal\n- Immediate effect on future order pricing\n- Cannot be undone - discount must be re-applied if needed\n- Activity log tracks removed discounts\n\n**Finding Discount IDs:**\nDiscount IDs can be found in the subscription contract's discount collection:\n- Query the subscription contract to see `discounts.edges[].node.id`\n- Format: `gid://shopify/SubscriptionManualDiscount/123456`\n- Each discount has a unique ID regardless of type\n\n**Types of Discounts:**\n- **Manual Discounts**: Applied via API (percentage, fixed, price)\n- **Code Discounts**: Applied using discount codes\n- **Automatic Discounts**: Applied by Shopify based on rules\n- **Build-a-Box Discounts**: Volume-based discounts\n- **Selling Plan Discounts**: Built into the subscription plan\n\n**Impact on Pricing:**\nWhen a discount is removed:\n- Future orders use full price (no discount)\n- Existing orders are not affected\n- Other discounts remain active\n- Shipping prices may be recalculated\n- Customer sees updated pricing immediately\n\n**Common Use Cases:**\n- End promotional period discounts\n- Remove expired or invalid discount codes\n- Clear discounts before applying new ones\n- Customer service adjustments\n- Correct pricing errors\n\n**Important Notes:**\n- Cannot remove selling plan built-in discounts\n- No customer notification sent (consider sending separately)\n- Cannot selectively remove - removes entire discount\n- Build-a-Box discounts may auto-reapply based on quantity\n- Some discounts may be required by business rules\n\n**Post-Removal Considerations:**\n- Customer may notice price increase on next order\n- May affect customer retention if unexpected\n- Consider grace periods or notifications\n- Document reason for removal in your system\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "removeDiscountV2", "parameters": [ { "description": "Subscription contract ID to remove discount from", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "ID of the discount to be removed. Must be the full GraphQL ID including the gid:// prefix. You can find discount IDs by querying the subscription contract and looking at the discounts collection. Format example: gid://shopify/SubscriptionManualDiscount/123456789", "example": "gid://shopify/SubscriptionManualDiscount/123456789", "in": "query", "name": "discountId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "customer": { "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "deliveryPrice": { "amount": "5.99", "currencyCode": "USD" }, "discounts": { "edges": [] }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "39.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "pricingPolicy": { "basePrice": { "amount": "39.99", "currencyCode": "USD" } }, "quantity": 2, "title": "Premium Coffee - Monthly Supply", "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "nextBillingDate": "2024-04-01T00:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Discount successfully removed" }, "400": { "content": { "application/json": { "examples": { "Cannot Remove System Discount": { "description": "Cannot Remove System Discount", "value": { "detail": "This discount is required by the subscription plan and cannot be removed", "status": 400, "title": "Cannot remove this discount", "type": "https://example.com/errors/bad-request" } }, "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "No subscription contract found with ID 123456789", "status": 400, "title": "Contract does not exist", "type": "https://example.com/errors/bad-request" } }, "Discount Not Found": { "description": "Discount Not Found", "value": { "detail": "The specified discount does not exist on this subscription", "status": 400, "title": "Discount with id gid://shopify/SubscriptionManualDiscount/999999 not found", "type": "https://example.com/errors/bad-request" } }, "Invalid Discount ID Format": { "description": "Invalid Discount ID Format", "value": { "detail": "Discount ID must be in format: gid://shopify/SubscriptionManualDiscount/[numeric_id]", "status": 400, "title": "Invalid discount ID format", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid contract ID or discount ID" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to modify subscription" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Draft Creation Failed": { "description": "Draft Creation Failed", "value": { "detail": "Subscription is currently being modified by another process", "status": 422, "title": "Unable to create subscription draft", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Cannot modify subscription during active billing attempt", "status": 422, "title": "Unable to remove discount", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Discount exists but cannot be removed" } }, "summary": "Remove discount from subscription", "tags": [ "Subscription Contracts", "Subscription Discounts" ] } }, "/api/external/v2/subscription-contracts-remove-line-item": { "put": { "description": "Removes a specific product line item from an existing subscription contract. Can optionally retain prorated discounts associated with the removed product.\n\n**Key Features:**\n- Validates minimum subscription requirements before removal\n- Handles discount cleanup for line-specific discounts\n- Enforces minimum cycle commitments on products\n- Supports Build-a-Box quantity validation\n- Automatic retry on concurrent modification conflicts\n- Email notifications for subscription changes\n\n**Validation Rules:**\n- At least one recurring subscription product must remain after removal\n- One-time products and free products don't count toward the minimum\n- Products with minimum cycle commitments cannot be removed until fulfilled\n- Build-a-Box subscriptions validate against minimum/maximum quantity rules\n\n**Discount Handling:**\nWhen `removeDiscount=true` (default):\n- Discounts applied only to the removed line item are deleted\n- Discounts applied to multiple line items are retained\n- System automatically identifies which discounts to remove\n\n**Retry Mechanism:**\nThe endpoint automatically retries in these scenarios:\n- Concurrent modification detected (another process updated the subscription)\n- Invalid discount code errors (removes problematic discount and retries)\n- This ensures reliable operation in high-traffic environments\n\n**Post-Removal Actions:**\n- Activity log created for audit trail\n- Email notification sent to customer\n- Shipping price recalculated asynchronously\n- Build-a-Box discounts resynced if applicable\n- Product-specific discounts resynced\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "removeLineItemV2", "parameters": [ { "description": "Subscription contract ID to remove product from. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "pattern": "^[0-9]+$", "type": "string" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Line item ID of the product to remove. Must be the full GraphQL ID including the gid:// prefix", "example": "gid://shopify/SubscriptionLine/123456789", "in": "query", "name": "lineId", "required": true, "schema": { "type": "string" } }, { "description": "Controls whether to remove discounts that apply only to this line item. When true (default), line-specific discounts are removed. When false, attempts to retain discounts where possible. Note: Discounts that apply to multiple lines are always retained regardless of this setting", "example": true, "in": "query", "name": "removeDiscount", "required": false, "schema": { "default": true, "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "billingPolicy": { "interval": "MONTH", "intervalCount": 1 }, "customer": { "email": "customer@example.com", "firstName": "John", "id": "gid://shopify/Customer/987654321", "lastName": "Doe" }, "deliveryPolicy": { "interval": "MONTH", "intervalCount": 1 }, "discounts": { "edges": [ { "node": { "id": "gid://shopify/SubscriptionManualDiscount/999999", "targetType": "ALL_LINES", "title": "10% OFF SUBSCRIPTION", "value": { "percentage": 10 } } } ] }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "29.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "quantity": 2, "sellingPlanId": "gid://shopify/SellingPlan/123456", "sellingPlanName": "Deliver every month", "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "nextBillingDate": "2024-03-01T00:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Product successfully removed from subscription" }, "400": { "content": { "application/json": { "examples": { "Build-a-Box Validation Error": { "description": "Build-a-Box Validation Error", "value": { "detail": "Build-a-Box subscriptions must maintain minimum item quantities", "status": 400, "title": "UserGeneratedError:Removing this item would violate the minimum quantity requirement for your Build-a-Box subscription", "type": "https://example.com/errors/bad-request" } }, "Invalid Line ID Format": { "description": "Invalid Line ID Format", "value": { "detail": "Line ID must be in format: gid://shopify/SubscriptionLine/[numeric_id]", "status": 400, "title": "Invalid line item ID format", "type": "https://example.com/errors/bad-request" } }, "Last Product Removal Attempt": { "description": "Last Product Removal Attempt", "value": { "detail": "Cannot remove the last recurring product from the subscription", "status": 400, "title": "UserGeneratedError:Cannot remove line item. Atleast one subscription product must be present in a subscription", "type": "https://example.com/errors/bad-request" } }, "Line Item Not Found": { "description": "Line Item Not Found", "value": { "detail": "The specified line item does not exist in this subscription", "status": 400, "title": "Couldn't find LineId=gid://shopify/SubscriptionLine/999999", "type": "https://example.com/errors/bad-request" } }, "Minimum Cycles Not Met": { "description": "Minimum Cycles Not Met", "value": { "detail": "Product has a minimum cycle requirement that has not been fulfilled", "status": 400, "title": "UserGeneratedError:This product requires a minimum commitment of {{minCycles}} billing cycles before removal", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to modify subscription" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Concurrent Modification": { "description": "Concurrent Modification", "value": { "detail": "Another process modified the subscription. The system will automatically retry.", "status": 422, "title": "The subscription contract has changed. Retry the operation.", "type": "https://example.com/errors/unprocessable-entity" } }, "Draft Commit Error": { "description": "Draft Commit Error", "value": { "detail": "Shopify API error: Billing attempt in progress", "status": 422, "title": "UserGeneratedError:Unable to commit subscription changes", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Unable to process the removal due to Shopify API constraints" } }, "summary": "Remove product from subscription", "tags": [ "Subscription Products", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-remove-line-items": { "put": { "description": "Removes multiple product line items from an existing subscription contract in a single request. Products are removed sequentially, allowing partial success if errors occur.\n\n**Key Features:**\n- Sequential processing - items removed one by one\n- Partial success allowed - previous removals persist if later ones fail\n- Validates each removal against current subscription state\n- Smart discount cleanup for line-specific discounts\n- Comprehensive validation for each product removal\n- Triggers all side effects after each successful removal\n\n**Processing Order Matters:**\nItems are removed in the order provided:\n1. First item validated and removed\n2. Second item validated against updated state\n3. Continue until all processed or error occurs\n4. Returns final subscription state\n\n**Validation Per Item:**\n- Line item must exist in subscription\n- At least one recurring product must remain\n- Build-a-Box min/max quantities maintained\n- Minimum cycle commitments honored\n- One-time and free products don't count toward minimum\n\n**Discount Handling:**\nWhen `removeDiscount=true`:\n- Removes discounts applied ONLY to the removed line\n- Preserves discounts that apply to multiple lines\n- Each removal evaluates discounts independently\n- Build-a-Box discounts auto-adjust based on quantity\n\n**Side Effects Per Removal:**\nEach successful removal triggers:\n- Activity log entry created\n- Customer email sent\n- Shipping price recalculation\n- Build-a-Box discount resync\n- Product discount adjustments\n\n**Partial Success Scenarios:**\nIf removing 3 items and the 2nd fails:\n- 1st item: Successfully removed\n- 2nd item: Fails, error returned\n- 3rd item: Not attempted\n- Result: Subscription with 1st item removed\n\n**Performance Considerations:**\n- Each removal is a separate Shopify API transaction\n- Multiple emails may be sent to customer\n- Consider using single remove for 1-2 items\n- Large batches may timeout\n- Recommended max: 5-10 items per request\n\n**Build-a-Box Handling:**\nFor Build-a-Box subscriptions:\n- Validates total quantity after EACH removal\n- May fail mid-batch if minimum breached\n- Discounts recalculate after each item\n- Consider removal order carefully\n\n**Important Notes:**\n- NOT atomic - no rollback on partial failure\n- Order of line IDs affects success probability\n- Customer receives email per removed item\n- All validations apply as if removing individually\n- Response shows final state after all attempts\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "removeLineItems", "parameters": [ { "description": "Subscription contract ID to remove products from", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "When true, removes discounts that apply only to each removed line item. When false, attempts to retain all discounts. Discounts that apply to multiple lines are always retained regardless of this setting.", "example": false, "in": "query", "name": "removeDiscount", "required": false, "schema": { "default": false, "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "List of line item IDs to remove. IDs must be in full GraphQL format. Items are processed sequentially in the order provided. If any removal fails, processing stops but previous removals are kept.", "items": { "type": "string" }, "type": "array" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "customer": { "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "discounts": { "edges": [ { "node": { "id": "gid://shopify/SubscriptionManualDiscount/444444", "targetType": "ALL_LINES", "title": "10% OFF ALL ITEMS" } } ] }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "19.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/333333", "quantity": 1, "title": "Essential Product - Monthly", "variantId": "gid://shopify/ProductVariant/42549172076700" } } ] }, "nextBillingDate": "2024-04-01T00:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Products successfully removed from subscription (full or partial success)" }, "207": { "content": { "application/json": { "example": { "detail": "2 of 3 items removed successfully", "failedLineIds": [ { "error": "Would violate minimum product requirement", "lineId": "gid://shopify/SubscriptionLine/333333" } ], "removedLineIds": [ "gid://shopify/SubscriptionLine/111111", "gid://shopify/SubscriptionLine/222222" ], "status": 207, "title": "Partial success", "type": "https://example.com/partial-success" } } }, "description": "Multi-Status - Some items removed successfully, others failed" }, "400": { "content": { "application/json": { "examples": { "Build-a-Box Minimum Violation": { "description": "Build-a-Box Minimum Violation", "value": { "code": "minQuantityNotReached", "detail": "Removing item would violate Build-a-Box minimum quantity. Some items may have been removed.", "status": 400, "title": "UserGeneratedError:Minimum 6 quantity is required", "type": "https://example.com/errors/bad-request" } }, "Empty Line IDs List": { "description": "Empty Line IDs List", "value": { "detail": "Line IDs list cannot be empty", "status": 400, "title": "Invalid request body", "type": "https://example.com/errors/bad-request" } }, "Line Item Not Found (Partial Success)": { "description": "Line Item Not Found (Partial Success)", "value": { "detail": "Line item not found. Previous items in batch may have been removed successfully.", "status": 400, "title": "Couldn't find LineId=gid://shopify/SubscriptionLine/999999", "type": "https://example.com/errors/bad-request" } }, "Minimum Cycles Not Met": { "description": "Minimum Cycles Not Met", "value": { "detail": "Product has minimum cycle requirement. Previous removals in batch were successful.", "status": 400, "title": "UserGeneratedError:Subscription cannot be modified until 3 orders have completed.", "type": "https://example.com/errors/bad-request" } }, "Would Remove Last Product": { "description": "Would Remove Last Product", "value": { "detail": "Removing these items would leave no recurring products in the subscription", "status": 400, "title": "UserGeneratedError:Cannot remove line item. Atleast one subscription product must be present in a subscription", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid contract ID or line item IDs - may indicate partial failure" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to modify subscription" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Concurrent Modification": { "description": "Concurrent Modification", "value": { "detail": "Another process modified the subscription. Some items may have been removed.", "status": 422, "title": "UserGeneratedError:The subscription contract has changed. Retry the operation.", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Cannot modify subscription during active billing attempt", "status": 422, "title": "Unable to remove line item", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "One or more products cannot be removed due to subscription constraints" } }, "summary": "Remove multiple products from subscription", "tags": [ "Subscription Products", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-billing-date": { "put": { "description": "Reschedules the next billing date for an active subscription contract. This endpoint allows you to change when the next order will be created and processed.\n\n**Key Features:**\n- Updates the next billing date to the specified date\n- Optionally reschedules all future orders based on the new date\n- Syncs the updated date to Shopify\n- Sends confirmation email to customer\n\n**The rescheduleFutureOrder Parameter:**\n- **true** (default): Updates the next billing date AND recalculates all future queued orders based on the new date. Use this to shift the entire billing schedule.\n- **false**: Only updates the next billing date. Other queued orders remain unchanged. Use this for one-time date adjustments.\n\n**Important Notes:**\n- The new date must be in the future (with 10 minute grace period)\n- Date is validated against the shop's timezone\n- If anchor days are configured, future orders may align to those anchors\n\n**Process Flow:**\n1. Validates the contract exists and belongs to the shop\n2. Validates the new date is not in the past\n3. Updates the billing attempt to the new date\n4. Syncs the updated nextBillingDate to Shopify\n5. If rescheduleFutureOrder=true, regenerates the queue from the new date\n6. Sends confirmation email to customer\n7. Records activity log entry\n\n**Date Format:**\n- Must be ISO 8601 format with timezone\n- Examples: `2024-03-15T12:00:00Z`, `2024-03-15T12:00:00+05:30`\n- URL encode the date when passing as query parameter\n\n**Timezone Handling:**\n- The provided date is used as-is for the billing attempt\n- Validation (past date check) uses the shop's configured timezone\n- All dates in the response are in UTC (Z suffix)\n\n**Date Restrictions (Customer Portal Only):**\nWhen called from customer portal context:\n- Minimum days from today (skipDaysFromCurrentDate setting)\n- Maximum days from today (billingDateRestrictToDays setting)\n- External API calls bypass these restrictions\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateNextBillingDateV2", "parameters": [ { "description": "Subscription contract ID to update", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "If true (or value not provided), next billing date will be changed and also schedule for future upcoming orders will be changed based on new updated billing date.\nIf false, then only next billing date will be changed, but the schedule for future upcoming orders will not change.", "example": true, "in": "query", "name": "rescheduleFutureOrder", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "New billing date in ISO 8601 format with timezone. The date must be in the future and may be subject to merchant-configured restrictions. Common formats:\n- UTC: 2024-03-15T12:00:00Z\n- With offset: 2024-03-15T12:00:00+05:30\n- With timezone: 2024-03-15T12:00:00[America/New_York]\n\nThe system will convert the date to the shop's timezone for validation.", "example": "2024-03-15T12:00:00Z", "in": "query", "name": "nextBillingDate", "required": true, "schema": { "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2}|\\[.+\\])$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "__typename": "SubscriptionContract", "billingPolicy": { "interval": "MONTH", "intervalCount": 1 }, "customer": { "displayName": "John Doe", "email": "customer@example.com" }, "id": "gid://shopify/SubscriptionContract/123456789", "nextBillingDate": "2024-03-15T12:00:00Z", "status": "ACTIVE", "updatedAt": "2024-02-15T10:30:00Z" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Billing date successfully updated. The response contains the updated subscription contract from Shopify with the new nextBillingDate.", "headers": { "X-Application-Context": { "description": "Application context with alert message", "schema": { "example": "appname:Subscription Updated:", "type": "string" }, "style": "simple" } } }, "400": { "content": { "application/json": { "examples": { "Contract Not Found": { "description": "Contract Not Found", "summary": "Invalid contract ID", "value": { "detail": "No subscription contract found with the specified ID", "instance": "/api/external/v2/subscription-contracts-update-billing-date", "status": 400, "title": "Contract does not exist", "type": "https://example.com/errors/bad-request" } }, "Date Outside Allowed Range": { "description": "Date Outside Allowed Range", "summary": "Customer portal date restrictions", "value": { "detail": "The selected date is outside the allowed range for rescheduling", "instance": "/api/external/v2/subscription-contracts-update-billing-date", "status": 400, "title": "Can't reschedule on this 2024-12-31T00:00:00Z", "type": "https://example.com/errors/bad-request" } }, "Date in Past": { "description": "Date in Past", "summary": "Billing date cannot be in the past", "value": { "detail": "The billing date must be a future date", "instance": "/api/external/v2/subscription-contracts-update-billing-date", "status": 400, "title": "The billing date you are trying to set (2024-01-01T00:00:00Z) is in the past. Billing dates cannot be updated to a time that has already passed. Please select a future billing date.", "type": "https://example.com/errors/bad-request" } }, "Invalid Date Format": { "description": "Invalid Date Format", "summary": "Date must be ISO 8601 format", "value": { "detail": "Date must be in ISO 8601 format with timezone (e.g., 2024-03-15T12:00:00Z or 2024-03-15T12:00:00+05:30)", "instance": "/api/external/v2/subscription-contracts-update-billing-date", "status": 400, "title": "Invalid date format", "type": "https://example.com/errors/bad-request" } }, "Shopify API Error": { "description": "Shopify API Error", "summary": "Failed to sync with Shopify", "value": { "detail": "Shopify returned an error when attempting to update the billing date", "instance": "/api/external/v2/subscription-contracts-update-billing-date", "status": 400, "title": "UserGeneratedError:Unable to update billing date", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request or date validation failed" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "instance": "/api/external/v2/subscription-contracts-update-billing-date", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "instance": "/api/external/v2/subscription-contracts-update-billing-date", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to update billing date" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with the specified ID not found in the system", "instance": "/api/external/v2/subscription-contracts-update-billing-date", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" } }, "summary": "Update next billing date for a subscription contract", "tags": [ "Subscription Contracts", "Billing & Payments" ] } }, "/api/external/v2/subscription-contracts-update-billing-interval": { "put": { "description": "Updates the billing frequency (how often the customer is charged) for a subscription contract. This comprehensive operation recalculates billing dates, adjusts pricing, updates selling plans, and may also modify delivery intervals.\n\n**Key Features:**\n- Changes billing frequency while maintaining subscription continuity\n- Automatically adjusts delivery interval when linked to billing\n- Recalculates next billing date based on store settings\n- Reprices all line items for the new frequency\n- Finds and applies matching selling plans\n- Handles anchor day adjustments for consistent billing\n- Validates prepaid subscription constraints\n\n**Billing Interval Types:**\n- **DAY**: Daily billing (use with caution)\n- **WEEK**: Weekly billing (e.g., every 1, 2, 3 weeks)\n- **MONTH**: Monthly billing (e.g., every 1, 2, 3 months)\n- **YEAR**: Annual billing\n\n**Validation Rules:**\n- Cannot set the same interval as current (no-op prevention)\n- For prepaid subscriptions: billing interval must exceed delivery interval\n- Example: Can't bill monthly if delivering weekly (would be paying for 1 delivery but receiving 4)\n\n**Next Billing Date Calculation:**\nThe system uses sophisticated logic to determine the new billing date:\n1. Starts from current or last successful billing date\n2. Applies store timezone and order time preferences\n3. Ensures date is in the future\n4. Respects day-of-week preferences if configured\n5. May keep current date if 'enableChangeFromNextBillingDate' is false\n\n**Side Effects:**\n- **Delivery Interval**: Updated if currently equal to billing interval\n- **Line Item Pricing**: Recalculated based on new frequency multiplier\n- **Selling Plans**: Finds and applies best matching plans for products\n- **Anchor Days**: Updates billing anchor for consistent scheduling\n- **Email Notifications**: Sends 'ORDER_FREQUENCY_UPDATED' to customer\n- **Activity Logs**: Records both billing and delivery changes\n\n**Prepaid vs Pay-Per-Delivery:**\n- Pay-per-delivery: Billing and delivery intervals typically match\n- Prepaid: Customer pays upfront for multiple deliveries\n- This endpoint enforces prepaid logic to prevent undercharging\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateBillingIntervalV2", "parameters": [ { "description": "Subscription contract ID to update. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Number of intervals between billings. For example, intervalCount=2 with interval=WEEK means 'every 2 weeks'", "example": 2, "in": "query", "name": "intervalCount", "required": true, "schema": { "maximum": 365, "minimum": 1, "type": "integer" } }, { "description": "Type of interval for billing frequency", "example": "MONTH", "in": "query", "name": "interval", "required": true, "schema": { "enum": [ "DAY", "WEEK", "MONTH", "YEAR", "$UNKNOWN" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "billingPolicy": { "anchors": [ { "day": 1, "type": "MONTHDAY" } ], "interval": "MONTH", "intervalCount": 2 }, "customer": { "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "deliveryPolicy": { "interval": "MONTH", "intervalCount": 2 }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "59.98", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "pricingPolicy": { "basePrice": { "amount": "29.99", "currencyCode": "USD" } }, "quantity": 1, "sellingPlanId": "gid://shopify/SellingPlan/222222", "sellingPlanName": "Deliver every 2 months", "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "nextBillingDate": "2024-04-01T12:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Billing interval updated successfully" }, "400": { "content": { "application/json": { "examples": { "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "No subscription contract found with ID 123456789", "status": 400, "title": "Subscription contract not found", "type": "https://example.com/errors/bad-request" } }, "Invalid Interval Count": { "description": "Invalid Interval Count", "value": { "detail": "Interval count must be between 1 and 365", "status": 400, "title": "Invalid interval count", "type": "https://example.com/errors/bad-request" } }, "Invalid Interval Type": { "description": "Invalid Interval Type", "value": { "detail": "Interval must be one of: DAY, WEEK, MONTH, YEAR", "status": 400, "title": "Invalid interval type", "type": "https://example.com/errors/bad-request" } }, "Prepaid Validation Error": { "description": "Prepaid Validation Error", "value": { "detail": "Cannot bill monthly for weekly deliveries in prepaid subscriptions", "status": 400, "title": "UserGeneratedError:Billing interval cannot be less than or equal to delivery interval for prepaid contracts", "type": "https://example.com/errors/bad-request" } }, "Same Interval Error": { "description": "Same Interval Error", "value": { "detail": "The subscription is already set to bill every 1 month", "status": 400, "title": "UserGeneratedError:Billing interval cannot be the same as old billing interval", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to update billing interval" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "No Matching Selling Plan": { "description": "No Matching Selling Plan", "value": { "detail": "No selling plan found for the requested billing frequency", "status": 422, "title": "No selling plan available", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Cannot modify subscription during active billing attempt", "status": 422, "title": "Unable to update billing interval", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Billing interval update failed due to Shopify constraints" } }, "summary": "Update billing interval for a subscription contract", "tags": [ "Subscription Contracts", "Billing & Payments" ] } }, "/api/external/v2/subscription-contracts-update-delivery-interval": { "put": { "description": "Updates the delivery interval for the specified subscription contract.\nThis endpoint allows external API consumers to change the delivery interval count\nand type (of type SellingPlanInterval) used for scheduling deliveries.\n\nThe service validates that the contract exists, that the new delivery interval\ndiffers from the current setting, and that it meets all business rules.\n\nAuthentication is enforced via the X-API-Key header (the 'api_key' parameter is deprecated).\n", "operationId": "updateDeliveryIntervalV2", "parameters": [ { "description": "Contract ID", "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } }, { "description": "Delivery Interval Count", "in": "query", "name": "deliveryIntervalCount", "required": true, "schema": { "format": "int32", "type": "integer" } }, { "description": "Delivery Interval Type", "in": "query", "name": "deliveryInterval", "required": true, "schema": { "enum": [ "DAY", "WEEK", "MONTH", "YEAR", "$UNKNOWN" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Delivery interval updated successfully" }, "400": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Invalid contract ID or delivery interval values" }, "401": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Authentication required" }, "403": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Insufficient permissions to update delivery interval" }, "404": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Subscription contract not found" }, "422": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Delivery interval update failed due to business rules" } }, "summary": "Update delivery interval for a subscription contract", "tags": [ "Subscription Management", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-delivery-method": { "put": { "description": "Updates the delivery method for a subscription contract, supporting standard shipping, local delivery, and customer pickup options. The delivery method determines how future orders will be fulfilled.\n\n**Delivery Method Types:**\nThe system automatically determines the type based on the subscription's current delivery address:\n- **SHIPPING**: Standard shipping to customer address (default)\n- **LOCAL**: Local delivery within merchant's delivery zones\n- **PICK_UP**: Customer pickup at designated location\n\n**Two Ways to Update:**\n1. **Manual Parameters**: Omit delivery-method-id and provide title, code, and presentment title directly. This preserves the delivery price on both legacy and market-driven shops and enables the contract's manual price override.\n2. **Delivery Method ID**: Provide a Shopify DeliveryMethodDefinition ID or a full Market delivery-option GraphQL ID returned by the shop delivery-options catalogue.\n\n**Using Delivery Method ID:**\nWhen providing a delivery-method-id:\n- Legacy shops fetch the method from Shopify's delivery profiles\n- Automatically sets title, code, and presentment title\n- Applies associated delivery price if defined\n- DeliveryMethodDefinition IDs can be numeric or full GraphQL IDs; Market option IDs must be full GraphQL IDs\n- On market-driven shops, the server resolves the selected option's title and applies a unique current quote for the contract under its draft lock\n- A missing or ambiguous live quote rejects the update without changing the contract\n- Applying a live quote resumes automatic shipping price synchronization\n\n**Delivery Type Requirements:**\n- **Standard Shipping**: No additional requirements\n- **Local Delivery**: Phone number must exist in delivery address\n- **Pickup**: Pickup location must be configured in subscription\n\n**Price Updates:**\n- If using delivery-method-id with a fixed price, updates delivery price\n- Manual updates don't change the delivery price\n- Price changes affect all future orders\n\n**Side Effects:**\n- Creates activity log entry with method details\n- May remove invalid discount codes automatically\n- Updates apply to all future orders immediately\n- No customer notification sent\n\n**Common Use Cases:**\n- Switch from standard shipping to express shipping\n- Change pickup location for customer convenience\n- Update local delivery options based on availability\n- Apply seasonal delivery methods\n\n**Important Notes:**\n- Cannot change the delivery type (shipping/local/pickup) - only the method within that type\n- Delivery methods must be configured in Shopify's shipping settings\n- Changes don't affect orders already in fulfillment\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateDeliveryMethod", "parameters": [ { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Subscription contract ID to update", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Display name of the delivery method. This is what customers see. Ignored if delivery-method-id is provided.", "example": "Express Shipping", "in": "query", "name": "delivery-method-title", "required": true, "schema": { "maxLength": 255, "type": "string" } }, { "description": "Internal code for the delivery method. Often same as title. Used for system identification. Ignored if delivery-method-id is provided.", "example": "EXPRESS_SHIP", "in": "query", "name": "delivery-method-code", "required": true, "schema": { "maxLength": 255, "type": "string" } }, { "description": "Localized version of the title for multi-language stores. Often same as title for single-language stores. Ignored if delivery-method-id is provided.", "example": "Express Shipping", "in": "query", "name": "delivery-method-presentment-title", "required": true, "schema": { "maxLength": 255, "type": "string" } }, { "description": "Optional DeliveryMethodDefinition ID (numeric or full GraphQL ID), or a full Market option ID such as gid://shopify/DeliveryFlatRateOptionDefinition/123. Market-driven shops apply a current eligible quote for the selected option. Omit for a custom title/code edit that preserves the current delivery price and enables manual price override.", "example": 123456, "in": "query", "name": "delivery-method-id", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Delivery method successfully updated", "headers": { "X-Alert": { "description": "Success message", "schema": { "example": "Subscription Updated", "type": "string" }, "style": "simple" } } }, "400": { "content": { "application/json": { "examples": { "Invalid Delivery Method ID": { "description": "Invalid Delivery Method ID", "value": { "detail": "The specified delivery method does not exist in store's delivery profiles", "status": 400, "title": "UserGeneratedError:Delivery method not found for deliveryMethodID:999999", "type": "https://example.com/errors/bad-request" } }, "Local Delivery Phone Required": { "description": "Local Delivery Phone Required", "value": { "detail": "Local delivery requires a phone number in the delivery address", "status": 400, "title": "UserGeneratedError:Phone number is required", "type": "https://example.com/errors/bad-request" } }, "No Delivery Address": { "description": "No Delivery Address", "value": { "detail": "Subscription has no delivery address configured", "status": 400, "title": "UserGeneratedError:Delivery method not found for contract:123456789", "type": "https://example.com/errors/bad-request" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Delivery method is not available for this delivery address", "status": 400, "title": "UserGeneratedError:Unable to update delivery method", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request or update failed" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify delivery methods", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions" }, "404": { "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "example": { "detail": "Selected delivery method cannot be used with subscription products", "status": 422, "title": "Delivery method incompatible", "type": "https://example.com/errors/unprocessable-entity" } } }, "description": "Delivery method cannot be applied" } }, "summary": "Update subscription delivery method", "tags": [ "Subscription Management", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-delivery-price": { "put": { "description": "Updates the fixed delivery price for all future orders in a subscription contract. This allows manual override of calculated shipping rates with a custom delivery fee.\n\n**Key Features:**\n- Sets a fixed delivery price regardless of shipping calculations\n- Overrides any dynamic shipping rates from carriers\n- Applies to all future orders immediately\n- Can set to 0 for free delivery\n- Automatically handles invalid discount codes\n- Tracks price changes in activity log\n\n**How Delivery Pricing Works:**\n- **Calculated Rates**: Default behavior uses carrier rates and rules\n- **Manual Override**: This endpoint sets a fixed price\n- **Precedence**: Manual price overrides all calculations\n- **Currency**: Always in shop's base currency\n\n**Common Use Cases:**\n- **Free Shipping Promotions**: Set to 0.00\n- **Flat Rate Shipping**: Fixed price regardless of location\n- **VIP Customer Rates**: Special shipping prices\n- **Subscription Perks**: Reduced delivery fees\n- **Price Corrections**: Fix shipping calculation errors\n- **Regional Adjustments**: Custom rates for specific areas\n\n**Impact on Orders:**\n- Next order uses new delivery price\n- All future recurring orders affected\n- Existing orders keep original pricing\n- Customer sees updated total immediately\n- No recalculation on address changes\n\n**Price Validation:**\n- Must be a valid decimal number\n- Can be 0 for free shipping\n- No maximum limit enforced\n- Negative values typically rejected by Shopify\n- Currency precision respected (e.g., 2 decimals for USD)\n\n**Side Effects:**\n- Invalid discount codes automatically removed\n- Activity log created with old/new prices\n- No customer email notification sent\n- Shipping tax recalculated if applicable\n- Total order value updated\n\n**Reverting to Calculated Rates:**\nTo restore dynamic shipping calculations:\n1. Use the sync shipping price endpoint\n2. Or update delivery method\n3. Manual price remains until explicitly changed\n\n**Important Notes:**\n- Price includes all delivery charges (shipping + handling)\n- Does not affect delivery method or speed\n- Consider customer communication for increases\n- May affect subscription profitability\n- Some payment methods may decline on total changes\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateDeliveryPrice", "parameters": [ { "description": "The unique identifier of the subscription contract", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "New delivery price to be applied to the subscription contract. This is a fixed price that overrides any calculated shipping rates. Set to 0 for free delivery. Price must be in the shop's base currency.", "example": 9.99, "in": "query", "name": "deliveryPrice", "required": true, "schema": { "format": "double", "maximum": 99999.99, "minimum": 0, "type": "number" } }, { "deprecated": true, "description": "Deprecated API Key parameter; use the X-API-Key header instead", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "customer": { "displayName": "John Doe", "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "deliveryMethod": { "__typename": "SubscriptionDeliveryMethodShipping", "shippingOption": { "code": "STANDARD", "presentmentTitle": "Standard Shipping (5-7 days)", "title": "Standard Shipping" } }, "deliveryPrice": { "amount": "9.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "39.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "quantity": 1, "title": "Monthly Subscription Box", "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "nextBillingDate": "2024-04-01T00:00:00Z", "status": "ACTIVE", "totalPrice": { "amount": "49.98", "currencyCode": "USD" } } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Successfully updated delivery price and returned the updated subscription contract" }, "400": { "content": { "application/json": { "examples": { "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "No subscription contract found with ID 123456789", "status": 400, "title": "Contract does not exist", "type": "https://example.com/errors/bad-request" } }, "Invalid Delivery Price": { "description": "Invalid Delivery Price", "value": { "detail": "Delivery price must be a valid positive number", "status": 400, "title": "Invalid delivery price", "type": "https://example.com/errors/bad-request" } }, "Negative Price Error": { "description": "Negative Price Error", "value": { "detail": "Delivery price must be 0 or greater", "status": 400, "title": "UserGeneratedError:Delivery price cannot be negative", "type": "https://example.com/errors/bad-request" } }, "No Delivery Method": { "description": "No Delivery Method", "value": { "detail": "Cannot set delivery price for subscriptions without delivery method", "status": 400, "title": "UserGeneratedError:No delivery method configured", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid contract ID, delivery price, or update failure due to business logic constraints" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify delivery pricing", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to update the delivery price" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Currency Precision Error": { "description": "Currency Precision Error", "value": { "detail": "Price 9.999 exceeds currency precision for USD (2 decimal places)", "status": 422, "title": "UserGeneratedError:Invalid price precision", "type": "https://example.com/errors/unprocessable-entity" } }, "Invalid Discount Code Removed": { "description": "Invalid Discount Code Removed", "value": { "detail": "Delivery price updated successfully, but invalid discount code 'FREESHIP' was automatically removed", "status": 422, "title": "Delivery price updated with warnings", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Cannot modify subscription during active billing attempt", "status": 422, "title": "UserGeneratedError:Unable to update delivery price", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Delivery price update failed due to invalid input or system constraints" } }, "summary": "Update delivery price for a subscription contract", "tags": [ "Subscription Management", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-delivery-price-override": { "put": { "description": "Sets the \"Use Custom Delivery Price\" option (`allowDeliveryPriceOverride`) for a subscription contract.\nThis is the same checkbox shown in the Delivery Information section of the subscription in the merchant portal.\n\n- **true**: The contract keeps its current delivery price. Automatic shipping price syncs from your Shopify\n shipping settings are skipped for this contract. Use this together with\n `PUT /api/external/v2/subscription-contracts-update-delivery-price` to keep a manually set price.\n- **false**: The delivery price syncs with your Shopify shipping settings again. When the option is turned off,\n the delivery price is recalculated from your Shopify shipping rates in the background (unless automatic\n shipping price calculation is turned off in your shop settings).\n\nSending the value the contract already has makes no changes.\n\nAuthentication is enforced via the X-API-Key header (the 'api_key' parameter is deprecated).\n", "operationId": "updateDeliveryPriceOverrideV2", "parameters": [ { "description": "Contract ID", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "Use Custom Delivery Price. true keeps the contract's current delivery price and skips automatic shipping price syncs; false syncs the delivery price with your Shopify shipping settings again.", "example": true, "in": "query", "name": "allowDeliveryPriceOverride", "required": true, "schema": { "type": "boolean" } }, { "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionContractDetailsDTO" } } }, "description": "Custom delivery price option updated. Returns the subscription contract details, including allowDeliveryPriceOverride." }, "400": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContractDetailsDTO" } } }, "description": "Invalid contract ID or the contract does not belong to this shop" }, "401": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContractDetailsDTO" } } }, "description": "Authentication required" }, "403": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContractDetailsDTO" } } }, "description": "Insufficient permissions to update the subscription contract" } }, "summary": "Turn custom delivery price on or off for a subscription contract", "tags": [ "Subscription Management", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-existing-payment-method": { "put": { "description": "Updates the payment method for an existing subscription contract to use a different existing payment method. The new payment method must already be associated with the customer in Shopify.\n\n**Important Notes:**\n- The payment method must already exist in the customer's Shopify payment methods\n- Only valid, non-revoked payment methods can be used\n- The update is processed through Shopify's subscription draft system\n- Payment method details are cached locally after successful update\n\n**Process Flow:**\n1. Validates subscription contract exists\n2. Creates a draft update in Shopify\n3. Updates the draft with new payment method\n4. Commits the draft to apply changes\n5. Caches payment instrument details locally\n6. Records activity log entry\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateExistingPaymentMethodV2", "parameters": [ { "description": "Subscription contract ID to update payment method for. Must be a valid contract ID that belongs to the authenticated shop.", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "ID of the existing customer payment method to use. Must be a valid Shopify GraphQL payment method ID in the format 'gid://shopify/CustomerPaymentMethod/{id}'. The payment method must:\n- Already exist in the customer's Shopify account\n- Be in a valid state (not expired or revoked)\n- Be authorized for subscription use\n\nYou can retrieve available payment methods using the customer payment methods endpoint.", "example": "gid://shopify/CustomerPaymentMethod/cdb2bbe581599b20439ebf636a380b8b", "in": "query", "name": "paymentMethodId", "required": true, "schema": { "pattern": "^gid://shopify/CustomerPaymentMethod/[a-zA-Z0-9]+$", "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Payment method updated successfully" } } }, "description": "Payment method updated successfully" }, "400": { "content": { "application/json": { "examples": { "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "No subscription contract found with the specified ID", "instance": "/api/external/v2/subscription-contracts-update-existing-payment-method", "status": 400, "title": "Contract does not exist", "type": "https://example.com/errors/bad-request" } }, "Invalid Payment Method": { "description": "Invalid Payment Method", "value": { "detail": "Payment method ID is required and must be valid", "instance": "/api/external/v2/subscription-contracts-update-existing-payment-method", "status": 400, "title": "UserGeneratedError:Invalid payment method provided", "type": "https://example.com/errors/bad-request" } }, "Invalid Payment Method Status": { "description": "Invalid Payment Method Status", "value": { "detail": "The payment method cannot be used because it is expired or revoked", "instance": "/api/external/v2/subscription-contracts-update-existing-payment-method", "status": 400, "title": "UserGeneratedError:Payment method is expired", "type": "https://example.com/errors/bad-request" } }, "Payment Method Not Found": { "description": "Payment Method Not Found", "value": { "detail": "The specified payment method does not exist or is not associated with this customer", "instance": "/api/external/v2/subscription-contracts-update-existing-payment-method", "status": 400, "title": "UserGeneratedError:Payment method not found", "type": "https://example.com/errors/bad-request" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify returned an error when attempting to update the payment method", "instance": "/api/external/v2/subscription-contracts-update-existing-payment-method", "status": 400, "title": "UserGeneratedError:Unable to update payment method at this time", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request or update failed" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "instance": "/api/external/v2/subscription-contracts-update-existing-payment-method", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to update payment methods", "instance": "/api/external/v2/subscription-contracts-update-existing-payment-method", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to update payment method" }, "404": { "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "example": { "detail": "Cannot update payment method while subscription has pending charges", "instance": "/api/external/v2/subscription-contracts-update-existing-payment-method", "status": 422, "title": "Payment method update failed", "type": "https://example.com/errors/unprocessable-entity" } } }, "description": "Payment method update failed due to business rules" } }, "summary": "Update subscription payment method", "tags": [ "Subscription Payments", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-frequency-by-compatible-plan": { "put": { "description": "Strict compatible frequency update. Use frequencyKey from /api/data/external/v2/compatible-selling-plan-frequencies or a sellingPlanId that belongs to one compatible frequency option. The existing /api/external/v2/subscription-contracts-update-frequency-by-selling-plan endpoint remains legacy for backward compatibility.", "operationId": "updateFrequencyByCompatiblePlanV2", "parameters": [ { "description": "Subscription contract ID to update. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Compatible frequency key returned by /api/data/external/v2/compatible-selling-plan-frequencies", "example": "MONTH:1", "in": "query", "name": "frequencyKey", "required": false, "schema": { "type": "string" } }, { "description": "A selling plan ID from a compatible frequency option. Provide the numeric ID without gid:// prefix.", "example": 56789, "in": "query", "name": "sellingPlanId", "required": false, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "OK" } }, "summary": "Update Subscription contract frequency by compatible selling-plan frequency", "tags": [ "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-frequency-by-selling-plan": { "put": { "operationId": "updateFrequencyBySellingPlanV2", "parameters": [ { "description": "Subscription contract ID to update. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the new selling plan. Provide the numeric ID without gid:// prefix.", "example": 56789, "in": "query", "name": "sellingPlanId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "billingPolicy": { "anchors": [], "interval": "DAY", "intervalCount": 5, "maxCycles": 6, "minCycles": 3 }, "customer": { "displayName": "abc xyz", "email": "abc@gmail.com", "firstName": "abc", "id": "gid://shopify/Customer/111111111111", "lastName": "xyz" }, "customerPaymentMethod": { "id": "gid://shopify/CustomerPaymentMethod/1111111111111111111", "instrument": { "brand": "bogus", "expiryMonth": 12, "expiryYear": 2030, "lastDigits": "1", "name": "abc xyz" } }, "deliveryMethod": { "address": { "address1": "test", "city": "Sunnyvale", "country": "United States", "province": "California", "zip": "94087" } }, "deliveryPolicy": { "anchors": [], "interval": "DAY", "intervalCount": 5 }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "154.0", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/49e73332-5dfc-4fba-9ee7-111111111", "lineDiscountedPrice": { "amount": "154.0", "currencyCode": "USD" }, "productId": "gid://shopify/Product/1111111111", "quantity": 1, "sellingPlanId": "gid://shopify/SellingPlan/691881211111", "sellingPlanName": "4 Monthly Subscription", "taxable": true, "title": "Blub Indoor", "variantId": "gid://shopify/ProductVariant/111111111111", "variantImage": { "transformedSrc": "https://cdn.shopify.com/s/files/1/0933/4738/1543/files/shopping_41111111111111111111111111111111111" } } } ] }, "nextBillingDate": "2025-08-08T13:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Subscription contract frequency updated successfully" }, "400": { "content": { "application/json": { "examples": { "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "No subscription contract found with ID 32212746535", "status": 400, "title": "Subscription contract not found", "type": "https://example.com/errors/bad-request" } }, "Invalid Interval Count": { "description": "Invalid Interval Count", "value": { "detail": "Interval count must be between 1 and 365", "status": 400, "title": "Invalid interval count", "type": "https://example.com/errors/bad-request" } }, "Invalid Interval Type": { "description": "Invalid Interval Type", "value": { "detail": "Interval must be one of: DAY, WEEK, MONTH, YEAR", "status": 400, "title": "Invalid interval type", "type": "https://example.com/errors/bad-request" } }, "Prepaid Validation Error": { "description": "Prepaid Validation Error", "value": { "detail": "Cannot bill every 5 days for 5-day deliveries in prepaid subscriptions", "status": 400, "title": "UserGeneratedError:Billing interval cannot be less than or equal to delivery interval for prepaid contracts", "type": "https://example.com/errors/bad-request" } }, "Same Interval Error": { "description": "Same Interval Error", "value": { "detail": "The subscription is already set to bill every 5 days", "status": 400, "title": "UserGeneratedError:Billing interval cannot be the same as old billing interval", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to update subscription contract" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 32212746535 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "No Matching Selling Plan": { "description": "No Matching Selling Plan", "value": { "detail": "No selling plan found for the requested billing frequency", "status": 422, "title": "No selling plan available", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Cannot modify subscription during active billing attempt", "status": 422, "title": "Unable to update subscription contract", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Update failed due to Shopify constraints" } }, "summary": "Update Subscription contract frequency by selling plan", "tags": [ "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-line-item": { "put": { "description": "Comprehensive endpoint for updating a subscription line item's quantity, price, product variant, and/or selling plan in a single API call. Changes are applied intelligently - only modified values trigger updates.\n\n**Key Features:**\n- Update any combination of: quantity, price, variant, or selling plan\n- Intelligent change detection - only updates what's different\n- Automatic handling of prepaid subscription pricing\n- Preserves existing discount cycles when updating price\n- Partial success allowed - some updates may fail while others succeed\n- Each change creates separate activity log entries\n\n**Prepaid Subscription Handling:**\nFor prepaid subscriptions (billing interval > delivery interval):\n- When `isPricePerUnit=true`: Price is multiplied by interval ratio\n- Example: Monthly billing, weekly delivery = price \u00d7 4\n- When `isPricePerUnit=false`: Price is used as total billing amount\n\n**Update Process:**\n1. Validates line item exists in the subscription\n2. Calculates interval multiplier for prepaid logic\n3. Updates in order: selling plan \u2192 price \u2192 quantity \u2192 variant\n4. Each update uses separate Shopify GraphQL mutation\n5. Failures are logged but don't block other updates\n\n**Selling Plan Updates:**\n- Can update by ID or name (name takes precedence)\n- Only updates if different from current plan\n- Useful for changing delivery frequency options\n\n**Price Updates:**\n- Preserves existing discount cycles (up to 2 cycles)\n- Recalculates cycle discounts based on new base price\n- Triggers shipping price recalculation\n- Sends price update email to customer\n\n**Quantity Updates:**\n- Validates against min/max quantity rules\n- Updates Build-a-Box totals if applicable\n- May trigger discount recalculations\n\n**Variant Updates:**\n- Changes the product itself (different SKU)\n- Validates new variant exists and is available\n- May affect pricing and discounts\n\n**Important Notes:**\n- All parameters except contractId and lineId are optional\n- Provide only the values you want to change\n- Price is always in shop's base currency\n- Changes apply to future orders only\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateLineItemV2", "parameters": [ { "description": "Subscription contract ID", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "New quantity for the line item. Leave unchanged if not updating quantity.", "example": 3, "in": "query", "name": "quantity", "required": false, "schema": { "maximum": 9999, "minimum": 1, "type": "integer" } }, { "description": "New product variant ID in Shopify GID format (e.g., gid://shopify/ProductVariant/42549172011164). This updates the associated product. Leave this parameter blank if you are not switching products.", "example": "gid://shopify/ProductVariant/42549172011164", "in": "query", "name": "variantId", "required": false, "schema": { "type": "string" } }, { "description": "Line item ID to update. Must be the full GraphQL ID including gid:// prefix", "example": "gid://shopify/SubscriptionLine/111111", "in": "query", "name": "lineId", "required": true, "schema": { "type": "string" } }, { "description": "New price for the line item in shop currency. Behavior depends on isPricePerUnit flag.", "example": 29.99, "in": "query", "name": "price", "required": false, "schema": { "format": "double", "maximum": 999999.99, "minimum": 0.01, "type": "number" } }, { "description": "Determines how price is interpreted for prepaid subscriptions:\n- true: Price is per unit (per delivery), will be multiplied by interval ratio\n- false: Price is total billing amount (for all deliveries in billing period)\n\nExample: Monthly billing, weekly delivery, price=$10\n- isPricePerUnit=true: Customer pays $40/month ($10 \u00d7 4 weeks)\n- isPricePerUnit=false: Customer pays $10/month total", "example": false, "in": "query", "name": "isPricePerUnit", "required": false, "schema": { "default": false, "type": "boolean" } }, { "description": "Name of the selling plan to apply. Takes precedence over current selling plan. Used to change delivery frequencies.", "example": "Deliver every 2 weeks", "in": "query", "name": "sellingPlanName", "required": false, "schema": { "maxLength": 255, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "billingPolicy": { "interval": "MONTH", "intervalCount": 1 }, "deliveryPolicy": { "interval": "WEEK", "intervalCount": 1 }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "119.97", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "pricingPolicy": { "basePrice": { "amount": "9.99", "currencyCode": "USD" }, "cycleDiscounts": [ { "adjustmentType": "PERCENTAGE", "adjustmentValue": { "percentage": 10.0 }, "afterCycle": 3, "computedPrice": { "amount": "107.97", "currencyCode": "USD" } } ] }, "quantity": 3, "sellingPlanId": "gid://shopify/SellingPlan/777777", "sellingPlanName": "Deliver every week", "title": "Premium Coffee - Medium Roast", "variantId": "gid://shopify/ProductVariant/98765432101" } } ] }, "nextBillingDate": "2024-03-01T00:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Line item successfully updated" }, "207": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Partial success - some updates succeeded while others failed" }, "400": { "content": { "application/json": { "examples": { "Invalid Quantity": { "description": "Invalid Quantity", "value": { "detail": "Invalid quantity value provided", "status": 400, "title": "UserGeneratedError:Quantity must be greater than 0", "type": "https://example.com/errors/bad-request" } }, "Invalid Selling Plan": { "description": "Invalid Selling Plan", "value": { "detail": "No selling plan found with the specified name", "status": 400, "title": "UserGeneratedError:Selling plan not found", "type": "https://example.com/errors/bad-request" } }, "Line Item Not Found": { "description": "Line Item Not Found", "value": { "detail": "The specified line item does not exist in this subscription", "status": 400, "title": "No line item found for contract:123456789 and line id:gid://shopify/SubscriptionLine/999999", "type": "https://example.com/errors/bad-request" } }, "Price Too Low": { "description": "Price Too Low", "value": { "detail": "Invalid price value provided", "status": 400, "title": "UserGeneratedError:Price must be greater than 0", "type": "https://example.com/errors/bad-request" } }, "Variant Not Found": { "description": "Variant Not Found", "value": { "detail": "The specified product variant does not exist", "status": 400, "title": "Product Variant not found for ID: 99999999999", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or update failed" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions" }, "404": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Subscription contract not found" } }, "summary": "Update multiple properties of a subscription line item", "tags": [ "Subscription Products", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-line-item-attributes": { "put": { "description": "Replaces the custom attributes (line item properties) of one line in a subscription contract with exactly the list you send. Any attribute you leave out is removed, Appstle's own included, so to change one attribute, read the line's current attributes first and send the complete list with your change included. A Build-A-Box line stores the box in five attributes (`products`, `_appstle-bb-id`, `__appstle-bb-name`, `_appstle-bb-product-sku` and `__appstle-bb-variants`), and a one-time line carries `_appstle-one-time-product`: leave that out and the line is no longer removed after the next order. The call acts as the merchant, so none of the customer portal's rules apply: not the editing setting, the product-change window, the minimum-cycle freeze or the box's limits. Authenticate with the `X-API-Key` header. The `api_key` query parameter is deprecated.", "operationId": "updateLineItemAttributesV2", "parameters": [ { "description": "The unique identifier of the subscription contract", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "deprecated": true, "description": "Deprecated: API key (use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "The line to update, as the line's GID from the contract's lines.", "example": "gid://shopify/SubscriptionLine/2f8c1d4e-7a3b-4c19-9d5e-6b0a1c2d3e4f", "in": "query", "name": "lineId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The line's complete list of attributes, as key and value pairs. It replaces all existing attributes: include every attribute the line should keep, because any you leave out are removed.", "items": { "$ref": "#/components/schemas/AttributeInfo" }, "type": "array" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Line item attributes updated successfully" }, "400": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Invalid contract ID, line item ID, or attribute values" }, "401": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Authentication required" }, "403": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Insufficient permissions to update the subscription" }, "404": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Subscription contract or line item not found" } }, "summary": "Update line item attributes for a subscription contract", "tags": [ "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-line-item-price": { "put": { "description": "Updates the base price of a specific product line item within a subscription contract. This endpoint intelligently handles pricing updates while preserving existing discount structures.\n\n**Key Features:**\n- Updates base price while maintaining discount cycles\n- Automatically calculates prepaid subscription prices\n- Preserves existing percentage/fixed discounts\n- Validates actual price changes before updating\n- Triggers shipping and discount recalculations\n- Sends price update notifications to customers\n\n**Base Price vs Current Price:**\n- **Base Price**: The unit price before any multipliers\n- **Current Price**: Base price \u00d7 fulfillment multiplier\n- For monthly billing/weekly delivery: Current = Base \u00d7 4\n- For pay-per-delivery: Current = Base \u00d7 1\n\n**Discount Preservation:**\nBy default, this endpoint preserves existing discount cycles:\n- Percentage discounts adjust to new base price\n- Fixed discounts remain at same dollar amount\n- Discount schedule (after X cycles) unchanged\n\n**Prepaid Subscription Handling:**\nFor prepaid subscriptions (billing interval > delivery interval):\n- Automatically calculates fulfillment multiplier\n- Updates current price accordingly\n- Ensures correct billing amounts\n\n**Post-Update Actions:**\n1. Build-a-Box discount recalculation\n2. Product discount synchronization\n3. Shipping price updates\n4. Customer email notifications\n5. Activity log creation\n\n**Important Notes:**\n- Price changes apply to future orders only\n- Cannot set price below $0.01\n- Maximum 2 discount cycles preserved\n- No update if price unchanged\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateLineItemPriceV2", "parameters": [ { "description": "Subscription contract ID. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "New base price for the line item (unit price before multipliers)", "example": 24.99, "in": "query", "name": "basePrice", "required": true, "schema": { "format": "double", "maximum": 999999.99, "minimum": 0.01, "type": "number" } }, { "description": "Line item ID to update. Must be the full GraphQL ID including the gid:// prefix", "example": "gid://shopify/SubscriptionLine/4245-cfgfg-xcfdg", "in": "query", "name": "lineId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "billingPolicy": { "interval": "MONTH", "intervalCount": 1 }, "customer": { "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "deliveryPolicy": { "interval": "WEEK", "intervalCount": 1 }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "99.96", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "pricingPolicy": { "basePrice": { "amount": "24.99", "currencyCode": "USD" }, "cycleDiscounts": [ { "adjustmentType": "PERCENTAGE", "adjustmentValue": { "percentage": 10.0 }, "afterCycle": 3, "computedPrice": { "amount": "89.96", "currencyCode": "USD" } } ] }, "quantity": 1, "title": "Premium Coffee - Monthly Supply", "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "nextBillingDate": "2024-04-01T12:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Line item price successfully updated" }, "400": { "content": { "application/json": { "examples": { "Invalid Base Price": { "description": "Invalid Base Price", "value": { "detail": "Base price must be greater than 0", "status": 400, "title": "Invalid base price", "type": "https://example.com/errors/bad-request" } }, "Invalid Line ID Format": { "description": "Invalid Line ID Format", "value": { "detail": "Line ID must be in format: gid://shopify/SubscriptionLine/[numeric_id]", "status": 400, "title": "Invalid line ID format", "type": "https://example.com/errors/bad-request" } }, "Line Item Not Found": { "description": "Line Item Not Found", "value": { "detail": "No line item found with ID: gid://shopify/SubscriptionLine/999999", "status": 400, "title": "Line item not found", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to modify subscription" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "No Price Change": { "description": "No Price Change", "value": { "detail": "The new base price is the same as the current base price", "status": 422, "title": "No update needed", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Cannot modify subscription during active billing attempt", "status": 422, "title": "UserGeneratedError:Unable to update line item price", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Unable to process the price update" } }, "summary": "Update product line item price", "tags": [ "Subscription Products", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-line-item-pricing-policy": { "put": { "description": "Sets up advanced pricing rules for a subscription line item that change based on the number of successful orders (cycles). This powerful feature enables loyalty discounts, promotional pricing tiers, and subscribe-and-save models.\n\n**What are Pricing Policies?**\nPricing policies define how a product's price changes over the subscription lifetime:\n- **Base Price**: Starting price for the product\n- **Cycle Discounts**: Price changes after specific numbers of orders\n- **Automatic Application**: System applies correct price based on order history\n\n**Supported Discount Types:**\n- **PERCENTAGE**: Percentage off base price (e.g., 10% off)\n- **FIXED**: Fixed amount off base price (e.g., $5 off)\n- **PRICE**: Override with new fixed price (e.g., $19.99)\nNote: SHIPPING and FREE_PRODUCT types are not supported by this endpoint\n\n**Cycle Counting:**\n- Cycles start at 1 (first order is cycle 1)\n- Only successful billing attempts count\n- Failed payments don't increment the cycle\n- Current cycle = 1 + count of successful past orders\n\n**Common Use Cases:**\n1. **Subscribe & Save**: 10% off starting from 3rd order\n2. **Loyalty Tiers**: 5% off after 3 orders, 10% after 6 orders\n3. **Introductory Pricing**: First 2 orders at $9.99, then $14.99\n4. **Promotional Periods**: Special price for orders 3-5\n\n**Important Limitations:**\n- Maximum 2 cycle discounts per line item\n- Cycles must have different afterCycle values\n- Changes apply to future orders only\n- Existing orders keep their original pricing\n\n**Prepaid Subscription Handling:**\nFor prepaid subscriptions (e.g., pay monthly for weekly delivery):\n- Base price is per delivery\n- Current price = base price \u00d7 delivery frequency\n- Discounts apply to base price, then multiply\n\n**Side Effects:**\n- Sends price update email to customer\n- Recalculates Build-a-Box discounts\n- Updates product discount synchronization\n- Triggers shipping price recalculation\n- Creates detailed activity log\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateLineItemPricingPolicyV2", "parameters": [ { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Subscription contract ID", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Line item ID to update. Must be full GraphQL ID format", "example": "gid://shopify/SubscriptionLine/111111", "in": "query", "name": "lineId", "required": true, "schema": { "type": "string" } }, { "description": "Base price for the product (before any discounts). This is the starting price", "example": 24.99, "in": "query", "name": "basePrice", "required": true, "schema": { "format": "double", "maximum": 999999.99, "minimum": 0.01, "type": "number" } } ], "requestBody": { "content": { "application/json": { "examples": { "Clear All Discounts": { "description": "Clear All Discounts", "value": [] }, "Fixed Amount Discounts": { "description": "Fixed Amount Discounts", "value": [ { "afterCycle": 2, "discountType": "FIXED", "value": 5.0 }, { "afterCycle": 5, "discountType": "FIXED", "value": 10.0 } ] }, "Special Pricing After Trial": { "description": "Special Pricing After Trial", "value": [ { "afterCycle": 3, "discountType": "PRICE", "value": 19.99 } ] }, "Subscribe & Save (10% off after 3 orders)": { "description": "Subscribe & Save (10% off after 3 orders)", "value": [ { "afterCycle": 3, "discountType": "PERCENTAGE", "value": 10.0 } ] }, "Tiered Loyalty Discounts": { "description": "Tiered Loyalty Discounts", "value": [ { "afterCycle": 3, "discountType": "PERCENTAGE", "value": 5.0 }, { "afterCycle": 6, "discountType": "PERCENTAGE", "value": 10.0 } ] } }, "schema": { "type": "string" } } }, "description": "List of cycle-based pricing rules. Maximum 2 cycles, must have unique afterCycle values" }, "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "24.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "pricingPolicy": { "basePrice": { "amount": "24.99", "currencyCode": "USD" }, "cycleDiscounts": [ { "adjustmentType": "PERCENTAGE", "adjustmentValue": { "percentage": 10.0 }, "afterCycle": 3, "computedPrice": { "amount": "22.49", "currencyCode": "USD" } }, { "adjustmentType": "PERCENTAGE", "adjustmentValue": { "percentage": 15.0 }, "afterCycle": 6, "computedPrice": { "amount": "21.24", "currencyCode": "USD" } } ] }, "quantity": 1, "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Pricing policy successfully updated" }, "400": { "content": { "application/json": { "examples": { "Invalid Base Price": { "description": "Invalid Base Price", "value": { "detail": "Base price must be greater than 0", "status": 400, "title": "Invalid base price", "type": "https://example.com/errors/bad-request" } }, "Invalid Cycle Configuration": { "description": "Invalid Cycle Configuration", "value": { "detail": "Cycle discounts must have unique afterCycle values", "status": 400, "title": "Invalid cycle configuration", "type": "https://example.com/errors/bad-request" } }, "Line Item Not Found": { "description": "Line Item Not Found", "value": { "detail": "No line item found with ID: gid://shopify/SubscriptionLine/999999", "status": 400, "title": "Line item not found", "type": "https://example.com/errors/bad-request" } }, "Too Many Cycles": { "description": "Too Many Cycles", "value": { "detail": "Maximum 2 cycle discounts allowed per line item", "status": 400, "title": "Too many cycle discounts", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Insufficient permissions" }, "404": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "example": { "detail": "Shopify API error: Invalid discount configuration", "status": 422, "title": "UserGeneratedError:Unable to update pricing policy", "type": "https://example.com/errors/unprocessable-entity" } } }, "description": "Unable to apply pricing policy" } }, "summary": "Update line item pricing policy with cycle-based discounts", "tags": [ "Subscription Products", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-line-item-quantity": { "put": { "description": "Updates the quantity of a specific product line item within a subscription contract. This comprehensive operation handles quantity validation, discount recalculation, and special Build-a-Box constraints.\n\n**Key Features:**\n- Updates quantity for future orders only\n- Validates minimum/maximum quantities for line items\n- Special handling for Build-a-Box subscriptions\n- Automatic discount recalculation\n- Shipping price updates\n- Activity log tracking with old/new values\n\n**Build-a-Box (BAB) Validation:**\nFor Build-a-Box subscriptions:\n- Enforces total minimum/maximum item counts\n- Only counts recurring products (excludes one-time and free items)\n- Validates across all BAB items in the subscription\n- Can be bypassed with 'allowToAddProductQuantityMinMaxReached' permission\n\n**Line Item Validation:**\nIndividual products may have:\n- Minimum quantity requirements (min_quantity attribute)\n- Maximum quantity limits (max_quantity attribute)\n- These are enforced separately from BAB constraints\n\n**Post-Update Actions:**\n1. **Activity Logging**: Records quantity change with old/new values\n2. **BAB Discount Sync**: Recalculates Build-a-Box volume discounts\n3. **Product Discount Sync**: Updates product-specific discounts\n4. **Shipping Price Update**: Recalculates shipping based on new quantity\n\n**Discount Recalculation:**\n- Build-a-Box discounts adjust based on total quantity tiers\n- May remove old discount codes and apply new ones\n- Handles 'subscription contract has changed' retry scenarios\n\n**Important Notes:**\n- Line ID must be the full GraphQL ID format\n- Quantity must be positive (minimum 1)\n- Changes apply to all future orders\n- Past or in-progress orders are not affected\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateLineItemQuantityV2", "parameters": [ { "description": "Subscription contract ID to update. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "New quantity for the line item. Must be a positive integer", "example": 3, "in": "query", "name": "quantity", "required": true, "schema": { "maximum": 9999, "minimum": 1, "type": "integer" } }, { "description": "Line item ID to update. Must be the full GraphQL ID including the gid:// prefix", "example": "gid://shopify/SubscriptionLine/111111", "in": "query", "name": "lineId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "customer": { "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "discounts": { "edges": [ { "node": { "id": "gid://shopify/SubscriptionManualDiscount/222222", "targetType": "ALL_LINES", "title": "BUILD_A_BOX_DISCOUNT_ABC123", "value": { "percentage": 15.0 } } } ] }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "44.97", "currencyCode": "USD" }, "customAttributes": [ { "key": "_min_quantity", "value": "1" }, { "key": "_max_quantity", "value": "5" } ], "id": "gid://shopify/SubscriptionLine/111111", "quantity": 3, "title": "Premium Coffee - Dark Roast", "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "nextBillingDate": "2024-04-01T12:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Product line item quantity updated successfully" }, "400": { "content": { "application/json": { "examples": { "Build-a-Box Maximum Exceeded": { "description": "Build-a-Box Maximum Exceeded", "value": { "code": "maxQuantityReached", "detail": "Build-a-Box subscriptions have a maximum total quantity limit", "status": 400, "title": "UserGeneratedError:Maximum 12 quantity is required", "type": "https://example.com/errors/bad-request" } }, "Build-a-Box Minimum Not Met": { "description": "Build-a-Box Minimum Not Met", "value": { "code": "minQuantityNotReached", "detail": "Build-a-Box subscriptions require a minimum total quantity", "status": 400, "title": "UserGeneratedError:Minimum 6 quantity is required", "type": "https://example.com/errors/bad-request" } }, "Invalid Quantity Value": { "description": "Invalid Quantity Value", "value": { "detail": "Quantity must be a positive integer", "status": 400, "title": "Invalid quantity", "type": "https://example.com/errors/bad-request" } }, "Line Item Not Found": { "description": "Line Item Not Found", "value": { "detail": "The specified line item does not exist in this subscription", "status": 400, "title": "No line item found for contract:123456789 and line id:gid://shopify/SubscriptionLine/999999", "type": "https://example.com/errors/bad-request" } }, "Quantity Below Minimum": { "description": "Quantity Below Minimum", "value": { "detail": "The product has a minimum quantity requirement", "status": 400, "title": "UserGeneratedError:Minimum quantity 2 is required for this product", "type": "https://example.com/errors/bad-request" } }, "Quantity Exceeds Maximum": { "description": "Quantity Exceeds Maximum", "value": { "detail": "The product has a maximum quantity limit", "status": 400, "title": "UserGeneratedError:Maximum quantity 5 is allowed for this product", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to update subscription" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Draft Commit Error": { "description": "Draft Commit Error", "value": { "detail": "The subscription contract has changed. Please try again.", "status": 422, "title": "UserGeneratedError:Unable to commit subscription changes", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Cannot modify subscription during active billing attempt", "status": 422, "title": "UserGeneratedError:Unable to update line item quantity", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Unable to process the quantity update due to Shopify API constraints" } }, "summary": "Update product line item quantity in subscription", "tags": [ "Subscription Products", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-line-item-selling-plan": { "put": { "description": "Updates the selling plan associated with a specific product line item in a subscription contract. Selling plans define the delivery schedule, pricing rules, and billing policies for subscription products.\n\n**What are Selling Plans?**\nSelling plans are Shopify's way of defining subscription rules for products:\n- **Delivery Schedule**: How often the product is delivered (e.g., 'every 2 weeks', 'monthly')\n- **Pricing Policy**: Discounts and pricing tiers (e.g., '10% off', 'first order free')\n- **Billing Policy**: When and how often customer is charged\n- **Plan Name**: Customer-facing description like 'Deliver every month'\n\n**Key Features:**\n- Update by selling plan ID or name (name takes precedence if both provided)\n- Validates line item exists before attempting update\n- Only creates activity log if plan actually changes\n- Uses Shopify's draft system for safe updates\n- Preserves existing line item attributes and customizations\n\n**Common Use Cases:**\n- Change delivery frequency: Weekly \u2192 Monthly\n- Switch pricing tiers: Regular \u2192 VIP pricing\n- Update from old plan to new plan with better terms\n- Migrate products to new selling plan groups\n- Apply seasonal or promotional plans\n\n**Update Process:**\n1. Validates subscription contract and line item exist\n2. Creates a draft of the subscription contract\n3. Updates the line item's selling plan in the draft\n4. Commits the draft to apply changes\n5. Records activity log if plan changed\n\n**Impact of Selling Plan Changes:**\n- **Delivery Schedule**: Next and future orders follow new schedule\n- **Pricing**: New plan's pricing applies from next billing\n- **Discounts**: Plan-specific discounts are recalculated\n- **Billing**: Billing frequency may change with the plan\n\n**Finding Selling Plans:**\nTo find available selling plans:\n1. Check product's selling plan groups in Shopify admin\n2. Use Shopify's GraphQL API to query selling plans\n3. Plans must be active and associated with the product\n\n**Important Notes:**\n- Both sellingPlanId and sellingPlanName are optional, but at least one required\n- If both provided, both are updated (name doesn't override ID)\n- Plan must be valid for the product variant\n- Changes apply to future orders only\n- No customer notification sent (consider sending separately)\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateLineItemSellingPlan", "parameters": [ { "description": "The unique identifier of the subscription contract", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "The unique identifier of the line item in the subscription contract. Must be in full GraphQL ID format", "example": "gid://shopify/SubscriptionLine/987654321", "in": "query", "name": "lineId", "required": true, "schema": { "type": "string" } }, { "description": "The unique identifier of the new selling plan. Provide the numeric ID without gid:// prefix. Required if sellingPlanName is not provided. The plan must be:\n- Active in your Shopify store\n- Associated with the product variant\n- Part of an active selling plan group", "example": 56789, "in": "query", "name": "sellingPlanId", "required": false, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "The customer-facing name of the new selling plan. Required if sellingPlanId is not provided. This is the name shown to customers like 'Deliver every 2 weeks' or 'Monthly subscription'. Must match exactly as configured in Shopify", "example": "Deliver every month", "in": "query", "name": "sellingPlanName", "required": false, "schema": { "maxLength": 255, "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "customer": { "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "deliveryPolicy": { "interval": "MONTH", "intervalCount": 1 }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "27.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/987654321", "pricingPolicy": { "basePrice": { "amount": "29.99", "currencyCode": "USD" }, "cycleDiscounts": [ { "adjustmentType": "PERCENTAGE", "adjustmentValue": { "percentage": 10.0 }, "afterCycle": 0 } ] }, "quantity": 2, "sellingPlanId": "gid://shopify/SellingPlan/56789", "sellingPlanName": "Deliver every month", "title": "Premium Coffee - Dark Roast", "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "nextBillingDate": "2024-04-01T00:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Selling plan updated successfully" }, "400": { "content": { "application/json": { "examples": { "Both Parameters Missing": { "description": "Both Parameters Missing", "value": { "detail": "At least one of sellingPlanId or sellingPlanName must be provided", "status": 400, "title": "UserGeneratedError:Both Selling Plan Id and Selling Plan Name cannot be null", "type": "https://example.com/errors/bad-request" } }, "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "No subscription contract found with ID 123456789", "status": 400, "title": "Subscription contract not found", "type": "https://example.com/errors/bad-request" } }, "Incompatible Selling Plan": { "description": "Incompatible Selling Plan", "value": { "detail": "The selected selling plan cannot be applied to this product variant", "status": 400, "title": "UserGeneratedError:Selling plan is not compatible with variant", "type": "https://example.com/errors/bad-request" } }, "Invalid Selling Plan": { "description": "Invalid Selling Plan", "value": { "detail": "The specified selling plan does not exist or is not available for this product", "status": 400, "title": "UserGeneratedError:Selling plan not found", "type": "https://example.com/errors/bad-request" } }, "Line Item Not Found": { "description": "Line Item Not Found", "value": { "detail": "No line item found with ID gid://shopify/SubscriptionLine/987654321 in contract 123456789", "status": 400, "title": "Line item not found", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid contract ID, line ID, or selling plan details" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to modify the subscription" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found in the system", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract or line item not found" }, "422": { "content": { "application/json": { "examples": { "Draft Commit Failed": { "description": "Draft Commit Failed", "value": { "detail": "Cannot update subscription during active billing attempt", "status": 422, "title": "UserGeneratedError:Unable to commit changes", "type": "https://example.com/errors/unprocessable-entity" } }, "Draft Creation Failed": { "description": "Draft Creation Failed", "value": { "detail": "Shopify API error: Subscription is currently being modified", "status": 422, "title": "Unable to create subscription draft", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Unable to update selling plan due to Shopify constraints" } }, "summary": "Update selling plan for a subscription line item", "tags": [ "Subscription Products", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-max-cycles": { "put": { "description": "Updates the maximum number of billing cycles (orders) after which a subscription will automatically terminate. This creates a fixed-duration subscription that ends after a specific number of orders.\n\n**What are Maximum Cycles?**\nMaximum cycles define subscription duration limits where:\n- Subscription automatically cancels after the specified number of orders\n- No further orders are generated once maximum is reached\n- Useful for fixed-term offers, trials, or seasonal subscriptions\n- Customer is notified before final order (if configured)\n\n**Key Features:**\n- Cannot set below current cycle count (prevents immediate cancellation)\n- Setting to null creates an indefinite subscription\n- Automatically reschedules order queue based on new limit\n- Preserves all other subscription settings\n- Validates against current subscription progress\n\n**Current Cycle Calculation:**\n- Current cycle = Successful billing attempts + 1\n- Failed payments don't count toward maximum\n- First order is cycle 1, second is cycle 2, etc.\n- System prevents setting max below current position\n\n**Common Use Cases:**\n- **Trial Subscriptions**: '3-box trial' that auto-ends\n- **Seasonal Programs**: '6-month summer subscription'\n- **Limited Series**: '12-issue magazine subscription'\n- **Promotional Offers**: 'First 5 boxes at special price'\n- **Gift Subscriptions**: Fixed duration gifts that don't renew\n\n**What Happens at Maximum:**\nWhen a subscription reaches its maximum cycles:\n1. Final order is processed normally\n2. Subscription status changes to CANCELLED\n3. No future orders are scheduled\n4. Customer receives cancellation notification\n5. Cannot be reactivated (new subscription required)\n\n**Interaction with Min Cycles:**\n- Can have both min and max (e.g., 3 min, 12 max)\n- Min cycles enforces commitment period\n- Max cycles enforces termination\n- Common pattern: Commitment with defined end\n\n**Queue Management:**\nAfter updating max cycles:\n- System recalculates future order schedule\n- Removes orders beyond the new maximum\n- Adjusts upcoming order notifications\n- Updates subscription end date projections\n\n**Important Notes:**\n- Validation prevents accidental immediate cancellation\n- Changes apply to future billing cycles only\n- Activity log tracks old and new values\n- Consider customer communication for changes\n- Setting null removes any duration limit\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateMaxCyclesV2", "parameters": [ { "description": "Contract ID", "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } }, { "description": "Maximum Cycles. The total number of orders after which the subscription will automatically terminate. Must be greater than or equal to the current cycle count and any configured minimum cycles. Common values:\n- 3: Three-order trial\n- 6: Six-month seasonal subscription\n- 12: Annual subscription\n- 24: Two-year commitment\n- null: Ongoing subscription with no end date", "example": 12, "in": "query", "name": "maxCycles", "required": true, "schema": { "maximum": 9999, "minimum": 1, "nullable": true, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "billingPolicy": { "anchors": [ { "day": 15, "type": "MONTHDAY" } ], "interval": "MONTH", "intervalCount": 1, "maxCycles": 12, "minCycles": 3 }, "createdAt": "2024-01-01T00:00:00Z", "customer": { "displayName": "John Doe", "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "deliveryPolicy": { "interval": "MONTH", "intervalCount": 1 }, "id": "gid://shopify/SubscriptionContract/123456789", "lastBillingAttemptDate": "2024-03-01T00:00:00Z", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "39.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "quantity": 1, "title": "12-Month Subscription Box", "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "nextBillingDate": "2024-04-01T00:00:00Z", "orders": { "edges": [ { "node": { "createdAt": "2024-03-01T00:00:00Z", "financialStatus": "PAID", "fulfillmentStatus": "FULFILLED", "id": "gid://shopify/Order/5678901234" } }, { "node": { "createdAt": "2024-02-01T00:00:00Z", "financialStatus": "PAID", "fulfillmentStatus": "FULFILLED", "id": "gid://shopify/Order/5678901233" } }, { "node": { "createdAt": "2024-01-01T00:00:00Z", "financialStatus": "PAID", "fulfillmentStatus": "FULFILLED", "id": "gid://shopify/Order/5678901232" } } ] }, "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Maximum cycles updated successfully" }, "400": { "content": { "application/json": { "examples": { "Already Cancelled": { "description": "Already Cancelled", "value": { "detail": "Cannot modify maximum cycles for cancelled subscriptions", "status": 400, "title": "UserGeneratedError:Cannot update cancelled subscription", "type": "https://example.com/errors/bad-request" } }, "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "No subscription contract found with ID 123456789", "status": 400, "title": "Subscription contract not found", "type": "https://example.com/errors/bad-request" } }, "Invalid Max Cycles Value": { "description": "Invalid Max Cycles Value", "value": { "detail": "Maximum cycles must be a positive integer", "status": 400, "title": "Invalid maximum cycles value", "type": "https://example.com/errors/bad-request" } }, "Max Cycles Below Current Cycle": { "description": "Max Cycles Below Current Cycle", "value": { "detail": "Cannot set maximum cycles to 3 when subscription has already completed 5 cycles", "status": 400, "title": "UserGeneratedError:Max cycles cannot be set to less than current cycle", "type": "https://example.com/errors/bad-request" } }, "Max Less Than Min Cycles": { "description": "Max Less Than Min Cycles", "value": { "detail": "Cannot set maximum cycles (6) to less than minimum cycles (12)", "status": 400, "title": "UserGeneratedError:Maximum cycles cannot be less than minimum cycles", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to update maximum cycles" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found in the system", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Queue Update Failed": { "description": "Queue Update Failed", "value": { "detail": "Failed to reschedule upcoming orders based on new maximum cycles", "status": 422, "title": "Unable to update order queue", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Cannot modify subscription during active billing attempt", "status": 422, "title": "UserGeneratedError:Unable to update maximum cycles", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Maximum cycles update failed due to Shopify constraints" } }, "summary": "Update maximum cycles for a subscription contract", "tags": [ "Subscription Management", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-min-cycles": { "put": { "description": "Updates the minimum number of billing cycles (orders) that a customer must complete before they can cancel their subscription. This creates a commitment period that helps with customer retention and business predictability.\n\n**What are Minimum Cycles?**\nMinimum cycles represent a commitment period where:\n- Customers must complete a specified number of orders\n- Cancellation is blocked until the minimum is met\n- Often tied to special pricing or promotional offers\n- Counted from the subscription start date\n\n**Key Features:**\n- Updates commitment period for existing subscriptions\n- Can increase or decrease minimum cycles\n- Setting to null removes the minimum commitment\n- Preserves all other subscription settings\n- Automatically handles invalid discount codes\n- Updates future billing queue after change\n\n**Common Use Cases:**\n- **Promotional Offers**: '3-month minimum for 50% off'\n- **Hardware Subsidies**: '12-month commitment with free device'\n- **Loyalty Programs**: Reduce minimum after customer proves loyalty\n- **Seasonal Campaigns**: Temporary commitment requirements\n- **Contract Adjustments**: Customer service exceptions\n\n**Impact on Customers:**\n- Cannot cancel via portal until minimum cycles complete\n- Pause/resume typically still allowed (check settings)\n- Shows commitment status in customer portal\n- No automatic notification sent (consider sending separately)\n\n**Cycle Counting:**\n- Only successful billing attempts count toward minimum\n- Failed payments don't increment the cycle count\n- Skipped orders (if allowed) don't count\n- Current cycle = successful past orders + 1\n\n**Interaction with Max Cycles:**\n- Min cycles must be less than or equal to max cycles\n- If max cycles exist, subscription auto-cancels after maximum\n- Common pattern: 3 min cycles, 12 max cycles\n\n**Best Practices:**\n- Clearly communicate commitment terms upfront\n- Consider grandfathering existing customers\n- Use reasonable minimums (typically 3-12 cycles)\n- Document reason for changes in activity logs\n- Send customer notification for transparency\n\n**Important Notes:**\n- Changes apply immediately to cancellation logic\n- Doesn't affect past or in-progress orders\n- Customer portal respects this setting automatically\n- Activity log tracks old and new values\n- Consider legal requirements in your jurisdiction\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateMinCyclesV2", "parameters": [ { "description": "Contract ID", "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } }, { "description": "Minimum Number of Orders. The minimum number of billing cycles a customer must complete before being allowed to cancel. Set to null to remove the minimum commitment. Common values:\n- 3: Three-month commitment\n- 6: Six-month commitment\n- 12: Annual commitment\n- null: No commitment", "example": 6, "in": "query", "name": "minCycles", "required": false, "schema": { "maximum": 9999, "minimum": 1, "nullable": true, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "billingPolicy": { "anchors": [ { "day": 1, "type": "MONTHDAY" } ], "interval": "MONTH", "intervalCount": 1, "maxCycles": null, "minCycles": 6 }, "createdAt": "2024-01-01T00:00:00Z", "customer": { "displayName": "John Doe", "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "customerPaymentMethod": { "id": "gid://shopify/CustomerPaymentMethod/123456", "instrument": { "__typename": "CustomerCreditCard", "brand": "VISA", "expiryMonth": 12, "expiryYear": 2025, "lastDigits": "4242" } }, "deliveryPolicy": { "interval": "MONTH", "intervalCount": 1 }, "id": "gid://shopify/SubscriptionContract/123456789", "lines": { "edges": [ { "node": { "currentPrice": { "amount": "49.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionLine/111111", "quantity": 1, "title": "Premium Subscription Box", "variantId": "gid://shopify/ProductVariant/42549172011164" } } ] }, "nextBillingDate": "2024-04-01T00:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Minimum cycles updated successfully" }, "400": { "content": { "application/json": { "examples": { "Contract Already Cancelled": { "description": "Contract Already Cancelled", "value": { "detail": "Cannot modify minimum cycles for cancelled subscriptions", "status": 400, "title": "UserGeneratedError:Cannot update cancelled subscription", "type": "https://example.com/errors/bad-request" } }, "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "No subscription contract found with ID 123456789", "status": 400, "title": "Subscription contract not found", "type": "https://example.com/errors/bad-request" } }, "Invalid Contract ID": { "description": "Invalid Contract ID", "value": { "detail": "Contract ID must be a positive number", "status": 400, "title": "Invalid contract ID", "type": "https://example.com/errors/bad-request" } }, "Invalid Min Cycles Value": { "description": "Invalid Min Cycles Value", "value": { "detail": "Minimum cycles must be a positive integer or null", "status": 400, "title": "Invalid minimum cycles value", "type": "https://example.com/errors/bad-request" } }, "Min Exceeds Max Cycles": { "description": "Min Exceeds Max Cycles", "value": { "detail": "Minimum cycles (12) cannot be greater than maximum cycles (6)", "status": 400, "title": "UserGeneratedError:Minimum cycles cannot exceed maximum cycles", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to update minimum cycles" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found in the system", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Invalid Discount Code": { "description": "Invalid Discount Code", "value": { "detail": "Invalid discount code detected. System will automatically remove and retry.", "status": 422, "title": "Contract draft discount with title COMMIT3 is invalid", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Cannot modify subscription during active billing attempt", "status": 422, "title": "UserGeneratedError:Unable to update minimum cycles", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Minimum cycles update failed due to Shopify constraints" } }, "summary": "Update minimum cycles for a subscription contract", "tags": [ "Subscription Management", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-multiple-line-item-attributes": { "put": { "description": "Updates custom attributes for multiple line items within a subscription contract. The request body must be a JSON object where each key is a line item identifier (as a String) and each value is a list of AttributeInfo objects containing attribute key/value pairs. For example: { \"gid://shopify/SubscriptionLineItem/987654321\": [ { \"key\": \"color\", \"value\": \"red\" }, { \"key\": \"size\", \"value\": \"M\" } ] }. The service validates that the contract exists and that each specified line item is eligible for update. Authentication is performed via the X-API-Key header (the 'api_key' parameter is deprecated).", "operationId": "updateMultipleLineItemAttributesV2", "parameters": [ { "description": "The unique identifier of the subscription contract", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": { "items": { "$ref": "#/components/schemas/AttributeInfo" }, "type": "array" }, "type": "object" } } }, "description": "A JSON object where each key is a line item ID (e.g., \"gid://shopify/SubscriptionLineItem/987654321\") and each value is a list of AttributeInfo objects containing the attribute key and value. Example: { \"gid://shopify/SubscriptionLineItem/987654321\": [ { \"key\": \"color\", \"value\": \"red\" }, { \"key\": \"size\", \"value\": \"M\" } ] }", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Multiple line item attributes updated successfully" }, "400": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Invalid contract ID, line item IDs, or attribute values" }, "401": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Authentication required" }, "403": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Insufficient permissions to update the subscription" }, "404": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Subscription contract or one of the specified line items not found" }, "422": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Unable to update one or more line item attributes due to subscription constraints" } }, "summary": "Update multiple line item attributes for a subscription contract", "tags": [ "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-order-note/{contractId}": { "put": { "description": "Updates the order note that will be added to all future orders generated by this subscription. Order notes help merchants track special instructions, customer preferences, or internal information about the subscription.\n\n**Key Features:**\n- Note is automatically added to all future recurring orders\n- Visible in both merchant portal and customer portal\n- Appears in Shopify order details for easy reference\n- Changes apply to future orders only (existing orders unchanged)\n**Common Use Cases:**\n- Customer preferences: \"No nuts - severe allergy\"\n- Delivery instructions: \"Leave package at side door\"\n- Gift messages: \"Happy Birthday from Mom!\"\n- Internal notes: \"VIP customer - priority handling\"\n- Processing instructions: \"Include sample with each order\"\n\n**Important Notes:**\n- Empty string clears the existing note\n- No character limit imposed by API (check Shopify limits)\n- HTML is not rendered - stored as plain text\n- Updates are logged in activity history\n- Note persists until explicitly changed\n\n**Order Generation:**\nWhen Appstle creates recurring orders:\n1. Retrieves current order note from subscription\n2. Adds note to new Shopify order\n3. Note appears in order details immediately\n4. Merchants can still edit individual order notes\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateOrderNoteV2", "parameters": [ { "description": "Subscription contract ID to update", "example": 123456789, "in": "path", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } }, { "description": "Note text to be added to all future orders. Can include special instructions, preferences, or internal notes. Pass empty string to clear existing note. HTML tags are not rendered - stored as plain text.", "examples": { "Allergy Note": { "description": "Allergy Note", "value": "No peanuts - severe allergy" }, "Clear Note": { "description": "Clear Note" }, "Delivery Instruction": { "description": "Delivery Instruction", "value": "Ring doorbell twice, leave at back door" }, "Gift Message": { "description": "Gift Message", "value": "Happy Anniversary! Love, Sarah" }, "Internal Note": { "description": "Internal Note", "value": "VIP Customer - Include free sample" } }, "in": "query", "name": "orderNote", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": true, "schema": { "type": "boolean" } } }, "description": "Order note successfully updated", "headers": { "X-Application-Context": { "description": "Application context with success message", "schema": { "example": "appname:Subscription Updated:", "type": "string" }, "style": "simple" } } }, "400": { "content": { "application/json": { "examples": { "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "No subscription contract found with ID: 123456789", "instance": "/api/external/v2/subscription-contracts-update-order-note/123456789", "status": 400, "title": "Contract not found", "type": "https://example.com/errors/bad-request" } }, "Invalid Contract ID": { "description": "Invalid Contract ID", "value": { "detail": "Contract does not belong to this shop", "instance": "/api/external/v2/subscription-contracts-update-order-note/123456789", "status": 400, "title": "invalid id", "type": "https://example.com/errors/bad-request" } }, "Missing Order Note": { "description": "Missing Order Note", "value": { "detail": "Required request parameter 'orderNote' is not present", "instance": "/api/external/v2/subscription-contracts-update-order-note/123456789", "status": 400, "title": "Missing required parameter", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request or contract not found" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "instance": "/api/external/v2/subscription-contracts-update-order-note/123456789", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "instance": "/api/external/v2/subscription-contracts-update-order-note/123456789", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "instance": "/api/external/v2/subscription-contracts-update-order-note/123456789", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" } }, "summary": "Update order note for subscription", "tags": [ "Subscription Management", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-payment-method": { "put": { "description": "Triggers Shopify to send an email to the subscription customer with a secure link to update their payment method. This endpoint initiates Shopify's native payment update flow without requiring direct payment handling.\n\n**Key Features:**\n- Sends official Shopify payment update email to customer\n- Customer receives secure link to Shopify-hosted payment update page\n- No PCI compliance required - Shopify handles all payment data\n- Supports all Shopify-supported payment methods\n- Automatically updates subscription after customer completes the process\n\n**Process Flow:**\n1. API call triggers email send request to Shopify\n2. Shopify sends branded email to customer's registered email\n3. Customer clicks secure link in email\n4. Customer authenticates on Shopify-hosted page\n5. Customer adds/updates payment method\n6. Subscription automatically uses new payment method\n\n**Email Details:**\n- Sent from Shopify's email servers\n- Uses store's configured sender email\n- Subject line typically: \"Update your payment method\"\n- Contains secure, time-limited link\n- Shopify-branded with store information\n\n**Use Cases:**\n- Failed payment recovery\n- Expiring credit card updates\n- Customer-requested payment changes\n- Proactive payment method maintenance\n\n**Important Notes:**\n- Customer must have valid email address\n- Email cannot be customized (Shopify template)\n- Link expiration time set by Shopify\n- Multiple emails can be sent if needed\n- No webhook for completion - poll contract for updates\n\n**Rate Limiting:**\n- Subject to Shopify's email sending limits\n- Recommended: Wait 24 hours between sends to same customer\n- Excessive sends may be blocked by Shopify\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updatePaymentMethodV2", "parameters": [ { "description": "Subscription contract ID for payment method update. Must be a valid contract ID that belongs to the authenticated shop.", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "message": "Payment method update email sent successfully" } } }, "description": "Payment update email sent successfully" }, "400": { "content": { "application/json": { "examples": { "Cancelled Subscription": { "description": "Cancelled Subscription", "value": { "detail": "Payment method cannot be updated for cancelled subscriptions", "instance": "/api/external/v2/subscription-contracts-update-payment-method", "status": 400, "title": "UserGeneratedError:Cannot update cancelled subscription", "type": "https://example.com/errors/bad-request" } }, "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "No subscription contract found with ID: 123456789", "instance": "/api/external/v2/subscription-contracts-update-payment-method", "status": 400, "title": "Contract not found", "type": "https://example.com/errors/bad-request" } }, "Customer Not Found": { "description": "Customer Not Found", "value": { "detail": "Customer associated with payment method not found", "instance": "/api/external/v2/subscription-contracts-update-payment-method", "status": 400, "title": "UserGeneratedError:Customer not found", "type": "https://example.com/errors/bad-request" } }, "Email Service Error": { "description": "Email Service Error", "value": { "detail": "Shopify email service temporarily unavailable", "instance": "/api/external/v2/subscription-contracts-update-payment-method", "status": 400, "title": "UserGeneratedError:Email could not be sent", "type": "https://example.com/errors/bad-request" } }, "Invalid Email Address": { "description": "Invalid Email Address", "value": { "detail": "Cannot send email to invalid email address", "instance": "/api/external/v2/subscription-contracts-update-payment-method", "status": 400, "title": "UserGeneratedError:Customer email is invalid", "type": "https://example.com/errors/bad-request" } }, "No Payment Method": { "description": "No Payment Method", "value": { "detail": "Subscription has no associated payment method", "instance": "/api/external/v2/subscription-contracts-update-payment-method", "status": 400, "title": "Payment method not found", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request or email send failed" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "instance": "/api/external/v2/subscription-contracts-update-payment-method", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to update payment methods", "instance": "/api/external/v2/subscription-contracts-update-payment-method", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions" }, "404": { "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Rate Limit Exceeded": { "description": "Rate Limit Exceeded", "value": { "detail": "Payment update email was recently sent. Please wait before sending another.", "instance": "/api/external/v2/subscription-contracts-update-payment-method", "status": 422, "title": "UserGeneratedError:Too many emails sent", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Unable to send payment update email at this time", "instance": "/api/external/v2/subscription-contracts-update-payment-method", "status": 422, "title": "Shopify API error", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Email cannot be sent due to business rules" } }, "summary": "Send payment method update email to customer", "tags": [ "Subscription Payments", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-shipping-address": { "put": { "description": "Updates the shipping address or delivery method for a subscription contract. Supports standard shipping, local delivery, and pickup options with comprehensive address validation.\n\n**Delivery Method Types:**\n- **SHIPPING**: Standard shipping to customer address (default)\n- **LOCAL**: Local delivery within specified zip codes\n- **PICK_UP**: Customer pickup at designated location\n\n**Key Features:**\n- Zip code restrictions for customer portal access\n- Optional ShipperHQ address validation\n- Automatic phone number handling for local delivery\n- Email notifications to customers\n- Shipping price recalculation\n- Activity log tracking with old/new addresses\n\n**Zip Code Validation (Customer Portal Only):**\nWhen called from customer portal:\n- Standard shipping: Validates against 'allowToSpecificZipCode' setting\n- Local delivery: Validates against 'allowToSpecificZipCodeForLocalDelivery' setting\n- External API calls bypass zip code restrictions\n\n**Address Validation:**\n- If ShipperHQ is configured, addresses are validated for deliverability\n- Invalid addresses will return appropriate error messages\n- Helps prevent failed deliveries and shipping issues\n\n**Special Handling:**\n- Local delivery addresses missing phone numbers are auto-populated\n- Uses customer's phone if available, otherwise defaults to placeholder\n- Handles missing address components gracefully\n\n**Post-Update Actions:**\n- Sends 'SHIPPING_ADDRESS_UPDATED' email to customer\n- Creates activity log with address change details\n- Triggers asynchronous shipping price recalculation\n- May remove invalid discount codes automatically\n\n**Important Notes:**\n- Province codes should use ISO 3166-2 format (e.g., 'NY' for New York)\n- Country codes should use ISO 3166-1 alpha-2 format (e.g., 'US')\n- Phone numbers should include country code for international addresses\n- Pickup locations must be pre-configured in Shopify\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateShippingAddressV2", "parameters": [ { "description": "Subscription contract ID to update. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "International Address": { "description": "International Address", "value": { "address1": "123 Rue de la Paix", "city": "Paris", "countryCode": "FR", "firstName": "Pierre", "lastName": "Dubois", "methodType": "SHIPPING", "phone": "+33123456789", "provinceCode": "75", "zip": "75001" } }, "Local Delivery Address": { "description": "Local Delivery Address", "value": { "address1": "789 Local Ave", "city": "Brooklyn", "countryCode": "US", "firstName": "Jane", "lastName": "Smith", "methodType": "LOCAL", "phone": "+17185551234", "provinceCode": "NY", "zip": "11201" } }, "Pickup Location": { "description": "Pickup Location", "value": { "methodType": "PICK_UP", "pickupLocationId": "gid://shopify/DeliveryLocationGroup/123456" } }, "Standard Shipping Address": { "description": "Standard Shipping Address", "value": { "address1": "456 New Street", "address2": "Suite 200", "city": "Los Angeles", "company": "Acme Corp", "countryCode": "US", "firstName": "John", "lastName": "Doe", "methodType": "SHIPPING", "phone": "+12135551234", "provinceCode": "CA", "zip": "90001" } } }, "schema": { "$ref": "#/components/schemas/ChangeShippingAddressVM" } } }, "description": "New shipping address and delivery method details", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": { "customer": { "email": "customer@example.com", "id": "gid://shopify/Customer/987654321" }, "deliveryMethod": { "__typename": "SubscriptionDeliveryMethodShipping", "address": { "address1": "456 New Street", "address2": "Suite 200", "city": "Los Angeles", "company": "Acme Corp", "countryCode": "US", "firstName": "John", "lastName": "Doe", "phone": "+12135551234", "provinceCode": "CA", "zip": "90001" } }, "deliveryPrice": { "amount": "7.99", "currencyCode": "USD" }, "id": "gid://shopify/SubscriptionContract/123456789", "nextBillingDate": "2024-03-01T00:00:00Z", "status": "ACTIVE" } } }, "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Shipping address successfully updated" }, "400": { "content": { "application/json": { "examples": { "Invalid Address (ShipperHQ)": { "description": "Invalid Address (ShipperHQ)", "value": { "detail": "The provided address could not be validated. Please check the address details.", "status": 400, "title": "Address validation failed", "type": "https://example.com/errors/bad-request" } }, "Invalid Method Type": { "description": "Invalid Method Type", "value": { "detail": "Method type must be one of: SHIPPING, LOCAL, PICK_UP", "status": 400, "title": "Invalid delivery method", "type": "https://example.com/errors/bad-request" } }, "Missing Required Fields": { "description": "Missing Required Fields", "value": { "detail": "Required fields missing: address1, city, countryCode", "status": 400, "title": "Validation error", "type": "https://example.com/errors/bad-request" } }, "Shop Settings Not Found": { "description": "Shop Settings Not Found", "value": { "detail": "Store configuration is missing or incomplete", "status": 400, "title": "Shop settings not found for shop: example-store", "type": "https://example.com/errors/bad-request" } }, "Zip Code Not Allowed": { "description": "Zip Code Not Allowed", "value": { "detail": "Delivery to zip code 12345 is not available for this subscription", "status": 400, "title": "UserGeneratedError: That zip code is not allowed", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to modify subscription" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Invalid Pickup Location": { "description": "Invalid Pickup Location", "value": { "detail": "The specified pickup location is not available", "status": 422, "title": "UserGeneratedError:Pickup location not configured", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Invalid province code for selected country", "status": 422, "title": "UserGeneratedError:Unable to update delivery address", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Unable to process the address update due to Shopify API constraints" } }, "summary": "Update subscription delivery address and method", "tags": [ "Subscription Management", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts-update-status": { "put": { "description": "Updates the status of a subscription contract to ACTIVE, PAUSED, or CANCELLED. This endpoint manages the lifecycle of subscriptions with automatic state tracking and notifications.\n\n**Status Transitions:**\n- **ACTIVE**: Resumes a paused subscription, enabling future billing and deliveries\n- **PAUSED**: Temporarily suspends all billing and deliveries until manually resumed\n- **CANCELLED**: Permanently terminates the subscription (irreversible)\n\n**Key Features:**\n- Validates status transitions (prevents same-status updates)\n- Tracks status change timestamps for audit trails\n- Sends automated email notifications to customers\n- Creates detailed activity logs for each status change\n- Handles concurrent modifications with automatic retry\n- Adjusts next billing date when resuming subscriptions\n\n**Permission Requirements (Customer Portal):**\nWhen called from customer portal context:\n- PAUSED status requires 'pauseResumeSub' permission\n- ACTIVE status (resuming) requires 'resumeSub' permission \n- CANCELLED status requires 'cancelSub' permission\n- External API calls bypass these permission checks\n\n**Status Change Side Effects:**\n- **Activating**: Recalculates next billing date, marks activation timestamp\n- **Pausing**: Stops all scheduled orders, marks pause timestamp\n- **Cancelling**: Terminates subscription permanently, marks cancellation timestamp\n\n**Error Recovery:**\nThe system automatically handles:\n- Invalid discount codes by removing them and retrying\n- Concurrent modifications by retrying the operation\n- This ensures reliable status updates in production environments\n\n**Important Notes:**\n- Status values are case-insensitive\n- Cancelled subscriptions cannot be reactivated\n- Paused subscriptions retain all settings and can be resumed\n- Email notifications are sent automatically unless internally suppressed\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "updateStatusV2", "parameters": [ { "description": "Subscription contract ID to update. Provide the numeric ID without the gid:// prefix", "example": 123456789, "in": "query", "name": "contractId", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "New status for the subscription contract. Case-insensitive.", "examples": { "Cancel subscription": { "description": "Cancel subscription", "value": "CANCELLED" }, "Pause subscription": { "description": "Pause subscription", "value": "PAUSED" }, "Resume subscription": { "description": "Resume subscription", "value": "ACTIVE" } }, "in": "query", "name": "status", "required": true, "schema": { "enum": [ "ACTIVE", "PAUSED", "CANCELLED", "active", "paused", "cancelled" ], "type": "string" } }, { "deprecated": true, "description": "API Key (Deprecated - Use X-API-Key header instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "description": "API Key for authentication", "example": "apst_your-api-key-here", "in": "header", "name": "X-API-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Status successfully updated - No content returned", "headers": { "X-Alert": { "description": "Success message", "schema": { "example": "Subscription Updated", "type": "string" }, "style": "simple" } } }, "400": { "content": { "application/json": { "examples": { "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "Subscription contract with ID 123456789 not found", "status": 400, "title": "No contract found for status update", "type": "https://example.com/errors/bad-request" } }, "Invalid Contract ID": { "description": "Invalid Contract ID", "value": { "detail": "Contract ID must be a positive number", "status": 400, "title": "Invalid contract ID", "type": "https://example.com/errors/bad-request" } }, "Invalid Status Value": { "description": "Invalid Status Value", "value": { "detail": "Status must be one of: ACTIVE, PAUSED, CANCELLED", "status": 400, "title": "UserGeneratedError:Invalid subscription status", "type": "https://example.com/errors/bad-request" } }, "Reactivate Cancelled Subscription": { "description": "Reactivate Cancelled Subscription", "value": { "detail": "Cancelled subscriptions cannot be reactivated. Please create a new subscription.", "status": 400, "title": "UserGeneratedError:Cannot reactivate cancelled subscription", "type": "https://example.com/errors/bad-request" } }, "Same Status Update": { "description": "Same Status Update", "value": { "detail": "Subscription is already ACTIVE. No update needed.", "status": 400, "title": "Contract already in same status", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request parameters or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid API key is required to access this endpoint", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - missing or invalid API key" }, "403": { "content": { "application/json": { "examples": { "API Key Permissions": { "description": "API Key Permissions", "value": { "detail": "API key does not have permission to modify subscription contracts", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } }, "Customer Portal - Pause Permission": { "description": "Customer Portal - Pause Permission", "value": { "detail": "Customer does not have permission to pause subscriptions", "status": 403, "title": "Customer permission denied", "type": "https://example.com/errors/forbidden" } } } } }, "description": "Insufficient permissions to modify subscription status" }, "404": { "content": { "application/json": { "example": { "detail": "Subscription contract with ID 123456789 not found in the system", "status": 404, "title": "Resource not found", "type": "https://example.com/errors/not-found" } } }, "description": "Subscription contract not found" }, "422": { "content": { "application/json": { "examples": { "Invalid Discount Code": { "description": "Invalid Discount Code", "value": { "detail": "Invalid discount code detected. System will automatically remove and retry.", "status": 422, "title": "Contract draft discount with title SUMMER20 is invalid", "type": "https://example.com/errors/unprocessable-entity" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API error: Cannot modify subscription during active billing attempt", "status": 422, "title": "UserGeneratedError:Unable to update subscription status", "type": "https://example.com/errors/unprocessable-entity" } } } } }, "description": "Unable to process the status update due to Shopify API constraints" } }, "summary": "Update subscription contract status", "tags": [ "Subscription Management", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts/contract-external/{contractId}": { "get": { "description": "Retrieves the complete, unprocessed subscription contract data directly from Shopify's GraphQL API. This endpoint returns the full Shopify subscription contract object exactly as Shopify provides it, including all nested fields, relationships, and GraphQL metadata.\n\n**What This Endpoint Returns:**\nUnlike processed/transformed endpoints, this returns Shopify's raw SubscriptionContract GraphQL object with all available fields. This is the same data structure you would receive if querying Shopify's GraphQL API directly, making it ideal for:\n- Debugging Shopify data synchronization issues\n- Accessing fields not exposed in other endpoints\n- Understanding complete Shopify contract structure\n- Building custom integrations requiring full data\n- Comparing Shopify source data with processed data\n\n**Data Included:**\n\n**Contract Core:**\n- Full subscription contract object from Shopify\n- All GraphQL __typename fields preserved\n- Complete nested object structures\n- All available Shopify contract fields\n\n**Customer Information:**\n- Complete customer object with all fields\n- Default address details\n- Customer tags and metadata\n- Marketing preferences\n\n**Line Items:**\n- Full line item details with edges/nodes structure\n- Product and variant complete objects\n- Pricing policies with all cycle discounts\n- Line item custom attributes\n- Current and original prices\n\n**Billing & Delivery:**\n- Complete billing policy object\n- Full delivery policy details\n- Delivery method with all fields\n- Delivery price breakdown\n- Billing anchor details\n\n**Payment Information:**\n- Payment method details (if available)\n- Customer payment instrument\n- Payment gateway information\n\n**Orders & History:**\n- Origin order details\n- Last payment status\n- Historical billing attempts (in Appstle)\n\n**Use Cases:**\n\n**1. Debugging & Troubleshooting:**\n- Investigate data sync discrepancies\n- Verify what Shopify actually stores\n- Debug webhook payload issues\n- Compare expected vs actual data\n\n**2. Advanced Integrations:**\n- Access Shopify-specific fields not in standard APIs\n- Build custom analytics using raw data\n- Integrate with Shopify GraphQL directly\n- Extract fields for custom processing\n\n**3. Data Analysis:**\n- Analyze complete contract structure\n- Extract all available metadata\n- Build comprehensive data exports\n- Perform deep data audits\n\n**4. Development & Testing:**\n- Understand Shopify's data model\n- Test new feature development\n- Verify API responses\n- Documentation and examples\n\n**Response Structure:**\n\nReturns SubscriptionContractQuery.SubscriptionContract object:\n```json\n{\n \"id\": \"gid://shopify/SubscriptionContract/123456789\",\n \"status\": \"ACTIVE\",\n \"nextBillingDate\": \"2024-03-15T00:00:00Z\",\n \"customer\": {\n \"id\": \"gid://shopify/Customer/987654321\",\n \"email\": \"customer@example.com\",\n \"displayName\": \"John Doe\",\n \"__typename\": \"Customer\"\n },\n \"lines\": {\n \"edges\": [\n {\n \"node\": {\n \"id\": \"gid://shopify/SubscriptionLine/111111\",\n \"quantity\": 2,\n \"variantId\": \"gid://shopify/ProductVariant/222222\",\n \"title\": \"Monthly Coffee Box\",\n \"variantTitle\": \"Medium Roast\",\n \"currentPrice\": {\n \"amount\": \"29.99\",\n \"currencyCode\": \"USD\"\n },\n \"pricingPolicy\": {...},\n \"__typename\": \"SubscriptionLine\"\n }\n }\n ]\n },\n \"billingPolicy\": {\n \"interval\": \"MONTH\",\n \"intervalCount\": 1,\n \"minCycles\": 3,\n \"maxCycles\": 12\n },\n \"deliveryPolicy\": {...},\n \"deliveryMethod\": {...},\n \"__typename\": \"SubscriptionContract\"\n}\n```\n\n**Important Considerations:**\n\n**Data Source:**\n- Queries Shopify GraphQL API in real-time\n- NOT cached in Appstle database\n- Always returns current Shopify state\n- Subject to Shopify API rate limits\n\n**Performance:**\n- Slower than database queries (500-1500ms typical)\n- Makes real-time call to Shopify\n- Response size can be large (10-50 KB)\n- Use sparingly to avoid rate limits\n\n**GraphQL Structure:**\n- Includes __typename fields throughout\n- Uses GraphQL ID format (gid://shopify/...)\n- Nested edges/nodes structure for lists\n- All fields as defined in Shopify's schema\n\n**Best Practices:**\n\n1. **Use for Debugging**: Perfect for troubleshooting data issues\n2. **Avoid Polling**: Don't call repeatedly - use cached/processed endpoints instead\n3. **Cache Response**: Cache the response if using for display\n4. **Parse Carefully**: Handle GraphQL structure (edges/nodes)\n5. **Monitor Rate Limits**: Each call counts against Shopify API limits\n\n**When to Use vs Other Endpoints:**\n\n**Use this endpoint when:**\n- Need complete Shopify contract data\n- Debugging synchronization issues\n- Accessing Shopify-specific fields\n- Building Shopify GraphQL integrations\n\n**Use /api/external/v2/subscription-contract-details when:**\n- Need processed, filtered contract data\n- Want faster response times\n- Querying multiple contracts\n- Building customer-facing UIs\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "getSubscriptionContractRawExternalV2", "parameters": [ { "description": "Contract ID", "in": "path", "name": "contractId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionContract" } } }, "description": "Successfully retrieved raw Shopify contract data" }, "400": { "content": { "application/json": { "example": { "detail": "Contract ID must be a valid positive integer", "status": 400, "title": "Invalid contract ID", "type": "https://example.com/errors/bad-request" } } }, "description": "Bad request - Invalid contract ID" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "Subscription contract does not belong to your shop", "status": 403, "title": "Access denied", "type": "https://example.com/errors/forbidden" } } }, "description": "Forbidden - Contract does not belong to authenticated shop" }, "404": { "content": { "application/json": { "example": { "detail": "No subscription contract found with ID 12345 in Shopify", "status": 404, "title": "Contract not found", "type": "https://example.com/errors/not-found" } } }, "description": "Contract not found in Shopify" }, "429": { "content": { "application/json": { "example": { "detail": "Shopify API rate limit exceeded. Please retry after 60 seconds.", "retryAfter": 60, "status": 429, "title": "Rate limit exceeded", "type": "https://example.com/errors/rate-limit" } } }, "description": "Rate limit exceeded - Shopify API rate limit hit" }, "502": { "content": { "application/json": { "example": { "detail": "Failed to retrieve contract from Shopify. Please try again later.", "status": 502, "title": "Shopify API error", "type": "https://example.com/errors/bad-gateway" } } }, "description": "Bad gateway - Shopify API error" } }, "summary": "Get raw Shopify GraphQL contract response", "tags": [ "Subscription Management", "Subscription Contracts" ] } }, "/api/external/v2/subscription-contracts/{id}": { "delete": { "description": "Cancels an existing subscription contract. This operation terminates all future billing and delivery cycles for the subscription. The cancellation takes effect immediately.\n\n**Important Notes:**\n- Any pending/scheduled orders will be cancelled\n- The customer will receive a cancellation confirmation email if SUBSCRIPTION_CANCELLED email template is enabled\n- Cancellation feedback and notes are stored for analytics and reporting\n- Minimum cycle requirements ARE enforced via API (unlike internal cancellations)\n- If the subscription is under a free trial period, minimum cycles are not enforced\n\n**Validation Rules:**\n- Contract must exist and belong to the authenticated shop\n- Contract must not already be cancelled\n- Must have completed minimum required billing cycles (unless in trial)\n\n**Post-Cancellation:**\n- Status changes to 'cancelled' (lowercase)\n- Any pause settings are cleared\n- Cancellation feedback and notes are saved\n- Activity log entry is created\n- Cancellation email is sent (if enabled)\n- Any invalid discount codes are automatically removed\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "deleteSubscriptionContractV2", "parameters": [ { "description": "The unique identifier of the subscription contract to cancel. Must be a valid contract ID that belongs to the authenticated shop.", "example": 123456789, "in": "path", "name": "id", "required": true, "schema": { "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Optional feedback from the customer about why they are cancelling. This information is valuable for understanding cancellation reasons and improving retention. Common values include: 'Too expensive', 'No longer needed', 'Found alternative', 'Quality issues', 'Delivery issues', 'Customer service', 'Product not as expected', etc. This field is stored permanently with the contract for analytics.", "example": "Too expensive", "in": "query", "name": "cancellationFeedback", "required": false, "schema": { "maxLength": 500, "type": "string" } }, { "description": "Optional internal note for recording additional cancellation context. This field is for internal use and not visible to customers. Can be used to track special circumstances, support ticket references, competitor information, or other relevant details about why the customer cancelled. This note is stored permanently with the contract.", "example": "Customer switching to competitor X due to pricing. Support ticket #12345", "in": "query", "name": "cancellationNote", "required": false, "schema": { "maxLength": 1000, "type": "string" } } ], "responses": { "204": { "description": "Subscription successfully cancelled. No content returned.", "headers": { "X-Application-Context": { "description": "Application context", "schema": { "type": "string" }, "style": "simple" } } }, "400": { "content": { "application/json": { "examples": { "Contract Not Found": { "description": "Contract Not Found", "value": { "detail": "No subscription contract found with the specified ID", "instance": "/api/external/v2/subscription-contracts/999999999", "status": 400, "title": "Contract does not exist", "type": "https://example.com/errors/bad-request" } }, "Invalid Contract ID": { "description": "Invalid Contract ID", "value": { "detail": "Contract does not belong to this shop", "instance": "/api/external/v2/subscription-contracts/123456789", "status": 400, "title": "Invalid id", "type": "https://example.com/errors/bad-request" } }, "Minimum Cycles Not Met": { "description": "Minimum Cycles Not Met", "value": { "detail": "Subscription has a minimum commitment that has not been fulfilled", "instance": "/api/external/v2/subscription-contracts/123456789", "status": 400, "title": "UserGeneratedError:You need to complete at least 3 orders before you can cancel this subscription.", "type": "https://example.com/errors/bad-request" } }, "Shopify API Error": { "description": "Shopify API Error", "value": { "detail": "Shopify API returned an error when attempting to cancel", "instance": "/api/external/v2/subscription-contracts/123456789", "status": 400, "title": "UserGeneratedError:Unable to cancel subscription at this time", "type": "https://example.com/errors/bad-request" } } } } }, "description": "Invalid request or business rule violation" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "instance": "/api/external/v2/subscription-contracts/123456789", "status": 401, "title": "Shop does not exist", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to cancel subscriptions", "instance": "/api/external/v2/subscription-contracts/123456789", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to cancel the subscription" } }, "summary": "Cancel a subscription contract", "tags": [ "Subscription Contracts" ] } }, "/api/external/v2/subscription-custom-csses/{id}": { "get": { "description": "Retrieves the custom CSS styling configuration for the customer portal. This endpoint returns all custom CSS rules that have been configured to customize the appearance, layout, and branding of the subscription customer portal.\n\n**What is Custom CSS?**\nCustom CSS allows merchants to fully customize the visual appearance of their customer portal beyond the basic theme settings. This enables complete brand alignment and creates a seamless experience that matches the merchant's main store design.\n\n**Custom CSS Capabilities:**\n- **Layout Customization**:\n - Modify page layouts and spacing\n - Adjust grid and flexbox configurations\n - Control responsive breakpoints\n - Customize navigation and sidebars\n\n- **Typography**:\n - Custom fonts and font families\n - Font sizes, weights, and line heights\n - Letter spacing and text transforms\n - Heading and paragraph styles\n\n- **Colors and Branding**:\n - Brand color palette application\n - Custom background colors and gradients\n - Button and link styling\n - Hover and focus states\n - Border colors and shadows\n\n- **Component Styling**:\n - Subscription card appearances\n - Form input styling\n - Button designs and interactions\n - Modal and dialog boxes\n - Navigation menus\n - Product images and thumbnails\n\n- **Advanced Features**:\n - CSS animations and transitions\n - Media queries for responsive design\n - Pseudo-elements and pseudo-classes\n - Custom icons using CSS\n - Transform and filter effects\n\n**CSS Structure:**\nThe returned CSS includes:\n- Global styles for portal-wide consistency\n- Component-specific styles\n- Responsive design rules\n- Theme overrides\n- Custom animations\n- Print styles (optional)\n\n**Common CSS Selectors Available:**\n```css\n/* Portal container */\n.subscription-portal { }\n\n/* Subscription cards */\n.subscription-card { }\n.subscription-card-header { }\n.subscription-card-body { }\n\n/* Buttons */\n.btn-primary { }\n.btn-secondary { }\n.btn-cancel { }\n\n/* Forms */\n.form-control { }\n.form-group { }\n.form-label { }\n\n/* Navigation */\n.portal-nav { }\n.nav-item { }\n\n/* Product displays */\n.product-item { }\n.product-image { }\n.product-title { }\n```\n\n**Use Cases:**\n- Apply custom branding to match main store design\n- Create unique visual experiences for different customer segments\n- Implement seasonal or promotional themes\n- Enhance mobile responsiveness\n- Add accessibility improvements (high contrast, larger fonts)\n- A/B test different portal designs\n- Integrate with design systems\n- Implement dark mode or theme switching\n\n**Important Notes:**\n- CSS is sanitized for security (XSS prevention)\n- Certain properties may be restricted for security reasons\n- External resources (fonts, images) must use HTTPS\n- CSS is cached for performance - changes may take a few minutes to propagate\n- Invalid CSS syntax is automatically filtered out\n- Some core portal elements have !important styles that cannot be overridden\n\n**Best Practices:**\n- Use specific selectors to avoid conflicts\n- Test across different browsers and devices\n- Keep CSS organized with comments\n- Use CSS variables for maintainability\n- Minify CSS for production performance\n- Consider accessibility in color choices (WCAG compliance)\n- Provide fallbacks for advanced CSS features\n\n**Security Considerations:**\n- CSS is sanitized to prevent code injection\n- External URLs are validated\n- JavaScript in CSS is blocked (e.g., expression(), behavior())\n- Data URIs are validated for malicious content\n\n**Authentication:** Requires valid X-API-Key header", "operationId": "getSubscriptionCustomCssV2", "parameters": [ { "description": "Id", "in": "path", "name": "id", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Success Response": { "description": "Success Response", "value": "{\n \"id\": 12345,\n \"shop\": \"example-shop.myshopify.com\",\n \"customCss\": \"/* Global Portal Styles */\\n\" +\n \".subscription-portal {\\n\" +\n \" font-family: 'Helvetica Neue', Arial, sans-serif;\\n\" +\n \" background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);\\n\" +\n \" min-height: 100vh;\\n\" +\n \"}\\n\\n\" +\n \"/* Subscription Cards */\\n\" +\n \".subscription-card {\\n\" +\n \" border-radius: 12px;\\n\" +\n \" box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);\\n\" +\n \" background: white;\\n\" +\n \" padding: 24px;\\n\" +\n \" margin-bottom: 16px;\\n\" +\n \" transition: transform 0.2s ease, box-shadow 0.2s ease;\\n\" +\n \"}\\n\\n\" +\n \".subscription-card:hover {\\n\" +\n \" transform: translateY(-2px);\\n\" +\n \" box-shadow: 0 6px 12px rgba(0, 0, 0, 0.15);\\n\" +\n \"}\\n\\n\" +\n \"/* Primary Button Styling */\\n\" +\n \".btn-primary {\\n\" +\n \" background-color: #4A90E2;\\n\" +\n \" border-color: #4A90E2;\\n\" +\n \" color: white;\\n\" +\n \" font-weight: 600;\\n\" +\n \" padding: 12px 24px;\\n\" +\n \" border-radius: 6px;\\n\" +\n \" transition: all 0.3s ease;\\n\" +\n \"}\\n\\n\" +\n \".btn-primary:hover {\\n\" +\n \" background-color: #357ABD;\\n\" +\n \" border-color: #357ABD;\\n\" +\n \" transform: scale(1.02);\\n\" +\n \"}\\n\\n\" +\n \"/* Form Inputs */\\n\" +\n \".form-control {\\n\" +\n \" border: 2px solid #E0E0E0;\\n\" +\n \" border-radius: 6px;\\n\" +\n \" padding: 10px 14px;\\n\" +\n \" font-size: 14px;\\n\" +\n \"}\\n\\n\" +\n \".form-control:focus {\\n\" +\n \" border-color: #4A90E2;\\n\" +\n \" box-shadow: 0 0 0 3px rgba(74, 144, 226, 0.1);\\n\" +\n \" outline: none;\\n\" +\n \"}\\n\\n\" +\n \"/* Responsive Design */\\n\" +\n \"@media (max-width: 768px) {\\n\" +\n \" .subscription-card {\\n\" +\n \" padding: 16px;\\n\" +\n \" }\\n\" +\n \" .btn-primary {\\n\" +\n \" width: 100%;\\n\" +\n \" }\\n\" +\n \"}\",\n \"enabled\": true,\n \"version\": 2,\n \"lastModified\": \"2024-02-20T14:45:00Z\",\n \"createdAt\": \"2024-01-15T10:30:00Z\",\n \"updatedAt\": \"2024-02-20T14:45:00Z\"\n}" } }, "schema": { "$ref": "#/components/schemas/SubscriptionCustomCssDTO" } } }, "description": "Custom CSS successfully retrieved" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required" }, "403": { "content": { "application/json": { "example": { "detail": "API key does not have permission to view custom CSS settings", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions to view custom CSS" }, "404": { "content": { "application/json": { "example": { "detail": "No custom CSS has been configured for this shop", "status": 404, "title": "CSS not found", "type": "https://example.com/errors/not-found" } } }, "description": "Custom CSS not found - No custom CSS has been configured" } }, "summary": "Get custom CSS for customer portal", "tags": [ "Customization", "Customer Portal" ] } }, "/api/external/v2/subscription-customers-detail/valid/{customerId}": { "get": { "description": "Retrieves comprehensive subscription contract details for a specific customer, including subscription status, products, billing information, delivery schedules, and more. This endpoint returns full subscription objects with all associated data, making it ideal for displaying subscription management interfaces and detailed analytics.\n\n**What This Endpoint Returns:**\nUnlike the contract IDs endpoint which returns only numeric IDs, this endpoint provides complete SubscriptionContractDetailsDTO objects for each of the customer's subscriptions. Each object contains all information needed to display and manage a subscription.\n\n**Data Included in Response:**\n\n**Subscription Identity:**\n- Subscription contract ID (Shopify numeric ID)\n- Subscription GraphQL ID (Shopify GID format)\n- Internal Appstle database ID\n- Contract creation date\n\n**Subscription Status & Lifecycle:**\n- Current status (ACTIVE, PAUSED, CANCELLED, EXPIRED, FAILED)\n- Status reason (why paused/cancelled)\n- Next billing date and time\n- Contract anchor date\n- Cancellation date (if applicable)\n- Current billing cycle number\n- Min/max cycle limits\n\n**Billing Configuration:**\n- Billing interval (WEEK, MONTH, YEAR)\n- Billing interval count (e.g., every 2 weeks)\n- Billing policy (pricing details)\n- Currency code\n- Recurring total price\n- Applied discounts and pricing policies\n\n**Delivery Configuration:**\n- Delivery interval (WEEK, MONTH, YEAR)\n- Delivery interval count\n- Delivery method (SHIPPING, PICK_UP, LOCAL_DELIVERY)\n- Delivery policy details\n- Delivery price\n\n**Products & Line Items:**\n- All subscribed products and variants\n- Product titles, SKUs, and images\n- Quantities per product\n- Individual line item prices\n- Product-specific discounts\n- Line item attributes and custom fields\n\n**Customer Information:**\n- Customer ID and GraphQL ID\n- Customer name and email\n- Customer acceptance status\n\n**Address Details:**\n- Billing address (full address object)\n- Shipping address (full address object)\n- Address validation status\n\n**Payment Information:**\n- Payment instrument type\n- Payment method details (card last 4, etc.)\n- Payment gateway used\n\n**Order & Fulfillment:**\n- Last order ID and details\n- Last order date\n- Order note\n- Fulfillment status\n\n**Additional Metadata:**\n- Custom note attributes\n- Tags and labels\n- Internal flags and settings\n- Selling plan ID and group ID\n- Shop domain\n\n**Use Cases:**\n\n**1. Customer Portal:**\n- Display all subscriptions on customer dashboard\n- Show subscription details page\n- Enable subscription management actions\n- Display upcoming order information\n\n**2. Admin Dashboard:**\n- View customer's complete subscription portfolio\n- Analyze subscription health and status\n- Identify at-risk or high-value subscriptions\n- Generate customer subscription reports\n\n**3. Customer Support:**\n- Quick access to all customer subscription details\n- Troubleshoot billing or delivery issues\n- Verify subscription configurations\n- Assist with subscription modifications\n\n**4. Analytics & Reporting:**\n- Calculate customer lifetime value\n- Analyze subscription mix per customer\n- Track subscription frequency distribution\n- Identify cross-sell/upsell opportunities\n\n**5. Integration & Automation:**\n- Sync subscription data to CRM/analytics platforms\n- Trigger workflows based on subscription details\n- Build custom reporting dashboards\n- Export subscription data for analysis\n\n**Response Format:**\n\nReturns an array of SubscriptionContractDetailsDTO objects:\n```json\n[\n {\n \"id\": 789,\n \"subscriptionContractId\": 5234567890,\n \"status\": \"ACTIVE\",\n \"nextBillingDate\": \"2024-03-15T00:00:00Z\",\n \"billingInterval\": \"MONTH\",\n \"billingIntervalCount\": 1,\n \"deliveryInterval\": \"MONTH\",\n \"deliveryIntervalCount\": 1,\n \"currencyCode\": \"USD\",\n \"currentTotalPrice\": \"49.99\",\n \"customerId\": 12345,\n \"customerEmail\": \"customer@example.com\",\n \"lineItems\": [...],\n \"billingAddress\": {...},\n \"shippingAddress\": {...}\n },\n {...}\n]\n```\n\n**Response Scenarios:**\n\n**Customer with no subscriptions:**\n```json\n[]\n```\nReturns empty array with 200 OK status (not an error).\n\n**Customer with multiple subscriptions:**\nArray contains multiple subscription objects, each representing a separate subscription contract.\n\n**Performance Considerations:**\n\n**Response Size:**\n- Each subscription object can be 5-50 KB depending on line items\n- Customer with 10 subscriptions: ~100-500 KB response\n- Consider pagination or filtering for customers with 20+ subscriptions\n\n**Query Performance:**\n- Typical response time: 200-500ms\n- Slower for customers with many subscriptions or complex products\n- Database query is optimized with indexed lookups\n\n**Best Practices:**\n\n1. **Cache Results**: Cache response data to minimize API calls\n2. **Filter Client-Side**: Filter/sort subscriptions on client after retrieval\n3. **Selective Display**: Don't display all fields if not needed\n4. **Handle Empty Array**: Always gracefully handle case with no subscriptions\n5. **Optimize Images**: Product images can be large - lazy load if displaying\n\n**Data Freshness:**\n- Data is retrieved from Appstle database (not real-time Shopify query)\n- Updated via webhooks with < 1 second lag typically\n- Use sync endpoint if data appears stale\n\n**Security Notes:**\n- Customer ID is validated against authenticated shop\n- Returns only subscriptions belonging to specified customer\n- Cannot access customers from other shops\n- Sensitive payment details (full card numbers) are never returned\n\n**Comparison with Other Endpoints:**\n\n**vs. GET /subscription-customers/valid/{customerId}:**\n- This endpoint: Returns complete subscription details\n- Valid contracts endpoint: Returns only contract IDs\n- Use this when you need full subscription information\n\n**vs. GET /subscription-contract-details:**\n- This endpoint: Filtered by single customer\n- Contract details endpoint: Query across all customers with filters\n- Use this for customer-specific views\n\n**vs. GET /subscription-contracts/contract-external/{contractId}:**\n- This endpoint: All contracts for a customer\n- Contract external endpoint: Single contract with Shopify raw data\n- Use this for customer overview, other for detailed single contract\n\n**Authentication:** Requires valid X-API-Key header or api_key parameter (deprecated)", "operationId": "getValidSubscriptionCustomerDetailsV2", "parameters": [ { "description": "Customer Id", "in": "path", "name": "customerId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "Customer with active subscriptions": { "description": "Customer with active subscriptions", "value": [ { "billingInterval": "MONTH", "billingIntervalCount": 1, "currencyCode": "USD", "currentCycle": 3, "currentTotalPrice": "49.99", "customerEmail": "customer@example.com", "customerId": 12345, "deliveryInterval": "MONTH", "deliveryIntervalCount": 1, "deliveryMethod": "SHIPPING", "id": 789, "nextBillingDate": "2024-03-15T00:00:00Z", "shop": "example-shop.myshopify.com", "status": "ACTIVE", "subscriptionContractId": 5234567890 }, { "billingInterval": "WEEK", "billingIntervalCount": 2, "currencyCode": "USD", "currentTotalPrice": "24.99", "customerEmail": "customer@example.com", "customerId": 12345, "id": 790, "status": "PAUSED", "subscriptionContractId": 5234567891 } ] }, "Customer with no subscriptions": { "description": "Customer with no subscriptions", "value": [] } }, "schema": { "items": { "$ref": "#/components/schemas/SubscriptionContractDetailsDTO" }, "type": "array" } } }, "description": "Successfully retrieved customer subscription details. Returns array of subscription objects (may be empty)." }, "400": { "content": { "application/json": { "example": { "detail": "Customer ID must be a valid positive integer", "status": 400, "title": "Invalid customer ID", "type": "https://example.com/errors/bad-request" } } }, "description": "Bad request - Invalid customer ID" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - Missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "Customer 12345 does not belong to your shop", "status": 403, "title": "Access denied", "type": "https://example.com/errors/forbidden" } } }, "description": "Forbidden - Customer does not belong to authenticated shop" }, "429": { "content": { "application/json": { "example": { "detail": "Too many requests. Please retry after 60 seconds.", "retryAfter": 60, "status": 429, "title": "Rate limit exceeded", "type": "https://example.com/errors/rate-limit" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "example": { "detail": "An unexpected error occurred while retrieving subscription details", "status": 500, "title": "Server error", "type": "https://example.com/errors/internal-error" } } }, "description": "Internal server error" } }, "summary": "Get detailed subscription information for a customer", "tags": [ "Customers", "Subscription Contracts" ] } }, "/api/external/v2/subscription-customers/sync-info/{customerId}": { "get": { "description": "Synchronizes customer subscription information from Shopify to the Appstle subscription system. This endpoint fetches the latest customer data from Shopify and updates the local database to ensure data consistency across platforms.\n\n**What Does This Endpoint Do?**\nThis endpoint triggers a synchronization process that pulls customer subscription data from Shopify's GraphQL API and updates the Appstle subscription database with the latest information. It ensures that customer details, subscription statuses, and associated metadata are current and accurate.\n\n**Sync Process:**\n\n1. **Data Retrieval**: Fetches customer subscription data from Shopify using their GraphQL API\n2. **Validation**: Validates the retrieved data against existing records\n3. **Update**: Updates customer subscription details in Appstle database\n4. **Reconciliation**: Reconciles any discrepancies between Shopify and Appstle data\n5. **Logging**: Logs all sync activities for audit trail\n\n**What Gets Synchronized:**\n\n**Customer Information:**\n- Customer ID and Shopify GraphQL ID\n- Customer name and email address\n- Customer tags and metadata\n- Customer acceptance status\n- Marketing preferences\n\n**Subscription Details:**\n- Active subscription contracts\n- Subscription statuses (ACTIVE, PAUSED, CANCELLED, EXPIRED)\n- Next billing dates\n- Billing interval and delivery interval\n- Subscription line items (products and variants)\n- Pricing and discounts\n\n**Payment Information:**\n- Associated payment methods\n- Payment instrument status\n- Billing address details\n\n**Delivery Information:**\n- Shipping address details\n- Delivery method and profile\n- Delivery preferences\n\n**Use Cases:**\n\n**1. Data Consistency:**\n- Resolve data discrepancies between Shopify and Appstle\n- Update customer information after changes in Shopify admin\n- Sync subscription modifications made directly in Shopify\n\n**2. Troubleshooting:**\n- Fix sync issues for specific customers\n- Recover from webhook delivery failures\n- Debug customer portal display issues\n\n**3. Migration & Integration:**\n- Initial data sync after app installation\n- Re-sync after system maintenance or updates\n- Integration testing and validation\n\n**4. Customer Support:**\n- Refresh customer data when assisting with support tickets\n- Verify latest subscription status during customer inquiries\n- Update data after manual changes in Shopify\n\n**When to Use This Endpoint:**\n\n**Recommended Scenarios:**\n- Customer reports incorrect subscription data in portal\n- After making manual changes to subscriptions in Shopify admin\n- When troubleshooting webhook sync failures\n- Before running bulk operations on customer subscriptions\n- During migration or data reconciliation processes\n\n**Avoid Using For:**\n- Real-time data refresh (webhooks handle this automatically)\n- Frequent polling (use webhooks instead to avoid rate limits)\n- Bulk syncs of many customers (use batch endpoints or scheduled jobs)\n\n**Sync Behavior:**\n\n**Synchronous Operation:**\n- Endpoint blocks until sync completes\n- Returns void on success\n- Throws exception on failure\n\n**Data Precedence:**\n- Shopify data is always treated as source of truth\n- Local Appstle data is overwritten with Shopify values\n- Custom Appstle-specific fields are preserved\n\n**Error Handling:**\n- Invalid customer ID: Returns 400 Bad Request\n- Customer not found in Shopify: Returns 404 Not Found\n- Shopify API errors: Returns 502 Bad Gateway\n- Rate limit exceeded: Returns 429 Too Many Requests\n\n**Important Considerations:**\n\n**Performance:**\n- Sync duration depends on number of subscriptions (typically 1-5 seconds)\n- May timeout for customers with 100+ active subscriptions\n- Consider using asynchronous sync for high-volume customers\n\n**Rate Limiting:**\n- Subject to Shopify GraphQL API rate limits\n- Frequent calls may exhaust rate limit budget\n- Use webhooks for real-time sync instead of polling this endpoint\n\n**Data Integrity:**\n- Always creates audit log entries for tracking\n- Preserves historical data and activity logs\n- Does not delete local-only data (e.g., custom notes)\n\n**Best Practices:**\n\n1. **Use Sparingly**: Rely on webhooks for automatic sync; use this only when needed\n2. **Check Logs**: Review activity logs after sync to verify changes\n3. **Validate Results**: Query customer data after sync to confirm updates\n4. **Handle Errors**: Implement retry logic with exponential backoff\n5. **Monitor Rate Limits**: Track Shopify API usage to avoid hitting limits\n\n**Security Notes:**\n- Requires valid API key authentication via X-API-Key header\n- Customer ID is validated against shop ownership\n- Cannot sync customers from other shops\n- All sync operations are logged for audit compliance\n\n**Response:**\n- Returns HTTP 204 No Content on successful sync\n- No response body returned\n- Check activity logs for detailed sync results\n\n**Alternative Approaches:**\n\nIf you need to:\n- **Sync multiple customers**: Use bulk sync endpoint or scheduled job\n- **Real-time updates**: Rely on webhook subscriptions\n- **Verify data without modifying**: Use GET endpoints to retrieve current data\n\n**Integration Workflow Example:**\n\n```\n1. Customer contacts support about incorrect billing date\n2. Support agent checks subscription in Appstle admin\n3. Agent makes correction in Shopify admin\n4. Agent calls sync endpoint for this customer\n5. Sync retrieves latest data from Shopify\n6. Appstle database is updated with corrected billing date\n7. Customer portal now shows correct date\n8. Support ticket resolved\n```\n\n**Authentication:** Requires valid X-API-Key header or api_key parameter (deprecated)", "operationId": "syncCustomerInfo", "parameters": [ { "description": "Customer Id", "in": "path", "name": "customerId", "required": true, "schema": { "format": "int64", "type": "integer" } }, { "description": "API Key (Deprecated - Use Header X-API-Key instead)", "in": "query", "name": "api_key", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "X-API-Key", "required": false, "schema": { "type": "string" } } ], "responses": { "204": { "content": { "application/json": {} }, "description": "Customer subscription data successfully synchronized from Shopify. No response body returned. Check activity logs to verify sync completion and review changes made." }, "400": { "content": { "application/json": { "example": { "detail": "Customer ID must be a valid positive integer", "status": 400, "title": "Invalid request", "type": "https://example.com/errors/bad-request" } } }, "description": "Bad request - Invalid customer ID or malformed request parameters" }, "401": { "content": { "application/json": { "example": { "detail": "Valid X-API-Key header is required", "status": 401, "title": "Authentication required", "type": "https://example.com/errors/unauthorized" } } }, "description": "Authentication required - Missing or invalid API key" }, "403": { "content": { "application/json": { "example": { "detail": "Customer does not belong to your shop or API key lacks required permissions", "status": 403, "title": "Insufficient permissions", "type": "https://example.com/errors/forbidden" } } }, "description": "Insufficient permissions or customer does not belong to authenticated shop" }, "404": { "content": { "application/json": { "example": { "detail": "No customer found with ID 12345 in Shopify", "status": 404, "title": "Customer not found", "type": "https://example.com/errors/not-found" } } }, "description": "Customer not found in Shopify or has no subscriptions" }, "429": { "content": { "application/json": { "example": { "detail": "Shopify API rate limit exceeded. Please retry after 60 seconds.", "retryAfter": 60, "status": 429, "title": "Rate limit exceeded", "type": "https://example.com/errors/rate-limit" } } }, "description": "Rate limit exceeded - Too many sync requests or Shopify API rate limit hit" }, "502": { "content": { "application/json": { "example": { "detail": "Failed to connect to Shopify API. Please try again later.", "status": 502, "title": "Shopify API error", "type": "https://example.com/errors/bad-gateway" } } }, "description": "Bad gateway - Shopify API error or connection failure" }, "504": { "content": { "application/json": { "example": { "detail": "Sync operation timed out. Customer may have too many subscriptions. Please contact support for manual sync.", "status": 504, "title": "Sync timeout", "type": "https://example.com/errors/timeout" } } }, "description": "Gateway timeout - Sync operation took too long (customer has too many subscriptions)" } }, "summary": "Sync customer subscription details from Shopify", "tags": [ "Customers", "Subscription Contracts" ] } }, "/api/external/v2/subscription-customers/valid/{customerId}": { "get": { "description": "Retrieves a set of all valid (active, paused, or otherwise non-deleted) subscription contract IDs for a specific customer. This endpoint returns only the contract IDs without detailed subscription information, making it ideal for quick lookups and validation checks.\n\n**What Are Valid Subscription Contracts?**\nValid contracts are subscriptions that exist in the system and haven't been permanently deleted. This includes subscriptions in all states except those that have been hard-deleted or hidden from the system. The contract IDs returned represent subscriptions that can be queried, modified, or managed through other API endpoints.\n\n**Contract States Included:**\n\n**Active States:**\n- `ACTIVE` - Currently active and billing recurring subscriptions\n- `PAUSED` - Temporarily paused subscriptions (customer can resume)\n\n**Inactive States:**\n- `CANCELLED` - Cancelled subscriptions (retained for historical data)\n- `EXPIRED` - Subscriptions that reached their max cycle limit\n- `FAILED` - Subscriptions with payment failures (may be in dunning)\n\n**Excluded:**\n- Hard-deleted subscription records\n- Hidden subscriptions (marked for cleanup)\n- Subscriptions from test/development that were purged\n\n**Use Cases:**\n\n**1. Customer Portal:**\n- Check if customer has any subscriptions before showing portal\n- Display subscription count in dashboard\n- Validate customer access to subscription management\n\n**2. Integration & Automation:**\n- Pre-flight check before bulk operations\n- Verify customer has subscriptions before sending emails\n- Filter customers for targeted campaigns (has active subscriptions)\n\n**3. Validation & Security:**\n- Verify a specific contract ID belongs to a customer\n- Validate user permissions before showing subscription details\n- Check authorization for subscription modification requests\n\n**4. Analytics & Reporting:**\n- Count total subscriptions per customer\n- Identify customers with multiple subscriptions\n- Build customer segmentation based on subscription count\n\n**Response Format:**\n\nReturns a `Set