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#

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” for a detailed overview of the errors returned by the API and recommendations for the debugging process.

Backend: Primary Endpoints#

GET /backend/get-country-from-ip/(private_key)/#

This endpoint accepts any IP address and returns the corresponding country code following the ISO 3166-1 alpha-2 standard. 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

Example request: Get the country for the IP 190.206.117.0 (Venezuela), with b1234567890abcdefgh as the private key.

GET https://api.parityvend.com/backend/get-country-from-ip/b1234567890abcdefgh/

Example response: "VE", which stands for Venezuela, is returned correctly.

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "country": "VE"
}

Example request: Get the country for the IP 8.8.8.8, with b1234567890abcdefgh as the private key. The response returns XX as the IP 8.8.8.8 is a DNS server, so the ParityVend anti-abuse system is triggered.

GET https://api.parityvend.com/backend/get-country-from-ip/b1234567890abcdefgh/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "country": "XX"
}

Example request: Get the country for the IP 2601:601:201:1af0:3196:493b:a286:2cee (USA), with b1234567890abcdefgh as the private key. The response correctly returns "US". ParityVend has full support for IPV6.

GET https://api.parityvend.com/backend/get-country-from-ip/b1234567890abcdefgh/2601:601:201:1af0:3196:493b:a286:2cee/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "country": "US"
}
GET /backend/get-discount-from-ip/(private_key)/(opt.: base_currency)/#

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. For example: EUR, USD, GBP, JPY, etc.

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.com/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 OK
Content-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
   }
}

Example request: Get the discount information for the IP 190.206.117.0 (Venezuela), with b1234567890abcdefgh as the private key. Context: the project is not configured for Venezuela, so there are no discounts.

GET https://api.parityvend.com/backend/get-discount-from-ip/b1234567890abcdefgh/

Example response: You will receive a response like this when you did not configure a discount or coupon code for the given country.

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "discount": 0.0,
   "discount_str": "0.00%",
   "coupon_code": "",
   "country": {
      "code": "VE",
      "name": "Venezuela",
      "flag": "🇻🇪"
   },
   "currency": {
      "code": "VES",
      "symbol": "Bs.",
      "localized_symbol": "VESBs.",
      "conversion_rate": 36.092756259083146
   }
}

Example request: Get the discount for the IP 8.8.8.8, with b1234567890abcdefgh as the private key. As the IP 8.8.8.8 is a DNS server, the ParityVend anti-abuse system is triggered, and an “empty” response is returned.

GET https://api.parityvend.com/backend/get-discount-from-ip/b1234567890abcdefgh/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "discount": null,
   "discount_str": null,
   "coupon_code": null,
   "country": {},
   "currency": {}
}

Example request: Get the discount information for the IP 102.128.79.255 (Zimbabwe), with b1234567890abcdefgh as the private key and set the base currency to GBP instead of the default value of USD.

GET https://api.parityvend.com/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. The "conversion_rate" is now returned for GBP, just as expected. Notice how the "conversion_rate" is now "390.93", compared to the "321.99" for USD as seen in the first example.

HTTP/1.1 200 OK
Content-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": 390.9304900917495
   }
}
GET /backend/get-banner-from-ip/(private_key)/(opt.: base_currency)/#

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. For example: EUR, USD, GBP, JPY, etc.

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.com/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 <span class="parityvend-var-country-name">Zimbabwe</span>. To enhance your experience, you're eligible for a special <span class="parityvend-var-discount-str">70.00%</span> discount. Use the coupon code <span class="parityvend-var-coupon-code">example_coupon</span> at checkout to get it.

Example request: Get the discount information for the IP 190.206.117.0 (Venezuela), with b1234567890abcdefgh as the private key. Context: the project is not configured for Venezuela, so there are no discounts.

GET https://api.parityvend.com/backend/get-banner-from-ip/b1234567890abcdefgh/

