# Overview

Zotlo is a modern revenue orchestration platform built to help digital businesses scale globally with minimal engineering effort. With a single integration, you can sell your digital product worldwide, manage subscriptions and billing, and launch monetization workflows in minutes.

Built for mobile apps, games, SaaS, and web products. Zotlo offers flexible checkout options, powerful subscription controls, and seamless web-to-app and app-to-web integrations, all from one unified interface.

<div data-full-width="false" data-with-frame="true"><figure><img src="/files/kPmJKmVVGpK5DzsX25EQ" alt="" width="563"><figcaption></figcaption></figure></div>

## **Why Zotlo?**

Zotlo simplifies the entire monetization stack, from global payments and customizable checkout experiences to flexible plans and deep analytics. Whether you choose no-code or developer-friendly low-code setup, you’ll launch faster and operate more efficiently without managing infrastructure.

## **Key Features**

Zotlo provides a complete infrastructure for [managing subscriptions](/features/subscriptions/subscriptions-overview), [payments](/features/payment-methods/payment-methods-overview), [pricing](/features/products-and-plans/products-overview) and [checkout](/features/checkout/checkout-overview) experiences including [quiz funnels](/features/quiz-funnels/funnels-flows-overview) across web and mobile environments. With flexible APIs, webhooks, and SDKs, developers can build scalable billing flows, automate lifecycle events, and synchronize user data in real time.

### **Global Payments**

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>🌎</h3></td><td><strong>195+ Countries, Multiple Methods</strong></td><td>Accept secure payments worldwide via Visa, Mastercard, Amex, Apple Pay, Google Pay, PayPal, and major local methods.</td><td><a href="/pages/ULmoXhthX9AEP6aH6ZSe">/pages/ULmoXhthX9AEP6aH6ZSe</a></td><td><a href="/pages/ULmoXhthX9AEP6aH6ZSe">/pages/ULmoXhthX9AEP6aH6ZSe</a></td></tr><tr><td><h3>💲 </h3></td><td><strong>Localized Pricing</strong></td><td>Boost conversion by offering country-specific pricing and payments in users’ local currencies. </td><td><a href="/pages/Q4QxztiAOWwsCH9FicQu">/pages/Q4QxztiAOWwsCH9FicQu</a></td><td><a href="/pages/Q4QxztiAOWwsCH9FicQu">/pages/Q4QxztiAOWwsCH9FicQu</a></td></tr></tbody></table>

### **Subscription Management**

**Full Subscription Lifecycle Management**\
[Manage subscriptions](/features/subscriptions/subscriptions-overview), renewals, cancellations, upgrades, downgrades, pauses, auto-renewals, and billing from a single dashboard.

**Retention Tools**\
Reduce churn with smart retries, automated dunning, and win-back incentives.

### **Smart Sales**

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>🛒 </h3></td><td><strong>Flexible Checkout Options</strong></td><td>Use embedded or hosted checkout flows, or generate checkout links via API to support any sales experience you need. </td><td><a href="/pages/lR7PFe0TnvNvDViTQNgI">/pages/lR7PFe0TnvNvDViTQNgI</a></td><td><a href="/pages/lR7PFe0TnvNvDViTQNgI">/pages/lR7PFe0TnvNvDViTQNgI</a></td></tr><tr><td><h3>📋</h3></td><td><strong>User Onboarding Funnels</strong></td><td>Build targeted pre-checkout quiz funnels to personalize offers and increase conversion rates.</td><td><a href="/pages/q5nXhnNW1y4DdcdjTReZ">/pages/q5nXhnNW1y4DdcdjTReZ</a></td><td><a href="/pages/q5nXhnNW1y4DdcdjTReZ">/pages/q5nXhnNW1y4DdcdjTReZ</a></td></tr><tr><td><h3>📦</h3></td><td><strong>Billing Controls</strong></td><td>Configure one-time purchases, subscriptions, trials, promotions, and discounts with fully flexible pricing options.</td><td><a href="/pages/AgMIz9ml27dnJ6SePAgX">/pages/AgMIz9ml27dnJ6SePAgX</a></td><td><a href="/pages/AgMIz9ml27dnJ6SePAgX">/pages/AgMIz9ml27dnJ6SePAgX</a></td></tr></tbody></table>

### **Analytics & Optimization**

**Real-Time Monitoring**\
Track traffic, conversions, and sales performance instantly as users interact with your product.

**User Journey Insights**\
Identify friction points across the checkout flow and optimize user behavior and funnel performance.

**Comprehensive Revenue & Subscription Analytics**\
Access detailed metrics on revenue, users, subscriptions, and transactions to guide strategic decisions.

→ [Explore Dashboard Analytics](/features/dashboard-analytics)

### **Easy & Fast Setup**

**No-Code & Low-Code Options**\
Start using Zotlo in minutes with ready-to-use components or minimal development effort.

**Customizable Themes**\
Launch branded checkout pages and funnels using clean, easy-to-customize design themes.

**Branded Checkout on Your Domain**\
Strengthen trust and consistency with fully branded checkout experiences hosted under your own domain.

→ [Explore Checkout Options](/features/checkout/checkout-overview)

→ [Explore Quiz Funnels](/features/quiz-funnels/funnels-flows-overview)

## **Seamless Integration**

Zotlo provides flexible integration options to fit different product architectures.\
Whether you prefer APIs, webhooks, SDK-based checkout, or cross-platform user flows, Zotlo enables you to build scalable payment and subscription experiences.

### API Services

Build fully customized payment and subscription workflows using Zotlo’s REST APIs. Manage subscriptions, retrieve payment data, create checkout links, and control billing operations programmatically.

→ [Explore API Reference](/integrating-zotlo/api-reference/introduction)

### Webhook Services

Receive real-time event notifications directly to your backend. Webhooks notify your system about subscription updates, payments, refunds, user registrations, and quiz responses.

→ [Explore Webhooks](/integrating-zotlo/webhooks/webhooks-overview)

### Checkout SDK

Embed a secure and customizable checkout form directly into your website using Zotlo’s Web SDK. Maintain a seamless payment experience without redirecting users away from your product.

→ [Explore Checkout SDK](/integrating-zotlo/web-sdk/sdk-overview)

### Personalized Checkout

Generate dynamic checkout links tailored to individual users or campaigns. Customize price, currency, text content, or metadata to create targeted purchase flows.

→ [Explore Personalized Checkout API](/integrating-zotlo/api-reference/checkout-endpoints)

### App → Web Payments

Redirect users from your mobile app to a secure web-based checkout to complete their purchase. This flow allows you to offer additional payment methods and manage subscriptions outside app store billing systems.

→ [Learn about App-to-Web Flows](/integrating-zotlo/user-sync)

### Web → App Conversion

Convert mobile web visitors into app users while keeping their identity and purchase history synchronized across platforms. Ideal for acquisition campaigns and funnel-based onboarding.

→ [Learn about Web-to-App Flows](/integrating-zotlo/user-sync)

### **Multi-Language Support**

Deliver localized user experiences across your checkout pages and quiz funnels. Zotlo allows you to present content, forms, and payment flows in multiple languages, helping improve conversion rates and user trust in different markets.

→ [Learn about Multi-Language Setup](/features/checkout/multi-language)

## 3rd-Party Integrations

Zotlo integrates with major marketing, attribution, and analytics platforms, allowing you to track conversions, optimize campaigns, and analyze user behavior across your sales funnels.

### Ad Platforms

Track purchases and subscription events directly inside advertising platforms to optimize campaigns and improve return on ad spend (ROAS).

Supported platforms include **Meta Ads** and **Google Ads**.

→ [View Ad Platform Integrations](/3rd-party-integrations/ad-platforms)

### Attribution Platforms

Send payment and subscription events to mobile attribution tools to measure install-to-revenue performance and user acquisition efficiency.

Supported platforms include **AppsFlyer** and **Adjust**.

→ [View Attribution Integrations](/3rd-party-integrations/attribution)

### Analytics Platforms

Analyze user behavior and funnel performance by sending checkout and purchase events to analytics tools.

Supported platforms include **Google Analytics** and **Google Tag Manager**.

→ [View Analytics Integrations](/3rd-party-integrations/analytics)

## Main Topics

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>⚡️</h3></td><td><strong>Quickstart Guide</strong></td><td><p>A step-by-step overview to help you onboard, connect, and go live with Zotlo.</p><p><br><a href="/pages/7FvWQMF0kTK7HGhlQfmo">Quickstart Guide</a></p></td><td></td><td></td><td><a href="/pages/7FvWQMF0kTK7HGhlQfmo">/pages/7FvWQMF0kTK7HGhlQfmo</a></td></tr><tr><td><h3>💼</h3></td><td><strong>Merchant Of Record</strong></td><td><p>An overview of Zotlo’s role as the legal seller managing taxes, billing, and compliance.</p><p><br><a href="/pages/nZurTyCXgIEXlbnwlNah">MoR Model</a> </p><p><a href="/pages/QK18GZnetv6NN4eL1eDn">Connect Your PSP</a></p><p><a href="/pages/nZurTyCXgIEXlbnwlNah#mor-vs-payment-service-provider-psp">MoR vs PSP</a></p></td><td></td><td></td><td><a href="/pages/nZurTyCXgIEXlbnwlNah">/pages/nZurTyCXgIEXlbnwlNah</a></td></tr><tr><td><h3>🔄</h3></td><td><strong>Subscriptions</strong></td><td><p>A guide to creating, managing, and optimizing subscription plans and lifecycles.</p><p></p><p><a href="/pages/imnHKo3ZCOZpCUX6L6Xy">Subscription Management</a><br><a href="/pages/edCwzQz2f1Jbie2dvTrP">Subscription Plans</a><br></p></td><td></td><td></td><td><a href="/pages/dzQbyP4NGmV7IYB1OBiu">/pages/dzQbyP4NGmV7IYB1OBiu</a></td></tr><tr><td><h3>📦</h3></td><td><strong>Pricing</strong></td><td><p>A guide to configuring global prices, localized pricing rules, and product-level settings.</p><p></p><p><a href="/pages/i73g4LZQanoLj7XtSO18">Products &#x26; Pricing</a></p></td><td></td><td></td><td><a href="/pages/AgMIz9ml27dnJ6SePAgX">/pages/AgMIz9ml27dnJ6SePAgX</a></td></tr><tr><td><h3>💳</h3></td><td><strong>Checkout</strong></td><td><p>An introduction to Zotlo’s checkout options and purchase experiences.<br></p><p><a href="/pages/cU7rIcCiKCZIri8jp5wb">Checkout Options</a><br><a href="/pages/lFdkqCMM0ijINcrcfFBN">Checkout SDK</a></p></td><td></td><td></td><td><a href="/pages/lR7PFe0TnvNvDViTQNgI">/pages/lR7PFe0TnvNvDViTQNgI</a></td></tr><tr><td><h3>🎯</h3></td><td><strong>Quiz Funnels</strong></td><td>A quick look at creating onboarding funnels that personalize offers and boost conversion.<br><br><a href="/pages/MxpeXBkxDnfaJ5hmv8qH">Quiz Funnels Guide</a></td><td></td><td></td><td><a href="/pages/q5nXhnNW1y4DdcdjTReZ">/pages/q5nXhnNW1y4DdcdjTReZ</a></td></tr><tr><td>🔌</td><td><strong>3rd Party Integrations</strong></td><td>Learn to connect  attribution, analytics, and marketing platforms seamlessly.<br><br><a href="/pages/AEeFKMbYAYHsVcrZOHLN">Ad Platforms</a><br><a href="/pages/apEhiEMsjHdrnFa7eUTK">3rd party Analytics</a><br><a href="/pages/HnOibtipGyjBNom7kvTy">Attribution Platforms</a></td><td></td><td></td><td><a href="/pages/HoBXmGFNaQpsE7TGjpFJ">/pages/HoBXmGFNaQpsE7TGjpFJ</a></td></tr><tr><td>📊</td><td><strong>Analytics</strong></td><td><p>A quick look at tracking revenue, users, subscriptions, and payment performance.</p><p><br><a href="/pages/ZnATt28zHJlXcPOLEpEc">Dashboard Analytics</a></p><p><a href="/pages/j0V8MQcEk3Ic4o0dII37">Financials</a><br></p></td><td></td><td></td><td><a href="/pages/ZnATt28zHJlXcPOLEpEc">/pages/ZnATt28zHJlXcPOLEpEc</a></td></tr><tr><td>🧩</td><td><strong>Integrating Zotlo</strong></td><td><p>Essential information on using APIs, webhooks, SDKs and 3rd party analytics to connect Zotlo.<br></p><p><a href="/pages/lFdkqCMM0ijINcrcfFBN">Web SDK</a><br><a href="/pages/zcObw6iQvrl5xuK5Sog9">API Services</a><br><a href="/pages/193bHj5d836MF2zlZQ4Z">Webhooks</a></p></td><td></td><td></td><td><a href="/pages/iMhz7WPOCJRz6R9Dzdbr">/pages/iMhz7WPOCJRz6R9Dzdbr</a></td></tr></tbody></table>


# Quickstart Guide

Get up and running with Zotlo in minutes. This guide walks you through the essential steps to integrate Zotlo, configure your first checkout, and start processing payments. Follow the steps to launch your first transaction quickly and verify that your integration works as expected.

{% stepper %}
{% step %}

### **Create Your Account**

