Shopify App Billing and Payments

Shopify App Billing & Payments — How It Works

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

• Recurring app plans — AppiFire uses Shopify App Pricing (Partner Dashboard plan picker), not in-app appSubscriptionCreate (see Shopify App Pricing)
• One-time app purchases (via appPurchaseOneTimeCreate) — AI credit packs in AppiFire
• 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 (AppiFire: Shopify App Pricing)

  • Plans free and appifire-ai-chat-plan-1 are defined in the Partner Dashboard.
  • Merchants choose plans on Shopify’s hosted plan picker; the app syncs plan_handle and subscription state (see shopify-app-pricing.md).
  • Legacy / manual billing: other apps may still use appSubscriptionCreate; AppiFire does not use that for new upgrades after migrating to App Pricing.

• 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.0 AppiFire: Shopify App Pricing (current)

1. Merchant clicks Upgrade or Change plan in the embedded app.
2. App redirects window.top to
   https://admin.shopify.com/store/{store}/charges/{appHandle}/pricing_plans.
3. Merchant selects Free or $20/mo plan on Shopify’s page.
4. Shopify redirects back with plan_handle (and optional welcome URL to /app/billing/confirm).
5. App runs resolveSubscriptionState() and updates shops.plan (free | paid).

Full detail: shopify-app-pricing.md.

2.1 Merchant flow (legacy Billing API — reference)

Apps that still use manual recurring billing call appSubscriptionCreate with returnUrl, receive confirmationUrl, and redirect the merchant to Shopify’s confirmation page. AppiFire replaced this upgrade path with the plan picker above.

Historical steps:

1. App calls appSubscriptionCreate with plan name, lineItems (appRecurringPricingDetails), and returnUrl (e.g. /app/billing/confirm).
2. Merchant approves or declines on Shopify’s confirmation page.
3. On approval, subscription becomes ACTIVE and appears on Shopify invoices.

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

Charge type	Shopify mechanism	AppiFire behavior
Free / Paid recurring	Shopify App Pricing (free, appifire-ai-chat-plan-1)	Plan picker redirect; sync via plan_handle + Admin/Partner API
Credit packs	appPurchaseOneTimeCreate	Paid plan only; amounts from ADD_ON_CREDIT_AMOUNTS

• Paid plan ($20/mo): includes PAID_PLAN_INCLUDED_CREDITS_USD per billing period (granted in-app to shops.credit_balance, not by Shopify).
• One-time packs: $10–$200 → balance increment after confirm/reconcile (credits wallet).
• Usage: variable cost per reply deducted from credit_balance (paid/wallet path); 50 replies/month cap on free (Free plan credits).
• Shopify invoices show app subscription + one-time line items; reply-level usage stays in our DB.

---

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. AppiFire: wallet & included credits (implementation)

This page explains Shopify’s billing APIs. AppiFire-specific flows:

• Shopify App Pricing — recurring plans, plan picker, paid vs free detection
• Credits wallet: one-time & subscription — balance, reconcile, included credits, buy-credits gate

---

8. 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.