Visa Merchant Offers Resource Center API Reference
Visa Merchant Offers Resource Center
The Offers Data API provides developers a quick and easy way to retrieve offer information from VMORC. The API allows you to retrieve all your available offers or retrieve specific offers. In an offer-specific request, you may choose to filter your accessible offers by certain offer attributes or you may request for offers by its identifiers.
Retrieve Offers by a Content Id v1 - Latest
Retrieve the language-specific offer. Each specified contentID returns one offer content object. Query param "contentId" is required.
Request
query Parameters
| accountranges | string Request for offers that fulfill a specific Account Range by providing either a "from" prefix value OR a "to" prefix value OR a "from" and a "to" prefix values. Each provided prefix value must be a minimum of 4 digits. Each account range request must contain a colon(":") to distinguish between the "from" and "to" values (even if only one boundary is provided). |
| accountranges_to_rpins | string Request for offers that fulfill a specific Account Range to RPIN pairing by providing either a "from" prefix value ~ RPIN OR a "to" prefix value ~ RPIN OR a "from" and a "to" prefix values ~ RPIN. Each provided account range prefix value must be a minimum of 4 digits. Each account range portion of the request must contain a colon(":") to distinguish between the "from" and "to" values (even if only one boundary is provided). Use a tilde("~") to separate the account range from the exact desired rpin. |
| bins | string Request for offers that fulfill one or more BIN options by inputting the exact desired bin value(s). Comma-delimit for multiple values |
| bins_to_rpins | string Request for offers that fulfill one or more BIN to RPIN pairing options by inputting the exact desired bin value, a tilde("~"), and the exact rpin value. |
| business_segment | string Filter offers by business segments. Provide one "key" integer or a comma-delimited string of "key" integers Refer to business_segments for sample values and keys. |
| card_payment_type | string Filter offers by card payment types. Provide one "key" integer or a comma-delimited string of "key" integers Refer to card_payment_types for sample values and keys. |
| card_product | string Filter offers by card products. Provide one "key" integer or a comma-delimited string of "key" integers Refer to card_product for sample values and keys. |
| category | string Filter offers by offer categories. Provide one "key" integer or a comma-delimited string of "key" integers Refer to category_subcategory for sample values and keys. |
| contentid | string Retrieve offers by their content ids. Provide an content id integer or a comma-delimited string of content id integers |
| expired | boolean Request for expired offers. Provide a boolean value. Default set to value to "false". |
| featured | boolean Request for featured offers. Provide a boolean value. |
| language | string Filter offers by offer languages. Provide one "key" integer or a comma-delimited string of "key" integers |
| max_offers | integer Optional. A maximum of 500 offer results are returned in the offer response. The index indicates the maximum number of offers to return in the response. Accepts an integer (greater than 0; less than or equal to 500). Default set to 500 |
| merchant | string Filter offers by merchants. Provide one "key" integer or a comma-delimited string of "key" integers Refer to merchant for sample values and keys. |
| merchant_county | string Filter for offers that have been assigned a merchant address in at least one merchant address country parameter Refer to country for sample values and keys. |
| merchant_region | string Filter for offers that have been assigned a merchant address in at least one merchant address region parameter Refer to region for sample values and keys. |
| non_cardAttribute | boolean Request for offers that do not have assignments to card attribute fields. Provide a boolean value. Default sets value to "false". |
| non_geo | boolean Optional for applying a geolocation filter.. Request for offers that have not been assigned merchant addresses with geo-location(latitude/longitude) coordinates. At minimum, an origin must be also provided to call this flag. Accepts a boolean value - By default, the boolean value is set to false. |
| offerid | string Retrieve offers by their offer ids. Provide an offer id integer or a comma-delimited string of offer id integers |
| origin | string Required for applying a geolocation filter. Input the origin by specifying the latitude, a comma (""), and the longitude. Coordinates must be inputted in decimal degree format. The accepted range for latitude is between -90 and 90, inclusive. The accepted range for longitude is between -180 and 180, inclusive. |
| pans | string Request for offers by PAN (must be a minimum of 16 digits). The provided PAN is padded-right with "0" to a length of 21 digits. The system returns the offers where the padded value is within the subset of at least one of the offer's account range assignments. |
| program | string Filter offers by programs. Provide one "key" integer or a comma-delimited string of "key" integers Refer to program for sample values and keys. |
| promotedfrom | string Request for offers where the offer’s promotion end date is on or after the provided date (in GMT). Accepts a date formatted by: yyyyMMdd e.g. 1, If promotedfrom=20150101 is provided, this will / return eligible offers where the promotion ends on or after January 1, 2015 e.g. 2, If promotedfrom=20150101&promotedto=20150131, this will return eligible offers where the promotion ends on or after January 1, 2015 and start on or before January 31, 2015 (promoted at least one day in January 2015). |
| promotedto | string Request for offers where the offer’s promotion start date is before or on the provided date (in GMT). Accepts a date formatted by: yyyyMMdd e.g. 1, If promotedto=20150131 is provided, this will return eligible offers where the promotion starts before or on January 31, 2015 e.g. 2, If validfrom=20150101&validto=20150131, this will return eligible offers that end on or after January 1, 2015 and start on or before January 31, 2015 (valid during at least one day in January 2015). |
| promoting_country | string Filter offers by promoting countries. Provide one "key" integer or a comma-delimited string of "key" integers Refer to country for sample values and keys. |
| promoting_region | string Filter offers by promoting regions. Provide one "key" integer or a comma-delimited string of "key" integers Refer to region for sample values and keys. |
| promotion_channel | string Filter offers by promotion channels. Provide one "key" integer or a comma-delimited string of "key" integers Refer to promotion_channel for sample values and keys. |
| radius | number Optional for applying a geolocation filter.. A maximum radius of 1000 (kilometers) or 621.371 (miles) is accepted. Default sets to 60 miles (or 100 kilometers if the "unit" geolocation parameter has been set to "km"). |
| redemption_country | string Filter offers by redemption countries. Provide one "key" integer or a comma-delimited string of "key" integers Refer to country for sample values and keys. |
| redemption_region | string Filter offers by redemption regions. Provide one "key" integer or a comma-delimited string of "key" integers Refer to region for sample values and keys. |
| rpins | string Request for offers that fulfill one or more RPIN options by inputting the exact desired rpin value(s). Comma-delimit for multiple values |
| start_index | integer A maximum of 500 offer results may be returned in the response. The parameter specifies the index of the total available offer results to start returning in the response. |
| subcategory | string Filter offers by offer subcategories. Provide one "key" integer or a comma-delimited string of "key" integers Refer to category_subcategory for sample values and keys. |
| unit | number Optional for applying a geolocation filter.. Indicate the distance unit of miles or kilometers. Default sets to miles. To use kilometers, specify "km". |
| updatefrom | string Request for offers where the provided date is before or on an offer’s last modified date/time (in GMT). Accepts a date formatted by: yyyyMMdd |
| updateto | string Request for offers where the provided date is after or on an offer’s last modified date/time (in GMT). Accepts a date formatted by: yyyyMMdd |
| validfrom | string Request for offers where the offer's redemption end date is on or after the provided date (in GMT). Accepts a date formatted by: yyyyMMdd e.g. 1, If validfrom=20150101 is provided, this returns eligible offers that end on or after January 1, 2015 e.g. 2, If validfrom=20150101&validto=20150131, this will return eligible offers that end on or after January 1, 2015 and start on or before January 31, 2015 (valid during at least one day in January 2015). |
| validto | string Request for offers where the offer’s redemption start date is before or on the provided date (in GMT). Accepts a date formatted by: yyyyMMdd e.g. 1, If validto=20150131 is provided, this will return eligible offers that start before or on January 31, 2015 e.g. 2, If validfrom=20150101&validto=20150131, this will return eligible offers that end on or after January 1, 2015 and start on or before January 31, 2015 (valid during at least one day in January 2015). |
Responses
200 ok
Response Schema: application/json
| Offers | Array of objects |
| Array |
| accountranges | Array of objects | | Array
| companyName | string
the name of the bank associated to the Account Range. Max length: 100 characters |
| ubid | integer
the companyName's UBID |
| valueFrom | string
the Account Range from value. Max length: 21 bytes |
| valueTo | string
the Account Range to value. Max length: 21 bytes |
| accountrangestorpins | Array of objects |
| Array
| AccountRange | object |
| | | |
| --- | --- |
| companyName | string
the name of the bank associated to the Account Range. Max length: 100 characters |
| ubid | integer
the companyName's UBID |
| valueFrom | string
the Account Range from value. Max length: 21 bytes |
| valueTo | string
the Account Range to value. Max length: 21 bytes |
| RPIN | object |
| | | |
| --- | --- |
| companyName | string
the name of the bank associated to the RPIN. Max length: 100 characters |
| description | string
the description of the RPIN. Max length: 500 characters |
| ubid | integer
the companyName's UBID |
| value | string
the RPIN numerical value. Max length: 50 characters |
| activeIndicator | boolean
indicator whether offer is active |
| barcode | object |
| | | |
| --- | --- |
| description | string
the description of the image. May return an empty String. Only applicable for Offer Images; Not applicable for QR Codes or Barcodes. Max length: 1024 characters |
| fileLocation | string
the external location for the merchant image file. Max length: File path should be less than 1024 characters |
| imageAltTag | string
the alt tag for the image Only applicable for Offer Images; Not applicable for QR Codes or Barcodes |
| imageFileHeight | string
the pixel height of the image Non-browser supported image (EPS, TIF) will return an empty String for this field. |
| imageFileSize | string
the size of the image file (in KB) |
| imageFileWidth | string
the pixel width of the image Non-browser supported image (EPS, TIF) will return an empty String for this field. |
| imageResolution | string
the resolution of the image. Only applicable for Offer Images; Not applicable for QR Codes or Barcodes. Max length:6 characters |
| key | integer
an identifier for the image |
| offerImagePromotionChannelIds | Array of objects
the promotion channel ids associated to the offer image Only applicable for Offer Images; Not applicable for QR Codes or Barcodes |
| offerImagePromotionChannels | Array of objects
the promotion channels associated to the offer image Only applicable for Offer Images; Not applicable for QR Codes or Barcodes |
| bins | Array of objects |
| Array
| companyName | string
the name of the bank associated to the BIN. Max length: 100 characters |
| ubid | integer
the companyName's UBID |
| value | string
the BIN numerical value. Max length: 20 characters |
| binstorpins | Array of objects |
| Array
| BIN | object |
| | | |
| --- | --- |
| companyName | string
the name of the bank associated to the BIN. Max length: 100 characters |
| ubid | integer
the companyName's UBID |
| value | string
the BIN numerical value. Max length: 20 characters |
| RPIN | object |
| | | |
| --- | --- |
| companyName | string
the name of the bank associated to the RPIN. Max length: 100 characters |
| description | string
the description of the RPIN. Max length: 500 characters |
| ubid | integer
the companyName's UBID |
| value | string
the RPIN numerical value. Max length: 50 characters |
| businessSegmentList | Array of objects |
| Array
| key | integer
an identifier |
| value | string
a label |
| cardPaymentType | Array of objects |
| Array
| key | integer
an identifier |
| value | string
a label |
| cardProductList | Array of objects |
| Array
| key | integer
an identifier |
| value | string
a label |
| categorySubcategoryList | Array of objects |
| Array
| key | integer
an identifier |
| subcategories | Array of objects |
| Array
| key | integer
an identifier |
| value | string
a label |
| value | string
the default label |
| creativeApprovalsEmail | string
the email of the creative approval of the offer. May return an empty String. Max length: 200 characters |
| creativeGuidelines | string
the creative guidelines of the offer. May return an empty String. Max length: 2GB |
| currentVersion | integer
the version of the offer |
| dateLocations | Array of objects |
| Array
| address1 | string
the first line of the location |
| address2 | string
the second line of the location. May return an empty String |
| city | string
the city of the location |
| countryName | string
the country name |
| dateLocationId | integer
a date location identifier |
| endDate | string
the end date (in GMT). Formatted as Mon DD, YYYY |
| isSoldOut | boolean
the sold out indicator |
| latitude | string
the latitude of the location. May return an empty String |
| longitude | string
the longitude of the location. May return an empty String |
| postalCode | string
the postal code/zip code |
| startDate | string
the start date (in GMT). Formatted as Mon DD, YYYY |
| state | string
the state/province/territory of the location |
| eventSubTitle | string
the event sub title. Returns an empty String if the offer is not an event. Field is optional for events |
| fAQs | object |
|---|---|
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| featuredOfferIndicator | boolean indicator whether the offer is featured |
| imageList | Array of objects |
| Array |
| description | string
the description of the image. May return an empty String. Only applicable for Offer Images; Not applicable for QR Codes or Barcodes. Max length: 1024 characters |
| fileLocation | string
the external location for the merchant image file. Max length: File path should be less than 1024 characters |
| imageAltTag | string
the alt tag for the image Only applicable for Offer Images; Not applicable for QR Codes or Barcodes |
| imageFileHeight | string
the pixel height of the image Non-browser supported image (EPS, TIF) will return an empty String for this field. |
| imageFileSize | string
the size of the image file (in KB) |
| imageFileWidth | string
the pixel width of the image Non-browser supported image (EPS, TIF) will return an empty String for this field. |
| imageResolution | string
the resolution of the image. Only applicable for Offer Images; Not applicable for QR Codes or Barcodes. Max length:6 characters |
| key | integer
an identifier for the image |
| offerImagePromotionChannelIds | Array of objects
the promotion channel ids associated to the offer image Only applicable for Offer Images; Not applicable for QR Codes or Barcodes |
| offerImagePromotionChannels | Array of objects
the promotion channels associated to the offer image Only applicable for Offer Images; Not applicable for QR Codes or Barcodes |
| indexNumber | integer
an integer identifier to signify the result index for the offer (specific to the request) |
| isOfferEvent | boolean
the indicator to specify that the offer is an event |
| language | string
the name of the language. Max length: 100 characters |
| languageId | integer
the identifier for the language of the offer |
| lastModifiedDateTime | string
the date and time the offer was last updated. Formatted as : DayOfWeek, DD Mon YYYY HH:MM:SS GMT |
| legalCountryExclusions | object |
|---|---|
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| merchantList | Array of objects |
| Array |
| merchant | string
the merchant name. Max length: 200 characters |
| merchantAddress | Array of objects |
| Array
| address1 | string
the first line of the merchant address. Max length: 200 characters |
| address2 | string
the second line of the merchant. May return an empty String |
| city | string
the city of the merchant address |
| countryName | string
the country name |
| distance | string
the distance from the origin to the merchant address. Only displayed when a geolocation filter has been applied and the address has valid latitude and longitude coordinates Max length: Computed - should be less than 20 bytes + distance unit |
| indexNumber | integer
an integer identifier to signify the result index for the merchant address (specific to your request). Only displayed for a merchant address reference data request |
| key | integer
the identifying value of the merchant address |
| languageIds | Array of objects
returns all keys for the languages associated with the address |
| languageName | string
Deprecated; languages returns a complete list | A single language associated to the merchant address |
| languages | Array of objects
returns all languages associated with the address |
| latitude | string
the latitude of the address |
| longtitude | string
the longitude of the address |
| merchantKey | integer
the identifying value of the merchant. Only displayed for a merchant address reference data request |
| merchantValue | string
the default merchant name. Only displayed for a merchant address reference data request |
| postalCode | string
the postal code/zip code |
| state | string
the state/province/territory of the merchant address |
| merchantId | integer
an identifier for the merchant |
| merchantImages | Array of objects |
| Array
| description | string
a description provided for the image. May return an empty String. Max length: 1024 characters |
| fileLocation | string
the external location for the merchant image file |
| fileName | string
name provided for the file. Max length: 50 characters |
| imageFileHeight | string
the pixel height of the image | Non-browser supported image (EPS, TIF) will return an empty String for this field. |
| imageFileSize | string
the size of the image file (in KB) |
| imageFileWidth | string
the pixel width of the image | Non-browser supported image (EPS, TIF) will return an empty String for this field. |
| imageResolution | string
a description provided for the image. Max length: 6 characters |
| key | integer
an identifier for the key |
| languageIds | Array of objects
returns all keys for the languages associated with the logo |
| languages | Array of objects
returns all languages associated with the logo |
| logoAltTag | string
the alt tag for the image. May return an empty String |
| promotionChannel | string
Deprecated; promotionChannels returns a complete list | Returns a single promotion channel associated with the image |
| promotionChannels | Array of objects
returns all promotion channels associated with the image |
| promotionId | integer
Deprecated; promotionIds returns a complete list | Returns a single key for the promotion channel associated with the image |
| promotionIds | Array of objects
returns all keys for the promotion channels associated with the image |
| merchantTerms | object |
|---|---|
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| offerContentId | integer a unique identifier for the offer for the specific version and specified language |
| offerCopy | object |
| --- | --- |
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| offerId | integer an identifier for the offer and any translations it may have |
| offerMetadata | Array of objects |
| Array |
| metaId | integer
an identifier |
| metaKey | string
a user-provided key |
| metaValue | string
a user-provided value |
| offerShortDescription | object |
|---|---|
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| offerSource | string the source agency asssociated with the offer. Max length: 200 characters |
| offerSourceContact | string the source agency contact asssociated with the offer. Max length: 100 characters |
| offerStatus | string the status of the offer |
| offerTitle | string the title of the offer. Max length: 1000 characters |
| offerType | Array of objects |
| Array |
| key | integer
an identifier |
| value | string
a label |
| programId | integer
the identifier for the program |
| programName | string
the name of the program. Max length: 500 characters. |
| promotingCountries | Array of objects |
| Array
| key | integer
an identifier |
| value | string
a label |
| promotionChannelList | Array of objects |
| Array
| key | integer
an identifier |
| value | string
a label |
| promotionFromDate | string
the start of the promotion date range (in GMT). Formatted as: Mon DD, YYYY |
| promotionRestictions | object |
|---|---|
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| promotionToDate | string the end of the promotion date range (in GMT). Formatted as: Mon DD, YYYY |
| qrCode | object |
| --- | --- |
| description | string the description of the image. May return an empty String. Only applicable for Offer Images; Not applicable for QR Codes or Barcodes. Max length: 1024 characters |
| fileLocation | string the external location for the merchant image file. Max length: File path should be less than 1024 characters |
| imageAltTag | string the alt tag for the image Only applicable for Offer Images; Not applicable for QR Codes or Barcodes |
| imageFileHeight | string the pixel height of the image Non-browser supported image (EPS, TIF) will return an empty String for this field. |
| imageFileSize | string the size of the image file (in KB) |
| imageFileWidth | string the pixel width of the image Non-browser supported image (EPS, TIF) will return an empty String for this field. |
| imageResolution | string the resolution of the image. Only applicable for Offer Images; Not applicable for QR Codes or Barcodes. Max length:6 characters |
| key | integer an identifier for the image |
| offerImagePromotionChannelIds | Array of objects the promotion channel ids associated to the offer image Only applicable for Offer Images; Not applicable for QR Codes or Barcodes |
| offerImagePromotionChannels | Array of objects the promotion channels associated to the offer image Only applicable for Offer Images; Not applicable for QR Codes or Barcodes |
| redemptionChannelList | Array of objects |
| Array |
| key | integer
an identifier |
| value | string
a label |
| redemptionCode | string
the redemption code of the offer. May return an empty String. Max length: 1024 characters |
| redemptionCountries | Array of objects |
| Array
| key | integer
an identifier |
| value | string
a label |
| redemptionEmail | string
the redemption Email of the offer. May return an empty String. Max length: 2048 characters |
| redemptionFormatInstructions | string
the format instructions for redemption of offer. May return an empty String. Max length: 2048 characters |
| redemptionTelephone | object |
|---|---|
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| redemptionUrl | string the redemption URL of the offer. May return an empty String. Max length: 2048 characters |
| rpins | Array of objects |
| Array |
| companyName | string
the name of the bank associated to the RPIN. Max length: 100 characters |
| description | string
the description of the RPIN. Max length: 500 characters |
| ubid | integer
the companyName's UBID |
| value | string
the RPIN numerical value. Max length: 50 characters |
| shareTitle | string
the social media sharing title. Returns an empty String if the offer does not have social media sharing types. |
| socialMediaSharingTypes | Array of objects |
| Array
| key | integer
an identifier |
| value | string
a label |
| soldOut | boolean
indicator whether offer is sold out |
| supData1 | object |
|---|---|
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| supData2 | object |
| --- | --- |
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| supData3 | object |
| --- | --- |
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| supData4 | object |
| --- | --- |
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| validityFromDate | string the start of the validity date range (in GMT). Formatted as: Mon DD, YYYY |
| validityToDate | string the end of the validity date range (in GMT). Formatted as: Mon DD, YYYY |
| visaTerms | object |
| --- | --- |
| richText | string the text inputted with styled tags. Max length: 2GB |
| text | string the text without styled tags. Max length: 2GB |
| ReturnedResults | integer The number of offers returned in the offer reponse. A maximum of 500 offers are returned |
| StartIndex | integer The index at which the offer response begins. The value corresponds with the start_index parameter. If it was not provided, defaults to 1 |
| TotalFoundResults | integer The total number of offers that match the request |
400 Invalid query
default Unexpected error