Sign up for a new Zotlo account and log in to your dashboard [console.zotlo.com](https://console.zotlo.com).
{% endstep %}

{% step %}

### **Add Your First Project**

From the left menu, click **+ Add Project**.\
Enter a project name, this is enough to get started.
{% endstep %}

{% step %}

### **Add Your First Product**

Go to **Sales Packages** and create your first item:

* Subscription plan
* One-time purchase
* Trial or introductory offer
* Local pricing options

Set the fundamentals of what you’ll be selling.&#x20;

Explore the details of [Products & Pricing](/features/products-and-plans).
{% endstep %}

{% step %}

### **Choose Your Service Model**

Select how you want Zotlo to process payments and handle financial operations:

**→** [**Merchant of Record (MoR)**](/welcome/merchant-of-record)

Zotlo manages taxes, billing, invoicing, and payouts.&#x20;

**→** [**Connect Your PSP**](/welcome/connect-your-psp)

Use your own payment provider (Stripe, Adyen, Checkout). Zotlo manages subscriptions & checkout while you receive the funds directly.&#x20;
{% endstep %}

{% step %}

### **Configure Payment Methods**

[Credit and debit cards](/features/payment-methods/cards) are enabled by default under the **Merchant of Record** model.\
To activate additional payment methods such as [Apple Pay](/features/payment-methods/apple-pay), [Google Pay](/features/payment-methods/google-pay), or [PayPal](/features/payment-methods/paypal), submit an activation request in **Dashboard → Integrations → Payment Methods**. These methods will go live after the platform verification process.

If you prefer using your own PSP instead, you can connect your provider account by adding your API credentials.
{% endstep %}

{% step %}

### **Design Your Sales Interface**

Choose the type of sales surface you want:

* [Hosted Checkout](/features/checkout/hosted-checkout-no-code) (no-code, fastest setup)
* [Embedded Checkout](/features/checkout/embedded-checkout) (integrated on your own site)
* [Funnel Interfaces](/features/quiz-funnels) (quiz funnels, multi-step flows)

{% hint style="info" %}
If using Hosted Checkout or flow links, remember to **set up your domain mapping**.
{% endhint %}
{% endstep %}

{% step %}

### **Configure Integrations**

If you want to receive real-time purchase and subscription events on your server, integrate:

* [Zotlo Webhooks](/integrating-zotlo/webhooks)
* [Zotlo Server-to-Server API](/integrating-zotlo/api-reference)

For marketing and analytics event flows, connect:

* [Meta Ads](/3rd-party-integrations/ad-platforms/meta-ads)
* [Google Ads](/3rd-party-integrations/ad-platforms/google-ads)
* [Google Analytics](/3rd-party-integrations/analytics/google-analytics)
* [Google Tag Manager](/3rd-party-integrations/analytics/google-tag-manager)
* [AppsFlyer](/3rd-party-integrations/attribution/appsflyer)
* [Adjust](/3rd-party-integrations/attribution/adjust)

Add your integration keys in **Dashboard → Integrations →** **Events**.
{% endstep %}

{% step %}

### **Configure Project Settings**

Before you start selling, configure your project settings. These global settings are required for compliance and proper user redirection.

**→**&#x41;dd Your Legal & Support Pages

Provide links to your Privacy Policy, Terms of Service, and Customer Support pages to ensure transparency and compliance. You can manage these settings via:\
Zotlo Dashboard → Your Project → Project Settings → Support Links

→Add Your App or Website Links

Provide your app’s store links or deeplinks to help users continue seamlessly after purchase. You can manage these via: Zotlo Dashboard → Your Project → Project Settings → Download Links
{% endstep %}

{% step %}

### **Publish and Start Selling  🚀**

Publish your checkout or sales link, run your campaigns, and start selling.

The dashboard will immediately show:

* Sales & revenue
* Active subscribers
* Renewals & churn
* Payouts or commission invoices
* Traffic statistics
* Funnel performance

{% endstep %}
{% endstepper %}


# Merchant Of Record

## **What is Merchant of Record?**

A Merchant of Record (MoR) is the **legal entity that sells goods or services to the end customer on your behalf**.&#x20;

When you use an MoR:

* The MoR appears as the seller on customer receipts and credit card statements.
* The MoR takes on legal, tax and compliance responsibility for all transactions.

In other words:

* **Your product is yours,** you control pricing, features, and delivery.
* **The MoR handles the financial and legal side** of every transaction behind the scenes.

## **Why Use an MoR?**

#### ✅ **Global tax & compliance handled for you**

The MoR calculates, collects and remits taxes (VAT, GST, sales tax, etc.) based on the customer’s location. You don’t need to register for taxes in every country you sell to.

#### ✅ **No need to open or maintain a PSP merchant account**

With the MoR model, you don’t need to open, verify or manage your own PSP (Payment Service Provider) account. The MoR manages all PSP relationships and infrastructure for you.

#### ✅ **Risk & liability transferred to the MoR**

The MoR manages fraud checks, disputes, chargebacks, and compliance requirements — reducing operational risk and complexity.

#### ✅ **Simplified financial operations**

Instead of building your own payment, tax and billing systems, you work with a single partner — the MoR.

#### ✅ **Faster time to market**

Since the MoR already has tax, compliance and payment infrastructure in place, you can start selling internationally **immediately**, without lengthy legal or technical setup.

## **MoR vs PSP**

#### **PSP (Payment Service Provider)**

A PSP (e.g., Stripe, PayPal, Adyen) **only processes the payment transaction**. It securely moves funds and offers payment options, but it does **not** take on tax, compliance, or legal liability. Your company remains the seller of record.

#### **MoR**

An MoR handles the **full payment ecosystem,** taxation, compliance, regulatory liability, risk management, and even multi-currency handling allowing you to focus on your product and growth.

The table below shows a basic comparison between the Merchant of Record (MoR) model and Payment Service Providers (PSPs).

| Feature                   | **MoR**                 | **PSP**                   |
| ------------------------- | ----------------------- | ------------------------- |
| Legal seller of record    | ✔️ Takes responsibility | ❌ You remain responsible  |
| Tax & compliance          | ✔️ Handled by MoR       | ❌ You must handle         |
| Fraud/chargeback risk     | ✔️ Managed by MoR       | ❌ You retain risk         |
| End-to-end billing        | ✔️ Yes                  | ❌ Only payment processing |
| Best for global expansion | ✔️ Simplifies growth    | 🟡 Requires internal ops  |

## **How Does MoR Work?**

1. The customer buys from your website via the MoR checkout.
2. The MoR acts as the legal seller and collects the payment.
3. The MoR calculates and remits applicable taxes.
4. Fraud checks, compliance, refunds and chargebacks are handled by the MoR.
5. After taxes and fees, the MoR sends you your **net payout**.

This enables global selling **without needing local legal entities or tax registrations** — the MoR manages all the complexity for you.

## **📌 When to Use MoR vs PSP**

**Choose MoR if:**

* You want to sell internationally without managing regional compliance.
* You want to minimize financial and legal risk.
* You prefer a turnkey solution for billing, tax, risk and payouts.

**Choose PSP if:**

* You operate primarily in a **single country**.
* You have in-house finance/legal teams to manage compliance.
* You want full control over billing flows and direct payment processing.

## ROAS & Growth Optimization

Zotlo supports advertising and attribution integrations in both MoR and PSP models. You can send purchase and subscription events to advertising platforms such as **Meta Ads and Google Ads** to measure campaign performance and optimize return on ad spend (ROAS).

However, the MoR model provides an additional advantage.

Because the MoR handles the entire financial and operational layer, including tax compliance, fraud management, billing infrastructure, and payment operations, your team can focus entirely on **customer acquisition and revenue growth**.

With operational complexity handled by the MoR, teams can spend more time optimizing:

* Optimizing acquisition and onboarding journeys
* Campaign performance and ROAS
* Pricing experiments and promotions
* Conversion optimization

In other words, the MoR manages the complexity of global payments and compliance, while you concentrate on **growing your customer base and revenue.**


# Connect Your PSP

## **Connect Your PSP Model**

In the Connect Your PSP (Payment Service Provider) model, you connect your own payment provider, such as Stripe,Adyen,PayPal or other supported gateways directly to Zotlo.

In this setup:

* **You remain the legal seller of record**
* You receive customer payments **directly into your PSP account**
* Zotlo provides the **checkout, quiz funnels, subscription engine, billing logic, retries, dunning, discounts, analytics**, and all operational tooling around the transaction
* Taxes, compliance, invoicing and risk management remain **your responsibility** (not Zotlo’s)

This gives you full ownership over your financial operations, while still benefiting from Zotlo’s subscription and sales infrastructure.

## **Why Use Your Own PSP?**

#### ⭐ **Full control over payments**

You have direct access to your payment provider, merchant dashboard, settlement reports, and transaction details.

#### ⭐ **Funds settle directly to your bank**

Payments go from the customer → PSP → your bank account.\
Zotlo does not hold or intermediate these funds.

#### ⭐ **Use your existing PSP contracts**

If you already have negotiated rates, fraud tools, local acquiring setups or existing merchant IDs, you can continue using them.

#### ⭐ **Flexible payment orchestration**

You can integrate PSPs that match your needs — global, regional, high-risk compatible, low-fee, local acquiring, etc.

## **How It Works?**

1. Connect your PSP credentials inside Zotlo
2. Zotlo routes all charges through **your PSP account**
3. Zotlo manages:
   * Sales Interfaces
   * Subscription lifecycle
   * Renewals & retries
   * Dunning flows
   * Discounts & coupons
   * Analytics & dashboards
4. Your PSP processes the payment and settles it directly to you
5. Zotlo issues **commission invoices** for the services you use

## **What Stays with You**

In the PSP model, you retain responsibility for:

* Tax registration & tax remittance
* Chargeback handling via your PSP
* Compliance with card scheme and regional regulations
* Fraud strategy (or your PSP’s fraud tools)
* Customer billing identity (you are the seller of record)

This gives you full ownership and flexibility, but also requires operational readiness.


# Products & Plans

Zotlo lets you create flexible product structures, define global or localized pricing, and sell both subscription-based and one-time products, including e-pin codes.

In this section, you can explore the following topics:

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>📦</h3></td><td><h4><strong>Products Overview</strong> </h4></td><td>Learn how products, packages, and pricing models work in Zotlo, and how they interact with checkout, subscriptions, and reporting.</td><td><a href="/pages/AgMIz9ml27dnJ6SePAgX">/pages/AgMIz9ml27dnJ6SePAgX</a></td></tr><tr><td><h3>⚙️ </h3></td><td><h4><strong>Pricing Rules</strong></h4></td><td>Discover how to set base prices, configure billing intervals, apply introductory offers, trial periods, discounts, and advanced pricing rules.</td><td><a href="/pages/AgMIz9ml27dnJ6SePAgX#pricing-rules">/pages/AgMIz9ml27dnJ6SePAgX#pricing-rules</a></td></tr><tr><td><h3>🌍</h3></td><td><h4><strong>Localized Pricing</strong></h4></td><td>Define country-specific prices and currencies, understand IP- and locale-based pricing logic, and optimize global conversion.</td><td><a href="/pages/Q4QxztiAOWwsCH9FicQu">/pages/Q4QxztiAOWwsCH9FicQu</a></td></tr><tr><td><h3>🔁</h3></td><td><h4><strong>Subscription Plans</strong></h4></td><td>Create flexible subscription packages with configurable billing cycles, renewal behavior, and upgrade or downgrade logic.</td><td><a href="/pages/edCwzQz2f1Jbie2dvTrP">/pages/edCwzQz2f1Jbie2dvTrP</a></td></tr><tr><td><h3>🎁</h3></td><td><h4>Introductory Offers</h4></td><td>Offer free or paid trials to let customers try your product before the first full subscription charge.</td><td><a href="/pages/edCwzQz2f1Jbie2dvTrP#trials-and-introductory-offers">/pages/edCwzQz2f1Jbie2dvTrP#trials-and-introductory-offers</a></td></tr><tr><td><h3>💳</h3></td><td><h4><strong>One-time Payments</strong></h4></td><td>Set up consumable or standalone products for single-purchase flows that do not create a subscription lifecycle.</td><td><a href="/pages/YTPhCOHPa8YZanNWvgt4">/pages/YTPhCOHPa8YZanNWvgt4</a></td></tr><tr><td><h3>#️</h3></td><td><h4><strong>E-pin Sales</strong></h4></td><td>Sell digital e-pin codes securely, manage stock, and deliver purchased codes instantly via Zotlo’s fulfillment flow.</td><td><a href="/pages/MXDa0SlxsFZkKK85mlC2">/pages/MXDa0SlxsFZkKK85mlC2</a></td></tr><tr><td><h3>🏷️</h3></td><td><h4>Discounts</h4></td><td>Configure flexible discount rules and coupon codes to manage promotional campaigns that incentivize purchases and optimize your revenue growth.</td><td></td></tr></tbody></table>


# Products Overview

[Products & pricing](/features/products-and-plans) lets you define **what you sell**, **how it’s priced**, and **how it is presented** to customers across your checkout and sales interfaces.

In Zotlo, every product you create must be attached to a **Sales Package** before it can be sold.

## **Sales Packages**

A **Sales Package** is a container for pricing rules, product settings and purchase behavior.

Before you can sell a product, you must create a Sales Package in the **Sales Packages** section of your Zotlo dashboard.

A package can contain:

* [One-time purchase items](/features/products-and-plans/one-time-payments)&#x20;
* [Subscription plans](/features/products-and-plans/subscription-plans)&#x20;
* [E-pin sales](/features/products-and-plans/e-pin-sales)&#x20;

Once created, Sales Packages can be used in **embedded checkout forms**, **funnel links**, and **hosted checkout links**.

## **Pricing Rules**

### **Tax-Inclusive Pricing**

All prices configured in Zotlo must be **tax-inclusive**. Zotlo never adds VAT, GST, or sales tax on top of the merchant-defined price during checkout.

* In the **MoR model**, taxes are calculated and extracted internally by Zotlo.
* In the **PSP model**, tax handling is the merchant’s responsibility, but the customer still pays exactly the configured price.

{% hint style="info" %}
**IMPORTANT :** Customers always pay the final amount you define for each country.
{% endhint %}

### **Localized Pricing**

You can define different prices for each country or currency.\
This improves conversion by showing users **trusted local currencies and familiar price points**.\
Zotlo supports 40+ currencies. See more about [localized pricing](/features/products-and-plans/localized-pricing).

### **Adaptive Pricing**

[Adaptive pricing](/features/products-and-plans/one-time-payments#adaptive-pricing) works only for **one-time payments**. It automatically converts your base price using the **real-time exchange rate**, displays the localized amount to the customer, and charges them at that rate. This lets you sell globally without manually configuring prices for every country.

### **Updating Prices**

You can update package prices at any time. Changes apply **instantly** to new purchases, but **do not affect existing subscriptions**.

If you need to adjust pricing for existing subscribers, this can be done, please contact our support team for assistance.

## **Best Practices**

* **Start with clear names** for your plans (e.g., Starter, Pro, Premium), avoid ambiguous labels
* **Define localized pricing** for key markets to increase trust
* **Use trials strategically,** short quality trials convert better than long free periods
* **Keep tier structure simple,** too many variants can confuse customers
* **Test pricing with real traffic** and analyze conversions to optimize offerings


# Subscription Plans

Subscription plans let you create and manage **recurring billing products** inside Zotlo. You can define billing intervals, trials, introductory offers, localized prices and renewal behavior to match your business model.

## **Subscription Plans**

A subscription plan includes:

* **Billing period** (weekly, monthly etc.)
* **Base price** (in USD)
* **Localized pricing** (optional)
* **Trial or introductory offer** (optional)
* **Plan metadata** (internal tags, product name)

Subscription plans must be added inside a **Sales Package** before they can appear in checkout or funnel interfaces.

## **Billing Intervals**

You can configure any of the following cycles:

* Weekly
* Monthly
* Every 2 months
* Every 3 months
* Every 6 months
* Annual

Zotlo automatically calculates renewal dates, processes recurring charges, and performs retry attempts when payments fail.

## **Trials & Introductory Offers**

You can offer:

* **Free trials** (e.g., 3 or 7 days free)
* **Paid trials** (e.g., first month $0.99 → then $14.99)

Trials and intro prices are automatically displayed in Hosted Checkout, Embedded Checkout and Funnel Interfaces.

## **Localized Pricing**

You can set different prices for each country to increase conversion and reduce friction.

[Localized pricing](/features/products-and-plans/localized-pricing) is recommended especially for:

* High-value plans
* Global funnels
* Regions with currency sensitivity

If localized pricing is not defined, the plan uses the **base USD price**, shown converted at checkout using real-time rates for display only (subscription charges are based on the configured plan currency).

## **Renewal Logic**

Zotlo manages:

* Automatic renewals
* Payment retries
* Dunning flows
* Grace periods
* Cancellations
* Plan changes (upgrade/downgrade behavior)

All events are visible in the dashboard under **Transactions**, **Subscriptions**, and **Events**.

## **Updating Subscription Prices**

You can update plan prices at any time, and changes:

* Apply **immediately** to new customers
* Do **not** affect existing subscribers

If you want to apply price changes for existing users, contact our support team for assistance.


# One-time Payments

One-time Payments allow you to sell **non-recurring products** such as digital goods, in-game items, downloadable content, credits, add-ons, or single-purchase items.\
These products are charged **once** and do not include renewals or subscription logic.

One-time products must be added to a **Sales Package** before they can be used in Hosted Checkout, Embedded Checkout, or Funnel Interfaces.

## **One-Time Products**

A one-time product includes:

* Base price (in USD)
* Localized pricing (optional)
* Adaptive Pricing (optional)
* Product metadata (internal tags, product name)

## **Pricing Options**

#### **Base Price**

The base USD price defines the standard cost of the product.

#### **Localized Pricing**

You can set different local prices for each country or currency to improve conversion.

Recommended when:

* Selling globally
* Price sensitivity varies by region
* You want consistent local price points instead of currency conversion

If localized pricing is not defined, the product uses the base USD price for display.

#### **Adaptive Pricing**

Adaptive Pricing works **only for one-time payments**.\
It automatically converts your base price using the **real-time exchange rate**, shows the localized amount to the customer, and charges them at that rate.

This allows you to:

* Sell globally without configuring individual prices
* Let customers pay in their local currency with accurate, real-time conversion
* Reduce friction caused by foreign currency pricing

## **Updating Prices**

You can update one-time product prices at any time.\
Changes apply immediately to all new purchases, there are no existing subscribers to preserve.

## **One-Time Payment Flow**

1. Customer selects a one-time product.
2. Checkout displays the appropriate price (localized or adaptive).
3. Customer completes the payment.
4. Zotlo records the transaction.
5. Delivery/fulfillment is handled based on your setup (e.g., access, file, credits).

There are **no renewals, retries, or subscription lifecycle events** — the flow ends after purchase.

## **Use Cases**

One-time payments are ideal for:

* Digital downloads (PDF, templates, audio, video)
* In-app/in-game items
* E-books / guides
* Credits or token packs
* Single-use access
* Add-ons to subscription plans
* Upsells / order bumps inside funnels
* Quiz funnel one-time offers
* Lifetime access products


# E-pin Sales

E-Pin Sales allow you to sell **digital PIN codes** that are delivered instantly after the payment is completed. E-Pins are ideal for prepaid services, vouchers codes, gift cards,  top-ups, promo or event codes and digital access keys.

E-Pin codes must be added to a **Sales Package**, and currently they can be sold **only through Sales Links (Flows)** inside Zotlo.

## **E-Pin Sales**

E-Pin sales operate through a simple flow:

1. You upload a file containing your PIN codes.
2. Each successful purchase consumes **one PIN** from your inventory.
3. Zotlo automatically delivers that PIN to the customer.
4. The PIN is deducted from stock instantly.
5. Zotlo notifies you when your inventory is running low.

This automated structure makes it easy to sell PIN-based digital products without operating your own fulfillment system.

## **E-Pin Products**

When creating an E-Pin Purchase type Sales Package, Zotlo will ask you to upload a **PIN inventory file**.

The file should contain:

* One PIN per line
* Unique, unused PINs
* Plain text format (no formatting or special characters)

After upload, Zotlo securely stores your PINs and prepares them for use.

## **Selling E-Pins**

Currently, E-Pin Sales work exclusively with **Sales Links**.

This allows you to place E-Pin products inside:

* Quiz funnels
* Multi-step flows
* Single-page sales links
* Upsell / downsell paths

E-Pin delivery happens automatically at the end of the flow after a successful payment.

## **Delivery & Stock Control**

Zotlo handles:

### **Instant Delivery**

Once payment succeeds, the customer receives their PIN via:

* Success page display
* Email (if configured)
* API callback / webhook (optional)

### **Stock Deduction**

Each delivered PIN is immediately removed from inventory.

### **Stock Tracking**

You can view:

* Total PINs uploaded
* Remaining PINs
* Used / delivered PINs
* Delivery logs

### **Low Stock Notifications**

When your PIN inventory reaches a low threshold, Zotlo automatically **alerts the merchant** so you can upload new codes before stock runs out.

## **Pricing Options**

E-Pin products support:

* **Base Price** (USD)
* **Localized Pricing**

Because E-Pins are one-time transactions, no renewals or subscription logic is included.


# Localized Pricing

Localized Pricing lets you control how your products are priced and presented across different countries and currencies. Zotlo applies your pricing rules at checkout so customers see prices that match your international strategy.

This feature reduces friction, improves conversion, and provides a localized payment experience without losing pricing control.

## **How Localization Works**

Zotlo does not decide the currency itself, **the merchant defines all pricing behavior.** Zotlo provides a country-based pricing structure and lets merchants fully control the amount and currency shown to customers in each market.

#### Merchant sets the pricing rules

Merchants control pricing and currency behavior in multiple ways:

* **Default behavior:**\
  When you enter a base price, Zotlo automatically generates localized prices for non-USD countries using local currencies.
* **Override options:**\
  You can disable automatic localization and charge **all customers in USD** (or any currency you select).
* **Country-level customization:**\
  You can override the currency and/or price for **specific countries**.\
  (Example: Brazil → BRL, Germany → EUR, Turkey → TRY, All Others → USD)
* **Whether adaptive-pricing applies** (one-time payments only)

#### Zotlo applies your rules

* Customers see prices **in the currency and amount you defined**
* If adaptive-pricing is enabled, Zotlo **automatically calculates a local price** using the adaptive base price and current FX logic
* Applies base price as fallback for countries with no specific rule&#x20;

This logic works the same in both the MoR and PSP models, Zotlo always applies your configuration at checkout.

## **Tax-Inclusive Pricing**

All prices configured in Zotlo must be **tax-inclusive**. Zotlo never adds VAT, GST, or sales tax on top of the merchant-defined price during checkout.

* In the **MoR model**, taxes are calculated and extracted internally by Zotlo.
* In the **PSP model**, tax handling is the merchant’s responsibility, but the customer still pays exactly the configured price.

{% hint style="info" %}
**PLEASE NOTE :** Customers always pay the final amount you define for each country.
{% endhint %}

## **Minimum Charge Amounts**

Zotlo enforces a global minimum threshold as **0.50 USD (or equivalent in local currency).**

{% hint style="warning" %}
**IMPORTANT :** If a country price falls below the minimum allowed amount, the transaction is restricted.
{% endhint %}

### Supported Currencies

Zotlo supports **43 currencies** for localized pricing and merchants can assign any of these currencies to any country.

| Currency Code | Currency Name      | Countries                                                                                                                                                                                                                                                                       |
| ------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AED           | UAE Dirham         | United Arab Emirates                                                                                                                                                                                                                                                            |
| ARS           | Argentine Peso     | Argentina                                                                                                                                                                                                                                                                       |
| AUD           | Australian Dollar  | Australia                                                                                                                                                                                                                                                                       |
| BRL           | Brazilian Real     | Brazil                                                                                                                                                                                                                                                                          |
| CAD           | Canadian Dollar    | Canada                                                                                                                                                                                                                                                                          |
| CHF           | Swiss Franc        | **Switzerland**                                                                                                                                                                                                                                                                 |
| CLP           | Chilean Peso       | Chile                                                                                                                                                                                                                                                                           |
| CNY           | Chinese Yuan       | China                                                                                                                                                                                                                                                                           |
| COP           | Colombian Peso     | Colombia                                                                                                                                                                                                                                                                        |
| CZK           | Czech Koruna       | Czech Republic                                                                                                                                                                                                                                                                  |
| DKK           | Danish Krone       | Denmark                                                                                                                                                                                                                                                                         |
| EGP           | Egyptian Pound     | Egypt                                                                                                                                                                                                                                                                           |
| EUR           | Euro               | <p><strong>European Union Countries:</strong><br>Austria<br>Belgium<br>Croatia<br>Cyprus<br>Estonia<br>Finland<br>France<br>Germany<br>Greece<br>Ireland<br>Italy<br>Latvia<br>Lithuania<br>Luxembourg<br>Malta<br>Netherlands<br>Portugal<br>Slovakia<br>Slovenia<br>Spain</p> |
| GBP           | British Pound      | United Kingdom                                                                                                                                                                                                                                                                  |
| HKD           | Hong Kong Dollar   | Hong Kong                                                                                                                                                                                                                                                                       |
| HUF           | Hungarian Forint   | Hungary                                                                                                                                                                                                                                                                         |
| IDR           | Indonesian Rupiah  | Indonesia                                                                                                                                                                                                                                                                       |
| ILS           | Israeli Shekel     | Israel                                                                                                                                                                                                                                                                          |
| INR           | Indian Rupee       | India                                                                                                                                                                                                                                                                           |
| JPY           | Japanese Yen       | Japan                                                                                                                                                                                                                                                                           |
| KWD           | Kuwaiti Dinar      | Kuwait                                                                                                                                                                                                                                                                          |
| KZT           | Kazakh Tenge       | Kazakhstan                                                                                                                                                                                                                                                                      |
| MXN           | Mexican Peso       | Mexico                                                                                                                                                                                                                                                                          |
| MYR           | Malaysian Ringgit  | Malaysia                                                                                                                                                                                                                                                                        |
| NOK           | Norwegian Krone    | Norway                                                                                                                                                                                                                                                                          |
| NZD           | New Zealand Dollar | New Zealand                                                                                                                                                                                                                                                                     |
| PEN           | Peruvian Sol       | Peru                                                                                                                                                                                                                                                                            |
| PHP           | Philippine Peso    | Philippines                                                                                                                                                                                                                                                                     |
| PLN           | Polish Zloty       | Poland                                                                                                                                                                                                                                                                          |
| QAR           | Qatari Riyal       | Qatar                                                                                                                                                                                                                                                                           |
| RON           | Romanian Leu       | Romania                                                                                                                                                                                                                                                                         |
| RUB           | Russian Ruble      | Russia                                                                                                                                                                                                                                                                          |
| SAR           | Saudi Riyal        | Saudi Arabia                                                                                                                                                                                                                                                                    |
| SEK           | Swedish Krona      | Sweden                                                                                                                                                                                                                                                                          |
| SGD           | Singapore Dollar   | Singapore                                                                                                                                                                                                                                                                       |
| THB           | Thai Baht          | Thailand                                                                                                                                                                                                                                                                        |
| TRY           | Turkish Lira       | Turkey                                                                                                                                                                                                                                                                          |
| UAH           | Ukrainian Hryvnia  | Ukraine                                                                                                                                                                                                                                                                         |
| USD           | US Dollar          | United States                                                                                                                                                                                                                                                                   |
| VND           | Vietnamese Dong    | Vietnam                                                                                                                                                                                                                                                                         |
| ZAR           | South African Rand | South Africa                                                                                                                                                                                                                                                                    |

## **MoR vs PSP Behavior**

Although pricing logic is identical, supported currencies and settlement behavior differ by model.

#### **Merchant of Record (MoR)**

* All 43 currencies available
* Local prices appear directly at checkout
* Zotlo handles FX, settlement, compliance, and taxation

#### **Connected PSP**

* Supported currencies depend on the PSP
* Zotlo still applies your country-based pricing rules
* Settlement, FX, and restrictions follow PSP policies

## **Refunds**

Refund behavior follows the original pricing configuration:

* Refunds are issued in the **original transaction currency**
* Partial refunds and proration also use the original currency
* The refund amount is based on the **original payment amount**, even if localized prices were updated later

## Invoices and Taxation

Localization affects invoice content but not tax logic:

* Invoices show the **charged currency** for that country
* Localized pricing does not automatically imply local taxation
* In MoR:
  * Zotlo calculates, applies, and remits taxes
  * Invoice is issued by Zotlo with the localized price
* In PSP model:
  * Taxes depend on your PSP / merchant tax settings
  * You control invoicing and tax compliance directly


# Discounts

Discounts allow you to create and manage promotional offers within Zotlo. You can configure flexible discount rules and coupon codes to apply targeted price reductions across your products, enhancing conversion rates and customer loyalty.

To start creating offers, navigate to Catalog > Discounts on the Zotlo Panel and click "New Discount".

### Discount Configuration

When setting up a new discount, you define the core identity and value of your promotion:

* Discount Name: An internal label used to identify your campaign (e.g., *Black Friday Sale*).
* Discount Percentage: The specific percentage to be deducted from the product price.
* Checkout Discount Code: The alphanumeric string customers enter at checkout (e.g., `SAVE30`). You can manually enter a custom code or click "Generate a random code for me" for a unique string.

### Applicability

These settings determine how the discount interacts with your subscription lifecycles and product catalog:

* Enable recurring discount: When active, the discount applies to every renewal cycle. If disabled, it only applies to the initial payment.
* Apply to paid trial: Determine if the discount should further reduce the price of an already discounted introductory or paid trial period.
* Apply to specific packages: Restrict the discount to selected sales packages instead of making it available for all products.

### Redemption Rules

Set boundaries to manage your campaign's reach and protect your margins:

* Limit total redemptions: Define a maximum number of times the code can be used globally (e.g., limited to the first 100 customers).
* Set an expiration date: Pick a specific date and time for the discount to automatically expire.

### Apply Discounts at Checkout

To display the discount input on your payment forms, follow these steps in the Zotlo Panel:

1. Navigate to Hosted Checkout or Embedded Checkout settings.
2. Locate the Discount Settings section.
3. Switch on the "Enable discount code entry" toggle.

Once activated, an "I have a discount code" option will appear on your checkout form. When a customer enters a valid code, Zotlo automatically validates the rules and updates the total price in real-time.

<div data-with-frame="true"><figure><img src="/files/MVXYygAU7aWaEJdng1qZ" alt=""><figcaption></figcaption></figure></div>

### Quick Examples

| If your goal is...   | Recommended Configuration                                         |
| -------------------- | ----------------------------------------------------------------- |
| New User Acquisition | Keep "Recurring" off for a one-time welcome gift.                 |
| Long-term Retention  | Turn "Recurring" on to offer a permanent loyalty price.           |
| Flash Sale           | Use "Total redemptions" to limit the offer to the first 50 users. |
| Holiday Promo        | Set an "Expiration date" to drive immediate conversions.          |

### Discount Behavior on Plan Changes

Zotlo ensures a seamless transition when customers upgrade or downgrade their subscription plans:

* Optional Discount Retention (Keep Discount): By default, if a Recurring Discount is active, you can choose to carry it over to the new plan using the `keepDiscount` parameter. This ensures the customer remains discounted after the transition, provided the discount is valid for the new package.
* Discount Overrides: During an upgrade or downgrade, you can apply a new discount by passing the `discountCode` parameter. In this case, the existing discount is invalidated and replaced by the new code. This is ideal for offering specialized incentives when users move to premium packages.
* Precise Pro-rata Calculations: For mid-cycle plan changes, Zotlo’s billing engine automatically calculates the pro-rated amount based on the discounted price. The system ensures that credits and charges are accurately adjusted by considering both the old and new discount rules.

Developer Note: For discount-related parameter details (such as `keepDiscount` and `discountCode`) and API usage examples, please visit our Upgrade/Downgrade API Documentation.

{% content-ref url="/pages/9EczLg9GDvjKL1UOIwql" %}
[Change Plan](/integrating-zotlo/api-reference/subscriptions-endpoints/change-plan)
{% endcontent-ref %}


# Payment Methods

Zotlo supports a wide range of global and local payment methods, ensuring higher conversion rates and a smooth checkout experience across devices and regions.

In this section, you can explore the following topics:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>📘</h3></td><td><h4><strong>Payment Methods</strong></h4></td><td>Learn how payment methods work in Zotlo, availability rules, and how methods are automatically displayed to users.</td><td><a href="/pages/ziCsbIbNtQXgjQzQkpxQ">/pages/ziCsbIbNtQXgjQzQkpxQ</a></td></tr><tr><td><h3>🌍 </h3></td><td><h4><strong>Regional Availability</strong></h4></td><td>Understand where different payment methods are available and supported across regions.</td><td><a href="/pages/ziCsbIbNtQXgjQzQkpxQ#regional-availability">/pages/ziCsbIbNtQXgjQzQkpxQ#regional-availability</a></td></tr><tr><td><h3>🔗</h3></td><td><h4><strong>Cards</strong></h4></td><td>Explore how card payments work, supported networks, SCA/3DS rules, card storage, and retry logic for subscription renewals.</td><td><a href="/pages/V6Y2gR5juam55Ggi2xvW">/pages/V6Y2gR5juam55Ggi2xvW</a></td></tr><tr><td><h3></h3></td><td><h4><strong>Apple Pay</strong></h4></td><td>Offer one-tap checkout on supported Apple devices and learn about eligibility requirements and integration details.</td><td><a href="/pages/Xdw9yfnN7KlCau17Kn01">/pages/Xdw9yfnN7KlCau17Kn01</a></td></tr><tr><td><h3>🇬</h3></td><td><h4><strong>Google Pay</strong></h4></td><td>Enable fast and secure payments on Android devices and Chrome, and learn how regional availability and device checks work.</td><td><a href="/pages/TxMhSh3ZV1YyPOtt7MLG">/pages/TxMhSh3ZV1YyPOtt7MLG</a></td></tr><tr><td><h3>🅿️</h3></td><td><h4><strong>PayPal</strong></h4></td><td>Integrate PayPal to increase conversions for users who prefer alternative payment wallets across global markets.</td><td><a href="/pages/NaYrg5Te9aLoyBMikdlP">/pages/NaYrg5Te9aLoyBMikdlP</a></td></tr></tbody></table>


# Payment Methods Overview

Payment Methods define **how customers pay** during checkout and subscription lifecycle. Zotlo allows you to accept multiple payment methods, either through **Zotlo’s built-in payment infrastructure** (MoR model) or through your **connected PSP**.

All payment methods can be used:

* **With Zotlo (Merchant of Record model)** → Zotlo processes the payment and manages tax, risk & billing.
* **With your own PSP** → If your PSP supports the method, Zotlo routes the charge to your gateway.

## **How Payments Work?**

Zotlo automatically determines which payment methods to show to the customer based on:

### **Payment Methods**

Currently supported methods:

* [Credit & Debit Cards](/features/payment-methods/cards)&#x20;
* [Apple Pay](/features/payment-methods/apple-pay)&#x20;
* [Google Pay](/features/payment-methods/google-pay)&#x20;
* [PayPal](/features/payment-methods/paypal)

### **🌍 Customer Location**

Payment methods appear only if available in the customer’s country. For example local wallet options appear only where supported. For more see [Regional Availability & Considerations](#regional-availability-and-considerations)

### 💵 **Transaction Currency**

Methods are filtered by whether they support the currency of the sale.

### **📱 Device Compatibility**

* **Apple Pay** → shown only on Apple devices using Safari
* **Google Pay** → shown on Android & Chrome
* **PayPal** → shown if regionally available
* **Cards** → always available globally (issuer rules may apply)

### 🧾 **Transaction Type**

Some methods (like Apple Pay / Google Pay) may have restrictions on:

* Recurring billing
* Subscription renewals
* Minimum/maximum amounts

{% hint style="info" %}
**Result :** Zotlo automatically hides incompatible methods to keep the experience smooth. Customers always see **the right methods**, increasing payment success and conversion.
{% endhint %}

## **Zotlo vs PSP Methods**

#### **If you use Zotlo’s built-in payment methods:**

👉 You are using the [**Merchant of Record (MoR)**](/welcome/merchant-of-record) model.\
Zotlo manages:

* Tax calculation & remittance
* Payment processing
* Fraud checks
* Chargeback handling
* Compliance
* Payouts to the merchant

This is the simplest way to start selling.

#### **If you connect your own PSP:**

👉 You use the [**PSP model**](/welcome/connect-your-psp).

* Payments are processed by your gateway
* Funds settle directly to your account
* Zotlo provides checkout, subscriptions, retries, analytics
* The payment methods shown depend on what **your PSP supports**

You still get Apple Pay, Google Pay, PayPal and Card payments, if your PSP supports them.

## **Regional Availability**

The following availability rules apply automatically:

* **Apple Pay**\
  Apple Pay is displayed only in supported countries and on compatible Apple devices using Safari browser. See the list of supported countries and regions by Apple Pay [👉 here](https://support.apple.com/en-us/102775)
* **Google Pay**\
  Google Pay is displayed only in supported countries and on compatible Android devices or the Chrome browser. See the list of supported countries and regions. by Google Pay [👉 here](https://support.google.com/googlepay/answer/12429287)
* **PayPal**\
  PayPal is displayed based on regional availability and the customer’s PayPal account eligibility.

  See the list of supported countries and regions by PayPal [👉 here](https://www.paypal.com/us/webapps/mpp/country-worldwide)
* **Card Payments**\
  Zotlo supports global card networks such as **Visa, Mastercard, American Express, Discover, JCB, Union Pay, Diners Club etc.** Card payment availability depends on issuer rules, network support, SCA requirements and local regulations.

Zotlo filters these automatically so customers never see unavailable options.

{% hint style="info" %}
**Tip:** Always consider your audience’s countries and devices to maximize payment success.
{% endhint %}


# Cards

Cards are the most widely used payment method in Zotlo. This page explains supported card networks, 3D Secure behavior, card storage, and how card payments work across the [Merchant of Record (MoR)](/welcome/merchant-of-record) and [Connected PSP models.](/welcome/connect-your-psp)

## **Supported Card Networks**

Zotlo supports all major global card schemes:

* Visa
* Mastercard
* American Express
* Discover
* Diners Club
* JCB
* UnionPay

Card availability and acceptance depend on the issuing bank, region, and the billing model used (MoR or PSP).

## **Security & Tokenization**

Zotlo **never stores raw card data** such as full card numbers or CVV. All sensitive card information is handled and stored exclusively by **PCI DSS–compliant payment partners**.

Zotlo stores only **non-sensitive tokens** or payment method references returned by these partners. These tokens are used safely for:

* Subscription renewals
* One-click checkout
* Retry and dunning flows
* Future charges without re-entering card details

## **3D Secure (3DS)**

Zotlo supports **3D Secure (3DS)** for card authentication and fraud prevention.

* 3DS is automatically triggered when required by the card issuer.
* Frictionless flows may occur when the issuer approves them.
* In regions where additional authentication requirements apply (e.g., Europe/UK under SCA rules), 3DS is used to meet these requirements via our payment partners or your PSP.

Zotlo displays the 3DS UI when needed and continues the payment flow seamlessly after authentication.

## **Card Payments in MoR**

The behavior of card payments depends on whether you use [Zotlo’s MoR](/welcome/merchant-of-record) or [your own PSP](/welcome/connect-your-psp).

#### **Merchant of Record (MoR)**

* Card processing is handled by Zotlo’s authorized payment partners
* Tokens are returned by partners, Zotlo stores only non-sensitive identifiers
* 3DS and authentication flows are managed automatically
* Chargebacks, risk checks, and compliance are handled under the MoR framework
* Funds are paid out by Zotlo to the merchant

#### **Connected PSP**

* Card processing follows your PSP’s rules and capabilities
* Tokens are stored inside your PSP’s vault; Zotlo stores only the reference token
* 3DS and authentication behavior depend on your PSP’s configuration
* Chargebacks and compliance are handled by your PSP
* Funds settle directly into your PSP merchant account

## **When to Use Cards**

Cards are ideal when you need:

* Global coverage with a single integration
* Subscription billing with renewals
* One-click checkout using saved payment methods
* Robust retry logic to reduce failed payments

Cards offer the highest acceptance across apps, SaaS products, digital content, and memberships.


# Apple Pay

Apple Pay allows customers to complete payments quickly using their saved cards on Apple devices. Zotlo supports Apple Pay in both [Merchant of Record (MoR)](/welcome/merchant-of-record) and [Connected PSP models](/welcome/connect-your-psp), depending on your PSP’s capabilities.

This page explains setup requirements, domain verification, supported platforms, and activation steps.

## **Availability Requirements**

Apple Pay is shown at checkout only when the customer meets Apple’s requirements:

* **Device:** iPhone, iPad, Mac, or Apple Watch
* **Browser:** Safari
* **Region:** Apple Pay–supported country
* **Card:** Supported card network (Visa, Mastercard, Amex, etc.)

Zotlo automatically hides Apple Pay if any requirement is not met.

## **Activation Required**

Apple Pay is **not enabled by default**. To activate Apple Pay for your project:

1. In the Zotlo Dashboard, add the domain(s) where you want to use Apple Pay and **submit an activation request**.
2. **Complete domain verification:**
   * **Hosted checkout / Sales Links:** Zotlo performs verification on your behalf.
   * **Embedded checkout:** You must upload the Apple verification file to your website.
3. Wait for Zotlo to complete Apple Pay configuration.
4. After activation is finalized, **enable Apple Pay in the specific sales interface you want to use** (embedded checkout or hosted options).

{% hint style="info" %}
**Note :** Apple Pay will not appear unless the domain is fully verified and activated, and Apple Pay is enabled in the chosen interface.
{% endhint %}

## **Domain Verification**

Apple Pay policies require every domain that uses Apple Pay to be verified.

**Hosted checkout / Sales Links:**\
Zotlo completes domain verification for you. No action is required on your side.

**Embedded checkout:**\
You must upload the verification file provided by Zotlo to your website at:\
`/.well-known/apple-developer-merchantid-domain-association`

Once the domain is verified, it becomes eligible for Apple Pay.

## **Apple Pay in MoR**

#### **Merchant of Record (MoR)**

* Apple Pay processing is handled by Zotlo
* Authentication and device validation are managed automatically
* Availability depends on Apple + region rules
* No technical setup other than domain verification

#### **Connected PSP**

* Apple Pay availability depends on whether your PSP supports it
* Processing and authentication follow your PSP’s rules
* Domain verification still required
* Settlement flows directly to your PSP merchant account

Zotlo automatically routes Apple Pay payments through whichever model you are using.

## **When to Use Apple Pay**

Apple Pay is ideal when you want:

* The fastest possible checkout flow
* Higher mobile conversion
* Lower friction for returning users
* Reduced failed payments (device + biometrics authentication)

Apple Pay can significantly increase conversion in mobile-heavy funnels.


# Google Pay

Google Pay allows customers to complete payments quickly using the cards stored in their Google account. Zotlo supports Google Pay in both [Merchant of Record (MoR)](/welcome/merchant-of-record) and [Connected PSP models](/welcome/connect-your-psp), depending on your PSP’s capabilities.

This page explains setup requirements, domain review, supported platforms, and activation steps.

## **Availability Requirements**

Google Pay is shown at checkout only when the customer meets Google’s requirements:

* **Device:** Android device or any device running Chrome
* **Browser:** Chrome
* **Region:** Google Pay supported country
* **Card:** Supported card network (Visa, Mastercard, Amex, etc.)

Zotlo automatically hides Google Pay if any requirement is not met.

## **Activation Required**

Google Pay is **not enabled by default.** To activate Google Pay for your project:

1. Add the domain(s) where you want to use Google Pay in the Zotlo Dashboard and **submit an activation request.**
2. Your domain must then go through **Google’s domain review process**, which Zotlo manages on your behalf.
3. Once the review is completed by Google and activation is finalized, enable Google Pay in the specific sales interface you want to use (embedded checkout or hosted options).

{% hint style="info" %}
**Note:** Google Pay will not appear unless the domain has been activated and Google Pay is enabled in the chosen interface.
{% endhint %}

## **Domain Review**

Google Pay requires every domain that will use Google Pay to pass a **Google-managed domain review**.

Zotlo submits your domain to Google and manages the entire review process for hosted checkout, sales links and embedded checkout. No action is required on your side.

Once the review is approved by Google, the domain becomes eligible for Google Pay.

## **Google Pay in MoR**

#### **Merchant of Record (MoR)**

* Google Pay processing is handled by Zotlo
* Authentication and device validation are managed automatically
* Availability depends on Google + region rules
* Only domain review is required on your side

#### **Connected PSP**

* Google Pay availability depends on whether your PSP supports Google Pay
* Processing and authentication follow your PSP’s rules
* Domain review is still required
* Funds settle directly to your PSP merchant account

Zotlo automatically routes Google Pay payments through whichever model you are using.

## **When to Use Google Pay**

Google Pay is ideal when you want:

* A fast mobile-first checkout experience
* Higher conversion on Android-heavy traffic
* Seamless payments with stored Google account cards
* Lower friction for returning users

Google Pay can significantly increase conversion for web and mobile funnels with a high Android or Chrome user base.


# PayPal

PayPal allows customers to pay using their PayPal balance, linked cards, or bank accounts. Zotlo supports PayPal in both [Merchant of Record (MoR)](/welcome/merchant-of-record) and [Connected PSP models](/welcome/connect-your-psp), depending on your PSP’s PayPal integration.

This page explains availability rules, activation steps, and how PayPal behaves across different billing models.

## **Availability Requirements**

PayPal is shown at checkout only when:

* The customer is in a **PayPal-supported region**
* The customer’s **PayPal account is eligible** for payments
* PayPal is **enabled** for the specific checkout or sales interface

Zotlo automatically hides PayPal for unsupported regions or accounts.

## **Activation Required**

PayPal is **not enabled by default**.<br>

1. To activate PayPal for your project, request PayPal activation in the Zotlo Dashboard. Zotlo will configure PayPal for your account and notify you when the setup is complete.
2. After activation, enable PayPal in the specific sales interface you want to use (embedded checkout or hosted options).

{% hint style="info" %}
**Note :**&#x20;

* PayPal will appear only after it has been activated in the Zotlo Dashboard and enabled in the chosen interface.&#x20;
* PayPal does **not** require domain verification, and once activated it can be used across all of your domains.
  {% endhint %}

## **PayPal Behavior in MoR**

#### **Merchant of Record (MoR)**

* PayPal processing is handled by Zotlo
* Availability depends on PayPal’s regional rules
* No merchant-side integration required
* Settlement is done through Zotlo under the MoR framework

#### **Connected PSP**

* PayPal availability depends on whether your PSP supports PayPal
* Processing and authentication follow your PSP’s rules
* Funds settle directly to your PSP merchant account
* Zotlo only manages the checkout flow and subscription logic

Zotlo automatically routes PayPal payments through the model you are using.

## **When to Use PayPal**

PayPal is ideal when you want to:

* Increase conversion in regions with high PayPal adoption
* Offer a trusted alternative to cards
* Reduce friction for customers who prefer wallet-based payments
* Support users who do not want to enter card information

PayPal can significantly improve conversion in Europe, the US, and markets where PayPal is a preferred payment method.


# Checkout

The Zotlo Checkout experience enables you to offer seamless, secure, and fully customizable payment flows, whether embedded on your website, opened as a hosted page, or generated dynamically via API.

In this section, you can explore the following topics:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>📘</h3></td><td><h4><strong>Checkout Overview</strong></h4></td><td>Learn how Zotlo Checkout works, the available integration models, and which approach best fits your product.</td><td><a href="/pages/lR7PFe0TnvNvDViTQNgI">/pages/lR7PFe0TnvNvDViTQNgI</a></td></tr><tr><td><h3>🧩 </h3></td><td><h4><strong>Embedded Checkout</strong></h4></td><td>Embed the checkout form directly inside your website or app to deliver a smooth on-page payment experience.</td><td><a href="/pages/hzwnoJuGA8gJC9lLEXgi">/pages/hzwnoJuGA8gJC9lLEXgi</a></td></tr><tr><td><h3>🔗</h3></td><td><h4><strong>Checkout Links</strong></h4></td><td>Use a fully hosted, ready-to-launch checkout page—ideal for fast integrations with minimal development effort.</td><td><a href="/pages/idyRyYGoEAxhccc76VyO">/pages/idyRyYGoEAxhccc76VyO</a></td></tr><tr><td><h3>⚙️</h3></td><td><h4><strong>Checkout API</strong></h4></td><td>Generate personalized checkout links and programmatically control pricing, parameters, and user flow with the API.</td><td><a href="/pages/A8NoW9Kwf4TZy5OMILIp">/pages/A8NoW9Kwf4TZy5OMILIp</a></td></tr><tr><td><h3>🌍</h3></td><td><h4><strong>Multi-language</strong></h4></td><td>Display checkout in your users’ preferred language automatically or manually configure language behavior.</td><td><a href="/pages/lm9TxMdoZHAfIDSzT88x">/pages/lm9TxMdoZHAfIDSzT88x</a></td></tr><tr><td><h3>🎨</h3></td><td><h4><strong>Branding</strong></h4></td><td>Customize visuals, colors, images, and messaging to match your brand and create a consistent user experience.</td><td><a href="/pages/qCvKHAnBPw3O9l6iMG7H">/pages/qCvKHAnBPw3O9l6iMG7H</a></td></tr></tbody></table>


# Checkout Overview

Checkout is Zotlo’s primary payment interface for selling subscriptions and one-time products. It supports embedded and hosted implementations, API-generated checkout links, localized pricing, multi-language experiences, and all global payment methods available in your project.

Checkout applies your configured pricing, country rules, taxes, and branding settings automatically, ensuring a consistent purchase experience across regions and devices.

<div data-with-frame="true"><figure><img src="/files/NGrmDb0aXxEFds1JMRV0" alt="" width="563"><figcaption></figcaption></figure></div>

## **Key Capabilities**

### **Global Payment Methods**

Checkout supports [cards](/features/payment-methods/cards), [Apple Pay](/features/payment-methods/apple-pay), [Google Pay](/features/payment-methods/google-pay), [PayPal](/features/payment-methods/paypal), and region-specific payment options. Availability is determined by device, region, merchant configuration, and PSP/MoR capabilities.

Explore all [payment methods](/features/payment-methods/payment-methods-overview).&#x20;

### **Localized Pricing**

Checkout displays prices based on your country-level pricing and currency configuration. Localized rules, overrides, and fallback behaviors are applied automatically at runtime.&#x20;

See more about [localized pricing](/features/products-and-plans/localized-pricing).

### **Multi-Language Experience**

Checkout UI is available in multiple languages, adapting to the user’s browser locale or to the language you select programmatically.&#x20;

See more about [multi-language support](/features/checkout/multi-language).

### **Automatic Tax Handling**

Checkout always charges the price you define.

* In MoR model, Zotlo calculates and processes taxes internally.
* In PSP model, tax responsibility is handled by the merchant. Prices must be entered tax-inclusive.

See more about [product & pricing](/features/products-and-plans/products-overview).

### **Business Tax ID Support**

Checkout can collect VAT/GST IDs and company billing information for B2B purchases. Tax-exemption logic applies in MoR model where applicable.

### **Branding & UI Style**

Merchants can customize the appearance of checkout through theme settings, colors, fonts, logos, and supported layout elements.&#x20;

Explore [branding & customization](/features/checkout/branding-and-customization).

### **Quantity Support**

Checkout supports quantity selection for one-time products and subscriptions where applicable.

### **Success & Redirect Flow**

After a successful payment, customers are redirected to your configured success URLs. Dynamic transaction parameters can be appended, and [Zotlo webhooks](/integrating-zotlo/webhooks/webhooks-overview) and/or [API confirmation endpoints](/integrating-zotlo/api-reference/introduction) may be used for server-side validation.

## **Checkout Options**

→ [**Embedded Checkout**](/features/checkout/embedded-checkout)\
Embed the checkout form inside your web or mobile experience.

→ [**Hosted Checkout**](/features/checkout/hosted-checkout-no-code)\
Use Zotlo-hosted checkout pages without handling UI or PCI requirements.&#x20;

→ [**Checkout Links API**](/features/checkout/checkout-api-support)\
Create checkout links programmatically for dynamic or internal use cases.&#x20;


# Embedded Checkout

Embedded Checkout allows you to place Zotlo’s secure checkout form directly inside your website or web app. This option provides a seamless, low-code purchase experience while allowing you to control the surrounding UI and user journey.

<div data-with-frame="true"><figure><img src="/files/vN7lM5ap44djUJYqL0fQ" alt="" width="563"><figcaption></figcaption></figure></div>

## **Embedded Checkout**

You embed the checkout form using the [Zotlo Checkout SDK](/integrating-zotlo/web-sdk/sdk-overview), which renders a secure payment form inside your page. The form automatically applies:

* Localized pricing
* Selected payment methods & custom ordering
* Multi-language UI
* Branding & theme settings
* Quantity selection (where applicable)
* Subscription or one-time product configuration

{% hint style="info" %}
Your customer completes the payment without being redirected to an external page.
{% endhint %}

## **Embedded Checkout Form**

To create a new embedded checkout:

1. Go to your project → **Embedded Checkout** in the Zotlo Dashboard.
2. Click **Get Started** and design your checkout form.
3. Configure your package, payment methods, language, and branding settings.
4. Use the [**Checkout SDK snippet**](/integrating-zotlo/web-sdk/checkout-sdk) to embed the form into your webpage.
5. Test your setup in **Test Mode**, then publish to accept live payments.

{% hint style="info" %}
Checkout forms start in Test Mode. You must publish the form before accepting real payments.
{% endhint %}

## **Configurations**

### **Package Settings**

Select the product or subscription plan to be sold. Checkout supports :&#x20;

* Subscriptions
* One-time purchases
* Trials
* Discounts
* Country-based pricing rules

Learn more about [product creation and pricing](/features/products-and-plans).

### **Payment Settings**

Choose which payment methods to display. After activating methods in your project:

* Add them to the checkout form
* Arrange display order as you prefer
* Ensure Apple Pay / Google Pay domains are verified
* External PSP-linked methods appear only if supported by your PSP

Learn more about [payment methods and how to activate them](/features/payment-methods/payment-methods-overview)

### **User Identification**

Choose whether the user should enter their **email** or **phone number** during checkout.\
If your app already knows the user, you can provide this information by passing a `subscriberId` while initiating the embedded checkout. When a valid identifier is provided, the user **does not need to enter email/phone again** in the checkout form.

When a `subscriberId` is passed, you can control how it behaves inside the checkout:

* **Auto-hide Email/Phone:** hide the field when the identifier is already provided
* **Allow Edit:** allow users to update the identifier if needed
* **UUID Support:** you may pass a UUID, but email/phone will still be required for subscriptions

{% hint style="info" %}
If you prefer you can pass a unique identifier (UUID) but remember if you are passing UUID as user identifier email/phone entry still be required for subscriptions.
{% endhint %}

### **Branding & Layout**

Choose from different layout themes and customize:

* Theme selection
* Logo & header
* Colors, fonts, label visibility
* Price layout (subtotal, total, discount visualization)
* CTA button styles (except Apple Pay, Google Pay, PayPal — brand rules apply)
* Optional product imagery
* Quantity settings
* Business purchase (tax ID) fields

## **Redirects After Payment**

After a successful payment, Zotlo can redirect users back to your app or to any web page, depending on your setup.

Zotlo supports two types of post-payment journeys:

### **1. App-to-Web Theme**

(When checkout is opened from a mobile app)

Use this flow when your app triggers the checkout.

* The app opens the checkout in an **external browser** or **in-app WebView**.
* After purchase, Zotlo redirects the user back into your app via a **deeplink**.
* If you're using a WebView, the **developer must close the WebView manually** after redirection.

{% hint style="success" %}
App-to-web is ideal for apps that offload purchases to the web and need to return users smoothly to in-app content.
{% endhint %}

### **2. Web-to-App Theme**

(When checkout is opened from the web)

This flow is used when the purchase journey begins on the web.\
After the payment is completed, Zotlo can:

**a) Redirect to your mobile app (Web → App)**

* By showing **deeplink buttons**
* Or **App Store / Google Play download buttons**
* Configured via dashboard (store URLs + deeplink)

{% hint style="success" %}
Web-to-app is ideal for marketing funnels that start on the web but should continue inside the app.
{% endhint %}

**b) Redirect to any web page (Web → Web)**

* Using your own success URL
* Or a generic redirect link
* Fully customizable

{% hint style="success" %}
Ideal for standard web-based businesses (no mobile app needed).
{% endhint %}

## **Publishing Checkout**

Embedded checkout forms start in Test Mode and must be published before you can accept real payments.

When you publish, Zotlo performs an automatic review to ensure the form is ready for live use. If everything is complete, the form goes live instantly.&#x20;

After publishing, your embedded checkout becomes immediately available for real users.

## **Checkout Analytics**

After publishing, a **Statistics** tab becomes available. You can track:

* Traffic
* Conversions
* Revenue
* Country, device, and package insights

These metrics help optimize your checkout experience and improve performance.

<table data-card-size="large" data-view="cards" data-full-width="true"><thead><tr><th></th><th></th><th data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Embedded Checkout Integration Guide</strong></td><td>Step-by-step guide to integrating embedded checkout with sample codes</td><td><a href="/pages/YucYcLTtypPkuB0GBSXV">/pages/YucYcLTtypPkuB0GBSXV</a></td></tr><tr><td><strong>Hosted Checkout (No-code)</strong></td><td>Learn more about the fully hosted checkout option that you can launch instantly.</td><td><a href="/pages/idyRyYGoEAxhccc76VyO">/pages/idyRyYGoEAxhccc76VyO</a></td></tr></tbody></table>


# Hosted Checkout (No-Code)

Hosted checkout allows you to launch a complete payment experience using a ready-to-use checkout page hosted by Zotlo. No SDK integration or frontend development is required.\
Simply create a checkout link, configure your product and payment settings, and share the link anywhere you want.

## **Hosted Checkout**

Zotlo generates a unique hosted checkout URL for each checkout link.\
The checkout page automatically applies:

* Localized pricing
* Selected payment methods & custom ordering
* Multi-language UI
* Branding and theme settings
* Subscription or one-time product configuration
* Quantity selection (where applicable)

## **Creating Checkout Links**

1. Go to **Projects → Checkout Links** in the Zotlo Dashboard.
2. Click **Get Started** to create your link.
3. Give your link a name (internal use only).
4. Configure your package, payment methods, language, and branding.
5. Save the link, it will first appear in **Draft** status.

## **Configurations**

### **Package Settings**

Choose the product or subscription plan that the checkout link will sell.\
Hosted Checkout supports:

* Subscriptions
* One-time purchases
* Trials
* Discounts
* Country-based pricing rules

Learn more about [product creation and pricing](/features/products-and-plans).

### **Payment Settings**

Choose which payment methods to show.\
After activating methods in your project:

* Add them to the checkout link
* Arrange the display order
* Ensure Apple Pay / Google Pay domains are verified
* PSP-linked methods appear only if supported by your PSP

Learn more about [payment methods](/features/payment-methods/payment-methods-overview).

### **User Identification**

Choose whether the user should enter their **email** or **phone number** during checkout.

If your app already knows the user, you can pass a `subscriberId` in the checkout URL.\
When a valid identifier is provided, the user **does not need to enter email/phone again** inside the checkout form.

**Example:**\
`premium.example.com?subscriberId=test@gmail.com`\
`premium.example.com?subscriberId=12124567890`

When a `subscriberId` is passed, you can control its behavior:

* **Auto-hide Email/Phone:** hide the field if the identifier is provided
* **Allow Edit:** allow the user to update the identifier
* **UUID Support:** you may pass a UUID, but email/phone will still be required for subscriptions

{% hint style="info" %}
If you prefer you can pass a unique identifier (UUID) but remember if you are passing UUID as user identifier email/phone entry still be required for subscriptions.
{% endhint %}

### **Branding & Layout**

Customize your hosted checkout:

* Theme selection
* Logo & header
* Colors, fonts, label visibility
* Price layout (subtotal, total, discount visualization)
* CTA button styles (except Apple Pay, Google Pay, PayPal — brand rules apply)
* Optional product imagery
* Quantity settings
* Business purchase (tax ID) fields

### **Custom Domain Settings**

By default, your checkout link uses a Zotlo domain.\
You can switch to your own custom domain:

1. Open the checkout link → **Change URL**
2. Enable **Use Custom Domain**
3. Add a CNAME record pointing your subdomain to Zotlo
4. Wait for automatic verification

{% hint style="info" %}
You can either use Zotlo domain or your own domain with hosted checkout links according to your preference.
{% endhint %}

## **Redirects After Payment**

After a successful payment, you can:

* Show Zotlo’s hosted success page
* Redirect to your own web URL
* Redirect into your mobile app (deeplink)
* Display app download buttons (App Store / Google Play)
* Use Web-to-Web or Web-to-App flows

Zotlo automatically determines the correct redirection based on your configuration.

### **1. App-to-Web Theme**

Used when the checkout link is opened from inside a mobile app.\
The app may open checkout in a browser or WebView.

* After payment, Zotlo redirects the user back to the app using a **deeplink**
* If opened in a WebView, the **developer must close the WebView manually**

{% hint style="success" %}
App-to-web is ideal for apps that offload purchases to the web and need to return users smoothly to in-app content.
{% endhint %}

### **2. Web-to-App Theme**

Used when the purchase starts on the web and should continue in your mobile app.

* Zotlo can show **deeplink buttons** or **App Store / Google Play buttons**
* Ideal for marketing funnels or onboarding flows

**This option can also be used for web-to-web flows** and redirect users to any landing page, dashboard, or custom success URL. No mobile app required.

{% hint style="info" %}
Web-to-app is ideal for marketing funnels that start on the web but should continue inside the app or for standard web-based businesses without mobile app.
{% endhint %}

## **Publishing Checkout Link**

Checkout links start in **Draft** or **Test Mode**. Click **Publish** to make them available for real users.

Zotlo performs an instant automated review. If everything is ready, your link goes live immediately. If not, you will see a short warning so you can fix and publish again.

## **Checkout Link Analytics**

After publishing, a Statistics tab becomes available. You can track:

* Traffic
* Conversions
* Revenue
* Country, device, and package insights

These metrics help optimize your checkout experience and improve performance.


# Checkout API Support

[Checkout API Support](/integrating-zotlo/api-reference/checkout-endpoints) allows you to generate **personalized checkout links** programmatically based on a checkout link you created in the Zotlo Dashboard. This is ideal when you want to create dynamic, user-specific, or campaign-specific purchase flows without modifying your main checkout link.

## **How It Works**

1. **Create a base checkout link**\
   In the Zotlo Dashboard, go to **Checkout Links** and create a checkout link.\
   This link will act as the **base template** for all personalized versions you generate through the API.
2. **Use the Checkout Link ID in your API call**\
   Every personalized link is created using the base link’s ID.\
   If no customization is provided, the link will be generated **exactly with the default settings** of the base checkout link.
3. **Apply optional customizations**\
   Through the [Checkout Endpoint](/integrating-zotlo/api-reference/checkout-endpoints), you can override several fields to create a tailored checkout experience for each user or scenario.

## **Customization**

Personalization is optional. If you don’t send overrides, the base link is used as-is.

You can customize:

### **Product or Package**

* Switch the package shown in checkout
* For one-time purchases, you can set a **custom price**, allowing you to charge a specific amount without creating a new product

### **Currency & Pricing**&#x20;

* Override the price or currency for the generated link **(One-time purchases only)**
* Useful for promotions, localized campaigns, or special offers

### **User Identification**

* Pass an email, phone number, or UUID as `subscriberId`
* Lets you **skip email/phone entry** during checkout when the user is known

### **Visual Overrides**

* Theme selection
* Title, description text
* Images or product visuals
* Button text
* Minor layout and presentation options

These do not affect your main checkout link, they only apply to the generated personalized link.

## **When To Use?**

* Show different offers to different users
* Run A/B tests on pricing, visuals, or CTA text
* Create partner/influencer-specific sales flows
* Offer one-time custom payments without creating new products
* Skip registration fields when the user is already authenticated in your app
* Build dynamic checkout flows based on events in your backend

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Checkout API Reference</strong></td><td>Full API guide for creating personalized checkout links.</td><td><a href="/pages/ghtJs2tCuYTuV8BhopXD">/pages/ghtJs2tCuYTuV8BhopXD</a></td></tr><tr><td><strong>Embedded Checkout</strong></td><td>Learn how to integrate the checkout form into your site with the Checkout SDK.</td><td><a href="/pages/vBneLxLG1tZagB87G2Gq">/pages/vBneLxLG1tZagB87G2Gq</a></td></tr></tbody></table>


# Multi-Language

Zotlo automatically adapts the checkout language based on the customer’s browser preferences. If the preferred language is supported, the checkout is shown in that language; otherwise, it falls back to English.

Multi-language support helps increase trust, reduce friction, and improve conversion in global funnels.

## **Language Selection**

* The user’s browser/OS language is detected automatically.
* If the language is supported, the checkout instantly switches to that language.
* If not supported, English is used as the fallback default.
* Merchants do not need to configure anything — language handling is automatic.
* RTL (right-to-left) languages are rendered with proper alignment.

## **Supported Languages**

Below is the full list of languages currently supported by Zotlo Checkout:

| Language           | Language                  |                     |
| ------------------ | ------------------------- | ------------------- |
| **ar**             | **Arabic** *(RTL)*        | **العربية**         |
| **az**             | **Azerbaijani**           | **Azərbaycan**      |
| **zh**             | **Chinese (Simplified)**  | **简体中文**            |
| **zh\_tw**         | **Chinese (Traditional)** | **繁體中文**            |
| **cs**             | **Czech**                 | **Czech**           |
| **da**             | **Danish**                | **Dansk**           |
| **nl**             | **Dutch**                 | **Dutch**           |
| **en** *(Default)* | **English**               | **English**         |
| **fr**             | **French**                | **French**          |
| **de**             | **German**                | **Deutsch**         |
| **he**             | **Hebrew** *(RTL)*        | **עִבְרִית**        |
| **hi**             | **Hindi**                 | **Hindi**           |
| **hu**             | **Hungarian**             | **Hungarian**       |
| **id**             | **Indonesian**            | **Indonesia**       |
| **it**             | **Italian**               | **Italian**         |
| **ja**             | **Japanese**              | **Japanese**        |
| **kk**             | **Kazakh**                | **Kazakh**          |
| **ko**             | **Korean**                | **Korean**          |
| **ms**             | **Malay**                 | **Melayu**          |
| **no**             | **Norwegian**             | **Norsk**           |
| **pt**             | **Portuguese**            | **Portuguese**      |
| **pt\_br**         | **Portuguese (Brazil)**   | **Portuguese (BR)** |
| **ro**             | **Romanian**              | **Romanian**        |
| **ru**             | **Russian**               | **Русский**         |
| **es**             | **Spanish**               | **Español**         |
| **sv**             | **Swedish**               | **Svenska**         |
| **tl**             | **Tagalog**               | **Tagalog**         |
| **th**             | **Thai**                  | **ภาษาไทย**         |
| **tr**             | **Turkish**               | **Türkçe**          |
| **uk**             | **Ukrainian**             | **Українська**      |
| **vi**             | **Vietnamese**            | **Việt Nam**        |

#### Override Language

(Developer Use) If needed, you can manually force a specific language using [SDK parameters](/integrating-zotlo/web-sdk/sdk-overview) or [API fields](/integrating-zotlo/api-reference/introduction). Otherwise, auto-detection handles everything.


# Branding & Customization

Zotlo allows you to create branded, high-converting checkout experiences without writing any code. You can customize the visual layout, messaging, and structure of your checkout pages, both [Embedded Checkout](/features/checkout/embedded-checkout) and [Hosted Checkout](/features/checkout/hosted-checkout-no-code), while ensuring full compliance and payment reliability.

## **Customization**

### **Themes & Layout**

Choose from multiple layout themes and control:

* Overall layout structure
* Header visibility (logo, project name)
* Section spacing, alignment, and padding
* Light/Dark mode compatibility

### **Brand Identity**

Customize key brand elements to match your product’s look:

* Logo
* Primary/secondary colors
* Fonts and label styles
* Optional product imagery
* Business purchase fields (Tax ID)

{% hint style="info" %}
*Note:* Apple Pay, Google Pay, and PayPal buttons follow their own brand guidelines and cannot be restyled.
{% endhint %}

### **Price Display Options**

Control how prices appear to users:

* Subtotal and total layout (if applicable for the selected theme)
* Optional visual discount / bonus presentation(if applicable)
* Localized pricing (automatically applied based on your configuration)

### **Payment Button Style**

Configure your main action button:

* Text (supports dynamic messages such as trial vs paid state)
* Color, size, borders and corners

### **Card Form Labels**

Manage how form fields are displayed:

* Show/hide labels
* Font size and style

## **After-Payment Page**&#x20;

Choose how the user experience continues after a successful payment:

* Use Zotlo’s hosted success page (App-to-Web or Web-to-App themes)
* Redirect to your own URL
* Redirect into your mobile app via deeplink
* Display app download buttons for app onboarding

Each theme supports:

* Custom button text
* Full styling controls
* Auto-redirect (optional)

## **Where to Customize**

Branding settings can be configured inside each:

* [**Embedded Checkout Form**](/features/checkout/embedded-checkout)
* [**Hosted Checkout Link**](/features/checkout/hosted-checkout-no-code)
* [**Checkout Links created via API**](/integrating-zotlo/api-reference/checkout-endpoints)

Design changes are immediately reflected in the checkout preview.


# Quiz Funnels

Quiz Funnels help you create high-converting, personalized purchase journeys by guiding users through interactive questions before checkout.

In this section, you can explore the following topics:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>📘</h3></td><td><h4><strong>Funnels Overview</strong></h4></td><td>Get an introduction to how quiz funnels work, their benefits, and how they integrate into your sales flows.</td><td><a href="/pages/q5nXhnNW1y4DdcdjTReZ">/pages/q5nXhnNW1y4DdcdjTReZ</a></td></tr><tr><td><h3>🎨 </h3></td><td><h4><strong>Designing Funnels</strong></h4></td><td>Learn how to structure your quiz, customize layouts, and design question sequences for maximum engagement and conversion.</td><td><a href="/pages/0GgXdBwiKW5mroCTzjqM">/pages/0GgXdBwiKW5mroCTzjqM</a></td></tr><tr><td><h3>🧠</h3></td><td><h4><strong>Quiz Logic</strong></h4></td><td>Explore conditional logic, branching, and dynamic question flows to create personalized user experiences.</td><td><a href="/pages/BexSXHYmg5YawKr91mWe">/pages/BexSXHYmg5YawKr91mWe</a></td></tr><tr><td><h3>🌍</h3></td><td><h4><strong>Multi-language</strong></h4></td><td>See how to create quizzes in multiple languages and manage translations for questions, options, and funnel screens.</td><td><a href="/pages/LXK0wtE371RqbpD62FaK">/pages/LXK0wtE371RqbpD62FaK</a></td></tr><tr><td><h3>🔐</h3></td><td><h4><strong>Social Login Options</strong></h4></td><td>Enable quick registration and higher completion rates by integrating social login options within funnel steps.</td><td><a href="/pages/WUvbiphhBkTQsUuVBLX1">/pages/WUvbiphhBkTQsUuVBLX1</a></td></tr><tr><td><h3>📤</h3></td><td><h4>Submission and Publication Process</h4></td><td>Understand how user responses are collected, validated, stored, and delivered to your backend via webhooks.</td><td><a href="/pages/tc1Ghj3gMmcrVplxfpDs">/pages/tc1Ghj3gMmcrVplxfpDs</a></td></tr></tbody></table>


# Funnels (Flows) Overview

Quiz funnels help you create interactive, step-based sales flows that guide users through personalized questions before reaching the checkout. They are ideal for increasing engagement, understanding user intent, and boosting conversion by presenting the right offer at the right moment.

A quiz funnel can include questions, conditional logic, personalized result pages, and optional login steps, all designed without writing code.

<div data-full-width="false" data-with-frame="true"><figure><img src="/files/7wgngbfPfpvwKF5dXoaE" alt="" width="563"><figcaption></figcaption></figure></div>

## **Quiz Funnels**

Quiz Funnels enable you to:

* **Present personalized offers** based on user answers
* **Segment users** and tailor product recommendations
* **Increase conversion** with an interactive pre-checkout experience
* **Collect insights** about your audience (intent, goals, preferences)
* **Send users seamlessly into checkout** with pricing, products, and subscriberId already prepared
* **Guide mobile users** with Web-to-App flows and by-pass store fees

## **How Funnels Work**

A quiz funnel typically follows this flow:

1. **User starts the quiz** (from an ad, website, email, or app)
2. **User answers step-based questions**
3. **Logic determines the next step** (simple or branched paths)
4. **A result page is shown**
5. **User proceeds to checkout** with preselected plan, pricing, or subscriberId

All logic, questions, layouts, and outcomes are configured inside the Zotlo Dashboard, no coding required.

## **Key Features**

* No-code flow builder (pages, steps, questions, images, buttons)
* Conditional logic to route users based on answers
* Result or paywall pages with messages and offers
* Automatic multi-language support
* Optional social login integration
* Checkout integration for subscriptions, one-time payments, and e-pin sales
* App redirection after successful payments
* Web-to-App synchronization tools
* Analytics to track views, completions, and conversion

## **When to Use Funnels**

Quiz funnels are especially powerful for:

* Subscription apps (fitness, meditation, productivity, learning)
* Meal planners / personalization tools
* Digital product recommendations
* SaaS onboarding flows
* Conversion-optimized marketing campaigns
* Pre-qualification flows (intent, level, goal, preferences)

If your product benefits from personalization, guidance, or segmentation, quiz funnels amplify your conversion dramatically.


# Designing Sales Flows

Designing a quiz funnel involves defining the steps your users will follow, choosing page types, adding questions or information, and shaping the visual experience. Zotlo’s no-code builder allows you to create and customize every part of your funnel without writing a single line of code.

<div data-with-frame="true"><figure><img src="/files/iYhNUKTWW6Irm7lan7s4" alt="" width="563"><figcaption></figcaption></figure></div>

## **Creating a Flow**

You can create a new quiz funnel from:\
**Zotlo Dashboard → Your Project → Sales Flows → Flow Design → New Flow**

After creating a flow, you can add pages, design steps, define logic rules, and configure multi-language content.

## **Flow Structure**

Every quiz funnel is made of a series of pages. Each page represents a step in the user journey:

* Welcome / Intro page
* Quiz question pages
* Registration page (optional or auto-filled)
* Paywall / Offer page
* Payment page
* Payment success page

You choose which pages to include based on the type of funnel you’re creating.

*Payment page is the only required page, all the other pages are optional.*\
If you prefer skipping registration page, you can merge with payment step using **Register On Payment** feature.

## **Page Types**

Quiz funnels are built using a set of flexible page types, each serving a specific purpose in the user journey:

### **Welcome Page**

Optional introduction page used to greet the user, highlight key benefits, or explain what the quiz will cover.

### **Quiz Question Pages**

Optional. Interactive pages where users answer questions through elements like multiple choice, image-based selections, numeric inputs, date/time pickers, or location inputs.

### **Registration Page**

Optional with register on payment feature. Collects the user’s email or phone number. Supports social login and can be skipped using *subscriberId* for a seamless experience.

### **Paywall Page**

Optional offer page shown before payment step where users see personalized subscription or one-time purchase options before checkout.

### **Payment Page**

Required page where users complete the payment. Payment methods and pricing appear automatically based on your configuration.

### **Payment Success Page**

Final page shown after payment. Can display app download links, activation instructions, or deeplink redirection for mobile flows.

* Redirect users to your app or website
* Display download links (App Store / Google Play)
* Show activation instructions
* Add deeplinks for Web-to-App flows

## **Designing Pages**

Each page is built using **sections** and **elements**.

### **Sections**

* Header (logo, progress bar)
* Body (text, buttons, images)
* Footer (legal text, support links)

### **Elements**

* Text blocks
* Buttons
* Images
* Answer options
* Input fields
* Plan selectors
* Social login buttons
* Payment form
* Success message blocks

Every element supports styling options such as:

* Colors
* Typography
* Alignment
* Spacing
* Dark/Light mode

You can add/remove elements and reorder them freely.

### **Media & Visuals**

You can enhance your funnel by adding:

* Images and GIFs
* Videos
* Icons

Visuals help increase engagement and make the flow more intuitive.

### **Registration Options**&#x20;

**(User Identification)** A flow can collect user information in different ways:

* **Email**
* **Phone number**
* **Social login** (Apple / Google)
* **SubscriberId pre-fill** (bypass registration)

If you already know the user, send with `subscriber_id` parameter:

```
premium.example.com?subscriberId=email_or_phone
```

This skips the registration step and auto-fills their information at checkout.

### **Activation (Optional)**

After purchase, users may activate their account using:

* Email/phone login
* Zotlo activation code (UUID)
* Your own activation system

For subscription or one-time purchases, activation settings appear on the success page.\
E-pin purchases automatically display the pin code.

## **Best Practices**

* Keep questions concise
* Use images to boost engagement
* Reduce friction with social login
* Add value messaging before the paywall
* Use subscriberId for smoother transitions from apps
* Keep total steps between 5–8 for best conversion


# Quiz Logic

Quiz Logic allows you to control how users move through your quiz funnel based on the answers they provide. With conditional rules, you can create personalized paths, skip irrelevant questions, show tailored result pages, and deliver highly optimized sales flows without writing any code.

<div data-with-frame="true"><figure><img src="/files/9XWxybMUg1RfaMYjbBzh" alt="" width="563"><figcaption></figcaption></figure></div>

### **What Quiz Logic Does**

Quiz Logic helps you:

* Route users to different steps based on their answers
* Skip unnecessary questions
* Show different result messages
* Build multi-path flows with personalized outcomes
* Improve conversion by keeping each user on the most relevant path

### **Logic Types**

Zotlo supports three main types of logic:

#### **1. Go to Next Step (Default)**

If no rule is added, users continue to the next question in sequence.

#### **2. Conditional Routing**

Create rules that send users to a specific question based on their answer:\
“If user selects Option A → go to Question 5”\
“If user picks Option B → go to Ending”\
“If user does not answer → show Underage page”

This is the core of multi-path funnels.

### **Adding Logic Rules**

Each question page can have its own set of rules. From the logic editor, you can:

* Add new conditions
* Combine multiple answer conditions
* Set AND / OR logic
* Define the target step (question, info page, ending)

### **Logic Validation**

Zotlo automatically checks for:

* Broken logic paths
* Loops (A → B → A)
* Steps without reachable entry
* Empty conditions
* Missing target pages

Flows with invalid logic cannot be submitted for review or publishing.

### **Best Practices**

* Keep logic simple—avoid too many branches
* Test all paths in Test Mode to ensure they flow correctly
* Use meaningful step names (e.g., “Goal Question”, “Experience”, “Result A”)
* Combine questions only when necessary
* Always define a fallback path


# Multi-language

Quiz funnels automatically adapt to the user’s preferred language based on their browser settings. If the detected language is supported in the flow, the content is displayed in that language. Otherwise, the default language is used.

Multi-language support helps you run global campaigns, increase trust, and improve conversion across different regions.

## **Language Selection**

When a user opens a quiz funnel:

1. Zotlo detects the user’s browser language.
2. If the language is enabled in the flow, the quiz is displayed in that language.
3. If not supported, the flow falls back to the default language defined in the project settings.

Language detection is automatic and requires no technical setup.

## **Configuring Languages**

Flows are created in English by default. You can enable additional languages during or after flow design.

To configure languages:

**Go to the Languages** → Manage **Language**&#x20;

For each enabled language:

* All page content must be entered separately
* Text, buttons, and descriptions can differ per language
* Images, videos and links can also be customized per language

This allows you to adapt not only translations but also messaging strategy by region.

## **Multi-Language Rules**

When using multiple languages:

* Every page must contain content in all enabled languages
* Missing translations will block submission for review
* Activation instructions must be provided in all enabled languages
* Social login and checkout steps automatically inherit language settings

## **RTL Language Support**

Right-to-left (RTL) languages such as:

* Arabic
* Hebrew

are automatically rendered with proper alignment and layout direction.

No additional configuration is required.

## **Best Practices**

* Keep translations consistent across quiz and checkout
* Adapt marketing tone per region when necessary
* Use localized images where relevant
* Review language content before submitting for approval

## **Supported Languages**

Below is the full list of languages currently supported by Zotlo Sales Flows:

| Language           | Language                  |                     |
| ------------------ | ------------------------- | ------------------- |
| **ar**             | **Arabic** *(RTL)*        | **العربية**         |
| **az**             | **Azerbaijani**           | **Azərbaycan**      |
| **zh**             | **Chinese (Simplified)**  | **简体中文**            |
| **zh\_tw**         | **Chinese (Traditional)** | **繁體中文**            |
| **cs**             | **Czech**                 | **Czech**           |
| **da**             | **Danish**                | **Dansk**           |
| **nl**             | **Dutch**                 | **Dutch**           |
| **en** *(Default)* | **English**               | **English**         |
| **fr**             | **French**                | **French**          |
| **de**             | **German**                | **Deutsch**         |
| **he**             | **Hebrew** *(RTL)*        | **עִבְרִית**        |
| **hi**             | **Hindi**                 | **Hindi**           |
| **hu**             | **Hungarian**             | **Hungarian**       |
| **id**             | **Indonesian**            | **Indonesia**       |
| **it**             | **Italian**               | **Italian**         |
| **ja**             | **Japanese**              | **Japanese**        |
| **kk**             | **Kazakh**                | **Kazakh**          |
| **ko**             | **Korean**                | **Korean**          |
| **ms**             | **Malay**                 | **Melayu**          |
| **no**             | **Norwegian**             | **Norsk**           |
| **pt**             | **Portuguese**            | **Portuguese**      |
| **pt\_br**         | **Portuguese (Brazil)**   | **Portuguese (BR)** |
| **ro**             | **Romanian**              | **Romanian**        |
| **ru**             | **Russian**               | **Русский**         |
| **es**             | **Spanish**               | **Español**         |
| **sv**             | **Swedish**               | **Svenska**         |
| **tl**             | **Tagalog**               | **Tagalog**         |
| **th**             | **Thai**                  | **ภาษาไทย**         |
| **tr**             | **Turkish**               | **Türkçe**          |
| **uk**             | **Ukrainian**             | **Українська**      |
| **vi**             | **Vietnamese**            | **Việt Nam**        |


# Adding Social Login

Social Login lets users authenticate with **Apple**, **Google**, or **Facebook** instead of manually entering email. When enabled, social login buttons appear on the **Registration Page** of a Quiz Funnel (only when registration type = Email).

This section focuses on how to configure provider integrations and how social login behaves inside flows.

## **Social Login Options**

* Social login is shown **only on the Registration Page**
* Available when Registration Type = **Email**
* After the user logs in through Apple/Google/Facebook:
  * Zotlo verifies the provider token
  * Extracts a validated email
  * Automatically sets this email as the user’s identifier
  * User continues the flow without entering email manually
* If a `subscriberId` is passed to the flow URL → registration step is skipped → social login buttons are hidden.

## **Provider Integrations**

Social login **cannot be used** until each provider is correctly integrated in **Project Settings → Social Logins**.

Below are the configuration fields required for each provider.

### **Google Login**

You must create an OAuth application in **Google Developer Console**.

Required fields:

* **Client ID** — OAuth 2.0 client ID for web
* **Client Secret** — OAuth 2.0 client secret
* **Redirect URL** — Provided by Zotlo; must be added to Google Developer Console under “Authorized redirect URIs”

**Steps:**

1. Go to Google Developer Console → Create Project
2. Enable “OAuth Consent Screen”
3. Create OAuth Client (Web Application)
4. Copy your **Client ID** and **Client Secret** into Zotlo
5. Add Zotlo’s Redirect URL to Google console
6. Save integration → Google login becomes available in flows

### **Apple Login**

You must configure an Apple Sign-In service in your **Apple Developer Account**.

Required fields:

* **Team ID**
* **Client ID (Service ID)**
* **Key ID**
* **Secret Key (.p8 file content)**
* **Redirect URL** (provided by Zotlo; add to Service ID configuration)

**Steps:**

1. Create a **Service ID** in Apple Developer
2. Enable *Sign in with Apple*
3. Create a private key → download `.p8` file
4. Copy **Team ID**, **Client ID**, **Key ID**, and **Secret Key** into Zotlo
5. Add Zotlo Redirect URL in Apple Developer → Web Redirects
6. Save integration → Apple login appears automatically in flows

### **Facebook Login**

You must create a Facebook App in **Meta for Developers**.

Required fields:

* **Client ID (App ID)**
* **Client Secret**
* **Redirect URL** (provided by Zotlo; add to Valid OAuth Redirect URIs)

**Steps:**

1. Create a Facebook App
2. Enable **Facebook Login** product
3. Copy **App ID** + **App Secret** into Zotlo
4. Add Zotlo Redirect URL to *Valid OAuth Redirect URIs*
5. Save integration → Facebook login becomes available

## **Enabling Social Login**

Once integrations are complete:

1. Open your flow → **Registration Page**
2. Set Registration Type = **Email Registration**
3. In the “Social Login” settings:
   * Enable Apple / Google / Facebook
   * Buttons will be displayed automatically to users
4. Customize button order and visibility if needed

Social login **does not work** with Phone Registration.

{% hint style="info" %}
IMPORTANT : Ensure Redirect URLs match exactly (case & trailing slash sensitive)
{% endhint %}


# Submission and Publishing

Before a Quiz Funnel can go live, it must pass Zotlo’s automated and manual checks. This ensures a smooth user experience, correct activation flows, and compliance with required standards.

## **Review Requirements**

A funnel must be **submitted for review** before it can receive traffic.\
Draft funnels cannot be used in production.

Zotlo applies two levels of checks:

### **Automated Checks**

Triggered immediately when you click **Submit for Review**. Your funnel will only proceed to manual review if all items pass.

The system verifies:

* Required pages exist (Registration + Checkout)
* At least one **activation method** is configured (for non–e-pin packages)
* If a quiz page exists:
  * At least one question is added
  * No broken or invalid logic rules
* If multi-language is enabled:
  * All added languages contain complete content
* Success Page contains required redirection links (deeplink / App Store / Generic link)
* Project-level URLs are provided (Privacy Policy, Terms, Support)
* Download URLs in Project Settings are filled

If any of these checks fail, the funnel cannot be submitted and the UI will show the issue instantly.

### **Manual Review**

After passing automated checks, the flow is reviewed for:

* Compliance of visual and written content
* Multi-language consistency
* Page layout integrity on desktop + mobile
* Correct logic routing
* Valid app download / deeplink configurations (App-to-Web / Web-to-App)

Review time is generally short but depends on queue volume.

## **Funnel Statuses**

You can track the review progress in the **Flows** section:

| Status                 | Meaning                            |
| ---------------------- | ---------------------------------- |
| **Waiting for Review** | Submitted, awaiting review         |
| **In Review**          | Currently being reviewed by Zotlo  |
| **Rejected**           | Issues found; corrections required |
| **Ready for Sale**     | Approved and ready to go live      |

If rejected, you can view **Rejection Details**, fix the issues, and resubmit.

{% hint style="info" %}
IMPORTANT: Approved flows cannot be edited. If you need to make changes, create a copy of the approved flow, apply your updates, and resubmit the new version.
{% endhint %}

### **After Approval**

Once a funnel is marked as Ready for Sale, it is officially approved. However, it is not yet live. To start receiving traffic, you must connect it to a Sales Link.

## Publishing via Sales Links

To publish your approved funnel, create a Sales Link:\
Zotlo Dashboard → Your Project → Sales Flows → Sales Links → New Link

By default, new links are created in Draft status and use the `buy.zotlo.com` domain.

### Domain Configuration

You have two options for your Sales Link URL:

* Default Domain: By default, new Sales Links are created using the Zotlo domain in the following format: **buy.zotlo.com/...**\
  This means no additional setup is required to use this default domain.
* Custom Domain: For a branded experience, you can use your own domain or subdomain instead of the default Zotlo domain.
  * CNAME Setup: If you choose a custom domain, you must create a **CNAME** record in your DNS settings pointing to **zcname.zotlo.com**. This ensures your Sales Link resolves correctly and is accessible to your users.

### Finalizing Site Content

Before moving a Sales Link from Draft to Live, go to the Site Content tab in settings:

* Default Flow: Select the approved(Ready for sale) Quiz Funnel you want to associate with this link.
* Primary Language: This determines the fallback language. If a user's browser language is not supported, the site will display this language.
  * *The primary language must be one of the languages supported within your selected flow.*

### Going Live

After completing the configurations, click the Publish button. Your link is now Live and ready for:

* Shared as a direct funnel link
* Used in marketing campaigns
* Web-to-App journeys.
* Connection to any checkout flow.

No additional steps are necessary.


# Subscriptions

Zotlo’s subscription system allows you to manage recurring payments, track lifecycle events, and keep full control over upgrades, downgrades, renewals, and cancellations.

In this section, you can explore the following topics:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>📘</td><td><h4><strong>Subscriptions Overview</strong></h4></td><td>Learn how Zotlo handles recurring billing, subscription types, statuses, and core concepts used throughout the subscription system.</td><td><a href="/pages/dzQbyP4NGmV7IYB1OBiu">/pages/dzQbyP4NGmV7IYB1OBiu</a></td></tr><tr><td><h3>⏳ </h3></td><td><h4><strong>Subscription Lifecycle</strong></h4></td><td>Understand how a subscription progresses—from trial to paid, renewals, grace periods, cancellations, and reactivations.</td><td><a href="/pages/u1gIMX7fUM607KT5MCxE">/pages/u1gIMX7fUM607KT5MCxE</a></td></tr><tr><td>📈</td><td><h4><strong>Plan Changes</strong></h4></td><td>Explore how upgrades, downgrades, and billing cycle adjustments work, including prorations and saveCycle options.</td><td><a href="/pages/Q2Dxtcxrqla6o4CHc03W">/pages/Q2Dxtcxrqla6o4CHc03W</a></td></tr></tbody></table>


# Subscriptions Overview

Zotlo provides a complete subscription management system that lets you create, sell, and operate recurring products across countries, currencies, and payment methods.

It handles the entire lifecycle, from plan creation to renewals, trials, failed payment recovery, and cancellation while keeping you in full control.

{% hint style="success" %}
Subscriptions work the same in both the **Merchant of Record (MoR)** and **Connected PSP** models.
{% endhint %}

## **Subscriptions**

Zotlo allows you to:

* Offer recurring products with flexible billing intervals
* Add free or paid trials
* Use localized pricing rules for global sales
* Automate renewals and handle tax calculation
* Reduce involuntary churn with smart retry & dunning
* Manage subscribers directly from the Zotlo Dashboard
* Integrate with your app easily using webhooks & API services

## **Key Capabilities**

### **Subscription Plans**

Create multiple [subscription plans](/features/products-and-plans/subscription-plans) with different periods (weekly, monthly etc.), local pricing rules, trials, discounts, and custom configurations.&#x20;

### **Recurring Billing**

Zotlo automatically handles renewals/[recurring billing](/features/subscriptions/subscription-lifecycle) through your chosen payment methods. For [merchant of record(MoR)](/welcome/merchant-of-record) sales, Zotlo also handles invoices, taxes, and compliance.

### **Trials**

Offer [free or paid trials](/features/subscriptions/subscription-lifecycle). Customers automatically convert to paid subscribers at the end of the trial period.

### **Localized Pricing**

Plans support [country-based pricing](/features/products-and-plans/localized-pricing) and currency overrides. Customers see the appropriate currency and price according to your configuration.&#x20;

### **Subscriber Management**

[Track subscribers](/features/customer-management/managing-subscriptions), view billing history, manage cancellations, refund individual charges, and review renewal attempts, all from the Zotlo Dashboard. Zotlo also provides a [self-service customer portal](/features/customer-management/customer-portal) where subscribers can update payment details, review invoices, and manage their subscriptions independently.

### **Churn Reduction**

Zotlo minimizes involuntary churn using:

* Smart retry logic
* Dunning flows
* Payment method fallbacks (where supported)

## **Integrations**

Use Zotlo [webhooks](/integrating-zotlo/webhooks/webhooks-overview), [subscriber APIs](/integrating-zotlo/api-reference/subscriptions-endpoints) to sync subscription status with your app or backend. See the essentials of [integrating Zotlo](/integrating-zotlo/api-reference)

## **When to Use Subscriptions**

Subscriptions are ideal for:

* SaaS and digital services
* Mobile apps with recurring content
* Fitness, wellness, education, productivity apps
* Media, streaming, and content platforms
* Any business needing predictable recurring revenue

If your product is delivered continuously and customers should be billed on a schedule, subscriptions provide the strongest revenue engine.


# Subscription Lifecycle

The subscription lifecycle defines how a subscriber progresses from initial purchase through renewals, failed payments, cancellations, and potential reactivation. Zotlo manages all billing logic, dates, retries, and status transitions, while your application decides how user access is handled.

## **Subscription Start**

A subscription begins the moment a user completes a checkout flow, either through Embedded Checkout, Hosted Checkout, Quiz Funnels, or API-generated checkout links.

When a subscription is created:

* A subscriber record is created
* The initial plan, pricing, currency, and billing cycle are locked in
* Payment method is attached (cards, Apple Pay, Google Pay, PayPal, or PSP token)
* State become **trial** (if the plan includes a trial) or **paid** (if no trial)
* Status become **active**
* If plan has a trial, first paid renewal is scheduled for the end of the trial
* If plan has no trial, first renewal is scheduled based on billing interval
* `start_date`, `expire_date`, and other lifecycle timestamps are calculated

{% hint style="info" %}
A subscription only enters the lifecycle once the first successful payment (or successful trial start) is recorded.
{% endhint %}

## **Recurring Billings**

At the end of billing cycles, Zotlo attempts to charge the saved payment method.

If the renewal succeeds:

* Status stays **active**
* A new cycle begins
* `expire_date` is recalculated

## **Dunning & Grace**

When a renewal fails, Zotlo begins an automated retry process designed to recover involuntary churn. Grace Period is 30 days by default. It gives subscribers time to update their payment method after failed renewal attempts.

During grace:

* Status = **grace**
* Zotlo apply smart retries&#x20;
* No new charges happen unless a retry succeeds

If a retry succeeds:

* Status returns to **active**
* Billing returns to normal

If all retries fail:

* The subscription moves into the **cancellation stage**

{% hint style="info" %}
**Access rules during grace are fully controlled by your application.**\
You may allow full access, partial access, or block access entirely.
{% endhint %}

## **Cancellations**

Subscriptions may be canceled by:

* The user (via Customer Portal)
* The merchant (Dashboard / API)
* Zotlo (automatically when grace period ends and recovery fails)

When a subscription is canceled:

* **Status immediately becomes `canceled`**
* **expire\_date does not change**
* No further renewal attempts occur

{% hint style="info" %}
**Access After Cancellation**

Zotlo does not block or allow access automatically.

Your application decides:

* Whether users retain access until the expire\_date, or
* Whether access is removed immediately after cancellation
  {% endhint %}

## **Reactivations**

A canceled subscription can be reactivated if the **expire\_date has not passed**.

Reactivation behavior:

* No additional charge is made immediately
* Status becomes **active** again
* The subscription continues until the existing `expire_date`
* On the next renewal attempt, normal billing behavior resumes

Reactivation is **not possible** after `expire_date` has passed.

## **Price & Currency Changes**

Price and currency updates affect **future renewals**, not historical charges.

* Existing subscriptions continue with their current price at the next billing cycle
* Past invoices remain unchanged
* If you want existing subscribers to move to a new price, this can be adjusted by Zotlo


# Plan Changes

Subscribers can move to a different subscription plan at any time.\
Zotlo manages the billing logic (renewal dates, credits, charges) and delivers updated subscription details to your system so you can adjust user access accordingly.

Plan changes can be made:

* **From the** [**Zotlo Dashboard**](https://console.zotlo.com)
* **Via the** [**Zotlo API**](/integrating-zotlo/api-reference/introduction)

Zotlo does **not** enforce access rules, your app decides how to behave based on the updated subscription data.

## **Upgrade**

An upgrade means moving to a **higher-priced** plan.

Zotlo supports **two upgrade behaviors**:

### **Reset Billing Cycle**&#x20;

The most common scenario for upgrades.

**What happens:**

* New plan starts immediately.
* A **new billing cycle** begins now.
* The remaining unused time on the previous plan is **calculated**.
* If the unused time has value, it is applied to reduce the amount charged for the upgrade.
* **Result for customer:** Instant access to the higher-tier plan.

### **Keep Current Cycle**

The subscriber keeps the original renewal date.

**What happens:**

* New plan becomes effective **immediately.**
* The billing cycle **does not reset**.
* Unused time from the previous plan is **prorated** and difference is **billed instantly**.
* The subscriber pays only the **pro-rated difference** for the remaining days until next renewal.
* **Result for customer:** Immediate access with a small top-up payment.

## **Downgrade**

A downgrade means moving to a **lower-priced** plan.

Zotlo always applies **next-cycle activation** for downgrades.\
(No immediate downgrades, no proration.)

**What happens:**

* The subscriber stays on the current plan until the end of the billing period.
* The downgrade becomes active **on the next renewal date**.
* No credit is created.
* Billing amount updates automatically on next renewal.
* **Result for customer:** They keep their current benefits until the cycle ends.

## **How Proration Works**

When a credit is applicable:

* Zotlo calculates the value of unused days based on:
  * Previous plan price
  * Days remaining in the current paid period
* This credit is applied to the amount of the upgrade.

{% hint style="info" %}
Proration applies **only for upgrades**. There is **no proration for downgrades**.
{% endhint %}

## **Trials During Plan Changes**

If the subscriber is currently in a **trial**, changing plans typically ends the trial unless the new plan also includes a trial.<br>

<table data-card-size="large" data-view="cards" data-full-width="true"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Plan Change API Reference</strong></td><td>Learn how to change subscription plans programmatically, including upgrade modes, proration options, and scheduling behavior.</td><td><a href="/pages/9EczLg9GDvjKL1UOIwql">/pages/9EczLg9GDvjKL1UOIwql</a></td><td><a href="/pages/zcObw6iQvrl5xuK5Sog9">/pages/zcObw6iQvrl5xuK5Sog9</a></td></tr><tr><td><strong>Subscriber Management</strong></td><td>See how to update a subscriber’s plan directly from the Zotlo Dashboard, including immediate upgrades and scheduled downgrades.</td><td><a href="/pages/BjKp23bYcJJRy3LQAFvk">/pages/BjKp23bYcJJRy3LQAFvk</a></td><td><a href="/pages/BjKp23bYcJJRy3LQAFvk">/pages/BjKp23bYcJJRy3LQAFvk</a></td></tr></tbody></table>


# Customer Management

Zotlo Customer Management helps you track user activity, manage subscription lifecycles, handle refunds or disputes, and offer a seamless self-service experience through the Customer Portal.

In this section, you can explore the following topics:

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>💳</h3></td><td><h4><strong>Tracking Payments</strong></h4></td><td>Monitor all user payments, renewals, and one-time transactions to maintain full visibility over customer purchase activity.</td><td><a href="/pages/AXQAsgFXwUPS5m1Xfc8T">/pages/AXQAsgFXwUPS5m1Xfc8T</a></td></tr><tr><td><h3>🔄 </h3></td><td><h4><strong>Managing Subscriptions</strong></h4></td><td>View and update subscription statuses, change plans, and handle lifecycle events such as renewals, grace periods, or cancellations.</td><td><a href="/pages/BjKp23bYcJJRy3LQAFvk">/pages/BjKp23bYcJJRy3LQAFvk</a></td></tr><tr><td><h3>↩️</h3></td><td><h4><strong>Refunds &#x26; Disputes</strong></h4></td><td>Process refunds, evaluate dispute cases, and manage resolutions securely and consistently.</td><td><a href="/pages/ax0TB3tHqtqfxbVvnZ9E">/pages/ax0TB3tHqtqfxbVvnZ9E</a></td></tr><tr><td><h3>👥</h3></td><td><h4><strong>Customer Portal</strong></h4></td><td>Provide users with a branded self-service portal to manage their subscriptions, update payment methods, or review billing history.</td><td><a href="/pages/lcNbNtGyocro098qrYx0">/pages/lcNbNtGyocro098qrYx0</a></td></tr></tbody></table>


# Tracking Payments

The **Payments** section gives you full visibility into all payments processed across your projects. From here, you can monitor statuses, review detailed transaction data, issue refunds, and inspect renewal attempts.

<div data-with-frame="true"><figure><img src="/files/TqJP0sxhpWjMxSGID1G1" alt="" width="563"><figcaption></figcaption></figure></div>

## **Payments Overview**

Navigate to your proect in **Zotlo** **Dashboard → Payments** to view all transactions in one unified list.\
The payments table includes key details such as:

* Transaction amount & currency
* Payment method
* Status
* Timestamp
* Subscriber information
* Linked subscription (if applicable)

## **Payment Details**

Click any transaction in the list to open its **Payment Details** page.\
This view provides a complete breakdown:

### **Transaction Summary**

* Payment ID
* Status
* Amount & currency
* Settlement amount (MoR model)
* Payment date
* Linked subscription (if applicable)

### **Payment Method Details**

* Card network & last four digits
* Issuer country (when available)
* Wallet method (Apple Pay / Google Pay / PayPal)
* PSP metadata for merchants using their own PSP

### **Customer Details**

* Subscriber ID
* Email or phone
* Country
* Billing details (MoR model only)

### **Product Cart**

Shows the exact plan or one-time item purchased, including quantity information.

### **Actions**

At the top of the page you can:

* **Issue a refund** (full or partial)
* **Download invoice** (MoR model)

## **Failed Payments**

For failed transactions, Zotlo displays:

* Error code from the payment provider
* Human-readable explanation
* Retry suggestions when applicable

Typical decline examples:

* `INSUFFICIENT_FUNDS`
* `EXPIRED_CARD`
* `SCA_REQUIRED`
* `DO_NOT_HONOR`

If the transaction is part of a subscription renewal, Zotlo automatically enters **dunning mode** and continues retry logic.

{% hint style="info" %}
You can track details of payments via [payments API endpoint](/integrating-zotlo/api-reference/payments-endpoints/get-payment-details) and also export transactions via [export API endpoints](/integrating-zotlo/api-reference/export-endpoints/payment-transactions-export).
{% endhint %}

## **Invoices (MoR Only)**

For merchants using Zotlo as **Merchant of Record**:

* Every successful charge automatically generates an invoice
* Invoices follow regional tax rules
* The download link is available on each transaction page
* Refunds automatically update the invoice with a credit note

## **What You Can Do**

* Track all charges and renewals
* Identify failed payments quickly
* Download invoices for accounting
* Review decline reasons and customer info
* Initiate refunds
* Inspect PSP transaction logs (PSP mode)


# Managing Subscriptions

The **Subscriptions** section lets you track all subscribers across your projects, review lifecycle states, manage cancellations, inspect billing history, and access payment logs in [Zotlo Dashboard](https://console.zotlo.com) or via [Zotlo API](/integrating-zotlo/api-reference/introduction). It provides a full operational view of every subscription and its events.

<div data-with-frame="true"><figure><img src="/files/MouLmsPTjJmkZEJPJoEd" alt="" width="563"><figcaption></figcaption></figure></div>

## **Subscriptions Overview**

Navigate to your project in **Zotlo Dashboard → Subscriptions** to view an aggregated list of all active, grace, and canceled subscriptions.

For each subscription, the list view shows:

* Subscriber ID
* Plan & billing interval
* Status
* Country
* Start & expire dates
* Latest renewal outcome
* Payment method

## **Subscription Details**

Click any subscriber to open the **Subscription Detail** page. The page includes three major sections:

### **Summary**

* Current **status** (active / grace / canceled)
* start\_date, expire\_date
* Next renewal attempt (if applicable)
* Currency & pricing info
* Trial information (if applicable)
* Linked payment method (card / wallet / PSP)

### **Transactions**

Shows all subscription events:

* Initial purchase
* Trial start & trial end
* Successful renewals
* Failed renewals
* Grace period transitions
* Cancellation events
* Reactivations

Each event links to its corresponding payment (if a payment exists).

### **Payment Logs**

A chronological log of all attempted, failed and successful charges, including:

* Retry attempts
* Error codes
* Timestamp of each attempt

This helps diagnose payment issues and involuntary churn.

## **Subscription States**

Each subscription has a **state** that reflects whether the subscriber is in a trial period or in a paid billing cycle. This is separate from the *status* (active, grace, canceled).

**Trial**\
The subscriber is currently in a trial period. This only indicates the phase of the subscription, not whether the subscription is active or passive.

**Paid**\
The subscriber is currently in a paid billing cycle. This also only reflects the billing phase and does not indicate subscription status.

{% hint style="info" %}
**Important Notes**

* A subscription transitions from **trial → paid only after the first renewal payment succeeds**
* State changes do not affect access behavior, your application determines how access is granted.
* State is always visible in subscription details and is included in webhook payloads.
  {% endhint %}

## **Subscription Statuses**

### **Active**

Subscription is fully valid. Next renewal is scheduled. This means the subscription is in a **paid** billing cycle with a successfully captured payment. The subscriber has full entitlement to the service.

### **Passive/Canceled**

Subscription has ended.

* No further renewals are attempted
* expire\_date remains unchanged
* Access rules depend on your app (you may allow or block access until expire\_date)

### **Grace**

Renewal has failed and the subscription is in the retry (dunning) period.

* Grace period lasts 30 days by default
* Retry schedule: **day 1, 2, 3, 5, 8, 13, 20, 30**
* If none succeed, status becomes **canceled**

{% hint style="info" %}
Your application decides whether **users have access during grace**.
{% endhint %}

## **Managing Subscriptions**

From the Subscription Detail page or via API, you can:

### **Cancel a Subscription**

Status becomes **canceled** immediately, but the user may continue to access the service until `expire_date`. Access rules are fully controlled by your application.

### **Pause a Subscription**

* Status becomes paused instantly
* No renewals occur while paused
* `expire_date` and existing paid time remain unchanged

### **Reactivate a Subscription**

A paused or canceled subscription can be reactivated **as long as expire\_date has not passed**:

* No immediate charge
* Status becomes active
* Renewal resumes at next scheduled cycle

## **Refund a Charge**

You can issue full or partial refunds. Refund actions include selecting the specific charge, choosing the refund amount, and submitting a reason for audit and reporting purposes.

## **Change Plans**

You can apply plan upgrades, downgrades, billing interval changes, or pricing adjustments to any active subscription. For detailed behavior and examples, see the [Plan Changes](/features/subscriptions/plan-changes))

{% hint style="info" %}
You can handle all subscription operations, cancellations, pauses, reactivations, and plan changes from the Dashboard or via the API.
{% endhint %}


# Refunds & Disputes

Zotlo allows you to manage refunds for any payment and provides clear visibility into dispute outcomes. Chargebacks do **not** appear as a live “dispute state” in the Dashboard, Zotlo updates the payment once the dispute is finalized by the bank or intercepted by a preventer service.

## **Refunds**

You can issue **full or partial refunds**. Refunds can be initiated from the **Payment Details** page, the **Subscription Details** page, or via the [**Refund API**](/integrating-zotlo/api-reference/payments-endpoints/refund-payment).

### **Refund behavior**

* Refunds are always processed using the **original transaction amount and currency**.
* A refund **does not modify** historical billing records.
* Partial refunds **do not cancel** subscriptions unless you explicitly cancel them.
* Refunding a renewal charge may cancel the subscription depending on the rules.

### **Access control after refund**

Refunds do **not automatically** change user access. Your app decides whether:

* Access continues until `expire_date`, or
* Access stops immediately after refund

## **Chargebacks (Disputes)**

### **How chargebacks appear**

Zotlo does not display a separate “dispute” status. Instead:

* If a chargeback is finalized by the bank, the payment is marked as **Refunded**.
* The refund reason shows one of the following:
  * **chargeback\_dispute** : The bank reversed the payment
  * **chargeback\_prevented** : A chargeback preventer service stopped the dispute before it reached the bank

This gives full transparency while keeping the interface clean and consistent.

### **Subscription impact**

* If a chargeback is finalized → the related subscription generally becomes **canceled**
* All access rules remain controlled by your application (`expire_date` vs immediate block)

## **Who Handles the Dispute?**

### **MoR Model**

When Zotlo is the **Merchant of Record**:

* Zotlo handles the entire dispute process with the bank/PSP
* Zotlo manages chargeback responses
* Zotlo updates payment status & reason after the dispute is resolved
* No action is required from the merchant

### **Connected PSP Mode**

When the merchant uses their **own PSP account**:

* Dispute handling is the merchant’s responsibility
* The PSP will notify the merchant directly


# Customer Portal

Zotlo provides a hosted **Customer Portal** [account.zotlo.com](https://account.zotlo.com) where end users can manage their purchases and subscriptions. Users can log in at **account.zotlo.com** using the email or phone number they used during checkout.

<div data-with-frame="true"><figure><img src="/files/n5naACHqLGHQx75qCtri" alt="" width="563"><figcaption><p>account.zotlo.com</p></figcaption></figure></div>

### **What Users Can Do?**

The Customer Portal allows users to:

* View all products and subscriptions purchased through Zotlo
* Download invoices
* Cancel or pause subscriptions
* Update their payment method (card updates, new card entry, etc.)
* Contact Zotlo Customer Support and submit refund or support requests

All features are available immediately for any purchase made via Zotlo.

### **Auto-Login Links**

If your app or platform already has authenticated users, you can generate **auto-login links** for the portal.\
This allows users to open **account.zotlo.com** without re-entering their email/phone, providing:

* Seamless app → portal navigation
* Faster access to subscription management
* A smoother experience for logged-in users

These auto-login links are commonly used by apps to ensure users can manage their subscriptions without a separate login step.


# Dashboard Analytics

Zotlo Dashboard includes a comprehensive analytics suite that helps you monitor your revenue, subscriber behavior, payment performance, and sales flow efficiency. All metrics update in real time and are grouped into three main areas: **Project Overview**, **Checkout & Flow Analytics**, and **Reporting Module**.

## **Project Overview**

The **Project Overview** page gives you a high-level snapshot of your business performance. You can track:

<div data-with-frame="true"><figure><img src="/files/ZbzKf4immaiFg0VztbPj" alt="" width="563"><figcaption></figcaption></figure></div>

### **Key Performance Metrics**

* **All Payments** – Total number of transactions
* **Gross Revenue** – Combined revenue from subscriptions, renewals, trials, one-time purchases, and e-pin sales
* **New Subscribers** – Newly activated subscriptions for the selected period
* **Recently Active Subscribers** – Returning active customers

### **Revenue & Activity Insights**

* **Daily New Purchases Graph** – Trends of new transactions day by day
* **Revenue Breakdown** – By event type: trials, subscription starts, renewals, one-time purchases, e-pins
* **Top Countries** – Geographic distribution of revenue and traffic
* **Top Products Sold** – Most purchased plans or items
* **Refund Trend** – Daily/weekly/monthly refund behavior
* **Churn Trend** – Subscription churn over time

### **Sales Performance**

See which sales interfaces generate the most revenue and conversions:

* **Embedded Checkout**
* **Checkout Links**
* **Quiz Funnel Links**

## **Checkout & Flow Analytics**

Every checkout link and quiz flow has its own **detailed analytics dashboard**, enabling precise optimization.

<div data-with-frame="true"><figure><img src="/files/D6HOACRhvYzt6lkrt8A7" alt="" width="563"><figcaption></figcaption></figure></div>

### **Core Metrics**

* **Daily Visits & Purchases**
* **Overall Conversion Rate**
* **New Revenue Generated**
* **Country Breakdown**
* **Device Breakdown** (mobile, desktop, tablet)
* **Language Breakdown**

### **Flow Funnel Analysis**

For quiz funnels, you can also view:

* Step-by-step drop-off
* Completion rate
* Result page performance
* Checkout start → purchase conversion

### **Payment Method Insights**

* Payment method distribution (cards, Apple Pay, Google Pay, PayPal, PSP methods)
* Success vs failure ratios
* Decline reasons

These insights help optimize pricing, design, and targeting for each sales interface.

## **Reporting Module**

The **Reporting Module** provides deeper, business-grade analyses with exportable reports.

<div align="center" data-with-frame="true"><figure><img src="/files/VhAXaU2kck989JjVFvUc" alt="" width="563"><figcaption></figcaption></figure></div>

### **Revenue Reports**

* **MRR & ARR Tracking**
* **Revenue by event type** (start, renewal, trial, one-time, e-pin)
* **Revenue by product, country, or payment method**

### **Subscription Analytics**

* **New Subscriptions**
* **Retention Reports**
* **Churn Reports**
* **Cohort Analysis** (based on start date or campaign)

### **Sales Reports**

* **One-Time Purchases**
* **E-Pin Sales**

### **Payment Health Reports**

* **Failed Payments Report**
* **Refund Report**

These reports help you understand your business performance at scale, monitor subscriber health, and refine your monetization strategies.


# Account Management

Zotlo Account Management helps you control your account/organization settings, manage team access, and configure financial information required for payouts and invoicing.

In this section, you can explore the following topics:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>⚙️</h3></td><td><h4><strong>Account Settings</strong></h4></td><td>Manage your organization-level configuration, update business details, and control global preferences for your Zotlo environment.</td><td><a href="/pages/2eA1aQhRxTOEngC83KRy">/pages/2eA1aQhRxTOEngC83KRy</a></td></tr><tr><td><h3>👥 </h3></td><td><h4><strong>Users &#x26; Access</strong></h4></td><td>Add team members, assign roles, and manage permissions to ensure secure and structured access to your Zotlo dashboard.</td><td><a href="/pages/NqHGh3Cue70A9zMZMXxX">/pages/NqHGh3Cue70A9zMZMXxX</a></td></tr><tr><td><h3>💰</h3></td><td><h4><strong>Financials</strong></h4></td><td>Set up payout information, manage billing details, and configure financial data required for merchant verification and payment processing.</td><td><a href="/pages/j0V8MQcEk3Ic4o0dII37">/pages/j0V8MQcEk3Ic4o0dII37</a></td></tr></tbody></table>


# Account Settings

The **Account Settings** section lets you manage your organization details, agreement status, payout settings, and platform-level configurations for your Zotlo account. These settings apply to your entire organization, not to individual projects.

## **Organization Settings**

This section displays the core details of your organization.\
You can update your organization name at any time. All other fields remain fixed for security and compliance purposes.

## **Merchant Agreement**

To go live and process real payments, you must complete the **Zotlo Merchant Agreement**. This is required for global compliance, risk management, and payout activation.

### **How It Works**

1. Open **Account Settings → Merchant Agreement**.
2. Click **Complete Enrollment**.
3. Upload the required identity and business verification documents.
4. Review and accept the agreement terms.
5. Submit your application.

After submission, your status becomes **In Review**. The Zotlo onboarding team will verify your documents and notify you once your account is approved.

{% hint style="info" %}
You cannot process live payments until the agreement is fully approved.
{% endhint %}

## **Payment Settings**

Your payout configuration depends on how you work with Zotlo:

#### **If using Zotlo’s payment infrastructure (MoR model)**

You must add your **bank account (IBAN)** to receive payouts from Zotlo.

#### **If using Connected PSP model**

You will add your **credit card** for Zotlo service charges instead of a bank account.

{% hint style="info" %}
The Payment Settings tab becomes available only after your merchant agreement is approved.
{% endhint %}


# Users & Access

The **Users & Access** section lets you manage team permissions across your Zotlo organization.\
You can invite teammates, assign roles, restrict access to specific projects, and update or remove users at any time.

Zotlo supports **organization-level** and **project-level** access control, allowing you to create a secure and collaborative workspace.

### **Inviting Users**

You can invite teammates in two ways:

#### **1. Organization-level invitation**

The user joins your entire organization and can be assigned roles across all projects.

#### **2. Project-level invitation**

The user is added only to selected projects and roles apply only to those projects.

After sending an invitation, you can update the user's role or remove access directly from the Users & Access page.

### **Roles & Permissions**

Zotlo includes five predefined roles.\
Each role defines which actions a user can perform across projects and account settings.

#### **Role Overview**

| Role              | Description                                                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Account Owner** | The owner of the Zotlo organization. Has full permissions. This role exists only for the account creator and cannot be changed.               |
| **Account Admin** | Has the same full permissions as the Account Owner. Can manage all projects, users, billing, and account-level settings.                      |
| **Project Admin** | Manages the projects they are assigned to. Can edit settings, checkout flows, products, subscriptions, and configurations for those projects. |
| **Operator**      | Performs operational tasks (e.g., refunding payments, managing subscriptions) for assigned projects, but cannot edit project configuration.   |
| **Reporter**      | Read-only access to financial reports and analytics for assigned projects. Cannot make changes.                                               |

### **Permission Matrix**

Below is a simplified permission model to help you understand what each role can do.

<table><thead><tr><th width="218.5625"></th><th width="103.8046875" data-type="checkbox">Account Owner</th><th width="103.74609375" data-type="checkbox">Account Admin</th><th width="100.95703125" data-type="checkbox">Project Admin</th><th width="106.484375" data-type="checkbox">Operator</th><th width="107.7109375" data-type="checkbox">Reporter</th></tr></thead><tbody><tr><td>Create/Delete Project</td><td>true</td><td>true</td><td>false</td><td>false</td><td>false</td></tr><tr><td>Manage Project</td><td>true</td><td>true</td><td>true</td><td>false</td><td>false</td></tr><tr><td>Manage Checkout</td><td>true</td><td>true</td><td>true</td><td>true</td><td>false</td></tr><tr><td>Manage Sales Flows</td><td>true</td><td>true</td><td>true</td><td>true</td><td>false</td></tr><tr><td>Manage Package Prices</td><td>true</td><td>true</td><td>true</td><td>false</td><td>false</td></tr><tr><td>View Traffic &#x26; Conversion Statistics</td><td>true</td><td>true</td><td>true</td><td>false</td><td>true</td></tr><tr><td>View Revenue Reports</td><td>true</td><td>true</td><td>true</td><td>false</td><td>false</td></tr><tr><td>Subscription Management</td><td>true</td><td>true</td><td>true</td><td>false</td><td>false</td></tr><tr><td>Refund</td><td>true</td><td>true</td><td>true</td><td>false</td><td>false</td></tr><tr><td>Financials/Billing</td><td>true</td><td>true</td><td>false</td><td>false</td><td>false</td></tr><tr><td>Account Management</td><td>true</td><td>true</td><td>false</td><td>false</td><td>false</td></tr></tbody></table>


# Financials

The **Financials** section (accessible under **Billing**) provides a complete view of your earnings, payouts, commissions, reserves, and financial activity.\
The content displayed depends on whether you are using the **Merchant of Record (MoR)** model or the **Connect Your PSP** model.

<div data-with-frame="true"><figure><img src="/files/2sk2q7X9pugzof3NYRkE" alt="" width="563"><figcaption></figcaption></figure></div>

## **If You Use Zotlo MoR**

When Zotlo processes payments and sends payouts, Financials displays:

#### **Current Balance**

Your real-time payable balance.

#### **Next Payout**

The amount scheduled for your upcoming payout.

#### **Refunds & Chargebacks**

Total refunds and chargebacks affecting the current payout period.

#### **Proceeds**

Monthly breakdown of:

* Gross sales
* Taxes
* Fees
* Net amount per project and per currency

#### **Payouts**

List of all payouts with:

* Status (Paid, Processing, Waiting)
* Coverage period
* Payout date
* Downloadable payout invoice

#### **Reserves (If Applied)**

If your account has a rolling reserve, you can view:

* Reserve total
* Release schedule

## **If You Connect Your PSP**

When payments are processed by your own PSP, Financials focuses on **sales reporting and Zotlo commission invoices**.

You will see:

#### **Current Balance**

Your current month’s commission amount.

#### **Monthly Sales Summary**

Overview of monthly processed volume and currencies.

#### **Payments (Commission Invoices)**

Monthly Zotlo service fees with:

* Status (Paid, Waiting, Failed)
* Invoice download

## **Summary**

* **MoR model:** You see payouts, proceeds, refunds, chargebacks, and reserve details.
* **Connect Your PSP model:** You see sales summaries and monthly commission invoices.
* All financial documents (invoices, payout reports) are downloadable.


# API Reference

Zotlo API enables you to manage subscriptions, payments, checkout, and reporting through secure, scalable, and developer-friendly endpoints.

With these APIs, you can build custom workflows, automate backend operations, and fully integrate Zotlo’s subscription and billing capabilities into your product.

In this section, you can explore the following topics:

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>🧩</h3></td><td><h4><strong>API Introduction</strong></h4></td><td>Start by reviewing the API fundamentals, authentication rules, required headers, and response structure before making your first request.</td><td></td><td><a href="/pages/hRv14lnehWLGK9pVgRui">/pages/hRv14lnehWLGK9pVgRui</a></td></tr><tr><td><h3>⚠️ </h3></td><td><h4><strong>Error Handling</strong></h4></td><td>Learn how Zotlo APIs return errors, how to interpret error codes, and how to build robust integrations using standardized error formats.</td><td></td><td><a href="/pages/AVEzT3GV6vkYi5qHQyW7">/pages/AVEzT3GV6vkYi5qHQyW7</a></td></tr><tr><td><h3>🛒</h3></td><td><h4><strong>Checkout Endpoints</strong></h4></td><td>Explore how to generate checkout links, personalize payment flows, and integrate Zotlo into your purchase funnel.</td><td></td><td><a href="/pages/ghtJs2tCuYTuV8BhopXD">/pages/ghtJs2tCuYTuV8BhopXD</a></td></tr><tr><td><h3>🔄</h3></td><td><h4><strong>Subscriptions Endpoints</strong></h4></td><td>Manage subscription lifecycles, including creation, status checks, plan changes, cancellations, and renewal logic.</td><td></td><td><a href="/pages/vTMFal3ukqOHcSIZkYih">/pages/vTMFal3ukqOHcSIZkYih</a></td></tr><tr><td><h3>💳</h3></td><td><h4><strong>Payments Endpoints</strong></h4></td><td>Retrieve payment details, track transaction history, and query billing records for both subscriptions and one-time purchases.</td><td></td><td><a href="/pages/pRGjMNc9Z7rVjBECLv7m">/pages/pRGjMNc9Z7rVjBECLv7m</a></td></tr><tr><td><h3>📊</h3></td><td><h4><strong>Export Endpoints</strong></h4></td><td>Use high-performance reporting APIs to export transactions, subscriptions, and refund records with cursor-based pagination.</td><td></td><td><a href="/pages/T8ayLRBSgcIdKrNV5Sug">/pages/T8ayLRBSgcIdKrNV5Sug</a></td></tr><tr><td><h3>🏷️</h3></td><td><h4>Packages  Details </h4></td><td>Returns package details such as pricing, features, and type (subscription or one-time).</td><td></td><td><a href="/pages/cGosQTGgSj1ebiN0dSOx">/pages/cGosQTGgSj1ebiN0dSOx</a></td></tr></tbody></table>


# Introduction

The Zotlo API allows you to manage subscriptions, payments, checkout links, and customer data programmatically.\
All endpoints follow a RESTful structure and return JSON responses.

This page provides the essential concepts you need before using any endpoint.

## **Environments**

Zotlo provides two environments:

<table><thead><tr><th width="213.29296875">Environment</th><th>Base URL</th></tr></thead><tbody><tr><td><strong>Live</strong></td><td><code>https://api.zotlo.com</code></td></tr></tbody></table>

Use Sandbox while building & testing your integration. Use Live only after your account is approved and activated.

## **Authentication**

Each API request must include your project’s credentials:

{% code overflow="wrap" %}

```js
AccessKey: YOUR_ACCESS_KEY
AccessSecret: YOUR_ACCESS_SECRET
ApplicationId: YOUR_APP_ID   (optional)
Language: en
```

{% endcode %}

* You can find these in **Dashboard → Developer Tools → API Keys**
* Never expose AccessKey or AccessSecret in client-side code
* ApplicationId is optional and used for analytics tagging

All API requests must be sent over HTTPS.

## **Request & Response Format**

* **Requests:** JSON payloads for POST/PUT, query parameters for GET
* **Responses:** All successes return **HTTP 200**
* Errors return **HTTP 400 or 500** with the following structure:

#### Error Response Format

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "abc123",
    "httpStatus": 400,
    "errorMessage": "Subscriber profile not found.",
    "errorCode": 400009
  },
  "result": []
}
```

{% endcode %}

## Error Fields

<table><thead><tr><th width="193.19921875">Field</th><th>Description</th></tr></thead><tbody><tr><td>requestId</td><td>Unique ID for debugging</td></tr><tr><td>httpStatus</td><td><code>400</code> or <code>500</code> for errors</td></tr><tr><td>errorMessage</td><td>Human-readable message (in the Language header you send)</td></tr><tr><td>errorCode</td><td>Zotlo-specific error code (<code>400008</code>, <code>400009</code>, etc.).</td></tr><tr><td>result</td><td>Empty or error-specific content.</td></tr></tbody></table>

## **Rate Limits**

Zotlo API uses standard rate limiting to ensure platform stability.\
If the limit is exceeded, the API returns **HTTP 429 – Too Many Requests**.

Recommended: add retry logic with exponential backoff.

## **Sandbox vs Live Behavior**

* Sandbox simulates full subscription & payment flow
* No real charges occur
* Webhooks work normally for integration testing
* Live mode requires **Agreement approval + Business verification**


# Error Handling

All Zotlo API endpoints use a unified error response format.\
Successful requests return **HTTP 200**, while failed requests return **HTTP 400** or **HTTP 500**.

## Failed Response Format

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "app2.domain-REQ-5e73a811d5d",
    "httpStatus": 400,
    "errorMessage": "Subscriber profile not found.",
    "errorCode": 400009
  },
  "result": []
}
```

{% endcode %}

## Failed Response Fields

<table><thead><tr><th width="193.19921875">Field</th><th>Description</th></tr></thead><tbody><tr><td>requestId</td><td>Unique request identifier generated by Zotlo.</td></tr><tr><td>httpStatus</td><td>HTTP status code (<code>400</code>,<code>500</code>).</td></tr><tr><td>errorMessage</td><td>Localized error message.</td></tr><tr><td>errorCode</td><td>Zotlo-specific error code (<code>400008</code>, <code>400009</code>, etc.).</td></tr><tr><td>result</td><td>Empty or error-specific content.</td></tr></tbody></table>

## **General Error Rules**

* All successful responses always return **HTTP 200**, even if business logic fails (e.g., subscription canceled).
* Technical failures return **HTTP 400** or **HTTP 500**.
* Error messages respect the `Language` header you send.
* Retry logic is recommended only for **500000** or network errors.

## Common Error Codes

<table><thead><tr><th width="193.19921875">Code</th><th>Meaning</th></tr></thead><tbody><tr><td>404001</td><td>Invalid endpoint</td></tr><tr><td>401002</td><td>Invalid AccessKey or AccessSecret</td></tr><tr><td>400008</td><td>Invalid subscriberId</td></tr><tr><td>400009</td><td>Subscriber profile not found</td></tr><tr><td>500000</td><td>Internal server error</td></tr></tbody></table>

{% hint style="info" %}
**Tip for Debugging**

Save the requestId value, our support team can use it to locate the exact log for any API call.
{% endhint %}


# Payment Error Codes

Zotlo standardizes all payment provider responses into a unified set of status and error codes.\
This ensures consistent behavior across different PSPs, easier debugging, and reliable handling of edge cases.

Each payment attempt returns one of the codes below.

## Success Code

<table><thead><tr><th width="174.828125">Code</th><th>Meaning</th></tr></thead><tbody><tr><td>S0000001</td><td>Payment completed successfully.</td></tr></tbody></table>

## Error Codes

Below is the full list of error codes returned by Zotlo.

{% hint style="info" %}
**Note:**

All error codes starting with E indicate a *recoverable* payment failure.

Codes starting with F indicate *fatal* failures where the user must contact support or retry later.
{% endhint %}

<table><thead><tr><th width="138.03125">Code</th><th>Meaning</th></tr></thead><tbody><tr><td>E0000000</td><td>There was an issue with the payment. Please try again later.</td></tr><tr><td>E0000050</td><td>There was an issue with the payment. Please try again later.</td></tr><tr><td>E0000001</td><td>The transaction was terminated before clicking the payment button.</td></tr><tr><td>E0000002</td><td>The transaction failed due to insufficient card limit.</td></tr><tr><td>E0000003</td><td>Security verification could not be completed successfully.</td></tr><tr><td>E0000004</td><td>The transaction failed. Please contact your bank.</td></tr><tr><td>E0000005</td><td>A technical error occurred. Please try again.</td></tr><tr><td>E0000006</td><td>The payment process was canceled by the user.</td></tr><tr><td>E0000007</td><td>Your card is not enabled for online transactions. Please contact your bank.</td></tr><tr><td>E0000008</td><td>The transaction failed due to security policies.</td></tr><tr><td>E0000009</td><td>Invalid card number was entered.</td></tr><tr><td>E0000010</td><td>Incorrect card expiration date.</td></tr><tr><td>E0000011</td><td>The user did not approve the transaction.</td></tr><tr><td>E0000012</td><td>Transaction could not be completed because the limit was exceeded.</td></tr><tr><td>E0000013</td><td>Payment could not be completed due to an incorrect amount.</td></tr><tr><td>E0000014</td><td>3DS security verification failed; subscription could not be activated.</td></tr><tr><td>E0000015</td><td>Payment was not approved by the bank.</td></tr><tr><td>E0000016</td><td>Payment was not approved by your bank. Please contact them.</td></tr><tr><td>E0000017</td><td>Incorrect CVV code.</td></tr><tr><td>E0000018</td><td>The card was not approved. Try another card.</td></tr><tr><td>E0000019</td><td>Your credit card has expired.</td></tr><tr><td>E0000020</td><td>Verification code entered incorrectly multiple times.</td></tr><tr><td>E0000021</td><td>A technical error occurred. Please try again.</td></tr><tr><td>E0000022</td><td>Your card is not supported by the current payment provider.</td></tr><tr><td>E0000023</td><td>The card was not approved. Try another card.</td></tr><tr><td>E0000024</td><td>Card expiration year incorrect.</td></tr><tr><td>E0000025</td><td>Card expiration month incorrect.</td></tr><tr><td>E0000026</td><td>Card expiration date incorrect.</td></tr><tr><td>E0000027</td><td>Unexpected regional transaction restrictions.</td></tr><tr><td>E0000028</td><td>Insufficient balance in wallet.</td></tr><tr><td>E0000029</td><td>The card was not approved. Try another card.</td></tr><tr><td>F0000000 – F0000010</td><td>Your transaction could not be completed. Please contact customer service.</td></tr></tbody></table>

<sup>*(All F-series codes share the same meaning.)*</sup>


# Packages Details Endpoint

This endpoint allows you to retrieve all defined details and properties for a package or packages configured in the Zotlo Panel. It includes information such as pricing, trial informations, limits, and other package settings.

The package can be of different types such as **`subscription`** or **`consumable` (one-time payment)**.

The service operates using the GET method.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:blue;"><code>GET</code></mark></h4></td></tr><tr><td>Standart URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/team/package
</code></pre></td></tr></tbody></table>

* To retrieve single package pricing:&#x20;

`GET team/package?packageId={packageId}`&#x20;

* To retrieve package pricing for a specific country:&#x20;

`GET team/package?packageId={packageId}&country={countryCode}`&#x20;

## **Sample Request**

{% code overflow="wrap" %}

```js
GET https://api.zotlo.com/v1/team/package HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** , **AccessSecret**  and  **ApplicationId** in the Zotlo Panel under **Developer Tools → API Keys**
{% endhint %}

## Successful Response

```json
{
    "meta": {
        "requestId": "192-168-1-137.eu-central-1.compute.internal-REQ-69ef7c2d0cc39",
        "httpStatus": 200
    },
    "result": {
        "packages": [
            {
                "id": 3589,
                "packageId": "test_12",
                "name": "TEST",
                "packageType": "subscription",
                "period": 1,
                "periodType": "month",
                "createDate": "2026-04-27 15:08:48",
                "trialPeriod": 7,
                "trialPeriodType": "day",
                "price": "6.00",
                "trialPrice": "2.00",
                "currency": "USD",
                "paypalStatus": 1,
                "status": 1,
                "providerId": 2223136,
                "description": "",
                "prices": [
                    {
                        "id": 165770,
                        "country": "AU",
                        "price": "8.35",
                        "currency": "AUD",
                        "trialPrice": "2.78",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165771,
                        "country": "HK",
                        "price": "47.05",
                        "currency": "HKD",
                        "trialPrice": "15.68",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165772,
                        "country": "IN",
                        "price": "564.83",
                        "currency": "INR",
                        "trialPrice": "188.28",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165773,
                        "country": "ID",
                        "price": "103950.00",
                        "currency": "IDR",
                        "trialPrice": "34650.00",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165774,
                        "country": "IL",
                        "price": "17.86",
                        "currency": "ILS",
                        "trialPrice": "5.95",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165775,
                        "country": "JP",
                        "price": "956.00",
                        "currency": "JPY",
                        "trialPrice": "319.00",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165776,
                        "country": "XK",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165777,
                        "country": "KW",
                        "price": "1.84",
                        "currency": "KWD",
                        "trialPrice": "0.61",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165778,
                        "country": "MY",
                        "price": "23.73",
                        "currency": "MYR",
                        "trialPrice": "7.91",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165779,
                        "country": "NZ",
                        "price": "10.14",
                        "currency": "NZD",
                        "trialPrice": "3.38",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165780,
                        "country": "PH",
                        "price": "364.44",
                        "currency": "PHP",
                        "trialPrice": "121.48",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165781,
                        "country": "QA",
                        "price": "21.95",
                        "currency": "QAR",
                        "trialPrice": "7.32",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165782,
                        "country": "SA",
                        "price": "22.51",
                        "currency": "SAR",
                        "trialPrice": "7.50",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165783,
                        "country": "KR",
                        "price": "8833.00",
                        "currency": "KRW",
                        "trialPrice": "2945.00",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165784,
                        "country": "TH",
                        "price": "194.01",
                        "currency": "THB",
                        "trialPrice": "64.67",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165785,
                        "country": "TR",
                        "price": "270.27",
                        "currency": "TRY",
                        "trialPrice": "90.09",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165786,
                        "country": "AE",
                        "price": "22.05",
                        "currency": "AED",
                        "trialPrice": "7.35",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165787,
                        "country": "VN",
                        "price": "158983.00",
                        "currency": "VND",
                        "trialPrice": "52995.00",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165788,
                        "country": "AT",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165789,
                        "country": "BE",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165790,
                        "country": "CY",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165791,
                        "country": "CZ",
                        "price": "124.46",
                        "currency": "CZK",
                        "trialPrice": "41.49",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165792,
                        "country": "DK",
                        "price": "38.19",
                        "currency": "DKK",
                        "trialPrice": "12.73",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165793,
                        "country": "EE",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165794,
                        "country": "FI",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165795,
                        "country": "FR",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165796,
                        "country": "DE",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165797,
                        "country": "GR",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165798,
                        "country": "HU",
                        "price": "1861.00",
                        "currency": "HUF",
                        "trialPrice": "621.00",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165799,
                        "country": "IE",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165800,
                        "country": "IT",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165801,
                        "country": "LV",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165802,
                        "country": "LT",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165803,
                        "country": "LU",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165804,
                        "country": "MT",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165805,
                        "country": "MC",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165806,
                        "country": "NL",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165807,
                        "country": "NO",
                        "price": "55.62",
                        "currency": "NOK",
                        "trialPrice": "18.54",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165808,
                        "country": "PL",
                        "price": "21.70",
                        "currency": "PLN",
                        "trialPrice": "7.23",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165809,
                        "country": "PT",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165810,
                        "country": "RO",
                        "price": "26.03",
                        "currency": "RON",
                        "trialPrice": "8.68",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165811,
                        "country": "RU",
                        "price": "449.93",
                        "currency": "RUB",
                        "trialPrice": "149.98",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165812,
                        "country": "SK",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165813,
                        "country": "SI",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165814,
                        "country": "ES",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165815,
                        "country": "SE",
                        "price": "55.22",
                        "currency": "SEK",
                        "trialPrice": "18.41",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165816,
                        "country": "CH",
                        "price": "4.70",
                        "currency": "CHF",
                        "trialPrice": "1.57",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165817,
                        "country": "UA",
                        "price": "264.84",
                        "currency": "UAH",
                        "trialPrice": "88.28",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165818,
                        "country": "GB",
                        "price": "4.43",
                        "currency": "GBP",
                        "trialPrice": "1.48",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165819,
                        "country": "VA",
                        "price": "5.11",
                        "currency": "EUR",
                        "trialPrice": "1.70",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165820,
                        "country": "EG",
                        "price": "315.44",
                        "currency": "EGP",
                        "trialPrice": "105.15",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165821,
                        "country": "ZA",
                        "price": "99.03",
                        "currency": "ZAR",
                        "trialPrice": "33.01",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165822,
                        "country": "AR",
                        "price": "8472.41",
                        "currency": "ARS",
                        "trialPrice": "2824.14",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165823,
                        "country": "BR",
                        "price": "29.95",
                        "currency": "BRL",
                        "trialPrice": "9.98",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165824,
                        "country": "CA",
                        "price": "8.16",
                        "currency": "CAD",
                        "trialPrice": "2.72",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165825,
                        "country": "CL",
                        "price": "5363.00",
                        "currency": "CLP",
                        "trialPrice": "1788.00",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165826,
                        "country": "CO",
                        "price": "21450.00",
                        "currency": "COP",
                        "trialPrice": "7150.00",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165827,
                        "country": "MX",
                        "price": "104.21",
                        "currency": "MXN",
                        "trialPrice": "34.74",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    },
                    {
                        "id": 165828,
                        "country": "PE",
                        "price": "20.95",
                        "currency": "PEN",
                        "trialPrice": "6.98",
                        "startDate": "2026-04-27 15:08:49",
                        "providerId": 2223136,
                        "period": 1,
                        "periodType": "month",
                        "trialPeriod": 7,
                        "createDate": "2026-04-27 15:08:49",
                        "paypalStatus": 1,
                        "trialPeriodType": "day",
                        "priceText": "",
                        "trialPriceText": "",
                        "endDate": null,
                        "status": 1
                    }
                ],
                "localizations": []
            }
        ]
    }
}
```

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# Checkout Endpoints

Zotlo API allows you to generate a **personalized checkout link** based on an existing checkout link created in the Zotlo Dashboard. You can customize the visual content (images & text), pricing (for one-time payments), and additional metadata to create a user-specific checkout flow.

Use this endpoint to run targeted campaigns, pass user attributes, app-2-web scenarios or integrate marketing parameters (MMPs, tracking IDs, Adjust/Appsflyer data, etc.).

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>🔗</h3></td><td><h4><strong>Checkout Link API</strong></h4></td><td>Learn how Zotlo APIs generate personalized checkout link, how to customized pricing and style.</td><td><a href="/pages/ghtJs2tCuYTuV8BhopXD">/pages/ghtJs2tCuYTuV8BhopXD</a></td></tr><tr><td><h3>🧩 </h3></td><td><h4><strong>API Overview</strong></h4></td><td>Explore the API fundamentals, authentication rules, required headers, and response structure before making your first request.</td><td><a href="/pages/hRv14lnehWLGK9pVgRui">/pages/hRv14lnehWLGK9pVgRui</a></td></tr></tbody></table>


# Generate Personalized Link

This endpoint allows you to generate a **personalized checkout link** based on an existing checkout link created in the Zotlo Dashboard. You can customize the visual content (images & text), pricing (for one-time payments), and additional metadata to create a user-specific checkout flow.

Use this endpoint to run targeted campaigns, pass user attributes, app-2-web scenarios or integrate marketing parameters (MMPs, tracking IDs, Adjust/Appsflyer data, etc.).

The service operates using the **POST** method.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:blue;"><code>POST</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v2/app-to-web/one-link
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="189.25390625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>applicationKey</code></td><td>Required</td><td>The unique key provided for your project. Available under Zotlo Dashboard → Developer Tools → Checkout SDK.</td></tr><tr><td><code>checkoutLinkId</code></td><td>Required</td><td>ID of the checkout link to be customized. A checkout link must first be created in the Zotlo Dashboard.</td></tr><tr><td><code>subscriberIpAddress</code></td><td>Required</td><td>IP address of the user. When country-based pricing  rules are enabled, Zotlo uses this IP as a signal to determine the appropriate price and currency on the checkout page.</td></tr><tr><td><code>language</code></td><td>Required</td><td>Checkout language (e.g., <code>EN</code>, <code>TR</code>).</td></tr><tr><td><code>subscriberId</code></td><td>Optional</td><td>The email or phone number of the user.</td></tr><tr><td><code>productImage</code></td><td>Optional</td><td>Custom product image URL.</td></tr><tr><td><code>additionalText</code></td><td>Optional</td><td>Additional text displayed on checkout.</td></tr><tr><td><code>packageName</code></td><td>Optional</td><td>Custom display name of the package.</td></tr><tr><td><code>customPrice</code></td><td>Optional</td><td>Custom price for one-time purchases.</td></tr><tr><td><code>customCurrency</code></td><td>Optional</td><td>Currency for custom pricing.</td></tr><tr><td><code>customParameters</code></td><td>Optional</td><td>Additional metadata (MMP parameters, tracking IDs).</td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
POST https://api.zotlo.com/v2/app-to-web/one-link HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: en

{
  "applicationKey": "989e9bc1fbbbc1b82e18548c4577ed3f24c9dc39cc416db5",
  "subscriberId": "",
  "subscriberIpAddress": "37.24.56.13",
  "language": "en",
  "productImage": "",
  "additionalText": "Zotlo Test",
  "checkoutLinkId": "123",
  "packageName": "Package Name Test",
  "customPrice": "",
  "customCurrency": "",
  "customParameters": {
    "mmp": {
      "appsflyer_id": "id6446176688"
    }
  }
}
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
    "meta": {
        "requestId": "68b5fbdd6f-hpwjc-REQ-683dbb1c4c569",
        "httpStatus": 200
    },
    "result": {
        "oneLink": "https://checkout.zotlo.com/payment/6e7ac760800a071338d6b81b9dc65b9ffbbdd18de17e4cb9a1"
    }
}
```

{% endcode %}

## Key **Response Fields**

<table><thead><tr><th width="193.19921875">Field</th><th>Description</th></tr></thead><tbody><tr><td>onelink</td><td>Personalized link to share</td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# Subscriptions Endpoints

Zotlo’s Subscription API gives you full control over the lifecycle of your subscribers.\
You can retrieve real-time subscription status, cancel active plans, upgrade or downgrade packages, and manage quantity-based pricing, all through simple REST endpoints.

Use these endpoints to keep your billing system aligned, automate subscription workflows, or synchronize user access across your web and mobile applications.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>🔔</h3></td><td><strong>Get Subscription Status</strong></td><td>Retrieve the most recent status, lifecycle dates, package details, and entitlement-related metadata of any subscriber.</td><td><a href="/pages/6d4ZshQuIdxfieCTMAZP">/pages/6d4ZshQuIdxfieCTMAZP</a></td></tr><tr><td><h3>🛑 </h3></td><td><strong>Cancel Subscription</strong></td><td>Cancel an active subscription immediately or at the end of the billing cycle based on your logic.</td><td><a href="/pages/jUd35oojoajE15PEZlLl">/pages/jUd35oojoajE15PEZlLl</a></td></tr><tr><td><h3>🔄</h3></td><td><strong>Change Plan</strong></td><td>Upgrade or downgrade a subscriber’s plan with full support for prorated upgrades, billing cycle continuity, and flexible migration rules.</td><td><a href="/pages/9EczLg9GDvjKL1UOIwql">/pages/9EczLg9GDvjKL1UOIwql</a></td></tr><tr><td><h3>📈</h3></td><td><strong>Update Quantity</strong></td><td>Adjust the billable quantity for seat-based or usage-based subscription models, including instant increases or scheduled decreases.</td><td><a href="/pages/oyiZfWj7nRaNYxbKP2Pg">/pages/oyiZfWj7nRaNYxbKP2Pg</a></td></tr></tbody></table>


# Get Subscription Status

This endpoint returns the most recent status of a subscription managed by Zotlo.

Use the **GET** method to query a subscriber. Both **subscriberId** and **packageId** parameters are required to retrieve the correct subscription record.

The response includes the subscription’s state, status, lifecycle dates, and related metadata.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:green;background-color:$primary;"><code>GET</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/subscription/profile?subscriberId=SUBSCRIBER_ID&#x26;packageId=PACKAGE_ID&#x26;isSandbox=true|false
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="176.16015625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscriberId</code></td><td>Required</td><td>The email or phone number the user provided when starting the subscription.</td></tr><tr><td><code>packageId</code></td><td>Required</td><td>The ID of the package to query. A successful response is returned only if the user has a subscription for this package.</td></tr><tr><td><code>isSandbox</code></td><td>Required</td><td><p>Indicates whether the subscription was created in sandbox or live mode.Send:</p><ul><li><strong>true</strong> → sandbox</li><li><strong>false</strong> → live</li></ul></td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
GET https://api.zotlo.com/v1/subscription/profile?subscriberId=SUB_ID&packageId=PACKAGE_ID HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: en
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

### **Active Subscription**

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "6d2989e84793-REQ-5f32a82e299ff",
    "httpStatus": 200
  },
  "result": {
    "profile": {
      "status": "active",
      "realStatus": "active",
      "subscriberId": "test@mail.com",
      "subscriptionType": "paid",
      "startDate": "2020-08-10 21:57:25",
      "expireDate": "2020-09-09 21:57:25",
      "package": "zotlo-premium",
      "country": "TR",
      "phoneNumber": "+905555555555",
      "language": "tr",
      "originalTransactionId": "80397a95-742d-4c74-975e-f740d1909580",
      "cancellation": null,
      "customParameters": {
        "source": "Landing",
        "adjust": {
          "idfa": "A161AD92-7DC3-4B15-B14C-3AA65995AFCC"
        }
      },
      "renewalFetchCount": 0
    },
    "package": {
      "packageId": "zotlo-premium",
      "price": 3.99,
      "currency": "USD",
      "packageType": "subscription",
      "name": "Zotlo Premium"
    },
    "newPackage": null,
    "card": {
      "cardNumber": "411111******1111",
      "expireDate": "12/20"
    },
    "customer": {
      "id": 1,
      "createDate": "2020-05-13 12:57:36",
      "country": "TR",
      "firstname": "Test",
      "lastname": "Test",
      "email": "test@test.com"
    }
  }
}
```

{% endcode %}

### **Canceled Subscription**

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "6d2989e84793-REQ-5f32a89037084",
    "httpStatus": 200
  },
  "result": {
    "profile": {
      "status": "active",
      "realStatus": "passive",
      "subscriberId": "313334342",
      "subscriptionType": "paid",
      "startDate": "2020-08-07 06:44:16",
      "expireDate": "2020-09-06 06:44:16",
      "package": "zotlo-premium",
      "country": "TR",
      "phoneNumber": "+905555555555",
      "language": "tr",
      "originalTransactionId": "51e8fd2a-5b28-4b9f-bfe3-5f752b09d3a3",
      "cancellation": {
        "date": "2020-08-07 06:46:00",
        "reason": "Not Interest",
        "code": "CU00001"
      },
      "customParameters": {
        "source": "Landing"
      }
    },
    "package": {
      "packageId": "zotlo-premium",
      "price": 2.99,
      "currency": "USD",
      "packageType": "subscription",
      "name": "Zotlo Premium"
    },
    "newPackage": null,
    "card": {
      "cardNumber": "411111******1111",
      "expireDate": "12/20"
    },
    "customer": {
      "id": 1,
      "createDate": "2020-05-13 12:57:36",
      "country": "TR",
      "firstname": "Test",
      "lastname": "Test",
      "email": "test@test.com"
    }
  }
}
```

{% endcode %}

## Key **Response Fields**

### **Subscription Fields**

<table><thead><tr><th width="193.19921875">Field</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>high-level subscription status delivered to your app. <code>active</code>, <code>grace</code>, <code>passive</code>.</td></tr><tr><td>realStatus</td><td>the system’s true internal status. Returns <code>passive</code> immediately after cancellation even if <code>status</code> remains <code>active</code> until expire_date.</td></tr><tr><td>subscriptionType</td><td><code>trial</code> (still in trial) or <code>paid</code> (charged at least once).</td></tr><tr><td>startDate</td><td>Subscription start date.</td></tr><tr><td>expireDate</td><td>Current billing end date.</td></tr><tr><td>package</td><td>Active package ID.</td></tr><tr><td>country</td><td>Subscriber’s country.</td></tr><tr><td>language</td><td>Subscriber’s language.</td></tr><tr><td>cancellation</td><td>Cancellation details if the user or system canceled the subscription. <code>null</code>if not canceled.</td></tr></tbody></table>

### Cancellation Details

<table><thead><tr><th width="193.19921875">Field</th><th>Description</th></tr></thead><tbody><tr><td>date</td><td>Cancellation timestamp.</td></tr><tr><td>reason</td><td>Reason text for cancellation.</td></tr><tr><td>code</td><td>Cancellation code (<code>CP00001</code>, <code>CU00001</code>, <code>CU00002</code>).</td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# Cancel Subscription

This endpoint to cancels a subscriber's active subscription. You can either cancel **at the end of the current billing period** or **immediately**, depending on the `force` parameter.

Use the **POST** method to query a subscriber. Both **subscriberId** and **packageId** parameters are required to retrieve the correct subscription record.

The response includes the subscription’s state, status, lifecycle dates, and related metadata.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:blue;"><code>POST</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/subscription/cancellation
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="176.16015625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscriberId</code></td><td>Required</td><td>The email or phone number the user provided when starting the subscription.</td></tr><tr><td><code>packageId</code></td><td>Required</td><td>The ID of the current active package. A successful response is returned only if the user has a subscription for this package.</td></tr><tr><td><code>cancellationReason</code></td><td>Required</td><td>Free-text reason for the subscription cancellation. Shown in the profile under <code>cancellation.reason</code>.</td></tr><tr><td><code>force</code> </td><td>Optional</td><td><p>Controls when the cancellation takes effect:</p><ul><li><code>1</code> → The subscription is terminated immediately.</li><li>any other value or omitted → The subscriber can continue using the service until the end of the current billing period.</li></ul></td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
POST https://api.zotlo.com/v1/subscription/cancellation HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: en

{
  "subscriberId": "test@mail.com",
  "cancellationReason": "Not Interest",
  "force": 0,
  "packageId": "zotlo-premium"
}
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "6d2989e84793-REQ-5f32a93a80310",
    "httpStatus": 200
  },
  "result": {
    "profile": {
      "status": "active",
      "realStatus": "passive",
      "subscriberId": "test@mail.com",
      "subscriptionType": "paid",
      "startDate": "2020-08-10 21:57:25",
      "expireDate": "2020-09-09 21:57:25",
      "package": "zotlo-premium",
      "country": "TR",
      "phoneNumber": "+905555555555",
      "language": "tr",
      "originalTransactionId": "80397a95-742d-4c74-975e-f740d1909580",
      "cancellation": {
        "date": "2020-08-11 14:20:42",
        "reason": "Not Interest",
        "code": "CU00001"
      },
      "customParameters": {
        "source": "Landing"
      }
    },
    "package": {
      "packageId": "zotlo-premium",
      "price": 3.99,
      "currency": "USD",
      "packageType": "subscription",
      "name": "Zotlo Premium"
    },
    "newPackage": null,
    "card": {
      "cardNumber": "411111******1111",
      "expireDate": "12/20"
    },
    "customer": {
      "id": 1,
      "createDate": "2020-05-13 12:57:36",
      "country": "TR",
      "firstname": "Test",
      "lastname": "Test",
      "email": "test@test.com"
    }
  }
}
```

{% endcode %}

## Key **Response Fields**

<table><thead><tr><th width="205.5546875">Field</th><th>Description</th></tr></thead><tbody><tr><td>profile.status</td><td>high-level subscription status delivered to your app. <code>active</code>, <code>grace</code>, High-level status of the subscription (<code>active</code>, <code>grace</code>, <code>passive</code>).</td></tr><tr><td>profile.realStatus</td><td><p>Internal status that immediately reflects cancellation.</p><ul><li><code>passive</code> → subscription is considered canceled by Zotlo, even if <code>status</code> may stay <code>active</code> until <code>expireDate</code> in some legacy flows.</li></ul></td></tr><tr><td>profile.subscriptionType</td><td><code>trial</code> → subscription is in trial period<br><code>paid</code> → subscription has been charged at least once</td></tr><tr><td>startDate / expireDate</td><td>Subscription start and current period end dates.</td></tr><tr><td>cancellation</td><td><p>Contains details if the subscription was canceled:</p><ul><li><code>cancellation.date</code> – cancellation timestamp</li><li><code>cancellation.reason</code> – human-readable reason</li><li><code>cancellation.code</code> – cancellation code (<code>CP00001</code>, <code>CU00001</code>, <code>CU00002</code>, etc.)</li></ul></td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# Change Plan

This endpoint allows you to replace a subscriber’s current package with a new one (upgrade or downgrade). Plan transitions follow Zotlo’s billing logic, including prorated upgrades, cycle preservation options, and deferred downgrades.

The service operates using the **POST** method.

## **How Plan Changes Work**

### **Upgrade**

When switching to a more expensive plan, Zotlo processes the change based on the **saveCycle** parameter.

**If `saveCycle = true` (Keep Billing Cycle)**

* The current billing cycle **does not change,** `expireDate`  **remains the same**.
* The unused portion of the current plan is **credited**.
* The user pays **only the price difference**.
* The new plan becomes active immediately **after a successful charge**.
* If the charge fails → upgrade does **not** happen; current plan continues.

**If `saveCycle = false` (Start New Cycle)**

* The current billing cycle is **terminated immediately**.
* The unused amount is **credited** to the new plan.
* A **full charge** for the new plan is attempted instantly.
* A **new billing cycle starts immediately** with a new expire date.
* If the charge fails → upgrade does **not** occur; the current plan continues unchanged.

{% hint style="info" %}
**Note:** Choosing `saveCycle = false` is ideal when you want users to “reset” into a new full cycle.
{% endhint %}

### **Downgrade**

When switching to a cheaper plan:

* The change **never happens immediately**.
* The new plan activates **at the next renewal**.
* The current billing cycle continues uninterrupted.
* **expireDate does not change**.
* No proration or credit calculation applies.

{% hint style="info" %}
**Note:** `saveCycle` is ignored for downgrades because downgrades always activate at the next renewal.
{% endhint %}

You can learn more about plan changes [👉 here](/features/subscriptions/plan-changes)

{% hint style="info" %}
**Currency Matching Rule**

The new plan must use the same currency defined for the subscriber’s country. Example: A subscriber using USD in the USA can only switch to another USD plan.
{% endhint %}

### Discount Behavior on Plan Change

* The **unused value of remaining days** is always calculated based on the **actual amount paid by the customer**. If the current subscription includes a discount, the discounted price is used.
* `keepDiscount` parameter can be used to **preserve the existing discount** during an upgrade or downgrade.
  * `true` → current discount continues if the target plan supports it.
* To apply a **different discount**, send `discountCode` .\
  If a new discount is provided, the **existing discount is overridden** (only one discount can be active).
* **Discount cycles (redemption count)** increase **only on renewal**, not during plan changes.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:blue;"><code>POST</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/payment/change-package
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="189.7109375">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscriberId</code></td><td>Required</td><td>The email or phone number the user provided when starting the subscription.</td></tr><tr><td><code>packageId</code></td><td>Required</td><td>The ID of the current active package. A successful response is returned only if the user has a subscription for this package.</td></tr><tr><td><code>newPackageId</code></td><td>Required</td><td>Package ID to switch to</td></tr><tr><td><code>changeType</code> </td><td>Required</td><td><code>upgrade</code> or <code>downgrade</code></td></tr><tr><td><code>saveCycle</code></td><td>Required</td><td><p>true → Upgrade with cycle continuity</p><p>false → Upgrade with a new billing cycle</p><p><sub><em>(This parameter has</em><em> </em><em><strong>no effect</strong></em><em> </em><em>for downgrades)</em></sub></p></td></tr><tr><td>keepDiscount</td><td>Optional</td><td><p>Indicates whether the current discount should be preserved during the plan change.</p><ul><li><code>true</code> → The existing discount is kept if the target plan supports it.</li><li><code>false</code> → The existing discount is not preserved.</li></ul></td></tr><tr><td>discountCode</td><td>Optional</td><td>The code of the discount to apply during the plan change (e.g., <code>NEWYEAR26</code>). If provided, the existing discount (if any) will be overridden.</td></tr><tr><td><code>subscriberIpAddress</code></td><td>Required</td><td>Subscriber’s IP address</td></tr><tr><td><code>redirectUrl</code></td><td>Optional</td><td>Required for 3DS flows, user is redirected here after authentication</td></tr><tr><td><code>platform</code></td><td>Optional</td><td>Example: <code>web</code>, <code>ios</code>, <code>android</code></td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
POST https://api.zotlo.com/v1/payment/change-package HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••

{
  "platform": "web",
  "subscriberId": "Z113322",
  "subscriberIpAddress": "212.154.57.216",
  "redirectUrl": "https://example.com",
  "changeType": "upgrade",
  "packageId": "zotlo.premium",
  "newPackageId": "zotlo.business",
  "saveCycle": "false", 
  "keepDiscount": "false"
}
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
    "meta": {
        "requestId": "6d2989e84793-REQ-5f32ad6851343",
        "httpStatus": 200
    },
    "result": {
        "profile": {
            "status": "active",
            "realStatus": "active",
            "subscriberId": "test@mail.com",
            "subscriptionId": 20338,
            "subscriptionType": "trial",
            "startDate": "2026-03-12 13:44:12",
            "expireDate": "2026-03-19 13:44:12",
            "renewalDate": "2026-03-19 13:44:12",
            "package": "package_1",
            "country": "US",
            "phoneNumber": null,
            "language": "en",
            "originalTransactionId": "ffad490c-6681-5c76-f63000cafc46",
            "lastTransactionId": "ffad490c-6681-5c178-f63000cafc46",
            "subscriptionPackageType": "single",
            "cancellation": null,
            "customParameters": {
                "saveCycle": true,
                "subscriberIpAddress": "111111"
            },
            "quantity": 1,
            "pendingQuantity": 0,
            "renewalFetchCount": 0,
            "freezeEndDate": null
        },
        "package": {
            "packageId": "package_1",
            "price": 0,
            "currency": "USD",
            "packageType": "subscription",
            "name": "package_1",
            "subscriptionPackageType": "single",
            "bundlePackages": [],
            "discount": {
                "code": "DISC75NOTRIAL",
                "type": "rate",
                "appliedRate": 75,
                "appliedAmount": "9.6699999999999999289 USD"
            }
        },
        "customer": null,
        "newPackage": null,
        "card": {
            "cardNumber": "42424242****4242",
            "expireDate": "12/30",
        },
        "response": {
            "isSuccess": true,
            "transactionId": "ffad490c-61-5c76-a178-f63000cafc46",
            "providerTransactionId": "pi_3TA9WwCbenXbI1ZL1CrILgpO",
            "customTransactionId": "",
            "statusCode": "S0000001",
            "statusMessage": "Ödeme işlemi başarıyla tamamlandı.",
            "paymentDate": "2026-03-12 01:44:08",
            "providerStatus": "Captured",
            "paymentStatus": "COMPLETE",
            "redirectUrl": null,
            "packageId": "package_1",
            "providerPaymentMethod": null,
            "networkDeclineCode": null,
            "networkDeclineMessage": null
        },
        "redirect": null,
        "paymentStatus": "COMPLETE",
        "paymentHash": "83f89c204fef73a34e4a04eb38f06f477f0",
        "oldOriginalTransactionId": "95271196-8438-d7637a100802"
    }
}
```