Example response: This is what an “empty” response looks like. You will receive a response like this when you did not configure a discount or coupon code for the given country, or the IP address is detected by the ParityVend anti-abuse systems.

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "html": null,
   "discount": null,
   "discount_str": null,
   "coupon_code": null,
   "country": {},
   "currency": {}
}

Example request: Get the discount for the IP 8.8.8.8, with b1234567890abcdefgh as the private key. As the IP 8.8.8.8 is a DNS server, the ParityVend anti-abuse system is triggered, and an “empty” response is returned.

GET https://api.parityvend.com/backend/get-banner-from-ip/b1234567890abcdefgh/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "html": null,
   "discount": null,
   "discount_str": null,
   "coupon_code": null,
   "country": {},
   "currency": {}
}

Example request: Get the HTML banner for the IP 102.128.79.255 (Zimbabwe), with b1234567890abcdefgh as the private key and set the base currency to GBP instead of the default value of USD.

GET https://api.parityvend.com/backend/get-banner-from-ip/b1234567890abcdefgh/102.128.79.255/GBP/

Example response: An HTML banner response is returned. If you have used the {conversion_rate} variable in the banner text, it will be rendered with the correct exchange rate data. Default banner text does not include this variable, which is why the response is completely the same as in example 1.

It seems like you're visiting from <span class="parityvend-var-country-name">Zimbabwe</span>. To enhance your experience, you're eligible for a special <span class="parityvend-var-discount-str">70.00%</span> discount. Use the coupon code <span class="parityvend-var-coupon-code">example_coupon</span> at checkout to get it.
GET /backend/get-discount-with-html-from-ip/(private_key)/(opt.: base_currency)/#

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. For example: EUR, USD, GBP, JPY, etc.

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.com/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 OK
Content-Type: application/json

{
   "status": "ok",
   "html": "It seems like you're visiting from <span class=\"parityvend-var-country-name\">Zimbabwe</span>. To enhance your experience, you're eligible for a special <span class=\"parityvend-var-discount-str\">70.00%</span> discount. Use the coupon code <span class=\"parityvend-var-coupon-code\">example_coupon</span> 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
   }
}

Example request: Get the discount information and HTML banner for the IP 190.206.117.0 (Venezuela), with b1234567890abcdefgh as the private key. Context: the project is not configured for Venezuela, so there are no discounts.

GET https://api.parityvend.com/backend/get-discount-with-html-from-ip/b1234567890abcdefgh/

Example response: This is what an “empty” response looks like. You will receive a response like this when you did not configure a discount or coupon code for the given country, or the IP address is detected by the ParityVend anti-abuse systems.

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "html": "",
   "discount": 0.0,
   "discount_str": "0.00%",
   "coupon_code": "",
   "country": {
      "code": "VE",
      "name": "Venezuela",
      "flag": "🇻🇪"
   },
   "currency": {
      "code": "VES",
      "symbol": "Bs.",
      "localized_symbol": "VESBs.",
      "conversion_rate": 36.092756259083146
   }
}

Example request: Get the discount information and HTML banner for the IP 8.8.8.8, with b1234567890abcdefgh as the private key. As the IP 8.8.8.8 is a DNS server, the ParityVend anti-abuse system is triggered, and an “empty” response is returned.

GET https://api.parityvend.com/backend/get-discount-with-html-from-ip/b1234567890abcdefgh/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "html": null,
   "discount": null,
   "discount_str": null,
   "coupon_code": null,
   "country": {},
   "currency": {}
}

Example request: Get the discount information and HTML banner for IP 102.128.79.255 (Zimbabwe), with b1234567890abcdefgh as the private key, and set the base_currency to GBP instead of the default value of USD.

GET https://api.parityvend.com/backend/get-discount-with-html-from-ip/b1234567890abcdefgh/102.128.79.255/GBP/

