Shopify app

The Subby Checkout Shopify app lets selected products enrol subscribers through Subby checkout. Shopify remains your storefront and order list. Subby remains the Subscription OS: plans, mandates, renewals, recovery and signed lifecycle events.

The app is not a payment gateway. Payment rails collect the charge. The app creates checkout sessions, records the matching Shopify order, and updates that order when webhooks arrive.

For a custom storefront, use @mysubbyapp/checkout. For WordPress, see the WordPress plugin.

Installation

1. In Shopify Admin → Apps and sales channels, click Add apps or sales channels.
2. Search for Subby Checkout.
3. Open the app and click Install.

The app asks for:

Setup

1. Connect Subby

1. Open Subby Checkout from your apps list.
2. Go to Settings → API configuration.
3. Click Connect Subby account and authorise in the Subby dashboard.
4. Confirm the environment: Test with pk_test_ while you integrate, Live only after going live.

2. Choose products

1. Open Products in the app.
2. Select the Shopify products that should offer Subby checkout.
3. Save.

Only selected products show the Subby subscribe path. Other products keep your existing Shopify checkout.

You can also open a product in Shopify Admin, scroll to Subby Checkout, and toggle Enable for this product.

3. Appearance

In Settings → Appearance:

• Theme — light or dark.
• Accent colour — hex, used on buttons and highlights.
• Logo — optional store logo on the checkout surface.

4. Webhooks

Keep Settings → Webhooks → Enable webhooks on. The app endpoint looks like:

https://your-app.myshopifyapps.com/webhooks/orders

Use Test connection after you connect. Deliveries also appear in Dashboard → Developers → Webhooks.

Customer flow

1. The subscriber opens an enabled product and chooses Subscribe with Subby.
2. Embedded checkout collects bank selection and mandate authorisation.
3. Shopify shows the order as Pending while the mandate waits on the bank (often 5 minutes, up to 24 hours).
4. When Subby emits subscription.created, the app marks the order active and can auto-fulfil if that setting is on.

Do not treat the in-browser mandate_pending event as fulfilment. Wait for the webhook.

Order status

Filter orders with the subby-subscription tag.

Configuration

Webhooks

The app listens for the same signed events as any Subby integration. See Webhooks for signatures, retries and payload shape.

Example subscription.created body (truncated):

{
  "id": "evt_3Lk9qPz1Tx",
  "object": "event",
  "type": "subscription.created",
  "data": {
    "object": {
      "id": "sub_9fK3mQ2xLp",
      "object": "subscription",
      "status": "active",
      "customer": "cus_4kQ2mT",
      "plan": "plan_8ZpR1v"
    }
  }
}

Testing

In Test mode, create an order with a sandbox payment method, then use Simulate webhook in the app if you need to exercise activation without waiting on a bank.

In Live mode, the bank confirms the mandate and Subby delivers subscription.created on its own.

App dashboard

From an order you can resend the confirmation, mark paid (manual override), refund, or cancel the subscription. Refunds and mandate changes should still be confirmed in the Subby dashboard — Shopify tags follow Subby state.

Subscription management

1. In Shopify Orders, filter by subby-subscription.
2. Open the order to see Subby status.
3. Use Mark subscription active only as a manual override after you have confirmed the mandate in Subby.
4. Cancel subscription asks for confirmation and notifies the customer.

Operate retries, reminders and mandate updates in Subby. The Shopify order is the storefront record, not the source of truth for the subscription engine.

Troubleshooting

Subscribe button does not show

1. Confirm the product is enabled in the app Products list.
2. Check Settings → API configuration is connected.
3. Hard-refresh the product page. If a custom theme hides app blocks, test with a default theme.

Connection failed

Disconnect and reconnect the Subby account. Confirm the publishable key still exists and is not revoked. Live keys only work after live access is approved.

Orders do not update

1. Settings → Webhooks → Test connection.
2. Read Webhook logs in the app and Developers → Webhooks → Deliveries in Subby.
3. Confirm you are looking at orders tagged subby-subscription for the correct date.

Checkout completes but no Shopify order

Turn on order creation / auto-create in Settings → Advanced. Pending orders may exist before the webhook; filter by today's date and the Subby tag.

Frequently asked questions

Do I need a Subby account?

Yes. Sign up at mysubbyapp.com, then connect the app with a publishable key.

What collection methods are available?

That depends on the rails enabled on your Subby account. See Country and rail coverage. Nigeria uses authorised debit mandates.

Can subscribers use Shopify Payments on the same store?

Yes. Subby checkout is for products you enable in the app. One-time purchases can keep using Shopify Payments or other apps.

Can I test without live charges?

Yes. Use Test environment, pk_test_ keys, and sandbox payment methods.

What happens when a renewal fails?

Subby retries according to the plan, sends configured nudges, and emits charge.failed then subscription.past_due. The app tags the order. After escalation, follow failed-payment recovery.

Can subscribers pause from Shopify?

Pause and resume from the Subby dashboard or the subscriber portal. The Shopify order tags update when those webhooks arrive.

How is tax handled?

Amounts on the Subby checkout session are what the subscriber authorises. The Shopify order stores the matching totals for your store records.

Can I export subscriber data?

Yes. Dashboard → Customers → Export CSV in the app.

Next steps

• @mysubbyapp/checkout — Embed the same checkout on a custom storefront.
• Webhooks — Signatures, retries and event types.
• Merchant operations — Plans, customers and subscription states in Subby.
• Going live — Live keys and launch checklist.