> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orderprotection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Loop Subscriptions

> Keep Order Protection on Loop subscriptions, and let subscribers turn it on or off from the customer portal

<Note>
  The Loop Subscriptions integration keeps Order Protection on the
  subscriptions where it belongs — automatically on subscriptions whose
  originating order had Order Protection, and on any subscription where
  the customer turns it on in the Loop customer portal. Order Protection
  is added by API to each upcoming order, so there are no theme or
  checkout changes.
</Note>

<Info>
  This page covers **Loop Subscriptions** (loopwork.co). For Loop
  *Returns*, see the [Loop Returns integration](/integrations/loop).
</Info>

## How it works

Loop sends Order Protection a webhook when a subscription is created,
cancelled, about to bill, or billed. For each subscription:

* **If the originating order had Order Protection on it**, we start
  tracking the subscription and keep Order Protection on it
  automatically.
* **If the customer turns Order Protection on in the Loop customer
  portal**, we add it to their next order right away, and to every
  order after that while it stays on. Turning it off removes it from
  the next order right away.
* **Before each order bills**, when Loop sends its *upcoming order*
  notification, we add Order Protection to that order as a one-time
  line, priced from your Order Protection price tiers.
* **Otherwise**, nothing changes. Loop bills the subscription exactly
  as it did before.

When the renewal order reaches Shopify with the Order Protection line,
the order is protected like any other Order Protection order.

### Requirements

* A Loop **Pro** plan. Admin API tokens are only available on Pro.
* Access to Loop's customer portal **Custom JS** (theme settings), to
  show the Order Protection toggle to subscribers.

## Installation

<Steps>
  <Step title="Generate a Loop Admin API token">
    In Loop, go to **Settings → API tokens & webhooks → API tokens** and
    click **Generate New Token**. Give it these scopes:

    * **Subscription contracts**: read and write
    * **Orders**: read
    * **Webhooks**: read and write

    Copy the token. You'll paste it into Order Protection in a later step.
  </Step>

  <Step title="Generate a Loop webhook secret">
    On the same page, open the **Webhook secrets** tab and generate a
    secret. Copy it.

    <Note>
      Loop only signs webhooks once a webhook secret exists, and Order
      Protection rejects unsigned webhooks. The integration can't be
      saved without one.
    </Note>
  </Step>

  <Step title="Connect Loop in Order Protection">
    In the Order Protection dashboard, go to **Integrations** and select
    **Loop Subscriptions**.

    * Paste the token into **Admin API Token**.
    * Paste the secret into **Webhook Secret**.
    * Click **Save**.

    Saving checks the token with Loop and registers Order Protection's
    webhooks in your Loop account automatically — there's no webhook URL
    to copy. If the token is rejected, you'll see `LOOPWORK_TOKEN_INVALID`;
    check the scopes above and that your Loop plan is Pro.
  </Step>

  <Step title="Check Loop's upcoming-order lead time">
    In Loop, go to **Settings → Notifications → Preferences → Upcoming
    order**. Order Protection adds protection to each order when this
    notification is sent, so this setting (1–25 days before billing) is
    how far ahead Order Protection appears on a subscriber's next order.
    The default of a few days works well.
  </Step>

  <Step title="Create the Subscription Widget in Order Protection">
    The toggle in the Loop customer portal takes its styling from a
    **Subscription Widget** config. In the Order Protection dashboard,
    go to **Customizations → Widgets**, click **Create New Widget**,
    select **Subscription** as the widget type, customize it, and click
    **Publish**. Without an active Subscription Widget, the toggle still
    works with default styling.
  </Step>

  <Step title="Add the Order Protection toggle to the Loop customer portal">
    In Loop, go to **Customer portal → Themes** and click **Customize**
    on your live theme.

    1. In **Layout**, click **+ Add section** to create a custom section.
       Set its **HTML ID** to `op-loopwork` and add a short heading such
       as *Order Protection*. Drag it to where the toggle should appear
       on the subscription page, for example above **Next order**.
    2. Open the **Custom JS** panel and paste the following, replacing
       the shop domain with your store's `.myshopify.com` domain:

    ```js Loop Custom JS theme={null}
    window.OrderProtectionLoopworkConfig = {
      shop: 'your-store.myshopify.com',
      anchorSelector: '#op-loopwork',
    };
    (function () {
      var s = document.createElement('script');
      s.src = 'https://cdn.orderprotection.com/subscriptions-widget/snippets/orderprotection-loopwork.js';
      document.head.appendChild(s);
    })();
    ```

    3. Click **Publish changes**.

    The toggle renders just below the `op-loopwork` section on each
    subscription's page. Custom JS only runs on the published portal,
    not in the theme editor's preview, so open a subscription from the
    live customer portal to see it.

    <Note>
      Loop's custom-section editor is a rich-text editor, so pasting
      Order Protection's HTML tag into it doesn't work. The
      `anchorSelector` setting inserts the toggle next to your section
      instead.
    </Note>
  </Step>