{% endcode %}

## Key **Response Fields**

<table><thead><tr><th width="205.5546875">Field</th><th>Description</th></tr></thead><tbody><tr><td>profile</td><td>Updated subscription profile after the change</td></tr><tr><td>package</td><td>Details of the new package and discount</td></tr><tr><td>response.isSuccess</td><td>Indicates whether any required payment was successful</td></tr><tr><td>card</td><td>Card information used for upgrade </td></tr><tr><td>expireDate</td><td>Updated expire date (only changes for successful upgrades)</td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))

##


# Update Quantity

This endpoint allows merchants to update the billable **quantity** associated with a subscriber’s active package.&#x20;

It is designed for **seat-based**, **license-based**, and similar pricing models where the total charge equals: *unit price × quantity***.**

Use the **POST** method with this endpoint.

## **How Quantity Changes Work**

### **Increasing Quantity (Upgrade)**

If the new quantity is **higher** than the current one:

* An **additional charge** is attempted for the difference
* If the charge succeeds → **quantity updates immediately**
* If it fails → no change is applied

### **Decreasing Quantity (Downgrade)**

If the new quantity is **lower** than the current one:

* Change is **not applied immediately**
* The updated quantity becomes active on the **next renewal**
* Until then, the current quantity continues to be billed

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:blue;"><code>POST</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/subscription/change-quantity
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="157.69921875">Field</th><th width="162.7421875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscriberId</code></td><td>Required</td><td>The email or phone number the user provided when starting the subscription.</td></tr><tr><td><code>packageId</code></td><td>Required</td><td>The ID of the current active package. A successful response is returned only if the user has a subscription for this package.</td></tr><tr><td><code>quantity</code></td><td>Required</td><td>The new quantity value. Must be <strong>≥ 1</strong></td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
POST https://api.zotlo.com/v1/subscription/change-quantity HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••

