External (0.0.1)

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Updates billing attempt details for a subscription contract. Billing attempts represent individual charge attempts for recurring subscription orders.

Key Information Updated:

• Billing Date: Next scheduled billing/charge date
• Status: Success, failed, pending, or scheduled
• Error Messages: Failure reasons for declined payments
• Retry Count: Number of retry attempts made
• Order ID: Associated Shopify order if billing succeeded
• Amount: Billing amount charged or attempted

Billing Attempt Lifecycle:

1. Scheduled: Billing attempt is queued for future processing
2. Pending: Charge is being processed by payment gateway
3. Success: Payment captured, order created
4. Failed: Payment declined or error occurred
5. Retrying: Automatic retry scheduled after failure

Common Use Cases:

• Reschedule failed billing attempts to a new date
• Update billing date to align with customer preferences
• Mark manual payment reconciliation in external systems
• Sync billing status with external payment processors
• Trigger retry logic for failed payment attempts
• Update billing metadata for reporting and analytics

Important Notes:

• Changing billing date will affect the subscription's billing cycle
• Only pending or failed attempts can typically be modified
• Successfully billed attempts are immutable in most cases

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Skips a scheduled billing attempt, preventing the order from being processed. The next billing date is automatically recalculated based on the subscription frequency.

Key Features:

• Flexible Skipping: Skip any upcoming order
• Auto-Rescheduling: Next billing date automatically adjusted
• Prepaid Support: Handles both regular and prepaid subscriptions
• Activity Logging: Tracks skip events for reporting
• Customer Control: Allow members to manage delivery timing

How It Works:

1. Marks the billing attempt as skipped
2. Calculates new next billing date (current date + frequency)
3. Updates subscription contract in Shopify
4. Logs skip activity with event source
5. Returns updated billing attempt details

Use Cases:

• Customer going on vacation
• Too much inventory on hand
• Temporary pause without canceling
• Budget constraints for specific month
• Customize delivery schedule

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Immediately triggers a billing attempt for a subscription contract, bypassing the normal scheduled billing time. This endpoint processes the billing asynchronously via Shopify's Subscription Billing API, creating an order and charging the customer's payment method.

How Billing Retry Works:

1. Validation: Checks if shop has enableImmediatePlaceOrder permission (premium feature)
2. Async Trigger: Queues billing job in background (returns immediately)
3. Shopify API Call: Sends subscriptionBillingAttemptCreate mutation to Shopify
4. Payment Processing: Charges customer's stored payment method
5. Order Creation: Creates Shopify order if payment succeeds
6. Notification: Sends order confirmation email to customer (if enabled)
7. Webhook Events: Triggers SUBSCRIPTION_BILLING_ATTEMPTS_SUCCESS or _FAILURE webhook

When to Use This Endpoint:

• Payment Failed Previously: Customer updated credit card, retry failed billing
• Scheduled Too Far Out: Customer wants early delivery, bill before scheduled date
• Payment Method Updated: Customer just added new payment method, retry immediately
• Manual Recovery: Merchant intervention to recover failed subscription
• Testing/QA: Validate subscription billing flow in test environments
• Customer Request: Expedited order fulfillment for urgent needs

Important Limitations & Restrictions:

• Permission Required: Only available to shops with enableImmediatePlaceOrder permission
  • This is a premium feature - free plans will receive 400 error
  • Upgrade subscription plan in Appstle admin to enable
• Rate Limiting: Maximum 5 billing attempts per contract per hour (anti-abuse)
• Billing Attempt Status: Can retry attempts with status QUEUED, SCHEDULED, or FAILED
• Cannot Retry: Billing attempts with status SUCCESS (order already created)
• Duplicate Prevention: Shopify prevents duplicate orders within 24-hour window
• Payment Method Required: Contract must have valid payment method attached

Asynchronous Processing Details: This endpoint returns immediately (200 OK) before billing completes. Actual billing happens in background:

• Success Response: Means billing job was queued, NOT that payment succeeded
• Actual Result: Check via webhooks or poll /subscription-billing-attempts endpoint
• Processing Time: Typically 5-30 seconds depending on Shopify API response time
• Timeout Handling: Background job retries up to 3 times if Shopify API times out

Checking Billing Result (Recommended Flow):

Step 1: Call this endpoint to trigger billing
  PUT /subscription-billing-attempts/attempt-billing/123456
  Response: 200 OK (billing queued)

Step 2: Wait 10-15 seconds for processing

Step 3: Poll billing attempt status
  GET /subscription-billing-attempts?id=123456
  Check 'status' field:
  - SUCCESS: Order created, payment captured
  - FAILED: Payment declined or error occurred
  - PROCESSING: Still in progress, poll again

Step 4: (Alternative) Use webhooks for real-time updates
  Configure webhook: SUBSCRIPTION_BILLING_ATTEMPTS_SUCCESS
  Receive notification when billing completes

Common Error Scenarios:

• 400 - Permission Denied: "You don't have permission to place immediate orders"
  • Solution: Upgrade to premium plan with enableImmediatePlaceOrder feature
• 400 - Rate Limit: "Too many billing attempts. Maximum 5 per hour per contract."
  • Solution: Wait before retrying, investigate why billing keeps failing
• 400 - Invalid Status: "Cannot retry billing attempt with status SUCCESS"
  • Solution: Order already created successfully, check order history
• 404 - Not Found: "Billing attempt not found"
  • Solution: Verify billing attempt ID belongs to this shop
• 500 - Shopify API Error: Background job may fail if Shopify API is down
  • Solution: Retry after 5 minutes, check Shopify status page

