Deal API

Introductionback to top

You have only but to be approved for a GPN account to gain access to our most up-to-date API and the deluge of 250k+ deals from all our channels (Local, Goods and Travel), will be right at your fingertips. This documentation will walk you through the commonly used terminology, and how to get deals by location and category.

Termsback to top

Affiliate Id
This is the unique ID assigned to the Affiliate in GPN to attribute referred sales. To find your Affiliate Id, log into your GPN account and navigate to My Account Account Profile Affiliate Id
Media Id
Specific value assigned to a promotional link in GPN.
SID
GPN provides the capability for publishers to pass unique values in their affiliate link to identify where sale actions originate. Loyalty and Rewards publishers may use this parameter to pass a unique member ID in order to credit cash-back or points to its members.
WID
This is an additional Id that can be used to associate a sale with a particular Affiliate website. This Id is useful when an affiliate has multiple websites to differentiate where sales are coming from.
tsToken
This tracking token must be used in all DEAL API calls to identify the affiliate and media that a customer sale originated from.

Example

tsToken=IE_AFF_0_200012_212556_0
The following values are assigned to Affiliate Id and Media Id for this example affiliate:
Affiliate Id=200012
Media Id= 212556

Please supply your own Affiliate Id in the tsToken when making your own calls.

UTM tracking parameters
Tracking parameters are used internally to track sales and then attribute those sales to the correct affiliate. They are generated automatically using the tsToken passed to the API. The tracking parameters may be overridden by passing in your values. We highly recommend you contact your affiliate manager before supplying your own parameters as you may not get attributed for the sales you generate.

Example

utm_source=GPN&utm_medium=afl&utm_campaign=200012
where
utm_source=GPN (Traffic Source)
utm_medium=afl (Identifier for a particular traffic source)
utm_campaign=200012 (Your Affiliate Id)

Performance Improvementsback to top

To optimize calls:

  • Use JSON endpoint
  • Include a location value whenever possible (division_id or Lat/lng). If you do not specify a location, the IP address of the invoking device will be used
  • Use pagination to limit the number of deals returned. The maximum number of deals returned is 250 per call

URLback to top

https://partner-int-api.groupon.com/deals {.json|.xml}

Supported Formatsback to top

  • JSON (default)
  • XML

URL parametersback to top

General

tsToken
  • Required
  • Your identifying tracking server token
  • Example: tsToken=IE_AFF_0_200012_212556_0
offset
  • Optional
  • The index (zero-based) of the complete search result set on which to start returning results, up to the provided or default result set size
  • Default: 0
  • Example: offset=0
limit
  • Optional
  • The number of deals to return in the response
  • Default: 75
  • Max limit: 250 per call
  • Example: limit=50

Location

Location can be specified using country_code and either division_id or using lat/lng pair with optional radius. If none are provided, the API will use location based off of IP address. If any of these values are present but do not map to a division, the API will return a "Invalid division" 400 response.

country_code
  • Required
  • The ISO 3166 Country Code
  • Refer to Division API for a list of valid country codes
  • Example: country_code=UK

By Division

division_id
  • Optional
  • Used for locating deals in a specific division or city
  • Refer to Division API for a list of valid divisions
  • Example: division_id=dublin

By Lat/lng pair with optional radius

lat
  • Optional
  • Used for locating deals near a specific lat / lng
  • Example: lat=53.33415
lng
  • Optional
  • Used for locating deals near a specific lat / lng
  • Example: lng=-6.25946
radius
  • Optional
  • Specified in kilometers
  • Default: 10
  • Maximum: 100
  • Example: radius=20

Categories

Return a list of deals that are currently launched for a specific category. Note, topcategory and category can be combined, see examples below.

filters=topcategory:
  • Optional
  • Append the category you wish to filter on, either goods or travel
  • Example: filters=topcategory:goods
filters=category:
  • Optional
  • Append the sub-category you wish to filter on
  • Example: filters=category:food-and-drink
  • Sub-categories can be joined using the | operator url-encoded as %7C. This will lead to deals from alternative categories being found.
  • Example: filters=category:food-and-drink%7Ccategory:things-to-do

Categoriesback to top

The following categories are subject to change:

Local Goods Travel
automotive auto-and-home-improvement cruise-travel
beauty-and-spas baby-kids-and-toys flights-and-transportation
food-and-drink collectibles hotels-and-accommodations
health-and-fitness electronics tour-travel
home-improvement entertainment-and-media  
personal-services for-the-home  
retail groceries-household-and-pets  
things-to-do health-and-beauty  
  jewelry-and-watches  
  mens-clothing-shoes-and-accessories  
  sports-and-outdoors  
  womens-clothing-shoes-and-accessories  

Category Supportback to top

We are working to cover all countries.

Country ISO Code Supports Category Filtering
Argentina AR Yes
Australia AU No
Belgium BE Yes
Brazil BR Yes
France FR Yes
Germany DE Yes
Hong Kong HK No
Ireland IE Yes
Israel IL No
Italy IT Yes
Malaysia MY No
Netherlands NL Yes
New Zealand NZ No
Poland PL Yes
Singapore SG No
South Africa ZA Yes
Spain ES Yes
United Arab Emirates AE No
United Kingdom UK Yes

Location Sample Callsback to top

The following sample calls use tsToken=IE_AFF_0_200012_212556_0. Please supply your own Affiliate Id in the tsToken when making your own calls.

Get 20 deals for the nearest city (uses IP-based geolocation) in Ireland

Note that the Deal API will use your IP address and try to map it to division. If the Deal API is unable to locate a division it will return an error response.

https://partner-int-api.groupon.com/deals.json?country_code=IE&tsToken=IE_AFF_0_200012_212556_0&offset=0&limit=20

Category Sample Callsback to top

The following sample calls use tsToken=IE_AFF_0_200012_212556_0. Please supply your own Affiliate Id in the tsToken when making your own calls.

Optional tracking informationback to top

The following sample calls use tsToken=IE_AFF_0_200012_212556_0. Please supply your own Affiliate Id in the tsToken when making your own calls.

Groupon offers the ability for Affiliates to add parameters to API links to enable the Affiliate to track origination of calls to these links as 2 Affiliate specific parameters; SID and WID. These parameters are NOT required by Groupon, but may be useful to enable an Affiliate to identify specific websites or pages generating clicks and sales, or to pass unique member information in clicks and sales.

If these fields are provided to to the API as call parameters, they are added to the API generated links as-is.

Error Messageback to top

Response Elements

All error responses contain at least the top level error object with httpCode and message

  • httpCode
    HTTP status code
  • message
    Human readable message indicating why the API request failed

Sample Response