{
    "subscriberId": "test@mail.com",
    "packageId": "zotlo.premium",
    "quantity": 2
}
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response <a href="#successful-response-example" id="successful-response-example"></a>

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "6d2989e84793-REQ-5f354e9240c23",
    "httpStatus": 200
  },
  "result": {
    "profile": {
      "status": "active",
      "realStatus": "active",
      "subscriberId": "905555555555",
      "subscriptionType": "paid",
      "startDate": "2020-07-27 11:56:16",
      "expireDate": "2020-10-25 11:56:16",
      "package": "zotlo.premium",
      "country": "TR",
      "phoneNumber": "+905555555555",
      "language": "tr",
      "originalTransactionId": "5a4d2db2-7be8-41e7-a6c8-63870762974b",
      "cancellation": null,
      "customParameters": null,
      "quantity": 19,
      "pendingQuantity": 17
    },
    "package": {
      "packageId": "zotlo.premium",
      "price": 49,
      "currency": "USD",
      "packageType": "subscription",
      "name": "Zotlo Premium"
    },
    "customer": {
      "id": 7,
      "createDate": "2020-05-19 08:54:07",
      "country": "TR",
      "firstname": "Test",
      "lastname": "User",
      "email": "test@zotlo.com"
    }
  }
}
```

{% endcode %}

## Key **Response Fields** <a href="#key-response-fields" id="key-response-fields"></a>

<table data-header-hidden><thead><tr><th width="188.1640625">Field</th><th>Description</th></tr></thead><tbody><tr><td>status</td><td>The subscriber’s <em>operational</em> status (<code>active</code>, <code>grace</code>, <code>passive</code>).</td></tr><tr><td>realStatus</td><td>The <em>true</em> cancellation state. If a subscription is canceled (customer-initiated, merchant-initiated, or system-initiated), <strong>realStatus = passive immediately</strong>, even if <code>status</code> remains <code>active</code> until expire_date.</td></tr><tr><td>subscriptionType</td><td>Subscription period type: <code>trial</code> or <code>paid</code>.</td></tr><tr><td>startDate</td><td>Subscription start date.</td></tr><tr><td>expireDate</td><td>The end of the current billing cycle.</td></tr><tr><td>package</td><td>The package ID of the currently active package.</td></tr><tr><td>quantity</td><td>Represents the currently active and billable quantity for the package.</td></tr><tr><td>pendingQuantity</td><td>The new quantity that will apply at next renewal (only appears when decreasing quantity).</td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# Apply Discount

This endpoint allows you to apply a previously created discount to an existing subscriber's active subscription.

{% hint style="success" %}
Before using this endpoint, create a discount in the **Zotlo Panel** under **Catalog > Discounts**. Once the discount has been created, it can be applied to an eligible subscriber's active subscription through this API.
{% endhint %}

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:blue;"><code>POST</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v2/subscription/add-discount
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="176.16015625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscriberId</code></td><td>Required</td><td>The email, phone number the user provided when starting the subscription.</td></tr><tr><td><code>discountCode</code></td><td>Required</td><td>The ID of the current active package. A successful response is returned only if the user has a subscription for this package.</td></tr><tr><td><code>packageId</code></td><td>Required</td><td>The ID of the subscription package to which the discount will be applied. The subscriber must have an active subscription to this package</td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
POST https://api.zotlo.com/v1/subscription/cancellation HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: en

{
  "subscriberId": "test@mail.com",
  "packageId": "test_1234",
  "discountCode": "FRIDAY20"
}
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
    "meta": {
        "requestId": "192-168-1-115.eu-central-1.compute.internal-REQ-6a5dd47879845",
        "httpStatus": 200
    },
    "result": {
        "message": "Discount applied successfully"
    }
}
```