Example response: A correct response with the discount information and HTML banner is returned. It includes the discount percentage, country and currency metadata, exchange rate, and the coupon code you configured. The "conversion_rate" is now returned for GBP, just as expected. Notice how the "conversion_rate" is now "390.93", compared to the "321.99" for USD as seen in the first example.

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "html": "It seems like you're visiting from <span class=\"parityvend-var-country-name\">Zimbabwe</span>. To enhance your experience, you're eligible for a special <span class=\"parityvend-var-discount-str\">70.00%</span> discount. Use the coupon code <span class=\"parityvend-var-coupon-code\">example_coupon</span> 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": 390.9304900917495
   }
}

Backend: Miscellaneous endpoints#

GET /backend/get-quota-info/(private_key)/#

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

Example request: Get the quota information for the account that holds the b1234567890abcdefgh private key.

GET https://api.parityvend.com/backend/get-quota-info/b1234567890abcdefgh/

Example response: Account quota returned correctly.

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "quota_limit": 1500000,
   "quota_used": 235,
   "quota_left": 1499765
}
GET /backend/get-discounts-info/(private_key)/#

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

Example request: Get all the discount information for the project with the b1234567890abcdefgh private key.

GET https://api.parityvend.com/backend/get-discounts-info/b1234567890abcdefgh/

Example response: Discounts information is returned

HTTP/1.1 200 OK
Content-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)/#

This endpoint provides a dictionary in ISO 4217 format 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. For example: EUR, USD, GBP, JPY, etc.

Example request: Get the exchange rate information (by default, with the base set to USD).

GET https://api.parityvend.com/backend/get-exchange-rate-info/b1234567890abcdefgh/

Example response: Exchange rate info is returned:

Exchange rates response (click to expand)
HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "rates": {
      "AED": 3.6727492809295654,
      "AFN": 70.99971008300781,
      "ALL": 94.69617462158203,
      "AMD": 405.6099853515625,
      "ANG": 1.8024892807006836,
      "AOA": 830.5093383789062,
      "ARS": 818.0521240234375,
      "AUD": 1.5186136960983276,
      "AWG": 1.8024992942810059,
      "AZN": 1.6985822916030884,
      "BAM": 1.7957864999771118,
      "BBD": 2.019382953643799,
      "BDT": 109.77002716064453,
      "BGN": 1.7983802556991577,
      "BHD": 0.37695232033729553,
      "BIF": 2856.99951171875,
      "BMD": 1.0,
      "BND": 1.3406791687011719,
      "BOB": 6.9113054275512695,
      "BRL": 4.927096843719482,
      "BSD": 1.0001884698867798,
      "BTC": 0.000023020582375465892,
      "BTN": 83.15725708007812,
      "BWP": 13.644479751586914,
      "BYN": 3.273144483566284,
      "BYR": 19599.99609375,
      "BZD": 2.0160038471221924,
      "CAD": 1.3495545387268066,
      "CDF": 2700.0,
      "CHF": 0.8614020943641663,
      "CLF": 0.03351945802569389,
      "CLP": 924.9100952148438,
      "CNY": 7.127498149871826,
      "COP": 3949.999755859375,
      "CRC": 519.7940673828125,
      "CUC": 1.0,
      "CUP": 26.499996185302734,
      "CVE": 101.04956817626953,
      "CZK": 22.75349235534668,
      "DJF": 177.72006225585938,
      "DKK": 6.859297275543213,
      "DOP": 58.55007553100586,
      "DZD": 134.8001251220703,
      "EGP": 30.89449119567871,
      "ERN": 14.99999713897705,
      "ETB": 56.349849700927734,
      "EUR": 0.9194497466087341,
      "FJD": 2.2351932525634766,
      "FKP": 0.7856394648551941,
      "GBP": 0.7914522290229797,
      "GEL": 2.677499294281006,
      "GGP": 0.7856394648551941,
      "GHS": 11.949804306030273,
      "GIP": 0.7856394648551941,
      "GMD": 67.2750244140625,
      "GNF": 8559.9990234375,
      "GTQ": 7.821099758148193,
      "GYD": 209.2442169189453,
      "HKD": 7.826749324798584,
      "HNL": 24.710004806518555,
      "HRK": 6.880320072174072,
      "HTG": 131.67135620117188,
      "HUF": 349.0796813964844,
      "IDR": 15622.7978515625,
      "ILS": 3.770329713821411,
      "IMP": 0.7856394648551941,
      "INR": 83.0743408203125,
      "IQD": 1309.9998779296875,
      "IRR": 42037.4921875,
      "ISK": 137.27984619140625,
      "JEP": 0.7856394648551941,
      "JMD": 155.43321228027344,
      "JOD": 0.7094023823738098,
      "JPY": 147.2130126953125,
      "KES": 159.50465393066406,
      "KGS": 89.3163833618164,
      "KHR": 4090.99951171875,
      "KMF": 449.60601806640625,
      "KPW": 900.0037841796875,
      "KRW": 1338.799560546875,
      "KWD": 0.30773982405662537,
      "KYD": 0.8334517478942871,
      "KZT": 452.5633239746094,
      "LAK": 20634.99609375,
      "LBP": 15062.4970703125,
      "LKR": 321.71038818359375,
      "LRD": 189.0503692626953,
      "LSL": 18.670555114746094,
      "LTL": 2.95274019241333,
      "LVL": 0.6048903465270996,
      "LYD": 4.795005798339844,
      "MAD": 9.963501930236816,
      "MDL": 17.627315521240234,
      "MGA": 4602.9990234375,
      "MKD": 56.58293914794922,
      "MMK": 2100.294921875,
      "MNT": 3421.143310546875,
      "MOP": 8.061112403869629,
      "MRU": 39.59860610961914,
      "MUR": 45.450340270996094,
      "MVR": 15.403953552246094,
      "MWK": 1682.999267578125,
      "MXN": 17.216598510742188,
      "MYR": 4.64698600769043,
      "MZN": 63.24993896484375,
      "NAD": 18.670106887817383,
      "NGN": 895.4942626953125,
      "NIO": 36.720462799072266,
      "NOK": 10.470093727111816,
      "NPR": 133.0514373779297,
      "NZD": 1.629513144493103,
      "OMR": 0.3849533796310425,
      "PAB": 1.0001976490020752,
      "PEN": 3.7019853591918945,
      "PGK": 3.710986614227295,
      "PHP": 55.94499969482422,
      "PKR": 280.51495361328125,
      "PLN": 4.037389278411865,
      "PYG": 7265.73095703125,
      "QAR": 3.640749931335449,
      "RON": 4.576601505279541,
      "RSD": 107.78895568847656,
      "RUB": 87.96007537841797,
      "RWF": 1272.9998779296875,
      "SAR": 3.7505569458007812,
      "SBD": 8.425458908081055,
      "SCR": 13.423576354980469,
      "SDG": 601.00048828125,
      "SEK": 10.442968368530273,
      "SGD": 1.342484951019287,
      "SHP": 1.2748501300811768,
      "SLE": 22.910032272338867,
      "SLL": 19749.998046875,
      "SOS": 571.0,
      "SRD": 36.797489166259766,
      "STD": 20697.9765625,
      "SYP": 13001.865234375,
      "SZL": 18.670339584350586,
      "THB": 35.410316467285156,
      "TJS": 10.946619033813477,
      "TMT": 3.4999992847442627,
      "TND": 3.093501567840576,
      "TOP": 2.3520140647888184,
      "TRY": 30.101892471313477,
      "TTD": 6.782756805419922,
      "TWD": 31.46649742126465,
      "TZS": 2515.0,
      "UAH": 37.93146896362305,
      "UGX": 3814.175537109375,
      "USD": 1.0,
      "UYU": 39.40886306762695,
      "UZS": 12424.998046875,
      "VEF": 3595779.5,
      "VES": 35.92100524902344,
      "VND": 24519.998046875,
      "VUV": 118.8431167602539,
      "WST": 2.7159276008605957,
      "XAF": 602.3064575195312,
      "XAG": 0.043626971542835236,
      "XAU": 0.0004928250564262271,
      "XCD": 2.702549695968628,
      "XDR": 0.7486168742179871,
      "XOF": 596.9996948242188,
      "XPF": 109.71953582763672,
      "YER": 250.37493896484375,
      "ZAR": 18.96849822998047,
      "ZMK": 9001.19921875,
      "ZMW": 26.254146575927734,
      "ZWL": 321.9995422363281
   }
}

