Welcome‎ > ‎

Version 2

Introduction

Welcome to the Group Commerce API.  Here you will find API documentation and snippets related to Version 2 of the Group Commerce API.  Version 2 is a significant upgrade from V1, and it's recommended that all API users upgrade to version 2 as soon as they can.  

The Group Commerce API is split into two parts: a Syndication API and a Publisher API.  The Syndication API is very simple and is designed primarily for aggregators (e.g. Yipit or The Deal Map), who can syndicate offers on their network.  The Publisher API is considerably more powerful, and can be used to perform complex tasks such as automating promotional emails, creating offer widgets, powering a mobile web application, or creating a fully-functional daily deal site that is hosted entirely within your own environment.  Hopefully you will find other uses for it that we haven't even thought of!  For questions, concerns, or feedback about the Group Commerce API please contact us at: apisupport@groupcommerce.com.

To try out some of the code snippets in this documentation you may need to use the following test keys:

ApiKey = "74901bb2-a09a-445f-8c50-ae7f4f12bf64"
SecretKey = "c3f9eef3-44e3-4039-8bc9-d9bf581e373b"

Syndication API

These methods are useful for aggregators and syndicators to display a subset of offer data.  Aggregators can get a list of Active Segments, Past Offers and Current Offers.  Past offers include limited querying and sorting abilities. Aggregators will need to acquire a Syndication API Key to include in the request.  The API Key is tied directly to an individual Group Commerce Publisher. Additionally, aggregators may be asked by publishers to include tracking parameters in all offer urls.

Sample Request:

To start exploring the api you would get a list of segments and then find current offers in a particular segment.
GET http://api.groupcommerce.com/api/v2/syndication/segments/?apiKey=74901bb2-a09a-445f-8c50-ae7f4f12bf64
GET http://api.groupcommerce.com/api/v2/syndication/offers/current/ny/?apiKey=74901bb2-a09a-445f-8c50-ae7f4f12bf64


Publisher API

The Publisher API provides functionality to communicate with the Group Commerce core platform. It allows application developers to create a similar purchase experience on a Group Commerce hosted site. Additionally this api can be used to develop facebook pages, mobile sites, integrate widgets into existing sites or develop line of business applications such as a content management tool for generating promotional emails.

There are two types of methods depending on the level of sensitivity for data: Read Access and Write Access. These are explained in more detail below.


Read Access

Read access methods are basic data retrieval methods: Past, Current, Future Offers, OfferById, Segment List. These methods provide more querying capabilities as well as all the datapoints of an object. Generally they are more detailed than the syndication methods. For example CurrentOffers in the publiusher api will contain customFields but the equivalent method on the syndication api will not. 

To access the Read Access methods, you will need to acquire a api key by sending a request to apisupport@groupcommerce.com.   The request follows the same pattern as syndication.

Sample Request:

GET http://api.groupcommerce.com/api/v2/publisher/offers/current/national?apiKey=74901bb2-a09a-445f-8c50-ae7f4f12bf64&format=xml



Write Access

The methods classified as Write Access allow a publisher to create a new application that has the same functionality as the Group Commerce hosted website.  Publishers are able to see offers, post customer service requests, invite and refer a friend, purchase and gift an offer, see past orders, and retrieve consumer voucher information.  Because of the sensitive nature of these methods, additional security is required. The Write Access methods are secured with oAuth authentication using a public and private key. You can acquire a api keys by sending a request to apisupport@groupcommerce.com

A great resource for understanding oAuth can be found here.  There are several oauth libraries that can be used to help when connecting to the Write Access methods.  Some of the ones we evaluated had their quirks.  The library with the fewest number of problems in our experience is oauth dot net.

Sample Request:
GET /api/v2/publisher/segments

Authorization: OAuth oauth_signature="Jyw2AiETFnWhTpa1SZfjIUTRdQQ%3d", oauth_nonce="1778781", oauth_timestamp="1303335405", oauth_consumer_key="43c5c674-620c-4f2b-bdcf-3082c99e8186", oauth_signature_method="HMAC-SHA1", oauth_version="1.0"
Host: apitest.groupcommerce.com


Group Commerce is in the process of releasing an SDK for both php and .net. This SDK will simplify access to the Publisher API by wrapping all urls and methods and providing strongly type return objects.

Response Formats

JSON and XML formats are supported by the API. JSON is the default format that unless the Request.ContentType is set to "application/xml" or format=xml querystring parameter is passed.

Dates & Times

Dates in the XML returned by the API use the ISO 8601 format.  Although the Date object has no support in json, there are some workarounds.  Group Commerce uses the format "\/Date(<ticks>)\/".  More information can be found here. Unless otherwise stated, all datetime values are  provided in UTC.

Currency

Money in the API is provided two decimal places. Pricing information includes a currency field using the ISO 4217 format. The decimal place is indicated by a period('.') regardless of currency or culture. 

Examples:
{Currency : "USD", Price: 5.00}