Payment Failure Reasons (Check After Async Processing): After billing processes, if status becomes FAILED, common reasons include:

• Card Declined: Insufficient funds, expired card, fraud detection
• Invalid Payment Method: Customer deleted payment method
• 3D Secure Failed: Authentication challenge not completed
• Gateway Error: Payment processor (Stripe/Shopify Payments) issue
• Inventory Shortage: Product out of stock, cannot fulfill order
• Subscription Canceled: Contract canceled between retry trigger and processing

Integration Best Practices:

1. Always Check Permission First: Call /shop-info or similar to verify feature access
2. Implement Webhooks: Don't rely on polling - use webhooks for real-time status
3. User Communication: Warn user "Billing in progress..." since it's async
4. Idempotency: Safe to call multiple times - Shopify prevents duplicate orders
5. Error Handling: Gracefully handle permission errors for free plan users
6. Logging: Track billing attempt ID for troubleshooting and support

Example Use Case - Customer Portal:

Scenario: Customer's card declined, they updated payment method

1. Customer sees "Payment Failed" in portal
2. Customer clicks "Update Payment Method" → adds new card
3. Customer clicks "Retry Payment Now" button
4. Frontend calls: PUT /subscription-billing-attempts/attempt-billing/789
5. Display: "Processing payment..." spinner
6. Poll endpoint every 5 seconds for status update
7. On SUCCESS: Show "Payment successful! Order #12345 created."
8. On FAILED: Show decline reason + retry instructions

Difference from Skip/Reschedule:

• Attempt Billing: Immediately charges customer and creates order NOW
• Skip: Postpones order to next billing cycle, no charge
• Reschedule: Changes billing date without triggering immediate charge

Authentication: Requires API key authentication via X-API-Key header or api_key parameter. Additionally requires merchant account to have enableImmediatePlaceOrder permission (premium feature).

Updates the order note/instructions for a specific upcoming billing attempt. These notes are stored with the billing attempt and will appear on the Shopify order when it's created. Order notes are visible to merchants in Shopify admin and can be printed on packing slips.

How It Works:

1. Accepts a billing attempt ID and new order note text
2. Updates the billing attempt record immediately
3. Note will be included when the order is created during billing
4. Previous order note (if any) is completely replaced
5. Empty string will clear the existing order note

Important Timing Considerations:

• Can only update billing attempts with status: QUEUED or SCHEDULED
• Cannot update billing attempts that have already been processed (SUCCESS or FAILED)
• Changes apply to the next billing cycle only (does not affect past orders)
• For recurring notes across all future orders, use subscription contract order notes instead

Character Limits & Validation:

• Maximum Length: 5000 characters (Shopify's order note limit)
• Encoding: Supports UTF-8 (emojis, international characters allowed)
• HTML: Not rendered - plain text only, HTML tags will display as text
• Line Breaks: Preserved using \n characters
• Special Characters: Quotes, apostrophes automatically escaped

Common Use Cases:

• Delivery Instructions: "Please leave package at side door" or "Ring doorbell twice"
• Special Handling: "Fragile items - handle with care" or "Refrigerate immediately"
• Gift Messages: "Happy Birthday! Love, Sarah" (for gift subscriptions)
• Custom Requests: "Include extra ice packs" or "No substitutions please"
• One-Time Changes: "Skip broccoli this week, double the carrots instead"
• Fulfillment Notes: "Use expedited shipping" or "Pack items separately"

Order Note vs Contract Note:

• Billing Attempt Note (this endpoint): Applies to ONE specific upcoming order only
• Contract Note (/subscription-contracts-update-order-note): Applies to ALL future orders
• If both exist, they are concatenated in the final Shopify order

Example Workflows:

Scenario 1: One-time delivery instruction
1. Customer going on vacation next week
2. Call this endpoint to add "Deliver to neighbor at #123" for next billing attempt
3. Following orders resume normal delivery (no note)

Scenario 2: Clearing unwanted notes
1. Previous note says "Call before delivery"
2. Customer requests removal
3. Call this endpoint with orderNote="" (empty string)
4. Note cleared from next order

Scenario 3: Gift message for specific order
1. Customer's subscription ships to recipient monthly
2. Special occasion (birthday) on next delivery
3. Add gift message to next billing attempt only
4. Regular shipments continue without message

Integration Tips:

• Fetch upcoming billing attempts via /subscription-billing-attempts endpoint first
• Check status field to ensure billing attempt can be modified
• Display character counter in UI (5000 char limit)
• Sanitize input to prevent injection attacks
• Consider validating against profanity/spam filters

Error Handling:

• 404: Billing attempt ID doesn't exist or belongs to different shop
• 400: Billing attempt already processed (status is SUCCESS/FAILED)
• 400: Order note exceeds 5000 character limit
• 401: Invalid or missing API key

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Retrieves upcoming/scheduled billing attempts for shop, contract, or customer. Returns future orders that haven't been processed yet.

Query Options:

• No params: All upcoming orders for shop
• contractId: Upcoming orders for specific contract
• customerId: Upcoming orders for specific customer

Use Cases:

• Display next delivery dates in portal
• Show upcoming charges
• Allow order modifications before processing

Authentication: Requires API key authentication via X-API-Key header or api_key parameter

Retrieves historical billing attempts including successful, failed, and skipped orders. Returns completed billing attempts for reporting and history display.

Query Options:

• No params: All past orders for shop
• contractId: Order history for specific contract
• customerId: Order history for specific customer

Use Cases:

• Display order history in customer portal
• Generate billing reports
• Track payment success/failure rates
• Customer service order lookup

Authentication: Requires API key authentication via X-API-Key header or api_key parameter