Welcome to ParityVend's documentation! ====================================== **NOTE: Please visit the [ParityVend Docs on our website](https://www.ambeteco.com/ParityVend/docs/index.html) to view the full ParityVend documentation.** [What is ParityVend](https://www.ambeteco.com/ParityVend/docs/index.html#what-is-parityvend) -------------------------------------------------------------------------------------------------------------------- ParityVend is a revolutionary tool designed to take your business to new heights by making your pricing adaptive. By detecting the location of every visitor to your website, ParityVend dynamically adjusts the pricing of your products to ensure fairness and balance for each visitor's country. In countries with varying purchasing power, it's essential to adapt product prices to align with the local economy. ParityVend solves this challenge by dynamically adjusting prices, ensuring fairness for all visitors, regardless of their location. Implementing ParityVend can lead to a significant boost in sales, profits, reach, and popularity for your business. Unlock the full potential of your business on a global scale by getting started with ParityVend. ParityVend - the key to your global success. [Learn more about the powerful features of ParityVend on its website.](https://www.ambeteco.com/ParityVend/) [ParityVend Solutions](https://www.ambeteco.com/ParityVend/docs/index.html#parityvend-solutions) ------------------------------------------------------------------------------------------------------------------------ ParityVend has two powerful solutions that you can use to integrate ParityVend on your website, No-Code and API. ### [ParityVend No-Code](https://www.ambeteco.com/ParityVend/docs/index.html#parityvend-no-code) Integrate ParityVend No-Code to display 'discount banners' on your website, offering coupons to visitors from countries with lower purchasing power. The No-Code solution is easy to integrate and can be implemented in less than 7 minutes. The No-Code solution offers 99 hand-crafted designs, 13 text templates, and 10 country grouping methods, making it a perfect fit for solopreneurs, low-code businesses, startups, and small companies. ### [ParityVend API](https://www.ambeteco.com/ParityVend/docs/index.html#parityvend-api) Utilize ParityVend API to build robust, secure, and flexible integrations, even for the most demanding or unique pricing flows. ParityVend API features advanced security and scalability, enabling you to build exceptional abuse-proof systems. The ParityVend API is the preferred choice for startups, SaaS companies, and enterprises seeking advanced pricing solutions. [How to Begin](https://www.ambeteco.com/ParityVend/docs/index.html#how-to-begin) -------------------------------------------------------------------------------------------------------- Are you prepared to take your business to the global level? Starting with ParityVend is straightforward. Our ["Getting Started"](https://www.ambeteco.com/ParityVend/docs/getting_started.html) guide is tailored for beginners, making it easy for you to navigate through the process. This comprehensive guide will lead you through the setup process step by step, enabling you to seamlessly integrate ParityVend into your business. Access the "[Getting Started with ParityVend](https://www.ambeteco.com/ParityVend/docs/getting_started.html)" guide now to begin your successful journey with ParityVend. [Need help?](https://www.ambeteco.com/ParityVend/docs/index.html#need-help) --------------------------------------------------------------------------------------------------- If you come across any issues or challenges during the integration process, we recommend referring to this documentation as your first resource. It provides comprehensive guidance to help you troubleshoot and resolve any errors you may encounter. If you require further support, our team is always ready to assist you. Feel free to [contact us](https://www.ambeteco.com/ParityVend/contact-us/) for personalized assistance to ensure a seamless integration experience or view the FAQ section at [ParityVend Support](https://www.ambeteco.com/ParityVend/support/). API Tutorial ============ *Average read time: 19 minutes* After completing the "Getting Started" guide, the next step is to integrate the ParityVend API into your website. This guide will walk you through the API basics that you need to know to start and also provide some examples and "recipes" that will help you integrate the ParityVend API into your project. We highly recommend that you read the full API overview before starting to use the ParityVend API in your application. [Getting Your API Keys](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#getting-your-api-keys) --------------------------------------------------------------------------------------------------------------------------------------------- To start using the ParityVend API, you first need to obtain the API keys that ParityVend has generated for you. Follow the simple steps below to get your API keys. ### [Step 1: Open the API Window](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#step-1-open-the-api-window) Access the 'API' window: you can always view the API keys for all your projects in this window. Additionally, you can re-issue your keys there. To open it, follow these steps: > 1. Go to the Dashboard. > > > 2. In the menu, click on "API". > > > 3. Scroll down until you see your project with the API keys. ### [Step 2: Copying Your Keys](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#step-2-copying-your-keys) Once you see your project with the three keys, you can click on any key to copy it to the clipboard. Now, let's continue to the next section to examine each key and its uses. [Explanation of API Keys](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#explanation-of-api-keys) ------------------------------------------------------------------------------------------------------------------------------------------------- ParityVend API uses a pair of `public_key` and `private_key`, along with a special token called `testing_secret`. See the explanation below to learn what those keys are and where they should be used. > `public_key`: > > - Can be freely shared and is intended to be seen by anyone. > > > - Gives limited access to the API. > > > - Should be used on the frontend of your website/web-applications. > `private_key`: > > - Must be kept secure; never share it with anyone. > > > - Gives you full access to the API. > > > - Should be used only on your backend (where you can ensure the security of the key). > `testing_secret`: > > - Enables the special "testing mode" for the `public_key`. > > > - Disables security measures and is required for testing on localhost. > > > - Remove it from the public source code before going live. > > > - Never use it in production, as it imposes security risks. Note Never share `private_key` and `testing_secret` with anyone, and keep them secure. Never use `private_key` on your frontend, or anywhere where the public can see or access it. Never leave "testing mode" enabled on production/live websites. [ParityVend API: "Hello World"](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#parityvend-api-hello-world) ---------------------------------------------------------------------------------------------------------------------------------------------------------- After you have your API keys, let's do a traditional "hello world" for the ParityVend API. But first, let's understand the structure of the ParityVend API and its basics. ### [Structure of the API](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#structure-of-the-api) ParityVend API is split into two groups: backend and frontend: > Backend group: > > - Offers 7 endpoints. > > > - Each request must be authenticated with your `private_key`. > > > - Endpoints give you full access to the API. > > > - Meant to be used from your server. > > > - As highlighted in the name, it should be used only on your backend (or where you can ensure the security of the `private_key`). > Frontend group: > > - Offers 4 endpoints (plus 4 for "testing mode"). > > > - Each request must be authenticated with your `public_key`. > > > - Meant to be used on the devices of your clients/visitors. > > > - Endpoints give you limited access to the API. > > > - As highlighted in the name, it should be used on your frontend. > > > - Offers special testing mode that disables certain security checks that are required for running on `localhost`. All endpoints have a similar request structure, where the key (whether it's `public_key` or `private_key`) is always the first in the request fields. After that, the endpoint may accept other required or additional arguments. All requests should be completed as a simple GET. Endpoints return JSON, which always has a `"status"` key that can be equal to either `"ok"` or `"error"`, indicating whether the request was completed successfully or with an error. ### [Your First Request with ParityVend API](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#your-first-request-with-parityvend-api) Now, let's try to make your first "hello world" request with the ParityVend API! This is the URL of the `get-quota-info` endpoint. It provides information about your account's current quota information. Also, making requests to this endpoint does not count against your quota usage (good news for you). To form your hello world request to the `get-quota-info` endpoint, take the URL below and change `<YOUR_PRIVATE_KEY>` with your actual private_key you copied in the earlier steps: > `https://api.parityvend.cloud/backend/get-quota-info/<YOUR_PRIVATE_KEY>/` After you insert your private key, simply open this URL in any browser. Uou can also use any HTTP client (such as curl, wget, etc.), or any HTTP request library (such as `requests`, `axios`, `httpx`, etc) and make a GET request to this URL. You will get a JSON response similar to this, where you will find your current quota information: [Example response from the `get-quota-info` endpoint:](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#id1 "Link to this code") `{"status": "ok","quota_limit": 1500000,"quota_used": 0,"quota_left": 1500000}` Congrats! You have just made your first ParityVend API request! This means that everything works correctly, and you are good to go! You are ready to move on to the next section. Hint If you get an error when you make this request, first check whether you have entered your `private_key` correctly; ensure that you did not accidentally enter any trailing spaces. If you still get an error, refer to the "[Debugging Guide](https://www.ambeteco.com/ParityVend/docs/debugging_guide.html)". [Brief Overview of Endpoints](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#brief-overview-of-endpoints) --------------------------------------------------------------------------------------------------------------------------------------------------------- In this section, we will briefly overview backend and frontend endpoints. Let's start with the backend group, which has a total of 7 endpoints. ### [Backend: Primary Endpoints](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#backend-primary-endpoints) 4 primary endpoints. Used to provide discount functionality to your pricing flows. The responses they return are closely related. > `/backend/get-country-from-ip/` > > - Takes in any IP address as an input and returns the identified country in the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). One special return case is `XX`, which means that the visitor uses a VPN, Proxy, or TOR. > > > > Auth: private_key Output: JSON > > Input argument 1: IP-address > `/backend/get-discount-from-ip/` > > - Takes in any IP address as an input and returns discount information if you have configured it to offer discounts for the IP's country. It uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: private_key Output: JSON > > Input argument 1: IP-address > > Input argument 2: Base currency (optional, default=USD) > `/backend/get-banner-from-ip/` > > - Takes in any IP address as an input and returns a rendered HTML banner. This is the same HTML banner that is used by the No-Code solution, except that this is a backend version that works from the input IP address. It uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: private_key Output: HTML > > Input argument 1: IP-address > > Input argument 2: Base currency (optional, default=USD) > `/backend/get-discount-with-html-from-ip/` > > - Takes in any IP address as input and returns both discount information and an HTML banner. You can think of it as a blend of the previous two endpoints. It uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: private_key Output: JSON > > Input argument 1: IP-address > > Input argument 2: Base currency (optional, default=USD) ### [Backend: Miscellaneous endpoints](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#backend-miscellaneous-endpoints) 3 miscellaneous endpoints. They can be related to your account, project, or metadata. > `/backend/get-quota-info/` > > - Returns quota information for your account, including how much you have used and how much quota you have left. > > > > Auth: private_key Output: JSON Quota-free > > Input: Does not take any input > `/backend/get-discounts-info/` > > - Returns discount information about the country groups you have configured for the current project. For each country, a coupon and discount percentage are attached. > > > > Auth: private_key Output: JSON > > Input: Does not take any input > `/backend/get-exchange-rate-info/` > > - Returns a dictionary for 170 world currencies with the base currency being USD, all in the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). It takes one optional argument, `base currency`, which is used as a "base" for the returned dictionary, where all currencies returned are calculated against the base currency. By default, the base currency is set to USD. > > > > Auth: private_key Output: JSON Plan: only for paid plans > > Input argument 1: Base currency (optional, default=USD) ### [Frontend: Primary Endpoints](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#frontend-primary-endpoints) The Frontend group offers four primary endpoints. These are used to provide discount functionality to your pricing flows, directly integrated into the frontend of your website. These endpoints are meant to be used by the users/visitors of your websites directly from their devices. Therefore, they don't take an "IP-address" as input, as the IP-address is detected automatically from the visitor's device. The responses they return are closely related. > `/frontend/get-country/` > > - Returns the identified country of the requestor's IP-address in the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. One special return case is `XX`, which means that the visitor uses a VPN, Proxy, or TOR. > > > > Auth: public_key Output: JSON > > No arguments > `/frontend/get-discount/` > > - Uses the requestor's IP-address and returns discount information if you have configured it to offer discounts for the requestor's country. Uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: public_key Output: JSON > > Input argument 1: Base currency (optional, default=USD) > `/frontend/get-banner/` > > - Uses the requestor's IP-address and returns a rendered HTML banner. This is exactly the endpoint used by the No-Code solution to deliver HTML banners to the websites. Uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: public_key Output: HTML > > Input argument 1: Base currency (optional, default=USD) > `/frontend/get-discount-with-html/` > > - Uses the requestor's IP-address and returns both discount information and an HTML banner. You can think of it as a blend of the previous two endpoints. Uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: public_key Output: JSON > > Input argument 1: Base currency (optional, default=USD) Each endpoint listed above has a "mirror" version of itself, with `testing-mode-` added to its name. Namely, `/frontend/testing-mode-get-banner/`, `/frontend/testing-mode-get-country/`, `/frontend/testing-mode-get-discount/`, and `/frontend/testing-mode-get-discount-with-html/`. These are the special "testing mode" versions of the frontend endpoints group, to which you can add a `testing-secret` parameter to enable the testing mode. This allows you to test and debug your integration on `localhost`, `127.0.0.1`, or any other domain. The live versions of the endpoints will simply not work anywhere outside your website, meaning that you would not be able to use them on `localhost` while testing your integration on your local development environment. Learn more about how to use the testing mode on the "[ParityVend Testing Mode](https://www.ambeteco.com/ParityVend/docs/testing_mode.html)" page. [Integration ideas](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#integration-ideas) ------------------------------------------------------------------------------------------------------------------------------------- Unlock the full potential of your business with the versatile capabilities of the ParityVend API. Below, you'll discover a range of innovative ways to leverage this powerful tool to enhance your website's functionality and drive business growth. From building an abuse-proof checkout system to dynamically adjusting product prices based on visitor location, the ParityVend API offers a myriad of features, that can be used to optimize the user experience, prevent fraud, and personalize interactions. Explore the following ideas to see how you can harness the power of location-based data to create a more tailored and secure online environment for your customers: Build Abuse-Proof Checkout: We highly recommend integrating the ParityVend API into your website's checkout process to prevent abuse of discounts. While offering coupons with discounts can help expand your business globally, it's important to protect against coupon code sharing. By incorporating the `/backend/get-discount-from-ip/` or `/backend/get-country-from-ip/` endpoint from the ParityVend API, you can verify the user's location at checkout and ensure that their coupon code is valid for that location (e.g., India). This implementation will create a secure and abuse-proof system for your business. Dynamic Pricing: Use the ParityVend API for its primary goal: to dynamically adjust product prices based on the visitor's location. This ensures fairness and balance by aligning prices with the local economy. For this case, you can use the `/frontend/get-discount/` or `/backend/get-discount-from-ip/` endpoints. Personalized Offers: Leverage ParityVend's location detection capabilities to dynamically present targeted discounts and promotions to website visitors based on their country, potentially increasing sales and conversion rates. Potentially useful endpoints: `/frontend/get-discount/` or `/backend/get-discount-from-ip/`. Enhanced Fraud Prevention: Use ParityVend API to identify and block activity associated with VPNs and proxies, offering enhanced protection against fraudulent transactions within payment-related workflows. Consider `/backend/get-country-from-ip/` endpoint to detect suspicious IP addresses. Access Control based on Location: The ParityVend API can be used to empower website owners to implement location-based access restrictions, potentially blocking suspicious activity or anonymized traffic (e.g., VPN usage) from accessing specific website sections. Utilize the `/backend/get-country-from-ip/` endpoint to detect the visitor's country. Localized Currency Display: ParityVend API can facilitate automatic product price display in the visitor's local currency, enhancing the user experience and potentially improving conversion rates by eliminating the need for mental currency conversions. Think about the `/frontend/get-discount/` or `/backend/get-discount-from-ip/` endpoints, as well as the `/backend/get-exchange-rate-info/` endpoint to retrieve exchange rate information. Location-Specific Welcome Offers: The ParityVend API enables you to create personalized welcome offers and discounts for first-time visitors based on their country, potentially fostering a positive first impression and encouraging engagement. For this idea, `/frontend/get-discount/` or `/backend/get-discount-from-ip/` endpoints can be useful. Location-Aware Content Optimization: The ParityVend API can empower website owners to dynamically adjust website content, promotions, and even language options based on the visitor's location, potentially improving user experience and engagement. Leverage endpoints like `/frontend/get-country/` or `/backend/get-country-from-ip/` endpoints to detect the visitor's country. Personalized Product Recommendations: ParityVend's API's location data and purchasing power insights can be leveraged to dynamically recommend products relevant to the visitor's cultural context and financial realities, potentially increasing cross-selling and upselling opportunities. Use the `/backend/get-country-from-ip/` endpoint to detect the visitor's country. [Integration Example](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#integration-example) ----------------------------------------------------------------------------------------------------------------------------------------- After providing a brief overview of the ParityVend API endpoints, we can proceed with the actual integration of the API into your website. We will provide examples and "recipes" to help you successfully build a pricing flow with the ParityVend API. Some examples will demonstrate the true flexibility of ParityVend by illustrating how to make use of both the ParityVend No-Code and ParityVend API simultaneously. Note All integration examples assume that you have already obtained your API keys. Additionally, these examples assume that you have created a "default" project, meaning that you have not made any changes to the country groups or discounts. If you have made changes, simply create a new project for learning purposes and use the domain "example.com". ### [Integration Example: Custom Pricing Page](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#integration-example-custom-pricing-page) In this example, we will explain how to use the ParityVend API to create an adaptive pricing page for your product using the `/frontend/get-discount/` endpoint. This example focuses on the `frontend` group endpoint. #### [Step 1: Preparation](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#step-1-preparation) Suppose you have a wonderful pricing page on your website for your *product A*. Currently, your pricing is fixed and shows the same prices to all people. Let's make it adaptive and integrate the ParityVend API to automatically make this pricing fairer, more accessible, and more profitable! - If you wish to follow this example locally, create a file named `pricing.html` and copy the initial code below into it. - Don't forget to insert your `public_key` and `testing_secret` when you copy the example code. - Later in this tutorial, only parts of the code will be shown for convenience. For each code block, you will see a link "view full HTML" that you can use to access the complete HTML code. Here is an initial pricing page (click to expand): Initial pricing page (pricing.html) [](https://www.ambeteco.com/ParityVend/docs/_static/examples/custom_pricing/pricing_1_0.html.txt)[](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#id2 "Link to this code") [![Step 1 - shows initial pricing page](https://www.ambeteco.com/ParityVend/docs/_images/e1_s1.png)](https://www.ambeteco.com/ParityVend/docs/_images/e1_s1.png) As you can see, this pricing page has prices *hardcoded* in it. To make it adaptive and integrate the ParityVend API, we first need to ensure that you store your prices in a programmatic way. There are multiple ways to do it. For example, you could store your prices in a simple variable, something like `const prices = { ... }`, or as an HTML attribute like this: `...`. Let's create a variable that holds our prices and use the attribute on the price element to get the correct price. We'll make some changes to the pricing page's `<head>` element to include a `<script>` with some JavaScript code and also add the attribute `data-plan` to each price ``. Pricing page v1.1 - move prices to a JS variable: [(view full HTML for pricing_1_1.html)](https://www.ambeteco.com/[ParityVend/docs/_static/examples/custom_pricing/pricing_1_1.html.txt)](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#id3 "Link to this code") `...<script>window.addEventListener('DOMContentLoaded', function () {const prices = {lite: 9.0,pro: 15.0,enterprise: 29.0,}const priceSpans = document.querySelectorAll('.plan-price');for (let i = 0; i < priceSpans.length; i++) {const priceSpan = priceSpans[i];let price = prices[priceSpan.dataset.plan];priceSpan.textContent = '$' + price.toFixed(0);}});</script></head><body>...

$9/ mo

...

$15/ mo

...

$29/ mo

...` When you refresh the page, you'll notice that the pricing page appears unchanged. However, behind the scenes, a significant change has occurred. The page has taken its first step towards becoming adaptive. By storing prices as variables, we have paved the way for integrating the ParityVend API into the pricing page. [![Step 1 - Pricing page still looks the same](https://www.ambeteco.com/ParityVend/docs/_images/e1_s1.png)](https://www.ambeteco.com/ParityVend/docs/_images/e1_s1.png) #### [Step 2: Integrating ParityVend API](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#step-2-integrating-parityvend-api) Let's modify the `<script>` and add some ParityVend API integration code that will use the `/frontend/get-discount/` endpoint to automatically get the discounts based on the visitor's location and then change our prices based on this discount. A simple and quick way to do it could be this. A quick write-down of what is changed: - Add a `getDiscount` function that uses the `/frontend/get-discount/` endpoint to get discount information for the visitor. - A `discount-label` element and some styles for it, which will be used to display discount information to the visitors where ParityVend is active. - Finally, modify the price-changing code to apply the discount from ParityVend API. Don't forget to change this code to replace `<YOUR PUBLIC KEY>` with your actual public_key! Pricing page v1.2 - Adding ParityVend API: yay! [(view full HTML for pricing_1_2.html)](https://www.ambeteco.com/[ParityVend/docs/_static/examples/custom_pricing/pricing_1_2.html.txt)](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#id4 "Link to this code") `<style>...#discount-label {font-weight: 500;background-color: rgba(191, 202, 214, 0.31);padding: 1rem;border-radius: 2rem;display: none;}</style><script>async function getDiscount() {let url = "https://api.parityvend.cloud/frontend/get-discount/";url += '<YOUR PUBLIC KEY>';const response = await fetch(url);const jsonData = await response.json();if (jsonData.status !== "ok") {console.error("ParityVend API returned an error:",JSON.stringify(jsonData));return;}if (jsonData.discount) {return {discount: jsonData.discount,discount_str: jsonData.discount_str,conversion_rate: jsonData.currency.conversion_rate,symbol: jsonData.currency.symbol,country: jsonData.country.name,}}}window.addEventListener('DOMContentLoaded', async function () {const prices = {lite: 9.0,pro: 15.0,enterprise: 29.0,}const priceSpans = document.querySelectorAll('.plan-price');const discountInfo = await getDiscount();const discountLabelElm = document.getElementById('discount-label');if (discountInfo) {discountLabelElm.textContent = `It seems you are from ${discountInfo.country}. We support PPP and want to make our prices fair for everyone, so we have applied a ${discountInfo.discount_str} discount for you!`;discountLabelElm.style.display = 'block';} else {discountLabelElm.style.display = 'none';}for (let i = 0; i < priceSpans.length; i++) {const priceSpan = priceSpans[i];let price = prices[priceSpan.dataset.plan];if (discountInfo) {newPrice = price * (1- discountInfo.discount);priceSpan.textContent = '$' + newPrice.toFixed(2);} else {priceSpan.textContent = '$' + price.toFixed(0);}}});</script></head><body>...

Making your pricing adaptive is easy with ParityVend!

...` Amazing! Now, when you open this pricing page in your browser, you will see that... it doesn't work. Why? [![Step 2 - An error in the console](https://www.ambeteco.com/ParityVend/docs/_images/e1_s2.png)](https://www.ambeteco.com/ParityVend/docs/_images/e1_s2.png) If you open the Console of your browser's devtools, you will see an error message, saying that ParityVend API has returned a non-OK response. Let's read the response's error message: > `"error_msg": "You are not authorized to use this API key from the given website"` Why does it happen? The reason for this behavior is that you are likely viewing this pricing page example on your local development environment, which could be a `localhost` or `127.0.0.1` domain if you are running it on a server, or simply a local file (`file://`) that you have opened in your browser. ParityVend employs a security feature known as Origin Checking to enhance the integrity of your integration. As part of this feature, ParityVend automatically examines all request headers, specifically the `Origin` header. This mechanism is crucial in preventing unauthorized use of your integration by ensuring that only requests originating from your website are accepted. When you send a request from your local machine, your web browser automatically includes a special `Origin` header, which in this case could be equal to `localhost`, `127.0.0.1`, or even `null`. ParityVend verifies this header to confirm that the request genuinely originates from your website, rather than from someone attempting to exploit your integration. If ParityVend detects that the request's Origin does not match the domain of your website (which you have entered during the project's creation), it will reject any requests made, deeming them "malicious". #### [Step 3: Enable testing mode](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#step-3-enable-testing-mode) However, testing integrations is a fundamental necessity for any developer. Therefore, ParityVend offers a special "testing mode" that disables this Origin check, allowing you to test your integration on any domain, even if it does not match your configured project's domain, and even if the Origin equals `localhost`, `127.0.0.1`, or even `null`. To enable the testing mode and test our integration, we need to add the `testing-mode-` prefix to the endpoint's URL and include your `testing_secret` as a parameter. This will prompt ParityVend to enable the testing mode, allowing you to use your integration on a local development environment. Additionally, we will add a second parameter, `testing-country`, and set it to `BD` (for Bangladesh). This parameter serves as a useful tool for testing our integration from any country while working on a local development environment. You can simply use this parameter to instruct the testing mode to "emulate" a request from the country of your choice. Simply set it to your desired country code (in this example, to `BD` for Bangladesh) to simulate requests originating from that location, allowing for seamless integration testing. This is an incredibly convenient and essential feature of the ParityVend API. Below is an example of how the modified pricing page appears with the testing mode enabled and emulation set to Bangladesh: Pricing page v1.2.1 - Enabling ParityVend API testing mode [(view full HTML for pricing_1_2_1.html)](https://www.[ambeteco.com/ParityVend/docs/_static/examples/custom_pricing/pricing_1_2_1.html.txt)](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#id5 "Link to this code") `...async function getDiscount() {let url = "https://api.parityvend.cloud/frontend/testing-mode-get-discount/";url += '<YOUR PUBLIC KEY>';url += '?testing-secret=<YOUR TESTING SECRET>';url += '&testing-country=BD'; // Emulate a visit from Bangladeshconst response = await fetch(url);const jsonData = await response.json();...` [![Step 2 - Pricing became adaptive!](https://www.ambeteco.com/ParityVend/docs/_images/e1_s2_1.png)](https://www.ambeteco.com/ParityVend/docs/_images/e1_s2_1.png) Refresh the page, and the pricing page should work! You will see a 70% discount along with a discount label: #### [Step 3: It works! Let's keep improving.](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#step-3-it-works-let-s-keep-improving) It's incredible how easy it is to make your pricing adaptive! However, our current integration is a bit too basic and lacks some important elements. Let's improve it! First and foremost, let's incorporate a subtle loading animation for the prices and apply some styles. Not everyone has fast internet speed, so ParityVend may take some time to respond. As it stands, the pricing page will display empty or incorrect prices while waiting for the ParityVend API to respond. This is clearly detrimental to the user experience and the overall aesthetics of the website, so let's address this issue. To achieve this, we'll make the following modifications: - Add the "plan-price-animated" class to the plan prices to introduce a "skeleton" loading animation. - Implement a "removeAnimations" function to revert the applied animations. - Include code to calculate the "additionalDelay" to ensure a seamless user experience. The enhanced pricing page code is as follows: Pricing page v1.3 - Adding loading animations [(view full HTML for pricing_1_3.html)](https://www.ambeteco.com/[ParityVend/docs/_static/examples/custom_pricing/pricing_1_3.html.txt)](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#id6 "Link to this code") `<style>....plan-price {position: relative;}.plan-price-animated::after {transition: opacity 0.7s;border-radius: 1.5rem;content: '';position: absolute;top: 0;left: 0;width: 100%;height: 100%;background-color: hsl(200, 20%, 80%);border: solid 0.15rem hsl(200, 16%, 89%);opacity: 1;animation: skeleton-loading 1s linear infinite alternate;}.plan-price-animated-end::after {opacity: 0 !important;}@keyframes skeleton-loading {0% {background-color: hsl(200, 20%, 80%);}100% {background-color: hsl(200, 20%, 95%);}}</style><script>async function getDiscount() {let url = "https://api.parityvend.cloud/frontend/testing-mode-get-discount/";url += '<YOUR PUBLIC KEY>';url += '?testing-secret=<YOUR TESTING SECRET>';url += '&testing-country=BD'; // Emulate a visit from Bangladeshconst response = await fetch(url);const jsonData = await response.json();if (jsonData.status !== "ok") {console.error("ParityVend API returned an error:",JSON.stringify(jsonData));return;}if (jsonData.discount) {return {discount: jsonData.discount,discount_str: jsonData.discount_str,conversion_rate: jsonData.currency.conversion_rate,symbol: jsonData.currency.symbol,country: jsonData.country.name,}}}window.addEventListener('DOMContentLoaded', async function () {const prices = {lite: 9.0,pro: 15.0,enterprise: 29.0,}const priceSpans = document.querySelectorAll('.plan-price');const loadTimeStart = Date.now();const discountInfo = await getDiscount();const discountLabelElm = document.getElementById('discount-label');for (let i = 0; i < priceSpans.length; i++) {const priceSpan = priceSpans[i];let price = prices[priceSpan.dataset.plan];if (discountInfo) {newPrice = price * (1 - discountInfo.discount);priceSpan.textContent = '$' + newPrice.toFixed(2);} else {priceSpan.textContent = '$' + price.toFixed(0);}}const elapsedTime = Date.now() - loadTimeStart;const additionalDelay = Math.min(1000, 1000 - elapsedTime);setTimeout(removeAnimations, additionalDelay);setTimeout(function () {if (discountInfo) {discountLabelElm.textContent = `It seems you are from ${discountInfo.country}. We support PPP and want to make our prices fair for everyone, so we have applied a ${discountInfo.discount_str} discount for you!`;discountLabelElm.style.display = 'block';discountLabelElm.clientHeight;discountLabelElm.style.opacity = 1;} else {discountLabelElm.style.display = 'none';}}, additionalDelay);});function removeAnimations() {const skeletonObjs = document.querySelectorAll('.plan-price-animated');for (let i = 0; i < skeletonObjs.length; i++) {const skeletonObj = skeletonObjs[i];skeletonObj.classList.add('plan-price-animated-end');setTimeout(function () {skeletonObj.classList.remove('plan-price-animated');skeletonObj.classList.remove('plan-price-animated-end');}, 750);}}</script></head>...

$9 <smallclass="text-muted">/ mo

...

$15 <smallclass="text-muted">/ mo

...

$29 <smallclass="text-muted">/mo

...

</body></html>` The animation we've just added is known as "skeleton animation". You may have noticed a peculiar `setTimeout` call, deliberately included to introduce a delay. Why, you might ask? While our loading animation is primarily designed for visitors with slower internet speeds, we must also consider those with faster connections. Without the delay, the ParityVend API might respond too quickly, causing the website to "blink" as the animation is abruptly added. This would appear more as an error than an intentional animation. Therefore, a common design practice is to introduce an artificial delay to ensure a smooth transition. This not only enhances the website's appearance but also contributes to its overall design. [![Step 3 - Skeleton Animation](https://www.ambeteco.com/ParityVend/docs/_images/e1_s3.png)](https://www.ambeteco.com/ParityVend/docs/_images/e1_s3.png) Now, we have a sleek, seamless, and, most importantly, fully automated pricing page that caters to visitors from all corners of the globe. But hold on, we can make it even better! [![Step 3.1 - Pricing page with animation](https://www.ambeteco.com/ParityVend/docs/_images/e1_s3_1.png)](https://www.ambeteco.com/ParityVend/docs/_images/e1_s3_1.png) Another enhancement we can implement is localizing the price: converting it to the visitor's local currency, formatting it with the respective currency symbol, and applying automatic formatting. With ParityVend, this can be easily achieved! Modify the `<script>` to incorporate automatic currency formatting using hourly exchange rate data: Pricing page v1.3.1 - Adding currency formatting and exchange rate [(view full HTML for pricing_1_3_1.html)](https://[www.ambeteco.com/ParityVend/docs/_static/examples/custom_pricing/pricing_1_3_1.html.txt)](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#id7 "Link to this code") `<script>...if (discountInfo) {newPrice = price * (1 - discountInfo.discount);newPrice *= discountInfo.conversion_rate;fixedNumber = price > newPrice ? 2 : 0;priceSpan.textContent = newPrice.toFixed(fixedNumber) + ' ' + discountInfo.symbol;} else {priceSpan.textContent = '$' + price.toFixed(0);}...</script>` When you refresh the page, you'll notice that your prices are now displayed in Bangladeshi Taka (BDT) instead of US dollars. This seamless conversion is made possible by ParityVend, making the shopping experience more convenient for your customers. [![Step 3.2 - Pricing page with localized currency](https://www.ambeteco.com/ParityVend/docs/_images/e1_s3_2.png)](https://www.ambeteco.com/ParityVend/docs/_images/e1_s3_2.png) To further enhance the user experience, consider displaying only the final price in local currency without any mention of discounts or the visitor's country. This approach, known as "silent" geographical pricing, is employed by leading companies like Netflix, Apple, Microsoft, and Spotify. By removing the `discount-label` element and related logic, you can achieve this streamlined presentation. [![Step 3.3 - Pricing page without discount label](https://www.ambeteco.com/ParityVend/docs/_images/e1_s3_3.png)](https://www.ambeteco.com/ParityVend/docs/_images/e1_s3_3.png) #### [Step 4: Going Live](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#step-4-going-live) Once you are satisfied with the integration and ready to deploy it to a live website, it's crucial to disable the testing mode. To do this, simply remove the `testing-mode-` prefix from the endpoint's URL, as well as the `testing-secret` and `testing-country` parameters. It's essential to ensure that the testing mode is disabled before going live, as leaving it enabled could expose your integration to potential exploitation by attackers. For more information on the risks associated with running the testing mode in a production environment, refer to the "[ParityVend Testing Mode](https://www.ambeteco.com/ParityVend/docs/testing_mode.html)" page. Below is an example of the code in its live version, with the testing mode disabled: Pricing page v1.4 - Final code [(view full HTML for pricing_1_4.html)](https://www.ambeteco.com/ParityVend/docs/[_static/examples/custom_pricing/pricing_1_4.html.txt)](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#id8 "Link to this code") `<script>...async function getDiscount() {let url = "https://api.parityvend.cloud/frontend/get-discount/";url += '<YOUR PUBLIC KEY>';...</script>` Congratulations on transforming your pricing strategy with ParityVend! You've successfully upgraded your pricing page from a static, outdated model to a dynamic, adaptive system that tailors itself to each visitor, fostering business growth and increased profitability. [What's Next?](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#what-s-next) -------------------------------------------------------------------------------------------------------------------------- As you prepare to integrate the ParityVend API into your project, your primary resource will be the comprehensive [API reference page](https://www.ambeteco.com/ParityVend/docs/api_reference.html), providing detailed descriptions of each endpoint. Additionally, we highly recommend exploring the "[Complete Overview](https://www.ambeteco.com/ParityVend/docs/complete_overview.html)" series for a deeper understanding of our platform. Should you encounter any errors during integration, be sure to consult the "[Debugging Guide](https://www.ambeteco.com/ParityVend/docs/debugging_guide.html)", which contains a comprehensive list of error codes and messages to assist you in troubleshooting. API Reference ============= *Average read time: 22 minutes* Welcome to the ParityVend API Reference documentation. This page contains detailed information about the structure of the ParityVend API, covering its backend and frontend groups, endpoints, and request structures. Whether you are developing the backend or frontend of your application, this documentation will serve as a valuable resource to assist you in integrating ParityVend's powerful features into your project. [Structure of the API](https://www.ambeteco.com/ParityVend/docs/api_reference.html#structure-of-the-api) -------------------------------------------------------------------------------------------------------------------------------- The ParityVend API is divided into two groups: the backend and the frontend. > Backend group: > > - Offers 7 endpoints. > > > - Each request must be authenticated with your `private_key`. > > > - Endpoints give you full access to the API. > > > - Meant to be used from your server. > > > - Should be used only on your backend (or where you can ensure the security of the `private_key`). > Frontend group: > > - Offers 4 endpoints (plus 4 for "testing mode"). > > > - Each request must be authenticated with your `public_key`. > > > - Meant to be used on the devices of your clients/visitors. > > > - Endpoints give you limited access to the API. > > > - Should be used on your frontend. > > > - Offers special testing mode that disables certain security checks that are required for running on `localhost`. All endpoints follow a similar request structure, with the key (either "public_key" or "private_key") always being the first in the request fields. Subsequently, the endpoint may accept other required or additional arguments. All requests should be made using a simple GET. Endpoints return JSON, which always includes a "status" key that can be either "ok" or "error," indicating the success or failure of the request. Refer to the "[Debugging Guide](https://www.ambeteco.com/ParityVend/docs/debugging_guide.html)" for a detailed overview of the errors returned by the API and recommendations for the debugging process. [Backend: Primary Endpoints](https://www.ambeteco.com/ParityVend/docs/api_reference.html#backend-primary-endpoints) ------------------------------------------------------------------------------------------------------------------------------------------- [GET /backend/get-country-from-ip/(*private_key*)/](https://www.ambeteco.com/ParityVend/docs/api_reference.html#get--backend-get-country-from-ip-(private_key)- "Link to this definition") This endpoint accepts any IP address and returns the corresponding country code following the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). If the visitor employs a VPN, proxy, or TOR, the special code "XX" will be returned. Parameters: - private_key -- Your private key - ip_address -- The IP-address that you wish to get the country for Ex. 1: valid IP-address Example request: Get the country for the IP `190.206.117.0` (Venezuela), with `b1234567890abcdefgh` as the private key. `GET https://api.parityvend.cloud/backend/get-country-from-ip/b1234567890abcdefgh/` Example response: `"VE"`, which stands for Venezuela, is returned correctly. `HTTP/1.1 200 OKContent-Type: application/json{"status": "ok","country": "VE"}` Ex. 2: VPNEx. 3: IPV6-address * * * * * [GET /backend/get-discount-from-ip/(*private_key*)/(*opt.: **base_currency*)/](https://www.ambeteco.com/ParityVend/docs/api_reference.html#get--backend-get-discount-from-ip-(private_key)-(opt.-base_currency)- "Link to this definition") Takes an IP address and retrieves the applicable discount information, if you have configured country-specific discounts for this project. Optionally, specify the `base currency` (defaults to `USD`) to include the exchange rate for the visitor's local currency. Parameters: - private_key -- Your private key - ip_address -- The IP-address that you wish to get the discount information - base_currency -- (optional, default=USD) Get exchange rate data with this currency as a base. Three uppercase letters, as in [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example: EUR, USD, GBP, JPY, etc. Ex. 1: valid discount Example request: Get the discount information for the IP `102.128.79.255` (Zimbabwe), with `b1234567890abcdefgh` as the private key. Context: the project is correctly configured for Zimbabwe with a 70% discount. `GET https://api.parityvend.cloud/backend/get-discount-from-ip/b1234567890abcdefgh/102.128.79.255/` Example response: A correct response with the discount information is returned. It includes the discount percentage, country and currency metadata, exchange rate, and the coupon code you configured. `HTTP/1.1 200 OKContent-Type: application/json{"status": "ok","discount": 0.7,"discount_str": "70.00%","coupon_code": "example_coupon","country": {"code": "ZW","name": "Zimbabwe","flag": "🇿🇼"},"currency": {"code": "ZWL","symbol": "$","localized_symbol": "ZWL$","conversion_rate": 321.99968729317396}}` Ex. 2: no discountEx. 3: VPNEx. 4: base currency * * * * * [GET /backend/get-banner-from-ip/(*private_key*)/(*opt.: **base_currency*)/](https://www.ambeteco.com/ParityVend/docs/api_reference.html#get--backend-get-banner-from-ip-(private_key)-(opt.-base_currency)- "Link to this definition") Similar to the No-Code solution's banner display, this endpoint generates an HTML banner with country-specific discounts (if configured) based on the provided IP address. This is a "backend" version of the endpoint that is used by the ParityVend No-Code. Optionally, specify the `base currency` (defaults to `USD`) to include the exchange rate for the visitor's local currency. Upon a valid request, the response format is rendered HTML (`text/html`). For invalid requests, error details are returned in JSON format (`application/json`). Parameters: - private_key -- Your private key - ip_address -- The IP-address that you wish to get the discount information - base_currency -- (optional, default=USD) Get exchange rate data with this currency as a base. Three uppercase letters, as in [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example: EUR, USD, GBP, JPY, etc. Ex. 1: valid discount Example request: Get the banner for the IP `102.128.79.255` (Zimbabwe), with `b1234567890abcdefgh` as the private key. Context: the project is correctly configured for Zimbabwe with a 70% discount. `GET https://api.parityvend.cloud/backend/get-banner-from-ip/b1234567890abcdefgh/102.128.79.255/` Example response: A correct HTML response is returned. It "renders" the variables that you configured in the banner text. `It seems like you're visiting from Zimbabwe. To enhance your experience, you're eligible for a special 70.00% discount. Use the coupon code example_coupon at checkout to get it.` Ex. 2: no discountEx. 3: VPNEx. 4: base currency * * * * * [GET /backend/get-discount-with-html-from-ip/(*private_key*)/(*opt.: **base_currency*)/](https://www.ambeteco.com/ParityVend/docs/api_reference.html#get--backend-get-discount-with-html-from-ip-(private_key)-(opt.-base_currency)- "Link to this definition") This endpoint combines functionality from the previous two, taking an IP address and returning both discount information and a rendered HTML banner. Optionally, specify the `base currency` (defaults to `USD`) to include the exchange rate for the visitor's local currency. Parameters: - private_key -- Your private key - ip_address -- The IP-address that you wish to get the discount information - base_currency -- (optional, default=USD) Get exchange rate data with this currency as a base. Three uppercase letters, as in [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example: EUR, USD, GBP, JPY, etc. Ex. 1: valid discount Example request: Get the discount information and HTML banner for the IP `102.128.79.255` (Zimbabwe), with `b1234567890abcdefgh` as the private key. Context: the project is correctly configured for Zimbabwe with a 70% discount. `GET https://api.parityvend.cloud/backend/get-discount-with-html-from-ip/b1234567890abcdefgh/102.128.79.255/` Example response: A correct response with the discount information and an HTML banner is returned. It includes the discount percentage, country and currency metadata, exchange rate, and the coupon code you configured, as well as the HTML code of the banner. `HTTP/1.1 200 OKContent-Type: application/json{"status": "ok","html": "It seems like you're visiting from Zimbabwe. To enhance your experience, you're eligible for a special 70.00% discount. Use the coupon code example_coupon at checkout to get it.","discount": 0.7,"discount_str": "70.00%","coupon_code": "example_coupon","country": {"code": "ZW","name": "Zimbabwe","flag": "🇿🇼"},"currency": {"code": "ZWL","symbol": "$","localized_symbol": "ZWL$","conversion_rate": 321.99968729317396}}` Ex. 2: no discountEx. 3: VPNEx. 4: base currency [Backend: Miscellaneous endpoints](https://www.ambeteco.com/ParityVend/docs/api_reference.html#backend-miscellaneous-endpoints) ------------------------------------------------------------------------------------------------------------------------------------------------------- [GET /backend/get-quota-info/(*private_key*)/](https://www.ambeteco.com/ParityVend/docs/api_reference.html#get--backend-get-quota-info-(private_key)- "Link to this definition") This endpoint provides quota information for your account, detailing your used and remaining quota. Using this endpoint does not affect your quota usage. Parameters: - private_key -- Your private key Ex. 1: valid response Example request: Get the quota information for the account that holds the `b1234567890abcdefgh` private key. `GET https://api.parityvend.cloud/backend/get-quota-info/b1234567890abcdefgh/` Example response: Account quota returned correctly. `HTTP/1.1 200 OKContent-Type: application/json{"status": "ok","quota_limit": 1500000,"quota_used": 235,"quota_left": 1499765}` * * * * * [GET /backend/get-discounts-info/(*private_key*)/](https://www.ambeteco.com/ParityVend/docs/api_reference.html#get--backend-get-discounts-info-(private_key)- "Link to this definition") This endpoint retrieves discount information specific to the country groups configured in your current project. For each country within the group, a coupon and discount percentage are provided. Parameters: - private_key -- Your private key Ex. 1: valid response Example request: Get all the discount information for the project with the `b1234567890abcdefgh` private key. `GET https://api.parityvend.cloud/backend/get-discounts-info/b1234567890abcdefgh/` Example response: Discounts information is returned `HTTP/1.1 200 OKContent-Type: application/json{"status": "ok","discounts": {"AC": null, "AD": null, "AE": null, "AF": ["example_coupon", 0.7], "AG": null, "AI": null, "AL": null, "AM": null, "AN": null, "AO": null, "AQ": null, "AR": null, "AS": null, "AT": null, "AU": null, "AW": null, "AX": null, "AZ": null, "BA": null, "BB": null, "BD": ["example_coupon", 0.7], "BE": null, "BF": ["example_coupon", 0.7], "BG": null, "BH": null, "BI": ["example_coupon", 0.7], "BJ": ["example_coupon", 0.7], "BL": null, "BM": null, "BN": null, "BO": null, "BQ": null, "BR": null, "BS": null, "BT": null, "BV": null, "BW": null, "BY": null, "BZ": null, "CA": null, "CC": null, "CD": ["example_coupon", 0.7], "CF": ["example_coupon", 0.7], "CG": ["example_coupon", 0.7], "CH": null, "CI": null, "CK": null, "CL": null, "CM": ["example_coupon", 0.7], "CN": null, "CO": null, "CR": null, "CS": null, "CU": null, "CV": null, "CW": null, "CX": null, "CY": null, "CZ": null, "DE": null, "DJ": null, "DK": null, "DM": null, "DO": null, "DZ": null, "EC": null, "EE": null, "EG": null, "EH": null, "ER": ["example_coupon", 0.7], "ES": null, "ET": ["example_coupon", 0.7], "FI": null, "FJ": null, "FK": null, "FM": null, "FO": null, "FR": null, "GA": null, "GB": null, "GD": null, "GE": null, "GF": null, "GG": null, "GH": null, "GI": null, "GL": null, "GM": ["example_coupon", 0.7], "GN": ["example_coupon", 0.7], "GP": null, "GQ": null, "GR": null, "GS": null, "GT": null, "GU": null, "GW": ["example_coupon", 0.7], "GY": null, "HK": null, "HM": null, "HN": null, "HR": null, "HT": ["example_coupon", 0.7], "HU": null, "IC": null, "ID": null, "IE": null, "IL": null, "IM": null, "IN": null, "IO": null, "IQ": null, "IR": ["example_coupon", 0.7], "IS": null, "IT": null, "JE": null, "JM": null, "JO": null, "JP": null, "KE": ["example_coupon", 0.7], "KG": null, "KH": ["example_coupon", 0.7], "KI": null, "KM": null, "KN": null, "KP": null, "KR": null, "KW": null, "KY": null, "KZ": null, "LA": null, "LB": null, "LC": null, "LI": null, "LK": null, "LR": ["example_coupon", 0.7], "LS": ["example_coupon", 0.7], "LT": null, "LU": null, "LV": null, "LY": null, "MA": null, "MC": null, "MD": null, "ME": null, "MF": null, "MG": ["example_coupon", 0.7], "MH": null, "MK": null, "ML": ["example_coupon", 0.7], "MM": ["example_coupon", 0.7], "MN": null, "MO": null, "MP": null, "MQ": null, "MR": null, "MS": null, "MT": null, "MU": null, "MV": null, "MW": ["example_coupon", 0.7], "MX": null, "MY": null, "MZ": ["example_coupon", 0.7], "NA": null, "NC": null, "NE": ["example_coupon", 0.7], "NF": null, "NG": ["example_coupon", 0.7], "NI": null, "NL": null, "NO": null, "NP": ["example_coupon", 0.7], "NR": null, "NU": null, "NZ": null, "OM": null, "PA": null, "PE": null, "PF": null, "PG": ["example_coupon", 0.7], "PH": null, "PK": ["example_coupon", 0.7], "PL": null, "PM": null, "PN": null, "PR": null, "PS": null, "PT": null, "PW": null, "PY": null, "QA": null, "RE": null, "RO": null, "RS": null, "RU": null, "RW": ["example_coupon", 0.7], "SA": null, "SB": ["example_coupon", 0.7], "SC": null, "SD": ["example_coupon", 0.7], "SE": null, "SG": null, "SH": null, "SI": null, "SJ": null, "SK": null, "SL": ["example_coupon", 0.7], "SM": null, "SN": null, "SO": ["example_coupon", 0.7], "SR": null, "SS": ["example_coupon", 0.7], "ST": null, "SV": null, "SX": null, "SY": null, "SZ": ["example_coupon", 0.7], "TA": null, "TC": null, "TD": ["example_coupon", 0.7], "TF": null, "TG": ["example_coupon", 0.7], "TH": null, "TJ": null, "TK": null, "TL": ["example_coupon", 0.7], "TM": null, "TN": null, "TO": null, "TR": null, "TT": null, "TV": null, "TW": null, "TZ": ["example_coupon", 0.7], "UA": null, "UG": ["example_coupon", 0.7], "UM": null, "US": null, "UY": null, "UZ": ["example_coupon", 0.7], "VA": null, "VC": null, "VE": null, "VG": null, "VI": null, "VN": null, "VU": null, "WF": null, "WS": null, "XK": null, "YE": ["example_coupon", 0.7], "YT": null, "ZA": null, "ZM": ["example_coupon", 0.7], "ZW": ["example_coupon", 0.7], }}` * * * * * [GET /backend/get-exchange-rate-info/(*private_key*)/(*opt.: **base_currency*)/](https://www.ambeteco.com/ParityVend/docs/api_reference.html#get--backend-get-exchange-rate-info-(private_key)-(opt.-base_currency)- "Link to this definition") This endpoint provides a dictionary in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217) for 170 world currencies, with USD as the base. Exchange rates are updated hourly. Optionally, you can define a `base currency` for the returned dictionary. All other currencies will be calculated against this base. `USD` is the default base. Note This endpoint is only available to accounts on paid plans. You can't use this endpoint if you are on a "free" plan. Parameters: - private_key -- Your private key - base_currency -- (optional, default=USD) Get exchange rate data with this currency as a base. Three uppercase letters, as in [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example: EUR, USD, GBP, JPY, etc. Ex. 1: valid response Example request: Get the exchange rate information (by default, with the base set to USD). `GET https://api.parityvend.cloud/backend/get-exchange-rate-info/b1234567890abcdefgh/` Example response: Exchange rate info is returned: Exchange rates response (click to expand) Ex. 2: change base [Frontend: Primary Endpoints](https://www.ambeteco.com/ParityVend/docs/api_reference.html#frontend-primary-endpoints) --------------------------------------------------------------------------------------------------------------------------------------------- Note The frontend endpoints do not accept an IP address as an input. Instead, they automatically identify the requestor's IP address based on the incoming network request. Therefore, for clarity and simplicity, each example in the documentation specifies the IP address that was used as the requestor's. [GET /frontend/get-country/(*public_key*)/](https://www.ambeteco.com/ParityVend/docs/api_reference.html#get--frontend-get-country-(public_key)- "Link to this definition") Based on the requestor's IP address, this endpoint returns the corresponding country code in [ISO 3166-1 alpha-2 format](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). "XX" indicates the use of a VPN, proxy, or TOR. Parameters: - public_key -- Your public key Ex. 1: valid IP-address Example request: Consider your IP address is `190.206.117.0` (Venezuela), with `a1234567890abcdefgh` as the public key. `GET https://api.parityvend.cloud/frontend/get-country/a1234567890abcdefgh/` Example response: `"VE"`, which stands for Venezuela, is returned correctly. `HTTP/1.1 200 OKContent-Type: application/json{"status": "ok","country": "VE"}` Ex. 2: VPNEx. 3: IPV6-address * * * * * [GET /frontend/get-discount/(*public_key*)/(*opt.: **base_currency*)/](https://www.ambeteco.com/ParityVend/docs/api_reference.html#get--frontend-get-discount-(public_key)-(opt.-base_currency)- "Link to this definition") If configured, this endpoint retrieves discount information specific to the requestor's country. Optionally, specify the `base currency` (defaults to `USD`) to include the exchange rate for the visitor's local currency. Parameters: - public_key -- Your public key - base_currency -- (optional, default=USD) Get exchange rate data with this currency as a base. Three uppercase letters, as in [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example: EUR, USD, GBP, JPY, etc. Ex. 1: valid discount Example request: Consider your IP address is `102.128.79.255` (Zimbabwe). Get the discount information with `a1234567890abcdefgh` as the public key. Context: the project is correctly configured for Zimbabwe with a 70% discount. `GET https://api.parityvend.cloud/frontend/get-discount/a1234567890abcdefgh/` Example response: A correct response with the discount information is returned. It includes the discount percentage, country and currency metadata, exchange rate, and the coupon code you configured. `HTTP/1.1 200 OKContent-Type: application/json{"status": "ok","discount": 0.7,"discount_str": "70.00%","coupon_code": "example_coupon","country": {"code": "ZW","name": "Zimbabwe","flag": "🇿🇼"},"currency": {"code": "ZWL","symbol": "$","localized_symbol": "ZWL$","conversion_rate": 321.99968729317396}}` Ex. 2: no discountEx. 3: VPNEx. 4: base currency * * * * * [GET /frontend/get-banner/(*public_key*)/(*opt.: **base_currency*)/](https://www.ambeteco.com/ParityVend/docs/api_reference.html#get--frontend-get-banner-(public_key)-(opt.-base_currency)- "Link to this definition") This endpoint generates a rendered HTML banner with country-specific discounts, if configured, based on the requestor's IP address. This is the endpoint that is used by the ParityVend No-Code solution. Optionally, specify the `base currency` (defaults to `USD`) to include the exchange rate for the visitor's local currency. For valid requests, a rendered HTML response is returned (`text/html`). For invalid requests, error details are returned in JSON format (`application/json`). Parameters: - public_key -- Your public key - base_currency -- (optional, default=USD) Get exchange rate data with this currency as a base. Three uppercase letters, as in [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example: EUR, USD, GBP, JPY, etc. Ex. 1: valid discount Example request: Consider your IP address is `102.128.79.255` (Zimbabwe). Get the banner with `a1234567890abcdefgh` as the public key. Context: the project is correctly configured for Zimbabwe with a 70% discount. `GET https://api.parityvend.cloud/frontend/get-banner/a1234567890abcdefgh/` Example response: A correct HTML response is returned. It "renders" the variables that you configured in the banner text. `It seems like you're visiting from Zimbabwe. To enhance your experience, you're eligible for a special 70.00% discount. Use the coupon code example_coupon at checkout to get it.` Ex. 2: no discountEx. 3: VPNEx. 4: base currency * * * * * [GET /frontend/get-discount-with-html/(*public_key*)/(*opt.: **base_currency*)/](https://www.ambeteco.com/ParityVend/docs/api_reference.html#get--frontend-get-discount-with-html-(public_key)-(opt.-base_currency)- "Link to this definition") Combining functionality from the previous two endpoints, this endpoint returns both discount information and a rendered HTML banner for the requestor's IP address. Optionally, specify the `base currency` (defaults to `USD`) to include the exchange rate for the visitor's local currency. Parameters: - public_key -- Your public key - base_currency -- (optional, default=USD) Get exchange rate data with this currency as a base. Three uppercase letters, as in [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). For example: EUR, USD, GBP, JPY, etc. Ex. 1: valid discount Example request: Consider your IP address is `102.128.79.255` (Zimbabwe). Get the discount information and HTML banner with `a1234567890abcdefgh` as the public key. Context: the project is correctly configured for Zimbabwe with a 70% discount. `GET https://api.parityvend.cloud/frontend/get-discount-with-html/a1234567890abcdefgh/` Example response: A correct response with the discount information and an HTML banner is returned. It includes the discount percentage, country and currency metadata, exchange rate, the coupon code you configured, as well as the HTML code of the banner. `HTTP/1.1 200 OKContent-Type: application/json{"status": "ok","html": "It seems like you're visiting from Zimbabwe. To enhance your experience, you're eligible for a special 70.00% discount. Use the coupon code example_coupon at checkout to get it.","discount": 0.7,"discount_str": "70.00%","coupon_code": "example_coupon","country": {"code": "ZW","name": "Zimbabwe","flag": "🇿🇼"},"currency": {"code": "ZWL","symbol": "$","localized_symbol": "ZWL$","conversion_rate": 321.99968729317396}}` Ex. 2: no discountEx. 3: VPNEx. 4: base currency [Frontend: Testing Mode](https://www.ambeteco.com/ParityVend/docs/api_reference.html#frontend-testing-mode) ----------------------------------------------------------------------------------------------------------------------------------- Each of the four frontend endpoints offers a testing mode, allowing you to conveniently debug and test your integration in your local development environment. Please refer to the "[ParityVend Testing Mode](https://www.ambeteco.com/ParityVend/docs/testing_mode.html)" page to learn how to use it. [What's Next?](https://www.ambeteco.com/ParityVend/docs/api_reference.html#whats-next) -------------------------------------------------------------------------------------------------------------- As you integrate the ParityVend API into your project, we highly recommend exploring the "[Complete overview](https://www.ambeteco.com/ParityVend/docs/complete_overview.html)" series for a deeper understanding of our platform. If you encounter any errors during integration, be sure to consult the "[Debugging Guide](https://www.ambeteco.com/ParityVend/docs/debugging_guide.html)", which contains a comprehensive list of error codes and messages to assist you in troubleshooting.Welcome to ParityVend's documentation! ====================================== [What is ParityVend](https://www.ambeteco.com/ParityVend/docs/index.html#what-is-parityvend) -------------------------------------------------------------------------------------------------------------------- ParityVend is a revolutionary tool designed to take your business to new heights by making your pricing adaptive. By detecting the location of every visitor to your website, ParityVend dynamically adjusts the pricing of your products to ensure fairness and balance for each visitor's country. In countries with varying purchasing power, it's essential to adapt product prices to align with the local economy. ParityVend solves this challenge by dynamically adjusting prices, ensuring fairness for all visitors, regardless of their location. Implementing ParityVend can lead to a significant boost in sales, profits, reach, and popularity for your business. Unlock the full potential of your business on a global scale by getting started with ParityVend. ParityVend - the key to your global success. [Learn more about the powerful features of ParityVend on its website.](https://www.ambeteco.com/ParityVend/) [ParityVend Solutions](https://www.ambeteco.com/ParityVend/docs/index.html#parityvend-solutions) ------------------------------------------------------------------------------------------------------------------------ ParityVend has two powerful solutions that you can use to integrate ParityVend on your website, No-Code and API. ### [ParityVend No-Code](https://www.ambeteco.com/ParityVend/docs/index.html#parityvend-no-code) Integrate ParityVend No-Code to display 'discount banners' on your website, offering coupons to visitors from countries with lower purchasing power. The No-Code solution is easy to integrate and can be implemented in less than 7 minutes. The No-Code solution offers 99 hand-crafted designs, 13 text templates, and 10 country grouping methods, making it a perfect fit for solopreneurs, low-code businesses, startups, and small companies. ### [ParityVend API](https://www.ambeteco.com/ParityVend/docs/index.html#parityvend-api) Utilize ParityVend API to build robust, secure, and flexible integrations, even for the most demanding or unique pricing flows. ParityVend API features advanced security and scalability, enabling you to build exceptional abuse-proof systems. The ParityVend API is the preferred choice for startups, SaaS companies, and enterprises seeking advanced pricing solutions. [How to Begin](https://www.ambeteco.com/ParityVend/docs/index.html#how-to-begin) -------------------------------------------------------------------------------------------------------- Are you prepared to take your business to the global level? Starting with ParityVend is straightforward. Our ["Getting Started"](https://www.ambeteco.com/ParityVend/docs/getting_started.html) guide is tailored for beginners, making it easy for you to navigate through the process. This comprehensive guide will lead you through the setup process step by step, enabling you to seamlessly integrate ParityVend into your business. Access the "[Getting Started with ParityVend](https://www.ambeteco.com/ParityVend/docs/getting_started.html)" guide now to begin your successful journey with ParityVend. [Need help?](https://www.ambeteco.com/ParityVend/docs/index.html#need-help) --------------------------------------------------------------------------------------------------- If you come across any issues or challenges during the integration process, we recommend referring to this documentation as your first resource. It provides comprehensive guidance to help you troubleshoot and resolve any errors you may encounter. If you require further support, our team is always ready to assist you. Feel free to [contact us](https://www.ambeteco.com/ParityVend/contact-us/) for personalized assistance to ensure a seamless integration experience or view the FAQ section at [ParityVend Support](https://www.ambeteco.com/ParityVend/support/). API Tutorial ============ *Average read time: 19 minutes* After completing the "Getting Started" guide, the next step is to integrate the ParityVend API into your website. This guide will walk you through the API basics that you need to know to start and also provide some examples and "recipes" that will help you integrate the ParityVend API into your project. We highly recommend that you read the full API overview before starting to use the ParityVend API in your application. [Getting Your API Keys](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#getting-your-api-keys) --------------------------------------------------------------------------------------------------------------------------------------------- To start using the ParityVend API, you first need to obtain the API keys that ParityVend has generated for you. Follow the simple steps below to get your API keys. ### [Step 1: Open the API Window](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#step-1-open-the-api-window) Access the 'API' window: you can always view the API keys for all your projects in this window. Additionally, you can re-issue your keys there. To open it, follow these steps: > 1. Go to the Dashboard. > > > 2. In the menu, click on "API". > > > 3. Scroll down until you see your project with the API keys. ### [Step 2: Copying Your Keys](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#step-2-copying-your-keys) Once you see your project with the three keys, you can click on any key to copy it to the clipboard. Now, let's continue to the next section to examine each key and its uses. [Explanation of API Keys](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#explanation-of-api-keys) ------------------------------------------------------------------------------------------------------------------------------------------------- ParityVend API uses a pair of `public_key` and `private_key`, along with a special token called `testing_secret`. See the explanation below to learn what those keys are and where they should be used. > `public_key`: > > - Can be freely shared and is intended to be seen by anyone. > > > - Gives limited access to the API. > > > - Should be used on the frontend of your website/web-applications. > `private_key`: > > - Must be kept secure; never share it with anyone. > > > - Gives you full access to the API. > > > - Should be used only on your backend (where you can ensure the security of the key). > `testing_secret`: > > - Enables the special "testing mode" for the `public_key`. > > > - Disables security measures and is required for testing on localhost. > > > - Remove it from the public source code before going live. > > > - Never use it in production, as it imposes security risks. Note Never share `private_key` and `testing_secret` with anyone, and keep them secure. Never use `private_key` on your frontend, or anywhere where the public can see or access it. Never leave "testing mode" enabled on production/live websites. [ParityVend API: "Hello World"](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#parityvend-api-hello-world) ---------------------------------------------------------------------------------------------------------------------------------------------------------- After you have your API keys, let's do a traditional "hello world" for the ParityVend API. But first, let's understand the structure of the ParityVend API and its basics. ### [Structure of the API](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#structure-of-the-api) ParityVend API is split into two groups: backend and frontend: > Backend group: > > - Offers 7 endpoints. > > > - Each request must be authenticated with your `private_key`. > > > - Endpoints give you full access to the API. > > > - Meant to be used from your server. > > > - As highlighted in the name, it should be used only on your backend (or where you can ensure the security of the `private_key`). > Frontend group: > > - Offers 4 endpoints (plus 4 for "testing mode"). > > > - Each request must be authenticated with your `public_key`. > > > - Meant to be used on the devices of your clients/visitors. > > > - Endpoints give you limited access to the API. > > > - As highlighted in the name, it should be used on your frontend. > > > - Offers special testing mode that disables certain security checks that are required for running on `localhost`. All endpoints have a similar request structure, where the key (whether it's `public_key` or `private_key`) is always the first in the request fields. After that, the endpoint may accept other required or additional arguments. All requests should be completed as a simple GET. Endpoints return JSON, which always has a `"status"` key that can be equal to either `"ok"` or `"error"`, indicating whether the request was completed successfully or with an error. ### [Your First Request with ParityVend API](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#your-first-request-with-parityvend-api) Now, let's try to make your first "hello world" request with the ParityVend API! This is the URL of the `get-quota-info` endpoint. It provides information about your account's current quota information. Also, making requests to this endpoint does not count against your quota usage (good news for you). To form your hello world request to the `get-quota-info` endpoint, take the URL below and change `<YOUR_PRIVATE_KEY>` with your actual private_key you copied in the earlier steps: > `https://api.parityvend.cloud/backend/get-quota-info/<YOUR_PRIVATE_KEY>/` After you insert your private key, simply open this URL in any browser. Uou can also use any HTTP client (such as curl, wget, etc.), or any HTTP request library (such as `requests`, `axios`, `httpx`, etc) and make a GET request to this URL. You will get a JSON response similar to this, where you will find your current quota information: [Example response from the `get-quota-info` endpoint:](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#id1 "Link to this code") `{"status": "ok","quota_limit": 1500000,"quota_used": 0,"quota_left": 1500000}` Congrats! You have just made your first ParityVend API request! This means that everything works correctly, and you are good to go! You are ready to move on to the next section. Hint If you get an error when you make this request, first check whether you have entered your `private_key` correctly; ensure that you did not accidentally enter any trailing spaces. If you still get an error, refer to the "[Debugging Guide](https://www.ambeteco.com/ParityVend/docs/debugging_guide.html)". [Brief Overview of Endpoints](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#brief-overview-of-endpoints) --------------------------------------------------------------------------------------------------------------------------------------------------------- In this section, we will briefly overview backend and frontend endpoints. Let's start with the backend group, which has a total of 7 endpoints. ### [Backend: Primary Endpoints](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#backend-primary-endpoints) 4 primary endpoints. Used to provide discount functionality to your pricing flows. The responses they return are closely related. > `/backend/get-country-from-ip/` > > - Takes in any IP address as an input and returns the identified country in the [ISO 3166-1 alpha-2 standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). One special return case is `XX`, which means that the visitor uses a VPN, Proxy, or TOR. > > > > Auth: private_key Output: JSON > > Input argument 1: IP-address > `/backend/get-discount-from-ip/` > > - Takes in any IP address as an input and returns discount information if you have configured it to offer discounts for the IP's country. It uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: private_key Output: JSON > > Input argument 1: IP-address > > Input argument 2: Base currency (optional, default=USD) > `/backend/get-banner-from-ip/` > > - Takes in any IP address as an input and returns a rendered HTML banner. This is the same HTML banner that is used by the No-Code solution, except that this is a backend version that works from the input IP address. It uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: private_key Output: HTML > > Input argument 1: IP-address > > Input argument 2: Base currency (optional, default=USD) > `/backend/get-discount-with-html-from-ip/` > > - Takes in any IP address as input and returns both discount information and an HTML banner. You can think of it as a blend of the previous two endpoints. It uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: private_key Output: JSON > > Input argument 1: IP-address > > Input argument 2: Base currency (optional, default=USD) ### [Backend: Miscellaneous endpoints](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#backend-miscellaneous-endpoints) 3 miscellaneous endpoints. They can be related to your account, project, or metadata. > `/backend/get-quota-info/` > > - Returns quota information for your account, including how much you have used and how much quota you have left. > > > > Auth: private_key Output: JSON Quota-free > > Input: Does not take any input > `/backend/get-discounts-info/` > > - Returns discount information about the country groups you have configured for the current project. For each country, a coupon and discount percentage are attached. > > > > Auth: private_key Output: JSON > > Input: Does not take any input > `/backend/get-exchange-rate-info/` > > - Returns a dictionary for 170 world currencies with the base currency being USD, all in the [ISO 4217 standard](https://en.wikipedia.org/wiki/ISO_4217). It takes one optional argument, `base currency`, which is used as a "base" for the returned dictionary, where all currencies returned are calculated against the base currency. By default, the base currency is set to USD. > > > > Auth: private_key Output: JSON Plan: only for paid plans > > Input argument 1: Base currency (optional, default=USD) ### [Frontend: Primary Endpoints](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#frontend-primary-endpoints) The Frontend group offers four primary endpoints. These are used to provide discount functionality to your pricing flows, directly integrated into the frontend of your website. These endpoints are meant to be used by the users/visitors of your websites directly from their devices. Therefore, they don't take an "IP-address" as input, as the IP-address is detected automatically from the visitor's device. The responses they return are closely related. > `/frontend/get-country/` > > - Returns the identified country of the requestor's IP-address in the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) standard. One special return case is `XX`, which means that the visitor uses a VPN, Proxy, or TOR. > > > > Auth: public_key Output: JSON > > No arguments > `/frontend/get-discount/` > > - Uses the requestor's IP-address and returns discount information if you have configured it to offer discounts for the requestor's country. Uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: public_key Output: JSON > > Input argument 1: Base currency (optional, default=USD) > `/frontend/get-banner/` > > - Uses the requestor's IP-address and returns a rendered HTML banner. This is exactly the endpoint used by the No-Code solution to deliver HTML banners to the websites. Uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: public_key Output: HTML > > Input argument 1: Base currency (optional, default=USD) > `/frontend/get-discount-with-html/` > > - Uses the requestor's IP-address and returns both discount information and an HTML banner. You can think of it as a blend of the previous two endpoints. Uses `base currency` (optional argument, by default equals to `USD`) to include the exchange rate for the country's local currency. > > > > Auth: public_key Output: JSON > > Input argument 1: Base currency (optional, default=USD) Each endpoint listed above has a "mirror" version of itself, with `testing-mode-` added to its name. Namely, `/frontend/testing-mode-get-banner/`, `/frontend/testing-mode-get-country/`, `/frontend/testing-mode-get-discount/`, and `/frontend/testing-mode-get-discount-with-html/`. These are the special "testing mode" versions of the frontend endpoints group, to which you can add a `testing-secret` parameter to enable the testing mode. This allows you to test and debug your integration on `localhost`, `127.0.0.1`, or any other domain. The live versions of the endpoints will simply not work anywhere outside your website, meaning that you would not be able to use them on `localhost` while testing your integration on your local development environment. Learn more about how to use the testing mode on the "[ParityVend Testing Mode](https://www.ambeteco.com/ParityVend/docs/testing_mode.html)" page. [Integration ideas](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#integration-ideas) ------------------------------------------------------------------------------------------------------------------------------------- Unlock the full potential of your business with the versatile capabilities of the ParityVend API. Below, you'll discover a range of innovative ways to leverage this powerful tool to enhance your website's functionality and drive business growth. From building an abuse-proof checkout system to dynamically adjusting product prices based on visitor location, the ParityVend API offers a myriad of features, that can be used to optimize the user experience, prevent fraud, and personalize interactions. Explore the following ideas to see how you can harness the power of location-based data to create a more tailored and secure online environment for your customers: Build Abuse-Proof Checkout: We highly recommend integrating the ParityVend API into your website's checkout process to prevent abuse of discounts. While offering coupons with discounts can help expand your business globally, it's important to protect against coupon code sharing. By incorporating the `/backend/get-discount-from-ip/` or `/backend/get-country-from-ip/` endpoint from the ParityVend API, you can verify the user's location at checkout and ensure that their coupon code is valid for that location (e.g., India). This implementation will create a secure and abuse-proof system for your business. Dynamic Pricing: Use the ParityVend API for its primary goal: to dynamically adjust product prices based on the visitor's location. This ensures fairness and balance by aligning prices with the local economy. For this case, you can use the `/frontend/get-discount/` or `/backend/get-discount-from-ip/` endpoints. Personalized Offers: Leverage ParityVend's location detection capabilities to dynamically present targeted discounts and promotions to website visitors based on their country, potentially increasing sales and conversion rates. Potentially useful endpoints: `/frontend/get-discount/` or `/backend/get-discount-from-ip/`. Enhanced Fraud Prevention: Use ParityVend API to identify and block activity associated with VPNs and proxies, offering enhanced protection against fraudulent transactions within payment-related workflows. Consider `/backend/get-country-from-ip/` endpoint to detect suspicious IP addresses. Access Control based on Location: The ParityVend API can be used to empower website owners to implement location-based access restrictions, potentially blocking suspicious activity or anonymized traffic (e.g., VPN usage) from accessing specific website sections. Utilize the `/backend/get-country-from-ip/` endpoint to detect the visitor's country. Localized Currency Display: ParityVend API can facilitate automatic product price display in the visitor's local currency, enhancing the user experience and potentially improving conversion rates by eliminating the need for mental currency conversions. Think about the `/frontend/get-discount/` or `/backend/get-discount-from-ip/` endpoints, as well as the `/backend/get-exchange-rate-info/` endpoint to retrieve exchange rate information. Location-Specific Welcome Offers: The ParityVend API enables you to create personalized welcome offers and discounts for first-time visitors based on their country, potentially fostering a positive first impression and encouraging engagement. For this idea, `/frontend/get-discount/` or `/backend/get-discount-from-ip/` endpoints can be useful. Location-Aware Content Optimization: The ParityVend API can empower website owners to dynamically adjust website content, promotions, and even language options based on the visitor's location, potentially improving user experience and engagement. Leverage endpoints like `/frontend/get-country/` or `/backend/get-country-from-ip/` endpoints to detect the visitor's country. Personalized Product Recommendations: ParityVend's API's location data and purchasing power insights can be leveraged to dynamically recommend products relevant to the visitor's cultural context and financial realities, potentially increasing cross-selling and upselling opportunities. Use the `/backend/get-country-from-ip/` endpoint to detect the visitor's country. [Integration Example](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#integration-example) ----------------------------------------------------------------------------------------------------------------------------------------- After providing a brief overview of the ParityVend API endpoints, we can proceed with the actual integration of the API into your website. We will provide examples and "recipes" to help you successfully build a pricing flow with the ParityVend API. Some examples will demonstrate the true flexibility of ParityVend by illustrating how to make use of both the ParityVend No-Code and ParityVend API simultaneously. Note All integration examples assume that you have already obtained your API keys. Additionally, these examples assume that you have created a "default" project, meaning that you have not made any changes to the country groups or discounts. If you have made changes, simply create a new project for learning purposes and use the domain "example.com". ### [Integration Example: Custom Pricing Page](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#integration-example-custom-pricing-page) In this example, we will explain how to use the ParityVend API to create an adaptive pricing page for your product using the `/frontend/get-discount/` endpoint. This example focuses on the `frontend` group endpoint. #### [Step 1: Preparation](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#step-1-preparation) Suppose you have a wonderful pricing page on your website for your *product A*. Currently, your pricing is fixed and shows the same prices to all people. Let's make it adaptive and integrate the ParityVend API to automatically make this pricing fairer, more accessible, and more profitable! - If you wish to follow this example locally, create a file named `pricing.html` and copy the initial code below into it. - Don't forget to insert your `public_key` and `testing_secret` when you copy the example code. - Later in this tutorial, only parts of the code will be shown for convenience. For each code block, you will see a link "view full HTML" that you can use to access the complete HTML code. Here is an initial pricing page (click to expand): Initial pricing page (pricing.html) [](https://www.ambeteco.com/ParityVend/docs/_static/examples/custom_pricing/pricing_1_0.html.txt)[](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#id2 "Link to this code") [![Step 1 - shows initial pricing page](https://www.ambeteco.com/ParityVend/docs/_images/e1_s1.png)](https://www.ambeteco.com/ParityVend/docs/_images/e1_s1.png) As you can see, this pricing page has prices *hardcoded* in it. To make it adaptive and integrate the ParityVend API, we first need to ensure that you store your prices in a programmatic way. There are multiple ways to do it. For example, you could store your prices in a simple variable, something like `const prices = { ... }`, or as an HTML attribute like this: `...`. Let's create a variable that holds our prices and use the attribute on the price element to get the correct price. We'll make some changes to the pricing page's `<head>` element to include a `<script>` with some JavaScript code and also add the attribute `data-plan` to each price ``. Pricing page v1.1 - move prices to a JS variable: [(view full HTML for pricing_1_1.html)](https://www.ambeteco.com/[ParityVend/docs/_static/examples/custom_pricing/pricing_1_1.html.txt)](https://www.ambeteco.com/ParityVend/docs/api_integration_tutorial.html#id3 "Link to this code") `...<script>window.addEventListener('DOMContentLoaded', function () {const prices = {lite: 9.0,pro: 15.0,enterprise: 29.0,}const priceSpans = document.querySelectorAll('.plan-price');for (let i = 0; i < priceSpans.length; i++) {const priceSpan = priceSpans[i];let price = prices[priceSpan.dataset.plan];priceSpan.textContent = '$' + price.toFixed(0);}});</script></head><body>...