{% endcode %}

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# Remove Discount

This endpoint allows you to remove an applied discount from an existing subscriber's active subscription.

Use this endpoint to remove a previously applied discount from an eligible subscriber's active subscription.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:blue;"><code>POST</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v2/subscription/remove-discount
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="176.16015625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscriberId</code></td><td>Required</td><td>The email, phone number the user provided when starting the subscription.</td></tr><tr><td><code>discountCode</code></td><td>Required</td><td>The ID of the current active package. A successful response is returned only if the user has a subscription for this package.</td></tr><tr><td><code>packageId</code></td><td>Required</td><td>The ID of the su</td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
POST https://api.zotlo.com/v1/subscription/cancellation HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: en

{
  "subscriberId": "test@mail.com",
  "packageId": "test_1234",
  "discountCode": "FRIDAY20"
}
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
    "meta": {
        "requestId": "192-168-1-107.eu-central-1.compute.internal-REQ-6a5dd5b1a3abd",
        "httpStatus": 200
    },
    "result": {
        "message": "Discount removed successfully"
    }
}
```

{% endcode %}

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# Payments Endpoints

Zotlo’s Payment API lets you access and manage every part of the payment lifecycle.\
You can retrieve detailed transaction data, issue refunds programmatically, and fetch a user’s complete payment history, including both subscription and one-time purchases.

Explore the payment endpoints:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>🧾</h3></td><td><h4><strong>Get Payment Details</strong></h4></td><td>Fetch full transaction information, including provider response, metadata, payment method, subscription linkage, and logs.</td><td><a href="/pages/cXewNvlVYIY6hmMtfq6x">/pages/cXewNvlVYIY6hmMtfq6x</a></td></tr><tr><td><h3>↩️ </h3></td><td><h4><strong>Refund Payment</strong></h4></td><td>Initiate a refund for any eligible transaction, with provider-level response data included in the API output.</td><td><a href="/pages/kUhd7uZ0JM6KM4L3nOgB">/pages/kUhd7uZ0JM6KM4L3nOgB</a></td></tr><tr><td><h3>📜</h3></td><td><h4><strong>User Payment History</strong></h4></td><td>List all payments made by a specific user, filterable by date range, package, and payment type (subscription or one-time).</td><td><a href="/pages/96w1qtRF66ooRAxUpmNu">/pages/96w1qtRF66ooRAxUpmNu</a></td></tr></tbody></table>


# Get Payment Details

This endpoint returns the detailed information about a payment processed through Zotlo. It returns the full transaction record, including payment metadata, provider response, logs, and refund information.

It is commonly used to verify purchase results, diagnose failed payments, or fetch receipt details.

Use the **GET** method to query a payment and `transactionId` is required.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:green;background-color:$primary;"><code>GET</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/transaction/detail?transactionId=TRANSACTION_ID
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="176.16015625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>transactionId</code></td><td>Required</td><td>The ID of the transaction you want to query.</td></tr><tr><td><code>isSandbox</code></td><td>Required</td><td><p>Indicates whether the subscription was created in sandbox or live mode.Send:</p><ul><li><strong>true</strong> → sandbox</li><li><strong>false</strong> → live</li></ul></td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
GET https://api.zotlo.com/v1/transaction/detail?transactionId=TRANSACTION_ID HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "Rhk8q8-REQ-676d1460b284f",
    "httpStatus": 200
  },
  "result": {
    "transaction": {
      "id": 143199,
      "payment_type": "consumable",
      "original_transaction_id": "d8ff7792-1c63-4370-be93-447dacaa09ea",
      "subscriber_id": "user@sample.com",
      "transaction_id": "0741a0ac-21d8-4750-941f-064f340700c3",
      "provider_transaction_id": "863AB913JK7512U",
      "package_id": "2",
      "status": "consumable",
      "purchase_date": "2024-12-25 11:16:36",
      "expire_date": "2024-12-25 11:16:36",
      "original_purchase_date": "2024-12-25 11:16:36",
      "price": "1.49",
      "currency": "USD",
      "country": "US",
      "provider_name": "PayPal",
      "subscriptionId": 0,
      "custom_parameters": {
        "invoice": { ... },
        "clientUuid": "c941fc12-cac3-42f8-9790-8bb6e9f4793c",
        "dataWarehouse": { ... },
        "utm": { ... },
        "agreement": { ... },
        "merchantParameters": [],
        "cardBrand": "unknown",
        "threeds": "0",
        "installment": "1",
        "bank": "paypal",
        "subscriberIpAddress": "67.219.150.38",
        "receiptDetail": {
          "url": "https://dashboard.zotlo.com/receipt/ff388f17-b35d-4851-a59c-05ff64477d11"
        }
      },
      "credit_card": "",
      "checkout_type": "paypal",
      "refund": null,
      "detail": [
        {
          "key": "receiptUrl",
          "value": "https://dashboard.zotlo.com/receipt/ff388f17-b35d-4851-a59c-05ff64477d11"
        }
      ],
      "exchange": {
        "status": false,
        "detail": []
      }
    },
    "transactionLog": [
      {
        "providerId": 3062,
        "createDate": "2024-12-25 11:16:05",
        "requestType": "transaction",
        "requestData": "{\"requestType\":\"SALE\", ...}",
        "responseData": "{\"isMockPayment\":true,\"success\":true}",
        "subscriberId": "liteye2440@rabitex.com",
        "transactionId": "0741a0ac-21d8-4750-941f-064f340700c3",
        "paymentType": "paypal",
        "code": "S0000001",
        "message": null
      }
    ]
  }
}
```

