# How to enable Zapiet integration

Setting up the Zapiet integration with Joy Subscription is straightforward. This guide walks you through installation, verification, and understanding how delivery dates work for your recurring orders.

### Part 1: Installation and Setup

**Step 1: Install Zapiet App**

Before you can enable the integration, you need Zapiet installed on your Shopify store. If you haven't installed it yet, get it from the Shopify App Store.

**Step 2: Enable the Integration**

1. Open the Joy Subscription app in your Shopify admin
2. Navigate to **Settings → Integrations**
3. Find the Zapiet card and click **"Try now"**
4. You'll see two steps on the integration detail page:
   * **Step 1 - Install Zapiet:** If not installed, click "Install app" to go to the App Store
   * **Step 2 - Enable Zapiet integration:** Toggle this ON to activate the integration
5. Once enabled, the status badge will change to "Connected" (green)

Note: The "Enable Zapiet integration" toggle will only be available after Zapiet is installed on your store.

**Step 3: Verify It's Working**

Test the integration to make sure everything is set up correctly:

1. Create a test subscription order on your storefront
2. At the cart page, the Zapiet widget should appear for selecting delivery/pickup date
3. Complete the checkout
4. In Joy Subscription, go to **Contracts** and open the new contract
5. You should see a **"Custom Attributes"** card displaying the Zapiet delivery information

The Custom Attributes card will show:

| Attribute            | Example    | Description               |
| -------------------- | ---------- | ------------------------- |
| Checkout-Method      | delivery   | Delivery or pickup        |
| Delivery-Location-Id | 306646     | Zapiet location ID        |
| Delivery-Date        | 2026-01-27 | Selected delivery date    |
| Custom-Attribute-1   | Zone 1     | Delivery zone from Zapiet |

### Part 2: Understanding Delivery Date Calculations

**Key Concepts**

Every subscription order has two important dates:

* **Charge Date:** When Joy Subscription creates the order and charges the customer's payment method
* **Delivery Date:** When the customer receives their order (delivery or pickup), managed by Zapiet
* **Gap:** The number of days between Charge Date and Delivery Date (this stays constant for all recurring orders)

**How the System Calculates Dates**

The system uses these formulas for recurring orders:

```
Gap = Initial Delivery Date − Initial Charge Date
Recurring Delivery Date = Previous Delivery Date + Frequency
Recurring Charge Date = Recurring Delivery Date − Gap
```

**Example 1: Weekly Subscription with 1-Day Gap**

A customer subscribes to a weekly meal box. They checkout on July 23 and select delivery for July 24.

* Frequency: 1 week
* Initial Charge Date: July 23
* Initial Delivery Date: July 24
* Gap: 1 day

| Order       | Charge Date | Delivery Date | Gap   |
| ----------- | ----------- | ------------- | ----- |
| 1 (Initial) | July 23     | July 24       | 1 day |
| 2           | July 30     | July 31       | 1 day |
| 3           | August 6    | August 7      | 1 day |
| 4           | August 13   | August 14     | 1 day |

**Example 2: Weekly Subscription with 4-Day Gap**

A customer subscribes to a weekly flower delivery. They checkout on July 20 (Monday) and select delivery for July 24 (Friday).

* Frequency: 1 week
* Initial Charge Date: July 20 (Monday)
* Initial Delivery Date: July 24 (Friday)
* Gap: 4 days

| Order       | Charge Date    | Delivery Date  | Gap    |
| ----------- | -------------- | -------------- | ------ |
| 1 (Initial) | July 20 (Mon)  | July 24 (Fri)  | 4 days |
| 2           | July 27 (Mon)  | July 31 (Fri)  | 4 days |
| 3           | August 3 (Mon) | August 7 (Fri) | 4 days |

### Part 3: Handling Blackout Dates

**What Are Blackout Dates?**

Blackout dates are days when you cannot make deliveries, configured in your Zapiet app. Common examples include holidays, weekends, or days when your business is closed.

**How They Work with Subscriptions**

**For Initial Orders:** The Zapiet widget on your cart page automatically blocks blackout dates, so customers cannot select them.

**For Recurring Orders:** Since delivery dates are calculated automatically based on frequency, a recurring delivery date may fall on a blackout date. Here's what happens:

1. The system detects that the upcoming delivery date is a blackout date
2. On the scheduled charge date, the payment is still processed
3. After successful charge, the order status changes to "Skipped"
4. The system displays an error message: "Skip: blackout date"

**Important:** When an order is skipped due to a blackout date, the customer has already been charged. You need to manually process a refund or apply a credit to their next order.

**Example Scenario**

Customer has weekly delivery on Fridays. July 26 is a holiday (blackout date).

| Order | Delivery Date  | Status    | Action Required        |
| ----- | -------------- | --------- | ---------------------- |
| 1     | July 19 (Fri)  | Delivered | None                   |
| 2     | July 26 (Fri)  | Skipped   | Refund or apply credit |
| 3     | August 2 (Fri) | Delivered | None                   |

### Part 4: Managing Custom Attributes

**Viewing Custom Attributes**

To view the Zapiet delivery information for a subscription:

1. Go to **Contracts** in Joy Subscription
2. Click on a contract to open the details page
3. Look for the **"Custom Attributes"** card (only visible for contracts with Zapiet info)

**Editing Custom Attributes**

You can manually edit the custom attributes if needed:

1. Click the Edit icon on the Custom Attributes card
2. Modify the values as needed
3. Save your changes

Note: When you edit the Delivery Date, future recurring delivery dates will be recalculated from this new date.

**Address Change and Zone Sync**

When the shipping address changes, the delivery zone is automatically updated:

**Merchant changes address (in Contract details):**

1. Go to Contract details → Delivery information card
2. Click Edit on Shipping address
3. Enter new address → Save
4. Custom Attributes (zone) will update based on new zipcode

**Customer changes address (in Customer Portal):**

1. Customer logs into Customer Portal
2. Updates their shipping address
3. System automatically syncs the new zone based on zipcode

### Part 5: Troubleshooting

| Issue                                    | Solution                                                                                                         |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Toggle is greyed out                     | Zapiet app is not installed. Install it from Shopify App Store first.                                            |
| No Custom Attributes card                | The initial order may not have Zapiet delivery info. Customer might not have selected delivery date at checkout. |
| Delivery dates not calculating correctly | Ensure subscription uses day/week/year intervals. Monthly intervals may not work correctly with Zapiet.          |
| Zone not updating after address change   | The new zipcode may not be within any Zapiet delivery zone. Check your Zapiet zone configuration.                |
| Orders being skipped unexpectedly        | Check if the delivery date falls on a blackout date in Zapiet. Review your blackout date settings.               |

### Need Help?

If you encounter any issues or need assistance with the Zapiet integration, contact support through:

* **In-app chat:** Click the chat icon in Joy Subscription app
* **Email:** Contact the support team for complex setup assistance
* **Help Center:** Visit the documentation for more guides and FAQs