Shopify-App-Billing-and-Payments

Shopify App Billing & Payments — How It Works

This document explains how Shopify bills merchants for apps, including:

• Recurring app subscriptions (via appSubscriptionCreate)
• One-time app purchases (via appPurchaseOneTimeCreate)
• When and how merchants are actually charged
• What happens if they install mid–billing-cycle (e.g. on the 20th)

It focuses on app billing, not customer/order payments (Shopify Payments, gateways, etc.).

---

1. Types of app charges

Shopify supports several billing mechanisms for apps:

• Recurring app subscription

  • Created with the appSubscriptionCreate GraphQL mutation.
  • Used for monthly / yearly pricing (for example, $20/month).
  • Can include usage-based line items, but in this project we’re using a flat recurring price plus our own credit system on top.

• One-time app purchase

  • Created with appPurchaseOneTimeCreate.
  • Used for buying fixed packs or “lifetime access” style features.
  • In our app, we use it for “Buy Credits” (for example, $10, $20, $50 credit packs).

• Usage charges (optional)

  • You can attach a usage-based line item to a subscription and charge via appUsageRecordCreate.
  • We don’t use this in Option A; instead we implement a credit-balance model and one-time top ups.

---

2. Recurring app subscriptions

2.1 Merchant flow

1. Your app calls appSubscriptionCreate with:
   • name: Human-readable plan name (for example, “AppiFire AI Chat — Paid plan”).
   • lineItems: Contains appRecurringPricingDetails with price.amount and interval (for example, EVERY_30_DAYS).
   • returnUrl: URL in your app (for example, /app/billing/confirm) where Shopify will redirect after the merchant approves or cancels.
2. Shopify returns a confirmationUrl.
3. Your app redirects the merchant (or, in embedded apps, sets window.top.location.href) to the Shopify-hosted confirmation page.
4. The merchant approves or declines the subscription:
   • If approved, the app subscription becomes ACTIVE.
   • If declined, Shopify redirects back to your app with a “charge declined” notice.
5. Once active, the subscription appears on the merchant’s Shopify app invoices and is billed automatically.

2.2 When does Shopify charge the merchant?

Key points (from Shopify billing docs and partner resources):

• App subscriptions are billed on a Shopify billing cycle, which is typically 30 days.
• Shopify aggregates all app charges (recurring and one-time) and adds them to the merchant’s main Shopify bill.
• Merchants are billed for apps either:
  • On their regular Shopify billing date, or
  • Earlier if they hit a billing threshold (for example, many high-value app charges in one period).

So your app does not charge the merchant directly. Instead:

• Your app creates/updates subscriptions and usage records via the Admin GraphQL API.
• Shopify collects the money from the merchant and then pays you out via your Partner account.

2.3 Example: subscribe on the 20th

Q: If a merchant installs the app and approves the subscription on the 20th of the month, when are they charged? Do they get a partial (10-day) charge until the 1st, or are they charged every 20th?

Important clarifications:

• Shopify does not prorate monthly app subscriptions to calendar months by default.
• The billing period for the app is based on when the subscription becomes active, not on the calendar month.
• Shopify tracks charges in 30-day cycles and then adds them to the merchant’s regular Shopify invoice.

What this means in practice:

• Suppose a merchant approves your app subscription on March 20.
• The app’s billing cycle will run in 30-day periods starting from around that time (for example, March 20 → April 19).
• Shopify will then decide when to invoice:
  • Usually on the merchant’s Shopify subscription billing date (which might not be the 20th), or
  • Earlier if the merchant hits the billing threshold for app charges.

So the merchant is not billed “only for 10 days until April 1”. Instead:

• The app subscription runs on its own 30-day cycle, starting when they approve.
• Shopify includes that subscription amount in the next Shopify invoice, which might be on a different date than the 20th.
• There is no prorated partial month for standard monthly app billing unless you manually handle refunds/credits.

Mental model: Think of the app subscription as a flat recurring fee per 30 days, starting from the approval date, and Shopify’s invoice decides when those charges are actually billed to the merchant.

2.4 Trials, upgrades, and cancellations

• Trials

  • You can add trialDays to appSubscriptionCreate.
  • The trial starts when the merchant approves the subscription.
  • After the trial, Shopify begins billing normally for each cycle.

• Upgrades/downgrades

  • If you change the plan (for example, upgrade from Basic to Pro), Shopify’s billing system supports proration:
    • The merchant is charged or credited based on time remaining in the cycle and price difference between plans.
  • Implementation depends on how you manage multiple subscriptions / replacement behavior.