Example request: Get the exchange rate information with EUR as the base currency.

GET https://api.parityvend.com/backend/get-exchange-rate-info/b1234567890abcdefgh/EUR/

Example response: Exchange rate info is returned:

Exchange rates response (click to expand)
HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "rates": {
      "AED": 3.9945080280303955,
      "AFN": 77.21977996826172,
      "ALL": 102.99222564697266,
      "AMD": 441.1442565917969,
      "ANG": 1.9603999853134155,
      "AOA": 903.267822265625,
      "ARS": 889.71923828125,
      "AUD": 1.6516549587249756,
      "AWG": 1.9604109525680542,
      "AZN": 1.847390055656433,
      "BAM": 1.9531099796295166,
      "BBD": 2.1962950229644775,
      "BDT": 119.38665008544922,
      "BGN": 1.9559309482574463,
      "BHD": 0.4099760055541992,
      "BIF": 3107.292724609375,
      "BMD": 1.0876070261001587,
      "BND": 1.458132028579712,
      "BOB": 7.516784191131592,
      "BRL": 5.358745098114014,
      "BSD": 1.0878119468688965,
      "BTC": 0.000025037346858880483,
      "BTN": 90.44242095947266,
      "BWP": 14.839832305908203,
      "BYN": 3.5598950386047363,
      "BYR": 21317.09375,
      "BZD": 2.192620038986206,
      "CAD": 1.4677850008010864,
      "CDF": 2936.5390625,
      "CHF": 0.9368669986724854,
      "CLF": 0.03645600005984306,
      "CLP": 1005.938720703125,
      "CNY": 7.751916885375977,
      "COP": 4296.04736328125,
      "CRC": 565.3316650390625,
      "CUC": 1.0876070261001587,
      "CUP": 28.821582794189453,
      "CVE": 109.9022216796875,
      "CZK": 24.746858596801758,
      "DJF": 193.2895965576172,
      "DKK": 7.460219860076904,
      "DOP": 63.679473876953125,
      "DZD": 146.60955810546875,
      "EGP": 33.60106658935547,
      "ERN": 16.314102172851562,
      "ETB": 61.28649139404297,
      "EUR": 1.0,
      "FJD": 2.431011915206909,
      "FKP": 0.85446697473526,
      "GBP": 0.8607890009880066,
      "GEL": 2.91206693649292,
      "GGP": 0.85446697473526,
      "GHS": 12.99669075012207,
      "GIP": 0.85446697473526,
      "GMD": 73.16878509521484,
      "GNF": 9309.9150390625,
      "GTQ": 8.506282806396484,
      "GYD": 227.5754852294922,
      "HKD": 8.51242733001709,
      "HNL": 26.874774932861328,
      "HRK": 7.483084201812744,
      "HTG": 143.20669555664062,
      "HUF": 379.6615295410156,
      "IDR": 16991.46484375,
      "ILS": 4.100636959075928,
      "IMP": 0.85446697473526,
      "INR": 90.35223388671875,
      "IQD": 1424.7650146484375,
      "IRR": 45720.2734375,
      "ISK": 149.3065185546875,
      "JEP": 0.85446697473526,
      "JMD": 169.0502471923828,
      "JOD": 0.7715510129928589,
      "JPY": 160.1099090576172,
      "KES": 173.47837829589844,
      "KGS": 97.14112854003906,
      "KHR": 4449.39990234375,
      "KMF": 488.9946594238281,
      "KPW": 978.8504638671875,
      "KRW": 1456.0877685546875,
      "KWD": 0.33469998836517334,
      "KYD": 0.9064679741859436,
      "KZT": 492.2110595703125,
      "LAK": 22442.767578125,
      "LBP": 16382.0771484375,
      "LKR": 349.89447021484375,
      "LRD": 205.6125030517578,
      "LSL": 20.30622673034668,
      "LTL": 3.211421012878418,
      "LVL": 0.6578829884529114,
      "LYD": 5.215082168579102,
      "MAD": 10.836374282836914,
      "MDL": 19.171592712402344,
      "MGA": 5006.25390625,
      "MKD": 61.540000915527344,
      "MMK": 2284.29541015625,
      "MNT": 3720.859619140625,
      "MOP": 8.767322540283203,
      "MRU": 43.06772232055664,
      "MUR": 49.43210983276367,
      "MVR": 16.753448486328125,
      "MWK": 1830.44189453125,
      "MXN": 18.72489356994629,
      "MYR": 5.0540947914123535,
      "MZN": 68.79107666015625,
      "NAD": 20.305740356445312,
      "NGN": 973.9458618164062,
      "NIO": 39.93743133544922,
      "NOK": 11.387347221374512,
      "NPR": 144.70767211914062,
      "NZD": 1.7722699642181396,
      "OMR": 0.4186779856681824,
      "PAB": 1.0878219604492188,
      "PEN": 4.026305198669434,
      "PGK": 4.036095142364502,
      "PHP": 60.84617614746094,
      "PKR": 305.09002685546875,
      "PLN": 4.391092777252197,
      "PYG": 7902.26025390625,
      "QAR": 3.959705114364624,
      "RON": 4.977543830871582,
      "RSD": 117.23202514648438,
      "RUB": 95.6659927368164,
      "RWF": 1384.5235595703125,
      "SAR": 4.079132080078125,
      "SBD": 9.163588523864746,
      "SCR": 14.599575996398926,
      "SDG": 653.65234375,
      "SEK": 11.357845306396484,
      "SGD": 1.460096001625061,
      "SHP": 1.3865360021591187,
      "SLE": 24.917112350463867,
      "SLL": 21480.236328125,
      "SOS": 621.0236206054688,
      "SRD": 40.021209716796875,
      "STD": 22511.265625,
      "SYP": 14140.919921875,
      "SZL": 20.305992126464844,
      "THB": 38.512508392333984,
      "TJS": 11.905619621276855,
      "TMT": 3.806623935699463,
      "TND": 3.364514112472534,
      "TOP": 2.5580670833587646,
      "TRY": 32.73902893066406,
      "TTD": 7.376974105834961,
      "TWD": 34.223182678222656,
      "TZS": 2735.331787109375,
      "UAH": 41.25453186035156,
      "UGX": 4148.32421875,
      "USD": 1.0876070261001587,
      "UYU": 42.86135482788086,
      "UZS": 13513.515625,
      "VEF": 3910795.0,
      "VES": 39.067935943603516,
      "VND": 26668.12109375,
      "VUV": 129.25460815429688,
      "WST": 2.953861951828003,
      "XAF": 655.07275390625,
      "XAG": 0.04744900017976761,
      "XAU": 0.0005360000068321824,
      "XCD": 2.939311981201172,
      "XDR": 0.8142009973526001,
      "XOF": 649.3010864257812,
      "XPF": 119.33174133300781,
      "YER": 272.3095397949219,
      "ZAR": 20.630271911621094,
      "ZMK": 9789.767578125,
      "ZMW": 28.5541934967041,
      "ZWL": 350.2089538574219
   }
}

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)/#