</Steps>

<Check>
  Once the integration is saved and the portal snippet is published:

  * Subscriptions whose originating order had Order Protection keep it
    on every renewal automatically.
  * Any subscriber can turn Order Protection on or off from the
    subscription page in the Loop customer portal. Their next order
    reflects the change immediately.
</Check>

## What gets added (and what doesn't)

* **Subscriptions that started with Order Protection, or that the
  customer opted in**: Order Protection is added to each upcoming order
  as a one-time line. The price comes from your Order Protection price
  tiers, based on the order's merchandise subtotal (shipping and Order
  Protection itself excluded), and the toggle shows the same price that
  will be charged.
* **Subscriptions that didn't start with Order Protection and aren't
  opted in**: nothing changes.
* **Cancelled subscriptions**: Order Protection stops being added as
  soon as Loop sends the cancellation webhook.
* **Turning the integration off** in Order Protection stops Order
  Protection from being added and removes its Loop webhooks. Protection
  already added to a subscriber's next order stays on that order unless
  the subscriber turns it off in the portal.

## Webhook events Order Protection listens for

| Loop event | What we do |
| - | - |
| `subscription/created` | Start tracking the subscription if its originating order had Order Protection |
| `order/upcoming` | Add Order Protection to the upcoming order for tracked, opted-in subscriptions (or remove it if they've opted out) |
| `order/processed` | Record the renewal and roll the subscription forward |
| `subscription/cancelled` | Stop adding Order Protection to the subscription |
| `order/skipped`, `order/paymentFailed` | Recorded for history |

Every webhook must carry a valid Loop signature made with your webhook
secret; unsigned or mismatched deliveries are rejected.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Saving the integration fails with LOOPWORK_TOKEN_INVALID">
    Loop rejected the Admin API token. Regenerate it in Loop with the
    scopes listed in step 1 (including **Webhooks: read and write**)
    and confirm your Loop plan is **Pro**, then save again.
  </Accordion>

  <Accordion title="Saving the integration fails with LOOPWORK_WEBHOOK_SECRET_REQUIRED">
    Generate a webhook secret in Loop under **Settings → API tokens &
    webhooks → Webhook secrets** and paste it into the **Webhook
    Secret** field.
  </Accordion>

  <Accordion title="The toggle isn't showing in the Loop customer portal">
    Check, in order:

    * The theme changes were **published**. Custom JS doesn't run in the
      editor preview.
    * The custom section's **HTML ID** is exactly `op-loopwork`, and the
      Custom JS `anchorSelector` matches it.
    * The `shop` value in Custom JS is your `.myshopify.com` domain.
    * Your store's widget bundle is live. The snippet loads
      `cdn.orderprotection.com/subscriptions-widget/<your-store>/widget.js`,
      where `<your-store>` is the part of your Shopify domain before
      `.myshopify.com`:

    ```bash theme={null}
    curl -I https://cdn.orderprotection.com/subscriptions-widget/<your-store>/widget.js
    ```

    A `200 OK` means the bundle is live. On `404`, your Onboarding &
    Implementation manager can trigger a Cart Deployment from the Order
    Protection admin dashboard to build it.
  </Accordion>

  <Accordion title="A subscriber turned Order Protection on but a renewal didn't include it">
    Order Protection is added to the subscriber's next order when they
    turn it on, and to later orders when Loop sends its upcoming-order
    notification. If an order was placed immediately (for example with
    **Order now**) right after a previous order, check that the
    **Upcoming order** notification lead time in Loop is set, and that
    the integration is turned on in Order Protection.
  </Accordion>

  <Accordion title="The toggle renders with default styling">
    The **Subscription Widget** config is missing or still in **Draft**.
    In the Order Protection dashboard, go to **Customizations →
    Widgets**, open (or create) the **Subscription** widget, and click
    **Publish**.
  </Accordion>
</AccordionGroup>

<Tip>
  **Headless customer portals** (for example a Shopify Hydrogen store)
  can render the toggle too: add
  `<order-protection data-op-integration="loopwork"></order-protection>`
  where it should appear, load
  `https://cdn.orderprotection.com/subscriptions-widget/snippets/orderprotection-loopwork.js`,
  and call
  `window.bootstrapOrderProtectionLoopwork({ shop, customer: { shopifyId }, subscriptions: [subscription] })`
  with the Loop subscription and the customer's Shopify id. Contact
  your Onboarding & Implementation manager for help.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.