• Uninstall / cancellation

  • If the merchant uninstalls your app:
    • Shopify automatically cancels the app subscription.
    • The merchant is not automatically refunded for the remaining days; you can voluntarily issue refunds via the Partner Dashboard if you choose.
  • If they cancel via your app and you call an API to cancel, same idea: the subscription will not bill in the next cycle, but any already-billed period is not automatically prorated.

---

3. One-time app purchases (credit packs)

Our app uses one-time purchases for buying extra AI credits (for example, $10, $20, $50, $100, $200).

3.1 Merchant flow

1. Your app calls appPurchaseOneTimeCreate with:
   • name: Something like “AppiFire AI Chat — $10 AI credits”.
   • price: { amount: 10, currencyCode: \"USD\" } (or 20/50/100/200).
   • returnUrl: A URL in your app where Shopify redirects after approval.
   • test: true/false for dev.
2. Shopify returns a confirmationUrl.
3. You redirect the merchant’s top window to the confirmationUrl.
4. The merchant approves or declines:
   • On approval, the one-time purchase becomes ACTIVE and is added as a line item on the merchant’s next Shopify invoice (or sooner if they hit the billing threshold).
   • On decline, Shopify redirects back to your app and no charge is created.

3.2 When are one-time charges billed?

• The actual money charge does not happen at the moment of approval in your app.
• Instead:
  • Shopify immediately records an active one-time charge.
  • That charge is added to the merchant’s Shopify bills, usually:
    • On their next Shopify invoice date, or
    • Earlier if they hit the billing threshold.

For your app’s logic (for example, giving credits), you usually:

• Trust that once appPurchaseOneTimeCreate reports an active status (or you are hit by the proper webhook/callback),
• You add the purchased credits to the merchant’s account.

---

4. How app charges appear on the merchant’s bills

From Shopify’s Help Center (“App charges on your Shopify bills”):

• App charges show as separate line items on the merchant’s Shopify invoice:
  • Recurring app subscriptions (for example, “AppiFire AI Chat – Subscription”)
  • Usage charges (if used)
  • One-time app purchases (for example, “AppiFire AI Chat – $10 AI credits”)
• All app charges are grouped under the Apps section of the invoice.
• Payouts to you (the developer) are handled via the Shopify Partner Dashboard, typically paid out twice monthly.

---

5. How this maps to our AppiFire AI Chat billing model

In Option A – Phase 5, our app uses Shopify billing APIs like this:

• Recurring subscription: $20/month plan (appSubscriptionCreate)

  • Includes $10 free AI credits each month (we implement credits via creditBalanceCents in our own DB).
  • Shopify charges the merchant in 30-day cycles and aggregates that into the Shopify invoice.

• One-time purchases: “Buy Credits” packs (appPurchaseOneTimeCreate)

  • Merchant clicks “Buy Credits” and approves a one-time app charge for $10 / $20 / $50 / $100 / $200.
  • After approval, we add that dollar amount to their credit balance (creditBalanceCents).
  • Shopify bills this as a separate line item on the merchant’s invoice.

• Internal credit system (not Shopify-native)

  • For paid shops: each AI reply deducts its actual cost (our charged_cost from OpenRouter plus markup) from creditBalanceCents.
  • For free shops: we apply a 50 replies/month cap.
  • This usage tracking is internal to our app database and not visible to Shopify—Shopify just sees the subscription fee + one-time credit packs.

---

6. Quick FAQ

Q1. If the merchant subscribes on the 20th, do they get a partial month?

No. App subscriptions are not prorated to calendar months by default. The subscription becomes active on the approval date (for example, the 20th), and:

• The merchant’s Shopify invoices will include your app’s 30-day subscription charges, based on their invoice date and billing thresholds.
• There is no automatic “10 days only” charge unless you implement a custom refund/credit logic yourself.

Q2. When does Shopify actually charge the merchant’s card?

• Shopify controls that:
  • On the merchant’s Shopify billing date (for example, every 30 days for the main store subscription), or
  • When the merchant hits an app billing threshold.
• Apps only create billing records (subscriptions/one-time charges); Shopify’s billing system decides when the card is charged.

Q3. How do refunds work for app charges?

• Shopify doesn’t automatically prorate or refund remaining time when an app is uninstalled.
• As a developer, you can issue refunds manually for app charges from the Partner Dashboard (for example, if you want to be generous or handle edge cases).

---

7. References

• Shopify Dev Docs – About billing for your app: high-level view of app billing models and APIs.
• Shopify Dev Docs – Subscription billing (appSubscriptionCreate, AppSubscription object).
• Shopify Dev Docs – One-time purchases (appPurchaseOneTimeCreate, AppPurchaseOneTime object).
• Shopify Help Center – App charges on your Shopify bills: how merchants see app charges on invoices and when they are billed.