Based on the requestor’s IP address, this endpoint returns the corresponding country code in ISO 3166-1 alpha-2 format. “XX” indicates the use of a VPN, proxy, or TOR.

Parameters:

  • public_key – Your public key

Example request: Consider your IP address is 190.206.117.0 (Venezuela), with a1234567890abcdefgh as the public key.

GET https://api.parityvend.com/frontend/get-country/a1234567890abcdefgh/

Example response: "VE", which stands for Venezuela, is returned correctly.

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "country": "VE"
}

Example request: Consider you are using a VPN, with a public key a1234567890abcdefgh. The response returns XX, as your IP is related to a VPN, so the ParityVend anti-abuse system is triggered.

GET https://api.parityvend.com/frontend/get-country/a1234567890abcdefgh/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "country": "XX"
}

Example request: Consider your IP address is 2601:601:201:1af0:3196:493b:a286:2cee (USA), with a1234567890abcdefgh as the public key. The response correctly returns "US". ParityVend has full support for IPV6.

GET https://api.parityvend.com/frontend/get-country/a1234567890abcdefgh/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "country": "US"
}
GET /frontend/get-discount/(public_key)/(opt.: base_currency)/#

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. For example: EUR, USD, GBP, JPY, etc.

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.com/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 OK
Content-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
   }
}

