# Introduction to Zapiet integration

If you sell subscription products that need local delivery or store pickup, you face a unique challenge: customers select their delivery date only during the first checkout, but recurring orders are created automatically without customer input. Without integration, recurring orders have no delivery date information.

The Zapiet integration solves this by automatically calculating delivery dates for all recurring orders based on your subscription frequency.

### What It Does

Joy Subscription integrates with Zapiet to automatically calculate delivery dates for all recurring orders based on your subscription frequency. This ensures:

* **Consistent delivery scheduling** across all subscription cycles
* **Automatic handling** of delivery zones and custom attributes
* **Proper management** of blackout dates
* **Maintained preparation gaps** between charge and delivery dates

**Example:**

If a customer chooses delivery on Wednesday and subscribes to a weekly plan, all future deliveries will automatically be scheduled for Wednesdays.

### Key Features

**Automatic Delivery Date Calculation**

When a customer places their first subscription order, they select a delivery date through the Zapiet widget. Joy Subscription then automatically calculates delivery dates for all future recurring orders based on your subscription frequency. If a customer chooses delivery on Wednesday and subscribes to a weekly plan, all future deliveries will automatically be scheduled for Wednesdays.

**Gap Preservation**

The system maintains the same gap between the charge date and delivery date for all orders. If your initial order charges on Monday and delivers on Wednesday (2-day gap), all recurring orders will maintain this 2-day gap.

| Order  | Charge Date | Delivery Date | Gap    |
| ------ | ----------- | ------------- | ------ |
| Week 1 | July 20     | July 24       | 4 days |
| Week 2 | July 27     | July 31       | 4 days |
| Week 3 | August 3    | August 7      | 4 days |

**Custom Attributes Sync**

Joy Subscription captures and stores Zapiet delivery information for each subscription contract, including:

* Delivery Method: Whether the customer chose delivery or pickup
* Delivery Zone: The zone assigned based on customer's address
* Location ID: The specific pickup location or delivery area
* Delivery Date: The scheduled delivery date for each order

**Blackout Date Handling**

When a recurring order's delivery date falls on a blackout date (a day you've marked as unavailable in Zapiet), the system handles it automatically:

1. The charge is processed as scheduled
2. After successful charge, the order is marked as "Skipped"
3. An error message indicates: "Skip: blackout date"
4. You can then process a refund or apply credit for the next cycle

Note: When orders are skipped due to blackout dates, refunds must be processed manually by the merchant.

**Address Change Sync**

When a customer or merchant updates the shipping address, the system automatically updates the delivery zone and custom attributes based on the new address's zip code. This ensures delivery information stays accurate even when customers move or change their delivery location.

### Who Should Use This Integration

This integration is ideal for merchants who:

* **Sell perishable goods:** Fresh produce, prepared meals, dairy products, or flowers that require scheduled delivery
* **Offer local delivery:** Deliver within a specific geographic area and need to manage delivery capacity
* **Provide store pickup:** Allow customers to collect orders from physical locations
* **Need delivery scheduling:** Want customers to choose specific delivery dates rather than receiving orders randomly
* **Have capacity limits:** Need to limit the number of deliveries per day or time slot

### What You Need

Before you start:

* Joy Subscription app (with subscription plans configured)
* Zapiet – Pickup + Delivery app from Shopify
* Zapiet set up with delivery zones and available dates
* Subscriptions using day, week, or year intervals (monthly isn't fully supported)

### Important Limitations

**Supported Intervals**

Only day, week, and year intervals are fully supported. Monthly intervals may not work correctly with Zapiet's date incrementation.

**Single Frequency per Order**

Each subscription order should contain products with the same frequency. Mixing different frequencies may cause date calculation errors.

**Backward Date Changes**

Changing the delivery date to a past date is not supported and may cause missed deliveries.

**Blackout Date Refunds**

When orders are skipped due to blackout dates, refunds must be processed manually by the merchant.

### Example Use Case

A farm offers produce boxes delivered every two weeks. Customers select their delivery day during checkout, and the farm maintains a 2-day gap between charging and delivery for harvest and packing time. During winter holidays, blackout dates prevent deliveries when the farm is closed. When customers move, the system automatically updates their delivery zone based on their new address.

The result: consistent delivery scheduling without manual intervention, and customers receive their produce on the same day every cycle.

### Requirements

Before enabling the integration, ensure you have:

* Joy Subscription app installed and configured with subscription plans
* Zapiet – Pickup + Delivery app installed from the Shopify App Store
* Zapiet configured with your delivery zones, pickup locations, and available dates
* Subscription products that use day, week, or year intervals (monthly intervals are not fully supported by Zapiet)

### Get Started

Ready to set up the integration? Check out the detailed setup guide: "How to Set Up Zapiet Integration with Joy Subscription" for step-by-step instructions on enabling the integration and understanding how delivery dates are calculated.

If you need assistance with the setup, contact support through:

* In-app chat in Joy Subscription
* Email support