{% endcode %}

## Key **Response Fields**

<table><thead><tr><th width="184.015625">Field</th><th>Description</th></tr></thead><tbody><tr><td>payment_type</td><td>Type of payment. <code>subscription</code> or <code>consumable</code> (one-time).</td></tr><tr><td>subscriber_id</td><td>The email or phone number of the user who made the purchase.</td></tr><tr><td>transaction_id</td><td>Unique ID of the transaction. </td></tr><tr><td>status</td><td>Payment or subscription action type. Possible values: <code>trial</code>, <code>trial_to_paid</code>, <code>start_paid</code>, <code>renewal</code>, <code>reactive</code>, <code>consumable</code>.</td></tr><tr><td>purchase_date</td><td>When the transaction was processed.</td></tr><tr><td>expire_date</td><td>Expiration date (for subscription transactions).</td></tr><tr><td>custom_parameters.paymentMethod</td><td>The payment method used.</td></tr><tr><td>transactionLog.code</td><td><p>Standardized payment status or error code. </p><p>(See <a href="/pages/CgpSDfcn6F4ZqWt6UZjM">Payment Status Codes</a>)</p></td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [Error Handling](/integrating-zotlo/api-reference/error-handling))


# Refund Payment

This endpoint processes refunds for purchases through Zotlo. It allows you to issue refunds for any payment processed by Zotlo, including one-time purchases, subscriptions.

Use the **POST** method to create a refund. You must provide the `transactionId` of the original payment.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:blue;"><code>POST</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/payment/refund
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="176.16015625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>transactionId</code></td><td>Required</td><td>The ID of the transaction to refund.</td></tr><tr><td><code>refundReason</code></td><td>Required</td><td>Explanation or reason for the refund.</td></tr><tr><td><code>refundUser</code></td><td>Optional</td><td>Who initiated the refund. Can be any descriptive string (e.g., “API”, “Support Agent”, “System Rule”).</td></tr><tr><td><code>refundPrice</code></td><td>Optional</td><td>The amount of the refund. Set a value lower than the original payment amount to process a partial refund.</td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
POST https://api.zotlo.com/v1/payment/refund HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••
{
    "transactionId": "0741a0ac-21d8-4750-941f-064f340700c3",
    "refundReason": "User request!"
}
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "246a8e676214-REQ-659557ea5289c",
    "httpStatus": 200
  },
  "result": {
    "providerResponse": [],
    "transaction": {
      "id": 57333,
      "payment_type": "subscription",
      "original_transaction_id": "d8ff7792-1c63-4370-be93-447dacaa09ea",
      "transaction_id": "0741a0ac-21d8-4750-941f-064f340700c3",
      "package_id": "premium",
      "team_id": 5,
      "app_id": 5,
      "status": "renewal",
      "create_date": "2024-01-03 12:47:20",
      "purchase_date": "2024-01-03 12:47:20",
      "original_purchase_date": "2023-01-03 12:47:16",
      "price": "12.00",
      "currency": "TRY",
      "country": "TR",
      "expire_date": "2025-01-03 12:47:16",
      "subscriber_id": "905456757656",
      "credit_card": "11111111****4111",
      "refund_price": "5.00",
      "refund_date": "2024-01-03 12:49:46",
      "refund_reason": "{\"reason\":\"Test .\",\"user\":\"API:\"}",
      "is_refund": 1,
      "provider_id": 8,
      "provider_transaction_id": "e963981a-4ee1-494b-b1e8-73db2a694c58",
      "provider_status": "unknown",
      "provider_name": "Zotlo",
      "quantity": 1,
      "package_price": "12.00",
      "subscription_id": 5370
    },
    "refundHistory": [
      {
        "id": 3627,
        "team_id": 5,
        "app_id": 5,
        "provider_id": 8,
        "package_id": "premium",
        "subscriber_id": "905456757656",
        "transaction_id": "0741a0ac-21d8-4750-941f-064f340700c3",
        "country": "TR",
        "price": "5.00",
        "currency": "TRY",
        "reason": "{\"reason\":\"Test .\",\"user\":\"API:\"}",
        "refund_date": "2024-01-03 12:49:46"
      }
    ]
  }
}
```

{% endcode %}

## Key **Response Fields**

<table><thead><tr><th width="184.015625">Field</th><th>Description</th></tr></thead><tbody><tr><td>providerResponse</td><td>Raw response returned by the payment provider during the refund.</td></tr><tr><td>transaction</td><td>Updated transaction record after the refund. Contains refund amount, refund date, status, and provider information.</td></tr><tr><td>refundHistory</td><td>List of all refunds issued for this transaction (useful for partial or multiple refunds).</td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# User Payment History

This endpoint returns all payment transactions (subscription payments and one-time purchases) for a given subscriber.

Use the **GET** method to query a subscriber, `subscriberId` is required.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:green;background-color:$primary;"><code>GET</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/transaction?subscriberId=&#x26;paymentType=&#x26;startDate=&#x26;endDate=&#x26;packageId=
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="176.16015625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>subscriberId</code></td><td>Required</td><td>The email or phone number used by the user when starting the subscription.</td></tr><tr><td><code>paymentType</code></td><td>Optional</td><td>Filters by payment type. Allowed values: <code>subscription</code>, <code>consumable</code> (one-time payments).</td></tr><tr><td><code>startDate</code></td><td>Optional</td><td>Should be string (YYYY-MM-DD). Returns payments occurring <strong>after</strong> this date.</td></tr><tr><td><code>endDate</code></td><td>Optional</td><td>Should be string (YYYY-MM-DD). Returns payments occurring <strong>before</strong> this date.</td></tr><tr><td>packageId</td><td>Optional</td><td>Filters transactions belonging to a specific package.</td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
GET https://api.zotlo.com/v1/transaction?subscriberId=SUBSCRIBER_ID&paymentType=subscription&startDate=2024-01-01&endDate=2024-01-30 HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "246a8e676214-REQ-659565f64ef8e",
    "httpStatus": 200
  },
  "result": {
    "transactions": [
      {
        "id": 57097,
        "payment_type": "subscription",
        "original_transaction_id": "48e39b30-2820-4d77-9699-221c896fca55",
        "transaction_id": "02c88e3a-f358-4adc-9c21-b979fb698e85",
        "provider_transaction_id": "b9b84a68-980e-404b-a705-45e5d327fdba",
        "package_id": "premium",
        "status": "renewal",
        "purchase_date": "2024-01-02 08:24:14",
        "expire_date": "2024-01-30 07:50:34",
        "original_purchase_date": "2023-11-30 07:50:34",
        "price": "49.00",
        "currency": "TRY",
        "country": "TR",
        "provider_name": "Zotlopos",
        "subscriptionId": 8260,
        "refund": null,
        "exchange": {
          "status": false,
          "detail": []
        }
      },
      {
        "id": 55001,
        "payment_type": "subscription",
        "original_transaction_id": "48e39b30-2820-4d77-9699-221c896fca55",
        "transaction_id": "48e39b30-2820-4d77-9699-221c896fca55",
        "provider_transaction_id": "b793670e-57d1-49df-8dcf-8d14426bd039",
        "package_id": "premium",
        "status": "start_paid",
        "purchase_date": "2023-11-30 07:50:34",
        "expire_date": "2023-12-30 07:50:34",
        "original_purchase_date": "2023-11-30 07:50:34",
        "price": "49.00",
        "currency": "TRY",
        "country": "TR",
        "provider_name": "Zotlo",
        "subscriptionId": 8260,
        "refund": null,
        "exchange": {
          "status": false,
          "detail": []
        }
      }
    ]
  }
}
```

{% endcode %}

## Key **Response Fields**

<table><thead><tr><th width="202.62890625">Field</th><th>Description</th></tr></thead><tbody><tr><td>transaction_id</td><td>Unique ID of the specific payment attempt. </td></tr><tr><td>original_transaction_id</td><td>The root transaction ID for the subscription or consumable order. All renewals reference this same ID.</td></tr><tr><td>payment_type</td><td>Type of payment:<br>• <code>subscription</code> – Subscription payment (start, renewal, trial→paid).<br>• <code>consumable</code> – One-time purchase.</td></tr><tr><td>package_id</td><td>Identifier of the product or subscription package.</td></tr><tr><td>status</td><td>Payment status type:<br>• <code>start_paid</code> – First paid subscription purchase<br>• <code>trial</code> – Trial started<br>• <code>trial_to_paid</code> – Trial converted to paid<br>• <code>renewal</code> – Subscription renewed<br>• <code>reactive</code> – Reactivation payment<br>• <code>consumable</code> – One-time purchase</td></tr><tr><td>purchase_date</td><td>Date and time when this payment attempt succeeded.</td></tr><tr><td>expire_date</td><td>Subscription expiry date for subscription payments (null for consumables).</td></tr><tr><td>original_purchase_date</td><td>First purchase date of the subscription.</td></tr><tr><td>price</td><td>Payment amount.</td></tr><tr><td>currency</td><td>Payment currency (USD, EUR, TRY etc.).</td></tr><tr><td>country</td><td>Country of purchase determined by payment metadata.</td></tr><tr><td>subscriptionId</td><td>Internal Zotlo subscription identifier (only for subscription payments).</td></tr><tr><td>refund</td><td>If the payment was refunded, contains refund metadata. Null otherwise.</td></tr><tr><td>exchange.status</td><td>Indicates whether currency exchange was applied.</td></tr><tr><td>exchange.detail</td><td>Additional exchange rate details if applicable.</td></tr><tr><td>checkout_type</td><td>Payment method (card, PayPal, GPay, ApplePay, etc.).</td></tr><tr><td>custom_parameters</td><td>May contains custom data (App specific user IDs, UTM data, Adjust/AppsFlyer/analytics IDs, IP address, etc.</td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# Export Endpoints

Zotlo’s Export API enables you to retrieve large-scale, paginated datasets for financial and operational reporting.\
You can export payment transactions, subscription lifecycle records, and refund activity, all optimized for analytics, BI pipelines, and backend processing.

Explore the export endpoints:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>🧾</h3></td><td><h4><strong>Payments Export</strong></h4></td><td>Retrieve all payment transaction records with filtering and cursor-based pagination.</td><td><a href="/pages/7nKwPnBniYu3HcTVqkai">/pages/7nKwPnBniYu3HcTVqkai</a></td></tr><tr><td><h3>📚 </h3></td><td><h4><strong>Subscriptions Export</strong></h4></td><td>Export detailed subscription lifecycle activity, including starts, renewals, cancellations, and grace transitions.</td><td><a href="/pages/YqAk8XsPCHLjdGuuNqEi">/pages/YqAk8XsPCHLjdGuuNqEi</a></td></tr><tr><td><h3>↩️</h3></td><td><h4><strong>Refunds Export</strong></h4></td><td>Fetch all refund operations, including refund amounts, reasons, timestamps, and related transaction metadata.</td><td><a href="/pages/JTxyfGCplAoXJiiAfuZB">/pages/JTxyfGCplAoXJiiAfuZB</a></td></tr></tbody></table>


# Payment Transactions Export

This endpoint enables you to retrieve all transaction data processed by Zotlo using filters such as date range, package, and country. The endpoint supports cursor-based pagination, allowing you to fetch large datasets efficiently and maintain stable integration workflows.

The service operates with the **GET** method.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:green;background-color:$primary;"><code>GET</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/reports/activity/transaction
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="176.16015625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>limit</code></td><td>Optional</td><td>Number of records to return in a single page. Default: <code>25</code>. Maximum: <code>100</code>.</td></tr><tr><td><code>country</code></td><td>Optional</td><td>Filters transactions by country where the payment was processed (2-letter ISO code, e.g. <code>UK</code>, <code>US</code>).</td></tr><tr><td><code>package_id</code></td><td>Optional</td><td>Filters transactions by the associated <code>packageId</code>.</td></tr><tr><td><code>start_date</code></td><td>Optional</td><td>Lists transactions created <strong>on or after</strong> this date. Format: <code>YYYY-MM-DD</code></td></tr><tr><td><code>end_date</code></td><td>Optional</td><td>Lists transactions created <strong>on or before</strong> this date. Format: <code>YYYY-MM-DD</code>.</td></tr><tr><td><code>before</code></td><td>Optional</td><td>Cursor token to fetch the <strong>previous</strong> page. Use the value returned under <code>paging.cursors.previous</code> from the last response.</td></tr><tr><td><code>after</code></td><td>Optional</td><td>Cursor token to fetch the <strong>next</strong> page. Use the value returned under <code>paging.cursors.next</code> from the last response.</td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
GET https://api.zotlo.com/v1/reports/activity/transaction?limit=50&start_date=2025-11-01&end_date=2025-11-30 HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "5896c0267514-REQ-6924605fb81f4",
    "httpStatus": 200
  },
  "result": {
    "data": [
      {
        "id": 1723,
        "paymentType": "subscription",
        "originalTransactionId": "29d557b4-2563-497b-ad1f-677ac6910b81",
        "transactionId": "29d557b4-2563-497b-ad1f-677ac6910b81",
        "packageId": "web_premium",
        "status": "start_paid",
        "purchaseDate": "2025-11-10 08:27:37",
        "originalPurchaseDate": "2025-11-10 08:27:37",
        "price": "20.00",
        "currency": "USD",
        "country": "US",
        "expireDate": "2025-11-10 08:28:08",
        "subscriberId": "3a33eb5d-3e4b-4875-916f-7e9fb5867f3f",
        "creditCard": "37442754***1042",
        "refundPrice": "20.00",
        "refundDate": "2025-11-10 08:28:08",
        "refundReason": "{\"reason\":\"\",\"user\":\"API: \"}",
        "isRefund": 1,
        "providerName": "Zotlo",
        "jsonPayload": "{\"forceWebhook\":true,\"cardBrand\":\"amex\",\"threeds\":\"0\",\"installment\":\"1\",\"bank\":\"testbank\",\"subscriberIpAddress\":\"0.0.0.0\"}",
        "quantity": 1,
        "packagePrice": "20.00",
        "subscriptionId": 343
      },
      {
        "id": 1722,
        "paymentType": "subscription",
        "originalTransactionId": "6edc57b0-86a1-4ba7-bf9a-81d05afbf505",
        "transactionId": "6edc57b0-86a1-4ba7-bf9a-81d05afbf505",
        "packageId": "web_premium",
        "status": "start_paid",
        "purchaseDate": "2025-11-10 08:19:29",
        "originalPurchaseDate": "2025-11-10 08:19:29",
        "price": "20.00",
        "currency": "USD",
        "country": "US",
        "expireDate": "2025-11-10 08:26:59",
        "subscriberId": "8aa4de92-a86d-4330-bb3c-6995a5f837ed",
        "creditCard": "37442754***1042",
        "refundPrice": "20.00",
        "refundDate": "2025-11-10 08:26:59",
        "refundReason": "{\"reason\":\"\",\"user\":\"API: \"}",
        "isRefund": 1,
        "providerName": "Zotlo",
        "jsonPayload": "{\"forceWebhook\":true,\"cardBrand\":\"amex\",\"threeds\":\"0\",\"installment\":\"1\",\"bank\":\"testbank\",\"subscriberIpAddress\":\"0.0.0.0\"}",
        "quantity": 1,
        "packagePrice": "20.00",
        "subscriptionId": 342
      }
    ],
    "paging": {
      "cursors": {
        "previous": null,
        "next": "DPn5BRhxQmvSvYRkfK3KQXUzYXpDSlcvUVVQREluUUxGbDFFR2xKV1dJNzM1Wnc2aE4xcERTNHdVWFRQV21selI1UDFuOWJ2Z0d4TmJCY3JFK3BzbTJxM0lkc3JGcVlmSThCK1ZYYUVPNWxmSnlTb0lhR0hnY2tBeE9HNEd5RFdnRFBOazVpMDlUZ1N1L1FuL0tCeDFzaUdxOGJLSFljZGdiTSttRzlkNzBXbXZPUnI0RWNWOHlUcDk3S1M1ZWlZbFBva0o1UENXV0RkOXlJTTdDUUtFalh1bEt2YzFTcUd6Nk9qUzBnNGRyVWcxbGZ2L2RBS2pvSVpNbVRPOE54WUZyQ3pMaFZtenhvbG4veHg"
      },
      "previous": "https://local-api.zotlo.com:39443/v1/reports/activity/transaction",
      "next": "https://local-api.zotlo.com:39443/v1/reports/activity/transaction?after=DPn5BRhxQmvSvYRkfK3KQXUzYXpDSlcvUVVQREluUUxGbDFFR2xKV1dJNzM1Wnc2aE4xcERTNHdVWFRQV21selI1UDFuOWJ2Z0d4TmJCY3JFK3BzbTJxM0lkc3JGcVlmSThCK1ZYYUVPNWxmSnlTb0lhR0hnY2tBeE9HNEd5RFdnRFBOazVpMDlUZ1N1L1FuL0tCeDFzaUdxOGJLSFljZGdiTSttRzlkNzBXbXZPUnI0RWNWOHlUcDk3S1M1ZWlZbFBva0o1UENXV0RkOXlJTTdDUUtFalh1bEt2YzFTcUd6Nk9qUzBnNGRyVWcxbGZ2L2RBS2pvSVpNbVRPOE54WUZyQ3pMaFZtenhvbG4veHg"
    }
  }
}
```

{% endcode %}

## Key **Response Fields**

<table><thead><tr><th width="194.51953125">Field</th><th>Description</th></tr></thead><tbody><tr><td>meta.requestId</td><td>Unique ID generated by Zotlo for this request (useful for debugging and support).</td></tr><tr><td>meta.httpStatus</td><td>HTTP status code for the response (e.g. <code>200</code>).</td></tr><tr><td>result.data</td><td>Array of payment transaction records returned for this page.</td></tr><tr><td>result.paging.cursors.previous</td><td>Cursor token to fetch the previous page. Send this value as <code>before</code> in the next request.</td></tr><tr><td>result.paging.cursors.next</td><td>Cursor token to fetch the next page. Send this value as <code>after</code> in the next request.</td></tr><tr><td>result.paging.previous</td><td>Full URL for the previous page request (helper link).</td></tr><tr><td>result.paging.next</td><td>Full URL for the next page request (helper link).</td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# Subscription Records Export

This endpoint enables you to retrieve all subscriptions data managed by Zotlo. It enables you to view active, inactive, or canceled subscriptions on the platform using various filters such as date range, package, and country. The endpoint allows you to fetch large volumes of subscription data efficiently and manage your reporting and operational workflows smoothly.

The service operates with the **GET** method.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:green;background-color:$primary;"><code>GET</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/reports/activity/subscription
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="176.16015625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>limit</code></td><td>Optional</td><td>Number of records to return in a single page. Default: <code>25</code>. Maximum: <code>100</code>.</td></tr><tr><td><code>country</code></td><td>Optional</td><td>Filters subscriptions by user country (2-letter ISO code, e.g. <code>UK</code>, <code>US</code>).</td></tr><tr><td><code>package_id</code></td><td>Optional</td><td>Filters subscriptions by the associated <code>packageId</code>.</td></tr><tr><td><code>start_date</code></td><td>Optional</td><td>Lists subscriptions created <strong>on or after</strong> this date. Format: <code>YYYY-MM-DD</code></td></tr><tr><td><code>end_date</code></td><td>Optional</td><td>Lists subscriptions created <strong>on or before</strong> this date. Format: <code>YYYY-MM-DD</code>.</td></tr><tr><td><code>before</code></td><td>Optional</td><td>Cursor token to fetch the <strong>previous</strong> page. Use the value returned under <code>paging.cursors.previous</code> from the last response.</td></tr><tr><td><code>after</code></td><td>Optional</td><td>Cursor token to fetch the <strong>next</strong> page. Use the value returned under <code>paging.cursors.next</code> from the last response.</td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
GET https://api.zotlo.com/v1/reports/activity/subscription?limit=50?&start_date=2025-11-01&end_date=2025-11-30 HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "5896c0267514-REQ-6924662e5718a",
    "httpStatus": 200
  },
  "result": {
    "data": [
      {
        "id": 343,
        "platform": "ios",
        "startDate": "2025-11-10 08:27:37",
        "expireDate": "2025-11-10 08:28:08",
        "subscriberId": "3a33eb5d-3e4b-4875-916f-7e9fb5867f3f",
        "productId": "web_premium",
        "originalTransactionId": "29d557b4-2563-497b-ad1f-677ac6910b81",
        "lastTransactionId": "29d557b4-2563-497b-ad1f-677ac6910b81",
        "lastTrandactionDate": "2025-11-10 08:27:37",
        "status": "passive",
        "subscriptionType": "paid",
        "currency": "USD",
        "price": "20.00",
        "trialPrice": "0.00",
        "country": "US",
        "language": "EN",
        "teamId": 1,
        "providerId": 13,
        "period": 1,
        "trialPeriod": 0,
        "renewalDate": "2025-12-10 08:27:37",
        "appId": 1,
        "cancellationDate": "2025-11-10 08:28:08",
        "cancellationReason": "{\"reason\":\"\",\"user\":\"API: \"}",
        "cancellationCode": "CU00002",
        "mobilePhone": "+905555555555",
        "email": "johndoe@example.com",
        "jsonPayload": "{\"forceWebhook\":true,\"subscriberIpAddress\":\"0.0.0.0\"}",
        "quantity": 1,
        "pendingQuantity": 0,
        "periodType": "month",
        "trialPeriodType": "day",
        "packageCountry": "TR",
        "freezeEndDate": null
      },
      {
        "id": 342,
        "platform": "ios",
        "startDate": "2025-11-10 08:19:29",
        "expireDate": "2025-11-10 08:26:59",
        "subscriberId": "8aa4de92-a86d-4330-bb3c-6995a5f837ed",
        "productId": "web_premium",
        "originalTransactionId": "6edc57b0-86a1-4ba7-bf9a-81d05afbf505",
        "lastTransactionId": "6edc57b0-86a1-4ba7-bf9a-81d05afbf505",
        "lastTrandactionDate": "2025-11-10 08:19:29",
        "status": "passive",
        "subscriptionType": "paid",
        "currency": "USD",
        "price": "20.00",
        "trialPrice": "0.00",
        "country": "US",
        "language": "EN",
        "teamId": 1,
        "providerId": 13,
        "period": 1,
        "trialPeriod": 0,
        "renewalDate": "2025-12-10 08:19:29",
        "appId": 1,
        "cancellationDate": "2025-11-10 08:26:59",
        "cancellationReason": "{\"reason\":\"\",\"user\":\"API: \"}",
        "cancellationCode": "CU00002",
        "mobilePhone": "+905555555555",
        "email": "johndoe@example.com",
        "jsonPayload": "{\"forceWebhook\":true,\"subscriberIpAddress\":\"0.0.0.0\"}",
        "quantity": 1,
        "pendingQuantity": 0,
        "periodType": "month",
        "trialPeriodType": "day",
        "packageCountry": "US",
        "freezeEndDate": null
      }
    ],
    "paging": {
      "cursors": {
        "previous": null,
        "next": "ExxyYaIVgzdwKWb7tuUf8WlwMlFSZmcxYVpiem5iWE93NW9EZkMrYk9oSE9tVEYrUlV4TUZMV2Y2ZG9VOEhucFdaSHRxNXVFaEdwYS90Z2lXRnpweEtzcG1WbG04THBLMGtJMWlmL2NKdjFneDJZZE5mNEIyVTNwQWlFSFV4ZU9wL2gyRUc0N2JYdjc0SEwxOVZwVGU4MUV3VUM2UFJCbWt0Y0tacUpjVFliRWg3eEoySVhWSEF2RDJIdkE2S3M4dCtiekZlMGJkZFFpblIxZU4vWE1hZmErTzJRSmdVNFBnbHFDQ28ya2hDMVJ5ZTJpU1ZyWGNLbGxrK009"
      },
      "previous": "https://local-api.zotlo.com:39443/v1/reports/activity/subscription",
      "next": "https://local-api.zotlo.com:39443/v1/reports/activity/subscription?after=ExxyYaIVgzdwKWb7tuUf8WlwMlFSZmcxYVpiem5iWE93NW9EZkMrYk9oSE9tVEYrUlV4TUZMV2Y2ZG9VOEhucFdaSHRxNXVFaEdwYS90Z2lXRnpweEtzcG1WbG04THBLMGtJMWlmL2NKdjFneDJZZE5mNEIyVTNwQWlFSFV4ZU9wL2gyRUc0N2JYdjc0SEwxOVZwVGU4MUV3VUM2UFJCbWt0Y0tacUpjVFliRWg3eEoySVhWSEF2RDJIdkE2S3M4dCtiekZlMGJkZFFpblIxZU4vWE1hZmErTzJRSmdVNFBnbHFDQ28ya2hDMVJ5ZTJpU1ZyWGNLbGxrK009"
    }
  }
}
```

{% endcode %}

## Key **Response Fields**

<table><thead><tr><th width="194.51953125">Field</th><th>Description</th></tr></thead><tbody><tr><td>meta.requestId</td><td>Unique ID generated by Zotlo for this request (useful for debugging and support).</td></tr><tr><td>meta.httpStatus</td><td>HTTP status code for the response (e.g. <code>200</code>).</td></tr><tr><td>result.data</td><td>Array of subscription records returned for this page.</td></tr><tr><td>result.paging.cursors.previous</td><td>Cursor token to fetch the previous page. Send this value as <code>before</code> in the next request.</td></tr><tr><td>result.paging.cursors.next</td><td>Cursor token to fetch the next page. Send this value as <code>after</code> in the next request.</td></tr><tr><td>result.paging.previous</td><td>Full URL for the previous page request (helper link).</td></tr><tr><td>result.paging.next</td><td>Full URL for the next page request (helper link).</td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# Refund Records Export

This endpoint enables you to retrieve all refunds to users processed by Zotlo. It enables you to export refund transactions using various filters such as date range, package, and country. The endpoint allows you to fetch large volumes of refund records efficiently and manage your financial reporting and operational workflows smoothly.

The service operates with the **GET** method.

<table data-header-hidden><thead><tr><th width="99.640625"></th><th></th></tr></thead><tbody><tr><td>Method</td><td><h4>  <mark style="color:green;background-color:$primary;"><code>GET</code></mark></h4></td></tr><tr><td>URL</td><td><pre data-overflow="wrap" data-full-width="false"><code>https://api.zotlo.com/v1/reports/activity/refund
</code></pre></td></tr></tbody></table>

## **Request Parameters**

<table><thead><tr><th width="176.16015625">Field</th><th width="115.48828125">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>limit</code></td><td>Optional</td><td>Number of records to return in a single page. Default: <code>25</code>. Maximum: <code>100</code>.</td></tr><tr><td><code>country</code></td><td>Optional</td><td>Filters refunds by user country (2-letter ISO code, e.g. <code>UK</code>, <code>US</code>).</td></tr><tr><td><code>package_id</code></td><td>Optional</td><td>Filters refunds by the associated <code>packageId</code>.</td></tr><tr><td><code>start_date</code></td><td>Optional</td><td>Lists refunds created <strong>on or after</strong> this date. Format: <code>YYYY-MM-DD</code></td></tr><tr><td><code>end_date</code></td><td>Optional</td><td>Lists refunds created <strong>on or before</strong> this date. Format: <code>YYYY-MM-DD</code>.</td></tr><tr><td><code>before</code></td><td>Optional</td><td>Cursor token to fetch the <strong>previous</strong> page. Use the value returned under <code>paging.cursors.previous</code> from the last response.</td></tr><tr><td><code>after</code></td><td>Optional</td><td>Cursor token to fetch the <strong>next</strong> page. Use the value returned under <code>paging.cursors.next</code> from the last response.</td></tr></tbody></table>

## **Sample Request**

{% code overflow="wrap" %}

```js
GET https://api.zotlo.com/v1/reports/activity/refund?limit=50?&start_date=2025-11-01&end_date=2025-11-30 HTTP/1.1
AccessKey: ••••••
AccessSecret: ••••••
Content-Type: application/json
ApplicationId: •
Language: ••
```

{% endcode %}

{% hint style="info" %}
You can find your **AccessKey** and **AccessSecret** in the Zotlo Panel under **Developer Tools → API Keys**

Sending **ApplicationId** is optional.
{% endhint %}

## Successful Response

{% code overflow="wrap" %}

```json
{
  "meta": {
    "requestId": "5896c0267514-REQ-69246705a5ea3",
    "httpStatus": 200
  },
  "result": {
    "data": [
      {
        "teamId": 1,
        "appId": 1,
        "packageId": "web_premium",
        "subscriberId": "3a33eb5d-3e4b-4875-916f-7e9fb5867f3f",
        "transactionId": "29d557b4-2563-497b-ad1f-677ac6910b81",
        "country": "US",
        "price": "20.00",
        "currency": "USD",
        "exchangeRate": "[]",
        "reason": "{\"reason\":\"\",\"user\":\"API: \"}",
        "refundDate": "2025-11-10 08:28:08",
        "refundType": "REFUND"
      },
      {
        "teamId": 1,
        "appId": 1,
        "packageId": "web_premium",
        "subscriberId": "8aa4de92-a86d-4330-bb3c-6995a5f837ed",
        "transactionId": "6edc57b0-86a1-4ba7-bf9a-81d05afbf505",
        "country": "US",
        "price": "20.00",
        "currency": "USD",
        "exchangeRate": "[]",
        "reason": "{\"reason\":\"\",\"user\":\"API: \"}",
        "refundDate": "2025-11-10 08:26:59",
        "refundType": "REFUND"
      }
    ],
    "paging": {
      "cursors": {
        "previous": null,
        "next": "jxNrkD7SxgoepgGb9tOAdytGbmJYSkh2V2hsVC8xRVlXODZKRmZRMkw4Y1dHcWZ0em5YdmxBa3hqckx3MkxBUitRUjNzL2dkQ0gwa2N2MFBRT3lpbDlsNnFjODZ1OHJsdlI3TmY2S2ZjUlFqYnhBbS9SRG5kdHhocHM1aTJYaFBwNS9STkRwci9YYUp3N2FEODdjZ3FacFNhbVlmUEtRMlZscUR6eFdxNEdZdUhuNWI3SnF2UEJYa29FakcvMEZTbXhrSk1tdktTYjV4c085Q2lTVnN4elJtNll4aEFpSkJ3WWkrSVE9PQ"
      },
      "previous": "https://local-api.zotlo.com:39443/v1/reports/activity/refund",
      "next": "https://local-api.zotlo.com:39443/v1/reports/activity/refund?after=jxNrkD7SxgoepgGb9tOAdytGbmJYSkh2V2hsVC8xRVlXODZKRmZRMkw4Y1dHcWZ0em5YdmxBa3hqckx3MkxBUitRUjNzL2dkQ0gwa2N2MFBRT3lpbDlsNnFjODZ1OHJsdlI3TmY2S2ZjUlFqYnhBbS9SRG5kdHhocHM1aTJYaFBwNS9STkRwci9YYUp3N2FEODdjZ3FacFNhbVlmUEtRMlZscUR6eFdxNEdZdUhuNWI3SnF2UEJYa29FakcvMEZTbXhrSk1tdktTYjV4c085Q2lTVnN4elJtNll4aEFpSkJ3WWkrSVE9PQ"
    }
  }
}
```