Example request: Consider your IP address is 190.206.117.0 (Venezuela). Get the discount information with a1234567890abcdefgh as the public key. Context: the project is not configured for Venezuela, so there are no discounts.

GET https://api.parityvend.com/frontend/get-discount/a1234567890abcdefgh/

Example response: This is what an “empty” response looks like. You will receive a response like this if you do not configure a discount or coupon code for the given country.

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "discount": 0.0,
   "discount_str": "0.00%",
   "coupon_code": "",
   "country": {
      "code": "VE",
      "name": "Venezuela",
      "flag": "🇻🇪"
   },
   "currency": {
      "code": "VES",
      "symbol": "Bs.",
      "localized_symbol": "VESBs.",
      "conversion_rate": 36.092756259083146
   }
}

Example request: Consider you are using a VPN. Get the discount with a1234567890abcdefgh as the public key. As your IP has connection to a VPN, the ParityVend anti-abuse system is triggered, and an “empty” response is returned.

GET https://api.parityvend.com/frontend/get-discount/a1234567890abcdefgh/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "discount": null,
   "discount_str": null,
   "coupon_code": null,
   "country": {},
   "currency": {}
}

Example request: Consider your IP address is 102.128.79.255 (Zimbabwe). Get the discount information with a1234567890abcdefgh as the public key and set the base currency to GBP instead of the default value of USD.

GET https://api.parityvend.com/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. The "conversion_rate" is now returned for GBP, just as expected. Notice how the "conversion_rate" is now "390.93", compared to the "321.99" for USD, as seen in the first example.

HTTP/1.1 200 OK
Content-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": 390.9304900917495
   }
}
GET /frontend/get-banner/(public_key)/(opt.: base_currency)/#

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. For example: EUR, USD, GBP, JPY, etc.

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.com/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 <span class="parityvend-var-country-name">Zimbabwe</span>. To enhance your experience, you're eligible for a special <span class="parityvend-var-discount-str">70.00%</span> discount. Use the coupon code <span class="parityvend-var-coupon-code">example_coupon</span> at checkout to get it.

Example request: Consider your IP address is 190.206.117.0 (Venezuela). Get the discount information with a1234567890abcdefgh as the public key. Context: the project is not configured for Venezuela, so there are no discounts.

GET https://api.parityvend.com/frontend/get-banner/a1234567890abcdefgh/

Example response: This is what an “empty” response looks like. You will receive a response like this if you do not configure a discount or coupon code for the given country.

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "html": null,
   "discount": null,
   "discount_str": null,
   "coupon_code": null,
   "country": {},
   "currency": {}
}

Example request: Consider you are using a VPN. Get the discount with a1234567890abcdefgh as the public key. As the IP has relation to a VPN, the ParityVend anti-abuse system is triggered, and an “empty” response is returned.

