How to enable Zapiet integration

Complete step-by-step guide to enable and configure the 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