{% endcode %}

## Key **Response Fields**

<table><thead><tr><th width="194.51953125">Field</th><th>Description</th></tr></thead><tbody><tr><td>meta.requestId</td><td>Unique ID generated by Zotlo for this request (useful for debugging and support).</td></tr><tr><td>meta.httpStatus</td><td>HTTP status code for the response (e.g. <code>200</code>).</td></tr><tr><td>result.data</td><td>Array of refund records returned for this page.</td></tr><tr><td>result.paging.cursors.previous</td><td>Cursor token to fetch the previous page. Send this value as <code>before</code> in the next request.</td></tr><tr><td>result.paging.cursors.next</td><td>Cursor token to fetch the next page. Send this value as <code>after</code> in the next request.</td></tr><tr><td>result.paging.previous</td><td>Full URL for the previous page request (helper link).</td></tr><tr><td>result.paging.next</td><td>Full URL for the next page request (helper link).</td></tr></tbody></table>

## **Failed Response**

All failed responses follow the same standard error format.\
(See: [**Error Handling**](/integrating-zotlo/api-reference/error-handling))


# Webhooks

Zotlo Webhooks enable your backend to receive real-time notifications for key lifecycle events—such as subscription updates, successful payments, refunds, new user registrations, and quiz responses.\
These event-driven callbacks help you automate workflows, maintain synchronized data, and seamlessly integrate Zotlo events into your own systems.

In this section, you can explore the following topics:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>🧭</h3></td><td><h4><strong>Webhooks Overview</strong></h4></td><td>Start by exploring the webhooks overview to understand how webhook delivery, retries, security, and activation work.</td><td><a href="/pages/yWG0UxWFTQ59OoKmapvL">/pages/yWG0UxWFTQ59OoKmapvL</a></td></tr><tr><td><h3>🔔 </h3></td><td><h4><strong>Subscriptions Webhook</strong></h4></td><td>Learn how to receive real-time updates on subscription lifecycle events.</td><td><a href="/pages/tvbWjRsZFlNliZItApqs">/pages/tvbWjRsZFlNliZItApqs</a></td></tr><tr><td><h3>💳</h3></td><td><h4><strong>Payments Webhook</strong></h4></td><td>See how to receive callbacks for successful payment events, including one-time payments and subscriptions.</td><td><a href="/pages/6g98mvSJUTph5k812vXS">/pages/6g98mvSJUTph5k812vXS</a></td></tr><tr><td><h3>↩️</h3></td><td><h4><strong>Refunds Webhook</strong></h4></td><td>Get detailed insights into refund events triggered by users or merchants, including refund amounts, dates, and original transaction references.</td><td><a href="/pages/rkabtwpV3vRaTtSEqmCd">/pages/rkabtwpV3vRaTtSEqmCd</a></td></tr><tr><td><h3>🧑‍💻</h3></td><td><h4><strong>Users Webhook</strong></h4></td><td>Receive notifications whenever a new user completes the registration step on your sales flow or checkout.</td><td><a href="/pages/7iNhcpldWDjkMTUMk26I">/pages/7iNhcpldWDjkMTUMk26I</a></td></tr><tr><td><h3>📝</h3></td><td><h4><strong>Quiz Responses Webhook</strong></h4></td><td>Collect quiz answers submitted by your users during purchase flows, with options to include both payer and non-payer responses.</td><td><a href="/pages/5eMyVY5bQ3kqraRnXK0u">/pages/5eMyVY5bQ3kqraRnXK0u</a></td></tr></tbody></table>


# Webhooks Overview

Zotlo Webhooks allow your backend to receive real-time notifications about events such as subscription status changes, successful payments, registered users, completed quizzes and refunds.&#x20;

Your server receives these events as **HTTP POST requests** in JSON format, enabling you to sync billing activity, update user access, trigger workflows, or maintain your internal records.

## **Activation**

To start receiving webhook events, you must activate each webhook type from the Zotlo Dashboard:

1. Navigate to **Developer Tools → Webhooks**.
2. Enter your server’s **endpoint URL** for the webhook(s) you want to subscribe to.
3. Once saved, the webhook becomes **active immediately**.
4. You can use the **“Send Test Webhook”** option to verify connectivity and validate your endpoint before going live.

## **How Webhooks Work**

Webhooks are delivered to the endpoint URL once they are activated.

Each webhook event is sent as a **POST request** with a JSON body containing:

* **queue** : event metadata
* **parameters** : actual event payload (subscription, payment, or refund details)

Example structure:

{% code overflow="wrap" %}

```json
{
  "queue": {
    "type": "...",
    "eventType": "...",
    "requestID": "...",
    "createDate": {...},
    "appId": 123
  },
  "parameters": { ... }
}
```

{% endcode %}

## **Delivery & Retry Logic**

A webhook is considered successful when your server returns **HTTP 200**.

If your server returns anything other than 200, the notification is retried with the following schedule:

| Attempt       | Delay            |
| ------------- | ---------------- |
| 1st retry     | 10 minutes       |
| 2nd–4th retry | Every 30 minutes |
| 5th retry     | After 1 hour     |
| Final state   | No more retries  |

If all attempts fail, the event is dropped and will not be resent.

## **Security Best Practices**

To ensure webhook authenticity, you should:

* Validate the IP/domain whitelist (optional).
* Verify the **requestID** does not repeat (idempotency check).
* Log all incoming events.
* Always return **200 OK** after successful processing, not before.

## **Event Types**

Zotlo currently provides three webhook categories:

| Webhook                         | Description                                                                                                       |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Subscription Status Webhook** | Sends events on subscription lifecycle changes (new subscriber, grace, renewal, cancellation, reactivation, etc.) |
| **Payment Webhook**             | Sends events for all successful payments (subscription & consumables)                                             |
| **Refund Webhook**              | Sends events for all successful refund operations                                                                 |
| **Registered Users Webhook**    | Sends events for all successful user registrations                                                                |
| **Completed Quizzes Webhook**   | Sends events for all completed quizzes                                                                            |

Each webhook type includes its own `queue.type`, `eventType`, and structured `parameters` payload.

Detailed specs for each webhook type are provided on their respective documentation pages.

## **Recommendations**

To ensure consistent processing:

* Treat all webhooks as **asynchronous**.
* Use **transaction\_id** and **subscriber\_id** as primary identifiers.
* Use **realStatus** instead of **status** when determining true subscription state.
* Apply **idempotent handling** to avoid duplicates.
* Process events in chronological order using `createDate` when needed.

## **Sample Response Structure**

While the payload differs per webhook type, all webhook POST bodies follow the same structure:

| Field               | Description                                                              |
| ------------------- | ------------------------------------------------------------------------ |
| **queue.type**      | Type of webhook (SubscriberUpdate, TransactionInsert, TransactionRefund) |
| **queue.eventType** | Specific event (renewal, newSubscriber, refund, transaction, etc.)       |
| **parameters**      | The event data (subscription profile, payment details, refund details)   |


# Subscription Status Webhooks

Receive real-time updates about subscription lifecycle events

The **Subscription Status Webhook** notifies your server whenever a subscriber’s status changes, including new subscriptions, renewals, grace transitions, cancellations, reactivations, and quantity/package updates.

Use this webhook to keep your internal user access logic, CRM, analytics systems, and billing dashboards fully synchronized with Zotlo lifecycle events.

## **When This Is Triggered**

You will receive a callback when any of the following events occur:

| Event Type          | Description                                         |
| ------------------- | --------------------------------------------------- |
| **newSubscriber**   | A new subscription has been created (trial or paid) |
| **renewal**         | A subscription has successfully renewed             |
| **activeToGrace**   | Renewal failed → subscriber moved to grace period   |
| **graceToActive**   | A retry succeeded → subscriber returned to active   |
| **graceToPassive**  | All retries failed → subscription became passive    |
| **cancel**          | Subscription canceled by user, merchant, or system  |
| **reactivate**      | A canceled subscription was reactivated             |
| **package\_update** | The subscriber upgraded or downgraded their plan    |

## **Webhook Structure**

Every Subscription Status webhook contains two main sections:

* **queue** → event metadata
* **parameters** → full subscription profile and changes

## Example Payload

{% code overflow="wrap" %}

```json
{
  "queue": {
    "type": "SubscriberUpdate",
    "eventType": "newSubscriber",
    "requestID": "5a33b022-b877-4888-9eed-89a294640a3c",
    "createDate": {
      "date": "2024-05-13 08:18:22.978000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "appId": 1651
  },
  "parameters": {
    "profile": {
      "status": "active",
      "realStatus": "active",
      "subscriberId": "testwebhook@mail.com",
      "subscriptionId": 10414,
      "subscriptionType": "trial",
      "startDate": "2024-05-13 08:18:22",
      "expireDate": "2024-05-16 08:18:22",
      "renewalDate": "2024-05-16 08:18:22",
      "package": "paypal_test",
      "country": "US",
      "phoneNumber": null,
      "language": "en",
      "originalTransactionId": "bfe87fcd-72f7-4902-88ba-b2695c829590",
      "lastTransactionId": "bfe87fcd-72f7-4902-88b2695c829590",
      "subscriptionPackageType": "single",
      "cancellation": null,
      "customParameters": {
        "clientUuid": "5adf7031-34f3-402b-88fc-2fe8cc87d0af"
      },
      "quantity": 1,
      "pendingQuantity": 0,
      "renewalFetchCount": 0
    },
    "package": {
      "packageId": "pro_test",
      "price": 1,
      "currency": "USD",
      "packageType": "subscription",
      "name": "pro_test",
      "subscriptionPackageType": "single",
      "bundlePackages": []
    },
    "newPackage": null,
    "card": {
      "cardNumber": "41111111****1111",
      "expireDate": "06/2024",
      "tokenId": 11082
    },
    "customer": null,
    "package_update": 0
  }
}
```

{% endcode %}

## **Field Reference**

#### **queue**

Metadata describing the event:

| Field                | Description                                                       |
| -------------------- | ----------------------------------------------------------------- |
| **queue.type**       | Always `SubscriberUpdate`                                         |
| **queue.eventType**  | Type of subscription event (renewal, cancel, newSubscriber, etc.) |
| **queue.requestID**  | Unique identifier for this webhook call                           |
| **queue.createDate** | Timestamp of the event                                            |
| **queue.appId**      | ID of the project where the transaction occurred                  |

#### **parameters.profile**

Current subscription profile and lifecycle state:

| Field                     | Description                                                                          |
| ------------------------- | ------------------------------------------------------------------------------------ |
| **status**                | Current status → `active`, `grace`, or `passive`                                     |
| **realStatus**            | The true state (canceled users return `passive` immediately even if cycle not ended) |
| **subscriptionType**      | `trial` or `paid`                                                                    |
| **subscriberId**          | Unique identifier sent during purchase (email or phone)                              |
| **subscriptionId**        | Internal Zotlo subscription record ID                                                |
| **startDate**             | Subscription start date                                                              |
| **expireDate**            | Access expiration date                                                               |
| **renewalDate**           | Scheduled next billing attempt                                                       |
| **package**               | Current packageId                                                                    |
| **originalTransactionId** | First purchase transactionId                                                         |
| **lastTransactionId**     | Latest successful payment transactionId                                              |
| **country**               | Subscriber’s country                                                                 |
| **language**              | Subscriber’s preferred language                                                      |
| **cancellation**          | Cancellation details if subscription was canceled                                    |
| **quantity**              | Current billable quantity                                                            |
| **pendingQuantity**       | Quantity change that will apply on next renewal                                      |
| **customParameters**      | Custom metadata sent during purchase                                                 |

#### **parameters.package**

Information about the package currently active or last used.

| Field           | Description             |
| --------------- | ----------------------- |
| **packageId**   | ID of the package       |
| **price**       | Base price              |
| **currency**    | Currency                |
| **packageType** | subscription / one-time |
| **name**        | Display name            |

#### **parameters.newPackage**

Returned when a **downgrade** has occurred.\
`null` if no plan change happened.

#### **parameters.card**

Masked card details, if a card is used.

| Field          | Description       |
| -------------- | ----------------- |
| **cardNumber** | Masked card       |
| **expireDate** | Expiry date       |
| **tokenId**    | Tokenized card ID |

#### **parameters.customer**

Customer details (if applicable).\
May return `null`.

#### **parameters.package\_update**

Indicates whether this event was triggered after a plan change:

* `1` → package was updated
* `0` → no change

## **How to Use This Webhook**

Typical use cases:

* Update subscription status in your backend
* Grant or revoke access based on `status` or `realStatus`
* Trigger email notifications (trial ending, renewal success, cancellation)
* Update CRM / marketing automation
* Sync billing data to analytics systems
* Automate upgrade/downgrade flows

## **Logic for Access Control**

Use **realStatus** for determining true access logic when cancellations are involved:

* `status = active` but `realStatus = passive` → user canceled; access decision depends on your rules
* `status = grace` → payment failed; retry active; your app decides access
* `status = passive` → subscription ended


# Payments Webhook

The **Payments Webhook** notifies your server whenever a **successful payment** occurs, including subscription transactions (trial start, initial purchase, renewal, reactivation) and one-time (consumable) purchases.

Use this webhook to sync revenue events, unlock purchased content, log payment activity, and trigger post-purchase workflows (emails, CRM events, fulfillment, etc.).

## **When This Is Triggered**

A callback is sent whenever Zotlo records one of the following successful payment events:

| Event Type          | Description                                            |
| ------------------- | ------------------------------------------------------ |
| **trial**           | A free or paid trial has started                       |
| **start\_paid**     | A subscription started without trial                   |
| **trial\_to\_paid** | Trial converted into a paid subscription               |
| **renewal**         | A recurring subscription renewal succeeded             |
| **reactive**        | A canceled subscription was reactivated with a payment |
| **consumable**      | A one-time purchase was completed                      |

{% hint style="warning" %}
Refunds are **not** included here — they are handled by the [Refunds Webhook](/integrating-zotlo/webhooks/refunds-webhook).
{% endhint %}

## Example Payload

{% code overflow="wrap" %}

```json
{
  "queue": {
    "type": "TransactionInsert",
    "eventType": "transaction",
    "requestID": "4fee-9169-a6b45555f89b",
    "createDate": {
      "date": "2024-06-15 11:51:35.807000",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "appId": 1
  },
  "parameters": {
    "id": "38359",
    "payment_type": "subscription",
    "original_transaction_id": "6kab56hfs773-a25f3ebf8e2f",
    "transaction_id": "ba3325ge3ad6791-49f4-9693-a25f3ebf8e2f",
    "package_id": "weekly_",
    "team_id": 22,
    "app_id": 1,
    "status": "trial",
    "create_date": "2024-06-15 11:51:35",
    "purchase_date": "2024-06-15 11:51:35",
    "original_purchase_date": "2024-06-15 11:51:35",
    "price": "0.00",
    "currency": "USD",
    "country": "US",
    "expire_date": "2024-06-22 11:51:35",
    "subscriber_id": "test@zotlo.com",
    "credit_card": "41111111****1111",
    "refund_price": null,
    "refund_date": null,
    "refund_reason": null,
    "is_refund": "0",
    "provider_id": 2222263,
    "provider_transaction_id": "417705901",
    "provider_status": "mastercard",
    "provider_name": "Credit Card",
    "quantity": 1,
    "package_price": 0,
    "subscription_id": "9292132",
    "custom_parameters": {
      "clientUuid": "0bb45b80-1ff5-42ee-a382-a5ee06e641c9",
      "dataWarehouse": {
        "paymentModule": "generate",
        "siteId": 38,
        "flowId": 600,
        "appId": 7,
        "teamId": 7,
        "acceptPolicy": true,
        "fullName": "test",
        "epinCode": "test1235"
      },
      "utm": {
        "source": null,
        "medium": null,
        "campaign": null,
        "term": null,
        "content": null
      },
      "cardBrand": "mastercard",
      "threeds": "1",
      "installment": "1",
      "bank": "lidio3p"
    },
    "paymentMethod": "creditCard",
    "installment": 1,
    "exchange": {
      "status": false,
      "detail": []
    },
    "coupon_campaign": {
      "isUsedCouponCode": false,
      "code": null,
      "discountType": null,
      "discountValue": null
    },
    "language": "en"
  }
}
```

{% endcode %}

## **Field Reference**

#### **queue**

Event metadata.

| Field                | Description                |
| -------------------- | -------------------------- |
| **queue.type**       | Always `TransactionInsert` |
| **queue.eventType**  | Always `transaction`       |
| **queue.requestID**  | Unique webhook delivery ID |
| **queue.createDate** | Payment timestamp          |
| **queue.appId**      | Project ID in Zotlo        |

#### **parameters**

Details about the successful payment.

#### **Core Transaction Fields**

| Field                         | Description                                                      |
| ----------------------------- | ---------------------------------------------------------------- |
| **id**                        | Internal payment record ID                                       |
| **payment\_type**             | `subscription` or `consumable` (one-time)                        |
| **transaction\_id**           | The unique ID used for refunds                                   |
| **original\_transaction\_id** | First transaction in a subscription chain                        |
| **status**                    | Payment lifecycle event (`trial`, `start_paid`, `renewal`, etc.) |
| **purchase\_date**            | Payment timestamp                                                |
| **expire\_date**              | Next billing date (subscriptions only)                           |
| **price**                     | Charged amount                                                   |
| **currency**                  | Payment currency                                                 |
| **country**                   | Country determined via IP                                        |
| **subscriber\_id**            | User email or phone                                              |
| **credit\_card**              | Masked card number                                               |
| **provider\_name**            | Payment provider (e.g., Credit Card, PayPal)                     |
| **provider\_transaction\_id** | Processor transaction ID                                         |
| **provider\_status**          | Card type, issuer, etc.                                          |

#### **Refund-Related Fields**

(Always null for payment webhook events, but included for consistency.)

| Field              | Description                                  |
| ------------------ | -------------------------------------------- |
| **refund\_price**  | Refunded amount (null for non-refund events) |
| **refund\_date**   | Refund date                                  |
| **refund\_reason** | Reason for refund                            |
| **is\_refund**     | Always `0` for this webhook                  |

#### **Subscription & Package Fields**

| Field                | Description                                |
| -------------------- | ------------------------------------------ |
| **package\_id**      | Purchased packageId                        |
| **package\_price**   | Defined package price                      |
| **quantity**         | Units/seats purchased                      |
| **subscription\_id** | Subscription ID (0 for one-time purchases) |

#### **Custom Metadata**

| Field                                | Description                                |
| ------------------------------------ | ------------------------------------------ |
| **custom\_parameters.clientUuid**    | User session identifier                    |
| **custom\_parameters.dataWarehouse** | Internal sales metadata (site, flow, team) |
| **custom\_parameters.utm**           | Campaign data                              |
| **custom\_parameters.epinCode**      | e-pin code if applicable                   |
| **custom\_parameters.cardBrand**     | Visa, Mastercard, etc.                     |
| **custom\_parameters.threeds**       | Whether 3DS was used                       |
| **custom\_parameters.installment**   | Installment count                          |

#### **Coupon Info**

| Field                | Description            |
| -------------------- | ---------------------- |
| **isUsedCouponCode** | Indicates coupon usage |
| **code**             | Coupon code            |
| **discountType**     | Percentage / fixed     |
| **discountValue**    | Discount amount        |

## **How To Use This Webhook**

Common use cases:

* Grant access to premium features after successful payment
* Log successful transactions in your backend billing system
* Trigger purchase confirmation emails
* Update dashboards or BI pipelines
* Trigger fulfillment (e-pin codes, digital goods)
* Enrich CRM events with revenue details
* Record internal audit logs

## **Best Practices**

* Use **transaction\_id** for all refund operations
* Use **payment\_type** to distinguish between subscriptions & one-time purchases
* Use **idempotency** on your side: ignore duplicate webhook deliveries
* Always return **HTTP 200** once processed successfully


# Refunds Webhook

The **Refunds Webhook** notifies your server whenever a **refund** is successfully processed, whether initiated by you (merchant), the system, or the end-user. This includes refunds for both **subscription payments** and **one-time purchases**.

Use this webhook to sync refund activity, update user access, record financial adjustments, and keep internal reporting systems accurate.

## **When This Is Triggered**

A callback is sent whenever Zotlo completes one of the following:

| Event Type | Description                              |
| ---------- | ---------------------------------------- |
| **refund** | A refund has been processed successfully |

{% hint style="info" %}
Only *successful refunds* trigger this webhook. Failed or pending refunds are not sent.
{% endhint %}

## Example Payload

{% code overflow="wrap" %}

```json
{
  "queue": {
    "type": "TransactionRefund",
    "eventType": "refund",
    "requestID": "bbb3a4bc-93fc-46da-9d35-b2a7db6f2e3c",
    "createDate": {
      "date": "2024-10-25 15:23:48",
      "timezone_type": 3,
      "timezone": "UTC"
    },
    "appId": 7
  },
  "parameters": {
    "id": 9599,
    "payment_type": "subscription",
    "original_transaction_id": "093b8307-1658-4f94-a9bd-f101748d3c4b",
    "transaction_id": "093b8307-16-a9bd-f101748d3c4b",
    "package_id": "premium2005",
    "team_id": 7,
    "app_id": 7,
    "status": "start_paid",
    "create_date": "2024-10-25 15:23:48",
    "purchase_date": "2024-10-25 15:23:48",
    "original_purchase_date": "2024-10-25 15:23:48",
    "price": "9.99",
    "currency": "USD",
    "country": "US",
    "expire_date": "2024-10-25 15:23:48",
    "subscriber_id": "test@mail.com",
    "credit_card": "41111111****1111",
    "refund_price": "9.99",
    "refund_date": "2024-10-25 15:23:48",
    "refund_reason": "",
    "is_refund": 1,
    "provider_id": 2005,
    "provider_transaction_id": "c9d9e426-c3a2-4b5f-ba67-e09618f1d066",
    "provider_status": "visa",
    "provider_name": "Credit Card",
    "comment": null,
    "json_payload": "",
    "quantity": 1,
    "package_price": "9.99",
    "subscription_id": 2005,
    "is_transfer": null,
    "paymentMethod": "creditCard"
  }
}
```

{% endcode %}

## **Field Reference**

#### **queue**

Metadata about the refund event.

| Field                | Description                |
| -------------------- | -------------------------- |
| **queue.type**       | Always `TransactionRefund` |
| **queue.eventType**  | Always `refund`            |
| **queue.requestID**  | Unique webhook delivery ID |
| **queue.createDate** | Timestamp of the refund    |
| **queue.appId**      | Project ID in Zotlo        |

#### **parameters**

Details about the refunded transaction.

#### **Core Refund Fields**

| Field              | Description                    |
| ------------------ | ------------------------------ |
| **is\_refund**     | Always `1` for this webhook    |
| **refund\_price**  | Amount refunded                |
| **refund\_date**   | Timestamp of the refund        |
| **refund\_reason** | Reason provided for the refund |

#### **Transaction Context**

Refund events include the original transaction details so you can fully reconstruct the refund in your system.

| Field                         | Description                                                                                         |
| ----------------------------- | --------------------------------------------------------------------------------------------------- |
| **transaction\_id**           | Transaction ID that was refunded                                                                    |
| **original\_transaction\_id** | Initial subscription transaction ID (first purchase)                                                |
| **payment\_type**             | `subscription` or `consumable`                                                                      |
| **status**                    | Transaction type associated with the refunded payment (`start_paid`, `renewal`, `consumable`, etc.) |
| **price**                     | Original payment amount                                                                             |
| **currency**                  | Original currency                                                                                   |
| **purchase\_date**            | Original payment date                                                                               |
| **expire\_date**              | Only applies to subscription transactions                                                           |
| **package\_id**               | Purchased package                                                                                   |
| **package\_price**            | Package price                                                                                       |
| **quantity**                  | Quantity purchased                                                                                  |

#### **User & Provider Info**

| Field                         | Description                                  |
| ----------------------------- | -------------------------------------------- |
| **subscriber\_id**            | Email or phone sent during purchase          |
| **country**                   | Country determined via IP                    |
| **credit\_card**              | Masked card number                           |
| **provider\_name**            | Payment provider (e.g., Credit Card, PayPal) |
| **provider\_transaction\_id** | ID provided by the payment provider          |
| **paymentMethod**             | Payment method used                          |

#### **Additional Metadata**

| Field                  | Description                                |
| ---------------------- | ------------------------------------------ |
| **team\_id**           | Zotlo account ID                           |
| **app\_id**            | Project ID within the account              |
| **custom\_parameters** | Any custom parameters sent during purchase |
| **json\_payload**      | Provider-specific data (if available)      |

## **Recommended Use Cases**

* Reverse access to subscription or premium content
* Log refund events in BI, finance, and internal tools
* Update CRM or marketing platforms
* Trigger refund confirmation emails
* Keep internal accounting systems aligned with real refund data
* Sync with tax or invoicing systems

## **Best Practices**

* Always match refunds with **transaction\_id**
* Keep `original_transaction_id` for subscription histories
* Ensure idempotency → retry-safe processing
* Return `HTTP 200` only after saving the event
* Store webhook logs for audit and reconciliation
* Use refund webhook to update entitlement / access rights


# User Registration Webhook

The **User Registration Webhook** notifies your server when a user successfully completes the registration step inside a Zotlo-hosted sales flow or checkout.

## **When This Is Triggered**

A callback is sent whenever Zotlo completes a user registration. Registration can occur in two contexts:

| Context                      | Description                                                      |
| ---------------------------- | ---------------------------------------------------------------- |
| **Self-Service Sales Sites** | Sent immediately after the user completes the registration step. |
| **Checkout**                 | Sent after a successful payment                                  |

Use this webhook to enrich CRM data, personalize onboarding, activate marketing workflows, or associate subscriptions with verified user information.

## Example Payload

{% code overflow="wrap" %}

```json
{
  "clientUuid": "string",
  "clientIp": "127.0.0.1",
  "country": "US",
  "language": "en",
  "storeRegister": true,
  "subscriberId": "905555555555",
  "subscriberName": "john doe",
  "appId": 1,
  "flowId": 1,
  "siteId": 1,
  "registerDate": "2020-03-20 12:35:41",
  "registerOtpStatus": false
}
```

{% endcode %}

## **Field Reference**

#### **User Information**

| Field              | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| **clientUuid**     | Unique session/user identifier generated during registration |
| **clientIp**       | User’s IP address                                            |
| **country**        | Country derived from IP                                      |
| **language**       | Language selected/used during registration                   |
| **subscriberId**   | User identifier (email or phone number)                      |
| **subscriberName** | Full name of the user (if collected)                         |

#### **Source & Context**

| Field             | Description                                  |
| ----------------- | -------------------------------------------- |
| **storeRegister** | `true` = Zotlo Store, `false` = Self-Service |
| **appId**         | Project ID                                   |
| **flowId**        | Flow ID where registration occurred          |
| **siteId**        | Sales site ID                                |

#### **Registration Metadata**

| Field                 | Description                                                          |
| --------------------- | -------------------------------------------------------------------- |
| **registerDate**      | Registration timestamp (UTC)                                         |
| **registerOtpStatus** | Whether registration flow included OTP verification (`true`/`false`) |

## **Common Use Cases**

* Create or update user profiles in your CRM
* Trigger onboarding emails or push notifications
* Track registration funnels and attribution
* Attach marketing identifiers (MMP/UTM) to user accounts
* Pre-warm subscriber profiles before first purchase
* Sync user identities across platforms


# Quiz Responses Webhook

The **Quiz Responses Webhook** sends the answers submitted by users when they complete a quiz on your sales funnels. This webhook helps you analyze user behavior, personalize funnels, score quizzes, or trigger post-quiz flows.

By default, you will **only receive quiz responses from users who completed a purchase**.\
If you would like to also receive quiz responses from **non-paying users**, you can enable this option in the Webhook settings page.

## **When This Is Triggered**

A callback is sent whenever a user completed registration after completed a quiz.&#x20;

| Context                      | Description                                                                                                                                                                                                                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Self-Service Sales Sites** | <ol><li><p><strong>If the “send unpaid quiz responses” option is enabled</strong></p><p>Sent immediately after the user completes the registration step.</p></li><li><strong>If the option is disabled (default)</strong></li></ol><p>      Sent after the user completes the payment </p> |

## Example Payload

{% code overflow="wrap" %}

```json
{
  "client": {
    "subscriberId": "test123@gmail.com",
    "subscriberName": "name surname",
    "email": "test123@gmail.com",
    "uuid": "29de05a7-5a6f-4107-b15a-1c8abdefad95",
    "isPayer": 1,
    "platform": "Mac OS",
    "country": "US",
    "language": "en",
    "utmSource": null,
    "utmMedium": null,
    "utmCampaign": null,
    "utmContent": null,
    "utmTerm": null,
    "paymentModule": "generate",
    "flowId": 600,
    "siteId": 38,
    "ip": "192.168.1.1"
  },
  "questions": {
    "5706": {
      "questionId": "question1",
      "questionName": "Question 1",
      "question": "Question Title",
      "settings": "{\"backgroundColor\":\"\",\"forceDesktopBG\":true,\"backgroundImage\":{\"desktop\":\"\",\"tablet\":\"\",\"mobile\":\"\"}}",
      "sequence": 1,
      "displayedSequence": 1,
      "required": 1,
      "isMultiple": 0,
      "typeId": 0,
      "typeName": "SingleSelection",
      "isLogic": false
    }
  },
  "answers": {
    "5706": {
      "answerDate": "2024-01-10 10:47:25",
      "answer": null,
      "answerOptions": [
        {
          "optionId": 8215,
          "name": "Option örnek 1",
          "type": "image",
          "image": ""
        }
      ]
    }
  }
}
```

{% endcode %}

## **Field Reference**

#### **Client Fields**

| Field                                                     | Description                                           |
| --------------------------------------------------------- | ----------------------------------------------------- |
| **client.subscriberId**                                   | Email or phone number used during quiz or purchase    |
| **client.subscriberName**                                 | User’s full name                                      |
| **client.email**                                          | User email (if collected)                             |
| **client.uuid**                                           | Unique user/session ID                                |
| **client.isPayer**                                        | `1` = user completed purchase, `0` = did not purchase |
| **client.platform**                                       | OS or device platform                                 |
| **client.country**                                        | User’s country                                        |
| **client.language**                                       | User’s language                                       |
| **client.utmSource / Medium / Campaign / Term / Content** | UTM parameters if present                             |
| **client.paymentModule**                                  | `generate` for Self-Service, `store` for Marketplace  |
| **client.flowId**                                         | Identifier of the flow where quiz was taken           |
| **client.siteId**                                         | Sales site ID                                         |
| **client.ip**                                             | User IP address                                       |

#### **Question Fields**

| Field                 | Description                                        |
| --------------------- | -------------------------------------------------- |
| **questionId**        | Unique question identifier                         |
| **questionName**      | Friendly name of the question                      |
| **question**          | Question title/text                                |
| **settings**          | Design configuration of the question               |
| **sequence**          | Actual question order                              |
| **displayedSequence** | Order shown to user (after logic/skips)            |
| **required**          | `1` if required, `0` if optional                   |
| **isMultiple**        | `1` if multiple answers allowed                    |
| **typeId**            | Numeric question type                              |
| **typeName**          | Example: `SingleSelection`, `ImageBox`, `Location` |
| **isLogic**           | Whether conditional logic is applied               |

#### **Question types:**

* 0: Single selection
* 2: Image chooser
* 4: Info page
* 5: Date
* 6: Time
* 7: Text input
* 8: Location
* 9: Ending page
* 10: File upload

## **Answer Fields**

| Field                              | Description                                                          |
| ---------------------------------- | -------------------------------------------------------------------- |
| **answers.answerDate**             | When the answer was submitted                                        |
| **answers.answer**                 | Raw answer value (text, date, time, location object, file URL, etc.) |
| **answers.answerOptions.optionId** | Option ID for selectable questions                                   |
| **answers.answerOptions.name**     | Selected option text                                                 |
| **answers.answerOptions.type**     | `text` or `image`                                                    |
| **answers.answerOptions.image**    | Selected option image (if applicable)                                |

{% hint style="info" %}
NOTE: For multilingual funnels, answers are returned in the language used by the user.
{% endhint %}


# Web SDK

Zotlo Web SDK enables you to embed secure checkout experiences and card update flows directly into your website, without redirecting the user away from your interface.

In this section, you can explore the following topics:

<table data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h3>📘</h3></td><td><h4><strong>Web SDK Overview</strong></h4></td><td>Start by exploring the webhooks overview to understand how webhook delivery, retries, security, and activation work.</td><td><a href="/pages/YucYcLTtypPkuB0GBSXV">/pages/YucYcLTtypPkuB0GBSXV</a></td></tr><tr><td><h3>🛒 </h3></td><td><h4><strong>Checkout SDK</strong></h4></td><td>Learn how to receive real-time updates on subscription lifecycle events.</td><td><a href="/pages/vBneLxLG1tZagB87G2Gq">/pages/vBneLxLG1tZagB87G2Gq</a></td></tr><tr><td><h3>💳</h3></td><td><h4><strong>Card Update SDK</strong></h4></td><td>See how to receive callbacks for successful payment events, including one-time payments and subscriptions.</td><td><a href="/pages/f9JsU7N02wyh0seaR4y9">/pages/f9JsU7N02wyh0seaR4y9</a></td></tr></tbody></table>


# SDK Overview

A lightweight JavaScript SDK that allows you to embed secure payment and card-update experiences directly into your website, without handling sensitive financial data on your servers.

The Web SDK powers two core components:

* **Checkout Form SDK** → Embedded payment form for subscription & one-time purchases
* **Card Update SDK** → Allows existing subscribers to update their saved credit cards

Both components are fully PCI-compliant, mobile-responsive, and work seamlessly with Zotlo’s billing engine.

## **What You Can Do With It**

The SDK enables you to:

### **Embed a checkout form**

* Accept subscription and one-time payments
* Use plan-level pricing, trials, country-based currency
* Receive webhook notifications for all transactions
* Customize the form’s design using the `style` config

### **Update saved cards**

* Let subscribers replace their payment card securely
* Trigger 3D Secure flows when needed
* Continue the subscription lifecycle without interruption

### **Track steps of the process**

Through SDK event hooks:

* `onLoad`
* `onSubmit`
* `onSuccess`
* `onFail`
* `onInvalidForm`

## **Where to Find Your Keys**

To initialize any checkout or card-update flow, you need:

#### **🔑 Web SDK Key**

A short-lived, auto-generated token used to start the SDK flow.

You can both live and sandbox keys in:\
**Zotlo Dashboard → Developer Tools → Checkout SDK**

## **How the Web SDK Works**

1. Your backend generates a **Checkout Token** using API Keys
2. You pass this token to the SDK in your web application
3. The SDK renders a PCI-compliant payment form
4. User completes the payment → SDK triggers callbacks
5. Zotlo sends **webhook events** to your server (optional but recommended)

## **Browser Support**

* All modern browsers supported
* Fully responsive mobile & tablet layouts
* Works in single-page apps and server-rendered sites

## **Security & Compliance**

* SDK handles all card data — your servers never touch it
* Fully PCI-DSS compliant
* Secure 3D Secure (3DS) flows handled automatically
* Sensitive fields are encrypted in-browser using Zotlo’s secure payment layer

## **When to Use Web SDK**

Use the SDK if you want:

* Embedded checkout on your own site
* Zero PCI burden
* Fully controlled UI/UX
* Dynamic user-targeted checkout flows
* Card update flows without exposing card info
* Conversion-optimized payment experience

If you prefer redirect flows instead of embedded forms, consider **Hosted Checkout** instead.

## **Related Documentation**

* [**About Embedded Checkout**](/features/checkout/embedded-checkout)
* [**Checkout Form SDK**](/integrating-zotlo/web-sdk/checkout-sdk)
* [**Card Update SDK**](/integrating-zotlo/web-sdk/card-update-sdk)


# Checkout SDK