GET https://api.parityvend.com/frontend/get-banner/a1234567890abcdefgh/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "html": null,
   "discount": null,
   "discount_str": null,
   "coupon_code": null,
   "country": {},
   "currency": {}
}

Example request: Consider your IP address is 102.128.79.255 (Zimbabwe). Get the HTML banner with a1234567890abcdefgh as the public key and set the base currency to GBP instead of the default value of USD.

GET https://api.parityvend.com/frontend/get-banner/a1234567890abcdefgh/

Example response: An HTML banner response is returned. If you have used the {conversion_rate} variable in the banner text, it will be rendered with the correct exchange rate data. The default banner text does not include this variable, which is why the response is completely the same as in Example 1.

It seems like you're visiting from <span class="parityvend-var-country-name">Zimbabwe</span>. To enhance your experience, you're eligible for a special <span class="parityvend-var-discount-str">70.00%</span> discount. Use the coupon code <span class="parityvend-var-coupon-code">example_coupon</span> at checkout to get it.
GET /frontend/get-discount-with-html/(public_key)/(opt.: base_currency)/#

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. For example: EUR, USD, GBP, JPY, etc.

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.com/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 OK
Content-Type: application/json

{
   "status": "ok",
   "html": "It seems like you're visiting from <span class=\"parityvend-var-country-name\">Zimbabwe</span>. To enhance your experience, you're eligible for a special <span class=\"parityvend-var-discount-str\">70.00%</span> discount. Use the coupon code <span class=\"parityvend-var-coupon-code\">example_coupon</span> 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
   }
}

Example request: Consider your IP address is 190.206.117.0 (Venezuela). Get the discount information and HTML banner with a1234567890abcdefgh as the public key. Context: the project is not configured for Venezuela, so there are no discounts.

GET https://api.parityvend.com/frontend/get-discount-with-html/a1234567890abcdefgh/

Example response: This is what an “empty” response looks like. You will receive a response like this if you do not configure a discount or coupon code for the given country.

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "html": "",
   "discount": 0.0,
   "discount_str": "0.00%",
   "coupon_code": "",
   "country": {
      "code": "VE",
      "name": "Venezuela",
      "flag": "🇻🇪"
   },
   "currency": {
      "code": "VES",
      "symbol": "Bs.",
      "localized_symbol": "VESBs.",
      "conversion_rate": 36.092756259083146
   }
}

Example request: Consider you are using a VPN. Get the discount information and HTML banner with a1234567890abcdefgh as the public key. As your IP has relation to a VPN, the ParityVend anti-abuse system is triggered, and an “empty” response is returned.

GET https://api.parityvend.com/frontend/get-discount-with-html/a1234567890abcdefgh/

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "html": null,
   "discount": null,
   "discount_str": null,
   "coupon_code": null,
   "country": {},
   "currency": {}
}

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 and set the base currency to GBP instead of the default value of USD.

GET https://api.parityvend.com/frontend/get-discount-with-html/a1234567890abcdefgh/

Example response: A correct response with the discount information and HTML banner is returned. It includes the discount percentage, country and currency metadata, exchange rate, and the coupon code you configured. The "conversion_rate" is now returned for GBP, just as expected. Notice how the "conversion_rate" is now "390.93", compared to the "321.99" for USD, as seen in the first example.

HTTP/1.1 200 OK
Content-Type: application/json

{
   "status": "ok",
   "html": "It seems like you're visiting from <span class=\"parityvend-var-country-name\">Zimbabwe</span>. To enhance your experience, you're eligible for a special <span class=\"parityvend-var-discount-str\">70.00%</span> discount. Use the coupon code <span class=\"parityvend-var-coupon-code\">example_coupon</span> 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": 390.9304900917495
   }
}

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” page to learn how to use it.

What’s Next?#

As you integrate the ParityVend API into your project, we highly recommend exploring the “Complete overview” series for a deeper understanding of our platform. If you encounter any errors during integration, be sure to consult the “Debugging Guide”, which contains a comprehensive list of error codes and messages to assist you in troubleshooting.