Transaction API

Introduction back to top

Groupon partner network (GPN) APIs allows you to retrieve transactions based on your clientId. Transaction is an umbrella term for different types of records, including; sale, refund, bonus, bounty and few others. The Transactions API allows you to view a list of transactions for your clientId. "clientId" is "Reporting API key" which you can find in the Account Profile under "Business Details" section when you log into to your GPN account. Currently, the GPN API only supports JSON.

Authorization Steps back to top

The Transaction API uses Authorization tokens as well as client id to improve authentication. In the future the aggregated reporting APIs will be updated to require these tokens. Check Account Profile to get your authorization token. We support one active token per affiliate. This token is unique to you and this token will be valid until you regenerate another token from Account Profile. There are two options for authorization.

1. Non salted authorization token (less secure option):

This option consists of passing the authorization token as an HTTP header.

curl -X GET 'http://partner-api.groupon.com/v3/transactions?clientId=[affiliate_client_id]&startDate=2018-08-29T00:00:00&endDate=2018-08-29T23:59:59' -H 'x-auth-token:[your-authorization-token]' -H 'x-auth-version: SEC1'

2. Salted authorization token (Secure and Recommended):

This option guarantees that each request will have a unique authorization token by concatenating the current timestamp to your secret token and hashing it using SHA256.

curl -X GET 'http://partner-api.groupon.com/v3/transactions?clientId=[affiliate_client_id]&startDate=2018-08-29T00:00:00&endDate=2018-08-29T23:59:59' -H 'x-auth-version: SEC2' -H 'x-auth-token:{hashToken}' -H 'x-auth-timestamp: {timestampUTC}'

hashToken = sha256Hex{secretToken + timestampUTC}
secretToken = [your-authorization-token]
timestampUTC = current UTC timestamp in format YYYY-MM-DDTHH:mm:SS


Please do reach out to us if you're facing any issues integrating with the API.

Supports back to top

Format : JSON

Maximum Time Frame: 30 days

Sample Callback to top

Retrieve all transactions between 2018-01-01 and 2018-01-31

https://partner-int-api.groupon.com/v3/transactions?clientId=[affiliate_client_id]&startDate=2018-01-01T00:00:00&endDate=2018-01-31T00:00:00

Sample Response

URL Parametersback to top

Parameter Definition Required
clientId Specific Affiliate clientId. "clientId" is "Reporting API key" which you can find in the Account Profile under "Business Details" section when you log into to your GPN account. Yes
startDate Default - UTC date. All transactions created/modified after startDate.
Example: 2018-01-01T00:00:00
Yes
endDate Default - UTC date. All transactions created/modified after endDate.
Example: 2018-01-31T00:00:00
Yes
timeZone Default - UTC. Timezone according to the list provided.  TimeZone Support No
transactionType Default - ALL. Type of transaction (supported values should include SALE, REFUND, BONUS, BOUNTY, BOUNTY_REFUND, PAYMENT & CORRECTION
Explained Here
No
transactionStatus Default - NON-INVOICED (all status excluding INVOICED). Possible values - NON-INVOICED, PENDING, COMMISSIONABLE, NON-COMMISSIONABLE, INVOICED
Explained Here
No
invoiceId Valid invoice identifier. No
summary Default - False. Include summary of transactions No

Response Parametersback to top

Field Description
Transaction Unique transaction id
transactionDate Date of the order/user interaction. This never changes. Refunds will refer to the original order date, not the date of the refund. Empty for BONUS, PAYMENT
lastModifiedDate Last modification of the record
orderId Groupon's order id. Empty for BOUNTY, BONUS, PAYMENT
shortId Legacy order Id . Empty for BOUNTY, BONUS, PAYMENT
cartId Uuid of the cart. Empty for BONUS, PAYMENT
cartItemId Uuid of the cart item. Empty for BOUNTY, BOUNTY_REFUND, BONUS, PAYMENT
supportId Support Id. Empty for BONUS, PAYMENT
linkId Media id which is also called link. Empty for BONUS, PAYMENT
permalink User friendly readable deal identifier. Empty for BOUNTY, BOUNTY_REFUND, BONUS, PAYMENT. E.g. wise-owl-drinkery-cookhouse
grossAmount Gross value 12.99. Empty for BOUNTY, BOUNTY_REFUND, BONUS, PAYMENT.
payableAmount Commission minor units. (+)ve/(-)ve.
sid The SID or Sub-Affiliate ID or is an additional ID parameter that can be defined by a partner to facilitate additional tracking in their report. Empty for BONUS, PAYMENT.
wid The WID or Website ID is an additional ID parameter that can be defined by a partner to facilitate additional tracking in their reports. Empty for BONUS, PAYMENT.
transactionStatus Possible values - PENDING, COMMISSIONABLE, NON-COMMISSIONABLE, INVOICED.
Explained Here
invoidId Invoice ID. Empty for NON-INVOICED transactions.
transactionType Type of transaction. Possible values - SALE, REFUND, BONUS, BOUNTY, BOUNTY_REFUND PAYMENT, CORRECTION
Explained Here
transactionDetails Free text, e.g. Bonus explanation. Empty for SALE, REFUND, BOUNTY, BOUNTY_REFUND, PAYMENT
currency ISO 4217 three letter currency code
commissionCategory Category of the commission.Only for SALE transactionType. Will be blank for NON-COMMISSIONABLE orders.
commissionDetails Explanation of the commission. Empty for NON-COMMISSIONABLE orders.
country ISO Level 2 code
isNewUser Is new user or not. Will be blank for NON-COMMISSIONABLE orders.

Transaction Type and Statusback to top

Possible status for each transaction type are listed here -

Transaction type Transaction Status Description
SALE PENDING Real-time sale tracking is indicative only, and will be rectified up to 48h later. A transaction can move from pending to commissionable or non-commissionable for a variety of reasons.
COMMISSIONABLE Sale event rectified and due for commission payment. Only a refund of this sale can deduct the commission value.
NON-COMMISSIONABLE Incorrect sale event. A reason field will be provided with more details.
INVOICED Invoiced sale event.
REFUND Refunds will only be considered for already validated and commissionable orders. COMMISSIONABLE Refund detected for a commissionable sale that was not invoiced yet.
INVOICED Refund event that has been considered in an invoice.
BONUS INVOICED Invoiced bonus transaction.
BOUNTY PENDING Since a bounty is tied to a sale event, they are also indicative and subject to rectification. These can evolve the same way as sale events.
COMMISSIONABLE Validated bounty that will be considered for commission payment. As for sale events, only a refund and deduct this bounty.
NON-COMMISSIONABLE Invalid bounty that will not be considered for payment. Reason will be provided.
INVOICED Invoiced bounty.
BOUNTY_REFUND Bounty refunds will only be considered for already validated and commissionable orders. COMMISSIONABLE The bounty was tied to a refunded sale. In this case the bounty is also refunded. The pending state means it was not invoiced yet.
INVOICED nvoiced bounty refund.
PAYMENT INVOICED Payment event. Occurs once a month if threshold is reached.
CORRECTION COMMISSIONABLE Incorrect transaction that was rectified. Reason will be provided.
INVOICED Correction that was considered for invoice processing.

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

Authorisation Error

<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
        <title>Error 401 Unauthorized</title>
    </head>
    <body>
        <h2>HTTP ERROR 401</h2>
        <p>Problem accessing /v3/transactions. Reason
            <pre>Unauthorized</pre>
        </p>
    </body>
</html>

Timezone Support