The Zotlo Web Checkout SDK allows you to display a seamless checkout form inside your web application. Your users can complete their purchase without leaving your site, while Zotlo securely handles payment processing, subscription creation, and 3D Secure (3DS) authentication.

## **Quick Start**

### **1. Install the SDK**

{% code title="NPM" %}

```bash
npm install zotlo-checkout
```

{% endcode %}

{% code title="Yarn" %}

```bash
yarn add zotlo-checkout
```

{% endcode %}

### **2.** Import the SDK

```javascript
import 'zotlo-checkout/dist/zotlo-checkout.css';
import ZotloCheckout from 'zotlo-checkout';
```

### **3.** Initialize Checkout

```javascript
const checkout = await ZotloCheckout({
  token: 'YOUR_CHECKOUT_TOKEN',
  packageId: 'YOUR_PACKAGE_ID',
  returnUrl: 'YOUR_RETURN_URL',
  language: 'en',
  customParameters: {
    myCustomParam: 'OK!'
  },
  events: {
    onSuccess(result) {
      // Payment succeeded
    },
    onFail(error) {
      // Payment failed
    }
  }
});
```

### **4.** Mount Checkout Form

{% code title="HTML" %}

```html
<div id="zotlo-checkout"></div>
```

{% endcode %}

{% code title="JavaScript" %}

```javascript
checkout.mount('zotlo-checkout');
```

{% endcode %}

## Using via CDN

**UNPKG**

{% code title="HTML" %}

```html
<link rel="stylesheet" href="https://unpkg.com/zotlo-checkout/dist/zotlo-checkout.css" />
<script src="https://unpkg.com/zotlo-checkout/dist/zotlo-checkout.min.js"></script>
```

{% endcode %}

**jsDelivr**

{% code title="HTML" overflow="wrap" %}

```html-derivative
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/zotlo-checkout/dist/zotlo-checkout.css" />
<script src="https://cdn.jsdelivr.net/npm/zotlo-checkout/dist/zotlo-checkout.min.js"></script>
```

{% endcode %}

#### **Usage Example**

{% code title="HTML" overflow="wrap" %}

```html
<div id="zotlo-checkout"></div>

<script>
  ZotloCheckout({
    token: 'YOUR_CHECKOUT_TOKEN',
    packageId: 'YOUR_PACKAGE_ID',
    returnUrl: 'YOUR_RETURN_URL',
    language: 'en',
    events: {
      onSuccess(result) {
        alert('Payment Success!');
      },
      onFail(error) {
        alert(error.message);
      }
    }
  }).then(function (checkout) {
    checkout.mount('zotlo-checkout');
  });
</script>
```

{% endcode %}

## **Configuration Parameters**

| Parameter                                           | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **token**                                           | Yes      | Checkout token from Zotlo Dashboard → Developer Tools → Checkout SDK                                                                                                                                                                                                                                                                                                                                                                                      |
| **packageId**                                       | Yes      | ID of the package to be purchased                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **returnUrl**                                       | Yes      | URL to redirect after payment or 3DS                                                                                                                                                                                                                                                                                                                                                                                                                      |
| **subscriberId**                                    | No       | Prefilled subscriber identifier (email, phone, UUID v4)                                                                                                                                                                                                                                                                                                                                                                                                   |
| <p><strong>enableDiscountCodeEntry</strong><br></p> | No       | <p></p><p>Controls whether customers can enter a discount code on the payment form.</p><ul><li><code>true</code> → The <strong>"I have a discount code"</strong> field is displayed and customers can enter a code.</li><li><code>false</code> → The <strong>"I have a discount code"</strong> field is hidden and code entry is disabled.</li><li><code>null</code> → The <strong>Embedded Form settings in the Zotlo Panel</strong> are used.</li></ul> |
| **style**                                           | No       | Custom styling configuration                                                                                                                                                                                                                                                                                                                                                                                                                              |
| **customParameters**                                | No       | Custom key-values sent to webhooks                                                                                                                                                                                                                                                                                                                                                                                                                        |
| **events**                                          | No       | Event listeners during checkout lifecycle                                                                                                                                                                                                                                                                                                                                                                                                                 |

## **Event Listeners**

#### **onLoad**

{% code title="JavaScript" overflow="wrap" %}

```javascript
onLoad?: (params: IFormLoad) => void;
```

{% endcode %}

#### onSubmit

{% code title="JavaScript" overflow="wrap" %}

```javascript
onSubmit?: () => void;
```

{% endcode %}

#### onSuccess

{% code title="JavaScript" overflow="wrap" %}

```javascript
onSuccess?: (result: PaymentDetail) => void;
```

{% endcode %}

#### onFail

{% code title="JavaScript" overflow="wrap" %}

```javascript
onFail?: (error: FailEventData) => void;
```

{% endcode %}

#### onInvalidForm

{% code title="JavaScript" overflow="wrap" %}

```javascript
onInvalidForm?: (error: IFormInvalid) => void;
```

{% endcode %}

## **SDK Methods**

#### **mount(containerId: string)**

Embeds the checkout form into a DOM element.

#### **refresh()**

Reloads the form (e.g., after a style or language update).

#### **unmount()**

Removes checkout form from the DOM.

## **Branding & Styling**

You can override default styles configured in Zotlo Dashboard.

{% code title="JavaScript" overflow="wrap" %}

```javascript
style: {
  design: {
    theme: 'mobileapp',
    borderWidth: 2,
    backgroundColor: '#CCCCCC'
  },
  success: {
    show: true,
    waitTime: 20
  }
}
```

{% endcode %}

More details are available in `IZotloCheckoutStyle`.


# Card Update SDK

The Card Update flow allows you to replace the payment card associated with an active subscription. This is useful when your application manages subscription states internally and you need to give users a secure way to update their billing details without exposing sensitive card data.

Only subscriptions paid with **credit cards** are eligible for card updates.\
One-time purchases are **not supported**.

## **Quick Start**

### **1. Install the SDK**

{% code title="NPM" overflow="wrap" %}

```bash
npm install zotlo-checkout
```

{% endcode %}

{% code title="Yarn" overflow="wrap" %}

```bash
yarn add zotlo-checkout
```

{% endcode %}

### 2. Import and Initialize

{% code title="JavaScript" overflow="wrap" %}

```javascript
import 'zotlo-checkout/dist/zotlo-checkout.css';
import ZotloCard from 'zotlo-checkout/card';

const cardUpdate = await ZotloCard({
  token: 'YOUR_CHECKOUT_TOKEN',
  packageId: 'YOUR_PACKAGE_ID',
  subscriberId: 'SUBSCRIBER_ID',
  returnUrl: 'YOUR_RETURN_URL',
  language: 'en',
  customParameters: {},
  style: {
    design: {
      backgroundColor: '#f5f7fa'
    },
    success: {
      show: true,
      genericButton: {
        url: 'https://yourapp.com/dashboard'
      }
    }
  },
  events: {
    onSuccess(result) {},
    onFail(error) {}
  }
});
```

{% endcode %}

### 3. Mount to a DOM Element

{% code title="HTML" overflow="wrap" %}

```html
<div id="zotlo-card"></div>
```

{% endcode %}

{% code title="JavaScript" overflow="wrap" %}

```javascript
cardUpdate.mount('zotlo-card');
```

{% endcode %}

## Using via CDN

{% code title="HTML" overflow="wrap" %}

```html
<link rel="stylesheet" href="https://unpkg.com/zotlo-checkout/dist/zotlo-checkout.css" />
<script src="https://unpkg.com/zotlo-checkout/dist/zotlo-card.min.js"></script>
```

{% endcode %}

#### **Usage:**

{% code title="JavaScript" overflow="wrap" %}

```javascript
<div id="zotlo-card"></div>

<script>
  ZotloCard({
    token: 'YOUR_CHECKOUT_TOKEN',
    packageId: 'YOUR_PACKAGE_ID',
    subscriberId: 'SUBSCRIBER_ID',
    returnUrl: 'YOUR_RETURN_URL',
    language: 'en'
  }).then(function (cardUpdate) {
    cardUpdate.mount('zotlo-card');
  });
</script>
```

{% endcode %}

## **Configuration Parameters**

These parameters define the configuration options for initializing the Card Update flow.

| Name                 | Required | Description                                                            |
| -------------------- | -------- | ---------------------------------------------------------------------- |
| **token**            | Yes      | Checkout token from Zotlo Dashboard → Developer Tools → Checkout SDK   |
| **packageId**        | Yes      | ID of the subscription package whose card will be updated              |
| **subscriberId**     | Yes      | Subscriber identifier (email, phone number, or UUID v4)                |
| **returnUrl**        | No       | URL to redirect the user after 3DS authentication or after card update |
| **language**         | No       | Interface language (e.g. `en`, `tr`)                                   |
| **customParameters** | No       | Custom key-value parameters sent to webhooks                           |
| **style**            | No       | Custom styling configuration (see below)                               |
| **events**           | No       | Callback events for the update lifecycle                               |

## **Style Configuration**

#### **style.design**

Customize the UI appearance of the card update form.

| Field                  | Required | Description                                     |
| ---------------------- | -------- | ----------------------------------------------- |
| **backgroundColor**    | No       | Background color of the form                    |
| **showLabel**          | No       | Show/hide input labels (boolean)                |
| **adaptDarkMode**      | No       | Automatically adapt to browser dark mode        |
| **buttonColor**        | No       | Background color of primary button              |
| **buttonTextColor**    | No       | Text color of primary button                    |
| **buttonCornerRadius** | No       | Border radius of the main button (px)           |
| **footerFontSize**     | No       | Footer text font size (px)                      |
| **fontType**           | No       | Custom font family (e.g., Inter, Roboto, Arial) |

#### **style.success**

Success screen customization.

| Field                 | Required | Description                            |
| --------------------- | -------- | -------------------------------------- |
| **show**              | No       | Show success screen after card update  |
| **genericButton.url** | No       | Redirect URL for success action button |

{% hint style="info" %}
**Note:** When `success.show = false`, you must handle all redirects inside the `onSuccess` callback.
{% endhint %}

## **Event Listeners**

Events allow you to track user actions and customize the update flow.

#### **onLoad**

Triggered when the card update form is fully loaded.

{% code title="JavaScript" overflow="wrap" %}

```javascript
onLoad?: (params: IFormLoad) => void;
```

{% endcode %}

#### **onSubmit**

Triggered when the form is submitted.

{% code title="JavaScript" overflow="wrap" %}

```javascript
onSubmit?: () => void;
```

{% endcode %}

#### **onSuccess**

Triggered after a successful card update.

{% code title="JavaScript" overflow="wrap" %}

```javascript
onSuccess?: (result: PaymentDetail) => void;
```

{% endcode %}

#### **onFail**

Triggered when the card update fails.

{% code title="JavaScript" overflow="wrap" %}

```javascript
onFail?: (error: FailEventData) => void;
```

{% endcode %}

#### **onInvalidForm**

Triggered if the user submits the form with invalid fields.

{% code title="JavaScript" overflow="wrap" %}

```javascript
onInvalidForm?: (error: IFormInvalid) => void;
```

{% endcode %}

## **Methods**

#### **mount(containerId: string)**

Renders the card update form.

#### **unmount()**

Removes the form from the DOM.

#### **refresh() → Promise**

Refreshes the card update form instance.

## **Notes & Best Practices**

* Only credit-card–based subscriptions support card updates.
* One-time purchases are *not* eligible.
* `returnUrl` is mainly for 3DS authentication.
* If you hide the success screen (`success.show: false`), redirect the user manually using `onSuccess`.


# User Sync

Zotlo allows seamless transitions between **web** and **mobile app** experiences. Whether a user moves from **web → app** or **app → web**, Zotlo ensures that identity, payments, and subscription states stay perfectly synced.

## **Web → App**&#x20;

### **What is Web→App**

Web→App is the flow where a user starts on your **web sales site** and continues the journey inside your **mobile app**.

This commonly occurs after onboarding funnels, quizzes, long-form landings, or pricing pages where the **"Open in App"** or **"Install App"** CTA is displayed after successful payment.

You can explore the Zotlo [Quiz Funnels](/features/quiz-funnels/funnels-flows-overview).&#x20;

### **When To Use**

Use Web→App when you want to:

* Convert mobile web visitors into app users
* Personalize the user journey before app install (quizzes, funnels, offer pages)
* Explain value before pushing users into the app
* Show localized or segmented offers based on country or behavior
* Capture UTM & attribution information **before** users move into the app

Ideal for **Facebook Ads, Google Ads, TikTok Ads, Snapchat, DSP campaigns**.

### **User Sync**&#x20;

When a user later installs/opens the app, Zotlo syncs all related data back into the app.

#### **How syncing happens**

* **Webhooks** → subscription, payment, registration, quiz response events
* **API services** → subscription status, payment history, customer info
* **Custom parameters** → subscriberId, session ID, attribution IDs (AF ID, GAID, IDFA, Adjust ID), language, country

#### **What gets synced**

* Active subscription state
* Renewals & cancellations
* Payment successes & failures
* Registration data
* Quiz answers
* Web purchases matched to the correct app user

### **Ads & Analytics**

Zotlo can forward events to advertising and analytics platforms with **100% web tracking accuracy**, including:

* Meta Ads (Pixel + CAPI)
* Google Ads (Purchase Events)
* TikTok Ads
* Google Analytics
* Google Tag Manager

This ensures Web→App conversions are correctly attributed.

### 🔗 **Useful Documents**

→ [Subscription Status Webhook](/integrating-zotlo/webhooks/subscription-status-webhooks)\
→ [Payments Webhook](/integrating-zotlo/webhooks/payments-webhook)\
→ [Users Webhook](/integrating-zotlo/webhooks/user-registration-webhook)\
→ [Quiz Responses Webhook](/integrating-zotlo/webhooks/quiz-responses-webhook)\
→ [3rd-party Integrations](/3rd-party-integrations/ad-platforms)

## **App → Web**&#x20;

### **What is App→Web**

App→Web is the flow where the user starts inside a **mobile app** and is redirected to a **secure Zotlo web checkout** to complete the purchase.\
This flow is fully compliant with updated **App Store & Google Play rules**, where applicable.

### **When to use**

Use App→Web when you want to:

* Offer payment methods beyond IAP (Card, PayPal, Apple Pay, Google Pay)
* Reduce or avoid app store commissions
* Use a more flexible checkout
* Keep subscription logic fully external to the app
* Redirect users back to your app after payment

Great for global subscription apps or apps that want to legally bypass store fees.

{% hint style="info" %}
**Legal Status**

* **iOS:** Legal in US, EU, South Korea, Netherlands (only dating apps), Japan (only reader apps)
* **Android:** Legal in all UCB-supported markets
  {% endhint %}

### **User Sync**

When redirecting to web checkout, apps can pass the necessary identifiers so the checkout immediately recognizes the user.

#### **Identifiers to pass**

* `subscriberId`
* Language & country
* Custom parameters (AF ID, Adjust ID, internal user ID, session token, campaign data)

#### **How syncing happens**

* **Checkout Web SDK** → send subscriber + custom parameters
* **Personalized Checkout Link API** → generate user-specific URLs
* **Webhooks** → real-time updates after payments
* **API** → verify subscription status from the app

#### **What gets synced back**

* New subscription activations
* Renewals
* Cancellations & grace transitions
* Payment failures
* Entitlements & app-side access rights
* Attribution events

### **Deep Link & Attribution**

After a web payment, Zotlo can send the user back into your app using:

* **Universal Links / Deep Links**
* **Attribution parameters** (AppsFlyer, Adjust, Meta, Google Ads)
* **Custom session identifiers**

This ensures purchases made outside the app are still attributed and applied correctly.

Zotlo also pushes successful web purchases to attribution platforms:\
→ [AppsFlyer Integration](/3rd-party-integrations/attribution/appsflyer)\
→ [Adjust Integration](/3rd-party-integrations/attribution/adjust)

### 🔗 **Useful Documents**

→ [Checkout Web SDK](/integrating-zotlo/web-sdk/checkout-sdk)\
→ [Personalized Checkout Link API](/integrating-zotlo/api-reference/checkout-endpoints)\
→ [Full API Reference](/integrating-zotlo/api-reference/introduction)\
→ [Webhooks Services](/integrating-zotlo/webhooks/webhooks-overview)


# Sandbox Mode

### Test Payment Cards

In sandbox mode, purchases can be made with the following test cards. Expire date and CVV are optional, but the expire date must not be older than the current date.

&#x20;These cards are only valid for credit card payment method. When other payment methods are selected, it is not expected to enter any card information, it is treated as a direct successful payment.

| Card                | Scenario                                               |
| ------------------- | ------------------------------------------------------ |
| 4111 1111 1111 1111 | Purchase successful                                    |
| 4111 1111 1111 1129 | Insufficient card limit.                               |
| 4128 1111 1111 1112 | The transaction was not approved by the bank.          |
| 4125 1111 1111 1115 | The card has expired.                                  |
| 4000 0600 0000 0006 | CVV is incorrect.                                      |
| 4000 1600 0000 0004 | 3DS validation error.                                  |
| 4120 1111 1111 1110 | The transaction was not approved for security reasons. |


# Ad Platforms

Track conversions, optimize campaigns, and improve attribution accuracy by integrating your advertising platforms with Zotlo.

\
In this section, explore how to connect your ad accounts and enable event tracking.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><strong>Meta Ads</strong></h4></td><td>Learn how to integrate Meta Pixel and Meta Conversions API (CAPI) to improve tracking accuracy, reduce data loss, and strengthen attribution.</td><td><a href="/pages/B0UaAC95bkBgQbC8CRUH">/pages/B0UaAC95bkBgQbC8CRUH</a></td><td><a href="/pages/B0UaAC95bkBgQbC8CRUH">/pages/B0UaAC95bkBgQbC8CRUH</a></td></tr><tr><td><h4><strong>Google Ads</strong></h4></td><td>See how to connect Google Ads and automatically track conversions across your checkout links and sales flows.</td><td><a href="/pages/44hi5vcenuwTjDJhWDQ3">/pages/44hi5vcenuwTjDJhWDQ3</a></td><td><a href="/pages/44hi5vcenuwTjDJhWDQ3">/pages/44hi5vcenuwTjDJhWDQ3</a></td></tr></tbody></table>


# Meta Ads

After setting up your project on **Zotlo**, you can integrate **Meta Ads** to enhance your advertising strategies and optimize campaign performance. This integration leverages both **Meta Pixel** and **Meta Conversions API (CAPI)** to ensure data accuracy and improved attribution.

## Pixel vs. CAPI

To maximize your ad efficiency, Zotlo supports both browser-based and server-side tracking mechanisms.

| Feature            | Meta Pixel (Browser-Side)                          | Meta CAPI (Server-Side)                                  |
| ------------------ | -------------------------------------------------- | -------------------------------------------------------- |
| **Mechanism**      | Tracks activity via the user's web browser.        | Sends data directly from Zotlo’s server to Meta.         |
| **Data Source**    | Relies on third-party cookies.                     | Relies on first-party data and server events.            |
| **Privacy Impact** | Affected by ad-blockers and ITP (browser privacy). | Bypasses ad-blockers and browser-based restrictions.     |
| **Reliability**    | May result in data gaps due to cookie loss.        | Provides higher data integrity and accurate attribution. |

{% hint style="success" %}
**Why use both?** Utilizing a hybrid setup (Pixel + CAPI) creates a redundant and robust tracking environment. While Meta Pixel captures behavioral data on-site, CAPI ensures that conversion events are recorded reliably, even when browser-based tracking is blocked.
{% endhint %}

## Integration Steps

Follow these steps to activate the Meta Ads integration within your **Zotlo Panel**:

1. **Navigate to Integrations:** Open the settings page of your Zotlo panel, click the "Integrations" tab.
2. **Select Meta Ads:** Find and select **"Meta Ads"** from the list of available integrations.
3. **Configure Settings:** Enable the integration and choose your preferred tracking type by filling in the required fields:

* **If you want to send only Pixel events:** You only need to fill in the **`Pixel ID`** field.
  * *Where to find:* In **Meta Events Manager**, go to **Data Sources**, select your Pixel, and copy the **ID** shown under the Pixel name.
* **If you want to send both Pixel and CAPI events (Recommended):** You must fill in both the **`Pixel ID`** and the **`Access Token`** fields.
  * *How to generate Access Token:* In **Meta Events Manager**, go to the **Settings** tab of your Pixel. Scroll down to the **Conversions API** section and click **"Generate access token"** under the manual setup heading.

## Tracked Events

The integration automatically sends the following events to Meta. Please note the difference between Pixel and CAPI event coverage:

<table><thead><tr><th width="204.00091552734375">Event Name</th><th align="center">Sent via Pixel</th><th align="center">Sent via CAPI</th><th>Trigger Description</th></tr></thead><tbody><tr><td><strong>PageView</strong> (All Pages)</td><td align="center">✅</td><td align="center">✅</td><td>Triggered for every page load.</td></tr><tr><td><strong>Purchase</strong></td><td align="center">✅</td><td align="center">✅</td><td>Triggered after a successful payment.</td></tr><tr><td><strong>InitiateCheckout</strong></td><td align="center">✅</td><td align="center">❌</td><td>Triggered when the pay button is clicked, before gateway response.</td></tr><tr><td><strong>AddToCart</strong></td><td align="center">✅</td><td align="center">❌</td><td>Triggered when the payment page is viewed.</td></tr><tr><td><strong>AddPaymentInfo</strong></td><td align="center">✅</td><td align="center">❌</td><td>Triggered when the payment page is viewed.</td></tr><tr><td><strong>CompleteRegistration</strong></td><td align="center">✅</td><td align="center">❌</td><td>Triggered after a successful registration.</td></tr><tr><td><strong>Lead</strong></td><td align="center">✅</td><td align="center">❌</td><td>Triggered when the first page of the onboarding funnel is viewed.</td></tr></tbody></table>

## Post-Integration Checklist

**Send CAPI Test Events**

&#x20;To ensure your Server-Side (CAPI) integration is working correctly, you should perform a test:

1. In **Meta Events Manager**, navigate to the **"Test Events"** tab of your Pixel.
2. Look for the **"Test Server Events"** section and copy the **Test Event Code** (e.g., `TEST12345`).
3. Return to your **Zotlo Panel** and find the **"Send CAPI Test Event"** section.
4. Paste your code into the **Test Event Code** field and click **Send**.
5. Go back to Meta Events Manager to confirm that the test event appears in the activity log with the "Server" source.<br>

## **Verification**

After completing the setup, visit the **Meta Events Manager** to verify that events  are being received. Meta automatically deduplicates these events when both Pixel and CAPI are active.


# Google Ads

Integrating **Google Ads** with your **Zotlo** panel allows you to track conversions across all your existing checkout and sales links. This data helps optimize your bidding strategies and provides a clearer view of your Return on Ad Spend (ROAS).

## Integration Steps

Follow these steps to activate the Google Ads integration within your **Zotlo Panel**:

1. **Navigate to Integrations:** In your Zotlo panel, click the **"Integrations"** tab in the side menu.
2. **Select Google Ads:** Find and select **"Google Ads"** from the list of available integrations.
3. **Configure & Activate:** Fill in the fields below with the information from your Google Ads dashboard.

* **Google Tag ID**
  * *Where to find:* In your Google Ads account, go to **Tools** > **Google Tag**. You can find your ID (e.g., `AW-12345678901`). in the installation instructions or the "Your Google Tag" section.
* **Conversion ID**
  * *Where to find:* Go to **Goals** > **Conversions** > **Summary**. Click on your conversion (e.g., Purchase), then click **Tag Setup** > **Use Google Tag Manager**. The ID is listed in the table.
* **Conversion Label**
  * *Where to find:* Found in the same **Use Google Tag Manager** table as the Conversion ID. The alphanumeric string used to identify a specific conversion event.

## Tracked Events

Zotlo currently supports the two most critical events for Google Ads to ensure your conversion data remains clean and focused:

| Event Name               | Trigger Description                                                 |
| ------------------------ | ------------------------------------------------------------------- |
| **PageView** (All Pages) | Triggered for every page load within the checkout and sales funnel. |
| **Purchase**             | Triggered after a payment is successfully completed.                |


# Tiktok Ads


# Analytics

Monitor user behavior, understand funnel performance, and measure key metrics by integrating analytics tools with your Zotlo.

\
In this section, learn how to connect your analytics platforms and start receiving real-time events from Zotlo.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><strong>Google Analytics</strong></h4></td><td><p>Learn how to send checkout, subscription, and purchase events directly to Google Analytics 4.</p><p><br>Use this guide to analyze user journeys, track conversion funnels, and measure performance across your sales flows.</p></td><td><a href="/pages/wI7bPnMJIBYW2taUgnIx">/pages/wI7bPnMJIBYW2taUgnIx</a></td><td><a href="/pages/wI7bPnMJIBYW2taUgnIx">/pages/wI7bPnMJIBYW2taUgnIx</a></td></tr><tr><td><h4><strong>Google Tag Manager</strong></h4></td><td><p>See how to integrate GTM to manage all your marketing and tracking tags in one place.</p><p><br>This setup enables flexible deployment of analytics tools, pixels, and custom scripts across your Zotlo pages.</p></td><td><a href="/pages/cpj4WixNvervPvlfeyaa">/pages/cpj4WixNvervPvlfeyaa</a></td><td><a href="/pages/cpj4WixNvervPvlfeyaa">/pages/cpj4WixNvervPvlfeyaa</a></td></tr></tbody></table>


# Google Analytics

Integrating **Google Analytics (GA4)** allows you to track how visitors interact with your site. It helps you understand where your users come from, which steps of your quiz they complete, and where they drop off before making a purchase. By using this data, you can improve your sales funnel and increase your conversion rates.

## Integration Steps

1. **Open Integrations:** In your Zotlo panel, click the **"Integrations"** tab in the side menu.
2. **Select Google Analytics:** Find Google Analytics in the list.
3. **Enter your ID:** Paste your code into the **GA4  ID** field and save.

## **GA4 Measurement ID**

* It is a unique identifier (format: `G-XXXXXXXXXX`) that tells Google where to send your website's data.
* **Where to find it**

  &#x20;1\. Log in to your [Google Analytics](https://analytics.google.com/) account. \
  2\. Go to **Admin** > **Data Streams**. \
  3\. Select your website stream. \
  4\. Copy the **Measurement ID** from the top right corner.

## Events Tracked

Once activated, Zotlo automatically sends these actions to your Google Analytics account:

| Activity        | What is tracked?                                                                     |
| --------------- | ------------------------------------------------------------------------------------ |
| **Visits**      | Every time a user loads a page in your funnel.                                       |
| **Quiz/Survey** | Button clicks, selected answers, and navigation through the quiz steps.              |
| **User Info**   | Successful email entries or errors when a user types an invalid email.               |
| **Payment**     | Interactions on the payment page, including credit card input errors and API issues. |
| **Sales**       | Successful payments and subscription starts.                                         |
| **General**     | Footer links, homepage buttons, and clicks on the "Success" page.                    |

## Custom Events

Zotlo automatically pushes granular events to the `window.dataLayer` and your GA4 property based on user interactions:

| Page / Step                               | Action        | Description                                                                          |
| ----------------------------------------- | ------------- | ------------------------------------------------------------------------------------ |
| **Homepage( first page of quiz funnels)** | `customClick` | Clicks on homepage buttons (e.g., "Start") including specific button IDs.            |
| **Survey (Quiz)**                         | `customClick` | Navigation clicks to the next question page.                                         |
| **Survey (Quiz)**                         | `answer`      | User responses to questions (single or multiple choice).                             |
| **Registration**                          | `Success`     | Successful email submission.                                                         |
| **Registration**                          | `error`       | Failed email entry attempts and validation errors.                                   |
| **Payment**                               | `customClick` | Clicks on the payment page elements.                                                 |
| **Payment**                               | `error`       | Technical issues including API errors, payment failures, and server response errors. |
| **Success Page**                          | `customClick` | Clicks on "Thank You" page buttons (e.g., "Go to App").                              |
| **Success Page**                          | `customClick` | Clicks on footer links or shared homepage/success page links.                        |

## Purchase Tracking

For successful transactions, Zotlo sends specialized purchase events to ensure accurate revenue tracking:

* **Purchase (`purchase`):** Triggered after a successful payment. Includes full transaction data: `transaction_id`, `value`, `currency`, and `items` (Package ID, name, package period).
* **Subscription Started (`subscription_started`):** A custom event triggered specifically when a new subscription-based product is successfully purchased.


# Google Tag Manager

## Why use GTM?

**Google Tag Manager (GTM)** is a powerful tool that allows you to manage and deploy marketing tags (pixels or code snippets) on your site without modifying the code directly. By integrating GTM with Zotlo, you can capture detailed user interactions from our **Data Layer** and send them to any third-party platform (such as TikTok, Pinterest, or custom analytics) with ease.

## Integration Steps

Follow these steps to activate the GTM integration within your **Zotlo Panel**:

1. **Navigate to Integrations:** In your Zotlo panel, click the **"Integrations"** tab in the side menu.
2. **Select Google Tag Manager:** Find **"Google Tag Manager"** from the list of available integrations.
3. **Configure & Activate:** Fill in the fields below with your GTM container information.

## **Configuration Requirements**

* **GTM Code (Tag ID)**
  * Your unique GTM container identifier (e.g., `GTM-KB68GJ5`).
  * *Where to find:* Log in to your [Google Tag Manager](https://tagmanager.google.com/) account. Your **Tag ID** is displayed at the top of the workspace, next to the "Preview" and "Submit" buttons.
* **Custom Domain (Optional)**
  * *What it is:* If you are using a server-side tagging setup with a custom subdomain (e.g., `https://gtm.yourdomain.com`), enter it here.

{% hint style="info" %}
Once activated, Zotlo will automatically begin pushing events to your GTM container across all existing checkout and sales links.
{% endhint %}


# Attribution

Track the true source of your users, optimize acquisition funnels, and improve campaign attribution by integrating leading mobile measurement partners with Zotlo.

\
In this section, you’ll learn how to send subscription, payment, and registration events to your attribution platform.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-type="content-ref"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><strong>AppsFlyer</strong></h4></td><td><p>Send key lifecycle events, such as registration, checkout events, subscriptions, renewals, and refunds to AppsFlyer for precise attribution and campaign optimization.</p><p><br>Use this guide to map Zotlo events to AppsFlyer schemas and verify event delivery.</p></td><td><a href="/pages/wZlxRCVExYUO80P1GhG5">/pages/wZlxRCVExYUO80P1GhG5</a></td><td><a href="/pages/wZlxRCVExYUO80P1GhG5">/pages/wZlxRCVExYUO80P1GhG5</a></td></tr><tr><td><h4><strong>Adjust</strong></h4></td><td><p>Integrate Adjust to attribute users accurately across your sales flows.</p><p><br>This guide helps you send purchase and subscription events from Zotlo to Adjust, improving ROAS tracking and campaign performance.</p></td><td><a href="/pages/OoesHFYySjYiYV2boY6l">/pages/OoesHFYySjYiYV2boY6l</a></td><td><a href="/pages/OoesHFYySjYiYV2boY6l">/pages/OoesHFYySjYiYV2boY6l</a></td></tr></tbody></table>


# AppsFlyer

Integrating **AppsFlyer** with Zotlo allows you to bridge the gap between your mobile app and web-based checkout flows. This integration ensures that user journeys starting in your app and ending on a Zotlo payment page are accurately attributed and tracked.

## Integration Steps

Follow these steps to activate the AppsFlyer integration within your **Zotlo Panel**:

1. **Navigate to Integrations:** In your Zotlo panel, click the **"Integrations"** tab in the side menu.
2. **Select AppsFlyer:** Find AppsFlyer from the list of available integrations.
3. **Configure OS Settings:** Choose the operating system (**iOS** or **Android**) you want to configure.
4. **Enter Credentials:** Fill in the **App ID** and **App Secret** provided by your AppsFlyer dashboard for the selected OS.
5. **Map Your Events:** Define which Zotlo events (e.g., Trial Converted to Paid,  Payment Page Viewed) you want to send and specify the corresponding event names used in your AppsFlyer setup.
6. **Activate:** Click the **Activate** button to save and enable the data flow.

## Required Parameters

To accurately match mobile users with web activities (App-to-Web redirection), you must pass specific identifiers through the Zotlo checkout URL.

| Parameter          | Required on iOS? | Required on Android? | Description                                                             |
| ------------------ | :--------------: | :------------------: | ----------------------------------------------------------------------- |
| **`appsflyer_id`** |       ✅ Yes      |         ✅ Yes        | Unique ID assigned by AppsFlyer; essential for cross-platform matching. |
| **`idfa`**         |    ⚠️ Optional   |         ❌ No         | iOS Advertising ID; only available if Apple ATT permission is granted.  |
| **`idfv`**         |  🆗 Recommended  |         ❌ No         | iOS Vendor Identifier; provides a stable fallback for matching.         |
| **`gpsAdid`**      |       ❌ No       |         ✅ Yes        | Android Advertising ID (Google Play Services).                          |

## URL Structure & Implementation

To send these parameters to Zotlo, you must include them within the `customParameters[mmp]` array in your checkout link.

**Example Checkout Link with AppsFlyer ID:** `https://zotlo.checkout.com/payment/[YOUR_PAYMENT_ID]?customParameters[mmp][appsflyer_id]=123456789-0123`

**Recommended Minimum Data Set:**

* **For iOS:** Pass `appsflyer_id`, `idfv`, and `idfa` (if available).
* **For Android:** Pass `appsflyer_id` and `gpsAdid`.

{% hint style="success" %}
**Pro Tip:** Ensure that your mobile app correctly captures the `appsflyer_id` and appends it to the Zotlo URL when redirecting users to the payment page. This is the most critical step for successful attribution.
{% endhint %}


# Adjust

Integrating **Adjust** with Zotlo allows you to seamlessly bridge the gap between your mobile app and web-based checkout flows. This integration ensures that user journeys starting in your app and ending on a Zotlo payment page are accurately attributed and tracked.

## Integration Steps

Follow these steps to activate the Adjust integration within your **Zotlo Panel**:

1. **Navigate to Integrations:** In your Zotlo panel, click the **"Integrations"** tab in the side menu.
2. **Select Adjust:** Find Adjust from the list of available integrations.
3. **Enter App Token:** Enter the **App Token** you obtained from your Adjust dashboard.
   * *Where to find:* Log in to your Adjust dashboard, select your app, and navigate to the **Settings** page at the top.
4. **Map Your Events:** Specify which Zotlo events you want to send and enter the corresponding event names used in your Adjust setup.
5. **Activate:** Click the **Activate** button to save and enable the integration.

## Required Parameters

To accurately match mobile users with web activities (App-to-Web redirection), you must pass specific identifiers through the Zotlo checkout URL.

| Parameter     | Required on iOS? | Required on Android? | Description                                                            |
| ------------- | :--------------: | :------------------: | ---------------------------------------------------------------------- |
| **`adid`**    |       ✅ Yes      |         ✅ Yes        | Unique user ID assigned by Adjust; essential for App-to-Web matching.  |
| **`idfa`**    |    ⚠️ Optional   |         ❌ No         | iOS Advertising ID; only available if Apple ATT permission is granted. |
| **`gpsAdid`** |       ❌ No       |         ✅ Yes        | Android Advertising ID (Google Play Services).                         |

## URL Structure & Implementation

To send these parameters to Zotlo, you must include them within the `customParameters[mmp]` array in your checkout link.

**Example Checkout Link with Adjust ID:** `https://zotlo.checkout.com/payment/[YOUR_PAYMENT_ID]?customParameters[mmp][adid]=3f4e1a2b5c6d7e8f9a0b1c2d3e4f5678`

**Recommended Minimum Data Set:**

* **For iOS:** Pass `adid` and `idfa` (if available).
* **For Android:** Pass `adid` and `gpsAdid`.

{% hint style="success" %}
**Pro Tip:** Ensure that your mobile app captures the `adid` and appends it to the Zotlo URL when redirecting users to the payment page. This ensures the highest level of attribution accuracy for your campaigns.
{% endhint %}