Welcome‎ > ‎Version 3‎ > ‎Publisher Api‎ > ‎Methods‎ > ‎1 - Offer Related‎ > ‎

Purchase


This method will purchase an offer.

Method: POST /api/v3/publisher/order

Authentication: oauth
 
This method requires three different data points:
BillingInfo - Information about the payment terms for the offer
ConsumerInfo - Information about the user purchasing the offer
OrderDetails - Which offer(s) are being purchased, quantities, etc...

Additional non-required data points:
AffiliateInfo - Information about affiliate tracking for purchases
PurchaseTrackingInfo - Information about third party purchase tracking for purchases (only available if publisher is set up to use a third party purchase tracking service)

Within the data points, the required fields change depending on the type of purchase.

Scenario 1: New Consumer / Full Credit Card Details

The ConsumerInfo object needs to be fully defined so a consumer user can be created in the system.  The BillingInfo object requires all of the consumer's credit card information.

Post
Required Form Name Data Type Explanation
NoAllowDuplicatePurchasebool
Determines whether a duplicate purchase is allowed.
YesBillingInfo.NameOnCardstring The name listed on the credit card.
YesBillingInfo.CardNumberstring The credit card number.
YesBillingInfo.CVVstring The 3 or 4 digit CVV listed on the back of the card.
NoBillingInfo.StoreCreditCard
bool Whether or not the credit card should be stored at the provider.  Default value is false.
YesBillingInfo.ExpirationMonthint16 The month the credit card expires.
YesBillingInfo.ExpirationYearint16 The year the credit card expires.
NoBillingInfo.BillingPhonestring The billing phone number on the credit card account.
YesBillingInfo.BillingAddressstring The billing address for the credit card.
NoBillingInfo.BillingAddress2string The optional second address line.
YesBillingInfo.BillingCitystring The city of the billing address
YesBillingInfo.BillingStatestring The state of the billing address
NoBillingInfo.BillingCountrystring The country of the billing address.  If available, it is recommended that you pass in this value.
YesBillingInfo.BillingZipstring The zip code of the billing address
NoBillingInfo.PaymentTypestring The payment type of the credit card.  Valid types: { Unknown, HouseAccount, MasterCard, Visa, Amex, Discover, DinersClub, JCB, enRoute }
NoBillingInfo.SpendCredits bool Whether or not to apply the consumer's credits (if available) on this purchase. Default is to apply the credits (true).
Yes
ConsumerInfo.UserKey
string The publisher assigned userKey.  Typically a Guid or one way hash of an email.  A user key uniquely identifies a consumer.
Yes
ConsumerInfo.Email
string The email address for the consumer.
Yes
ConsumerInfo.FirstName
string The first name of the consumer.
Yes
ConsumerInfo.LastName
string The last name of the consumer.
No ConsumerInfo.ReferredByUserKey
string The user key of the consumer who referred the current consumer to the website.  The referrer may get a reward for the purchase, depending on the publisher.
NoConsumerInfo.NoEmailbool Indicates if this consumer does not have a email address. By default, this value is false (which means this consumer has an email address).
No AffiliateInfo.AffiliateId int32 When recording affiliate tracking, the id of the affiliate.
No AffiliateInfo.AffiliateSource string When recording affiliate tracking, the source of the affiliate.
No* AffiliateInfo.CreateUnixTimestamp int64 When recording affiliate tracking, the Unix time or POSIX time the affiliate tracking started recording. 
* CreateUnixTimestamp is required if the AffiliateId is provided
No PurchaseTrackingInfo.
    AdditionalFields[0...n].Key
string The list of keys for the additional purchase tracking fields, useful for third party purchase tracking.
No PurchaseTrackingInfo.
    AdditionalFields[0...n].Value
string The list of values for the additional purchase tracking fields, useful for third party purchase tracking.
    
NoPromoCodeslistA list of promo codes (strings) to apply to the purchase.  The promo codes are applied in order, starting with the first promo code in the list.  If any of the codes are invalid, the purchase will not be completed and an error will be returned.
NoUsePromotionalPriceboolIf this offer has a promotional price, this field determines whether or not it will be used.  UsePromotionalPrice is not related to promo codes.
YesOrderDetailslistA list of order detail objects.  See the bottom of this page for the format of the OrderDetail model.
NoSendEmailbool Indicates whether or not emails should be sent in relation to this offer purchase. By default, SendEmail is true.
NoCustomTrackingInfostringAny custom tracking information that is associated with this purchase.

Scenario 2: Existing Consumer / Using Stored Credit Card

The Consumer - Credit Cards method will return a list of previously used credit cards if the consumer has requested that they be stored at the provider.  The StoredCreditCardId can be set to use an existing card.

Although the ConsumerInfo.{Email, FirstName, LastName} fields are not required, it is suggested to supply these to update any changes from the consumer.

Post
Required Form Name Data Type Explanation
Yes BillingInfo.StoredCreditCardId stringThe credit card id returned from the Consumer - Credit Cards method.
NoBillingInfo.SpendCredits bool Whether or not to apply the consumer's credits (if available) on this purchase. Default is to apply the credits (true).
Yes
ConsumerInfo.UserKey
string The publisher assigned userKey.  Typically a Guid or one way hash of the email address.  A user key uniquely identifies a consumer.
No
ConsumerInfo.Email
string The email address for the consumer.
No
ConsumerInfo.FirstName
string The first name of the consumer.
No
ConsumerInfo.LastName
string The last name of the consumer.
No ConsumerInfo.ReferredByUserKey
string The user key of the consumer who referred the current consumer to the website.  The referrer may get a reward for the purchase, depending on the publisher.
NoConsumerInfo.NoEmailbool Indicates if this consumer does not have a email address. By default, this value is false (which means this consumer has an email address).
No AffiliateInfo.AffiliateId int32 When recording affiliate tracking, the id of the affiliate.
No AffiliateInfo.AffiliateSource string When recording affiliate tracking, the source of the affiliate.
No* AffiliateInfo.CreateUnixTimestamp int64 When recording affiliate tracking, the Unix time or POSIX time the affiliate tracking started recording. 
* CreateUnixTimestamp is required if the AffiliateId is provided
No PurchaseTrackingInfo.
    AdditionalFields[0...n].Key
string The list of keys for the additional purchase tracking fields, useful for third party purchase tracking.
No PurchaseTrackingInfo.
    AdditionalFields[0...n].Value
string The list of values for the additional purchase tracking fields, useful for third party purchase tracking.
    
No PromoCodes listA list of promo codes (strings) to apply to the purchase.  The promo codes are applied in order, starting with the first promo code in the list.  If any of the codes are invalid, the purchase will not be completed and an error will be returned.
No UsePromotionalPrice bool If this offer has a promotional price, this field determines whether or not it will be used.  UsePromotionalPrice is not related to promo codes.
Yes OrderDetails list A list of order detail objects.
No SendEmail boolIndicates whether or not emails should be sent in relation to this offer purchase. By default, SendEmail is true.
No CustomTrackingInfostringAny custom tracking information that is associated with this purchase.

Scenario 3: Off-Platform Purchase

You also have the option to handle the payment processing on your end (off of the Group Commerce platform) and specify that the order has already been paid for using a flag on the purchase method.  In this case, it will be assumed that the customer has already been charged and no payment processing will occur.  All other order related events will still occur (validation, order creation, confirmation emails, etc...).

It is recommended to call the ValidateOrder method before executing an off-platform purchase to get important purchase related information and to make sure that the amounts you plan to charge the user agree with the amounts Group Commerce would have charged the user.

Note: Group Commerce platform consumer credits will not be applied for off-platform purchases.

Post
Required Form Name Data Type Explanation
YesBillingInfo.PaymentCapturedOffSiteboolThis value should be set to true to indicate an off-platform purchase.
No
BillingInfo.
ExternalTransactionInformation.
AmountCharged
decimal
The amount charged to the consumer making this purchase at an off-site payment processor (the Group Commerce platform will not do any payment processing for off-site purchases).
No
BillingInfo.
ExternalTransactionInformation.
CreditValueUsed
decimal
The value of the credits used from an off-site credits system to make this purchase (this value is unrelated to consumer credits in the Group Commerce platform)
No
BillingInfo.
ExternalTransactionInformation.
PaymentType
int
The payment type used by the consumer to make this purchase.  You will need to determine which integers map to which payment types on your end.
No
BillingInfo.
ExternalTransactionInformation.
TransactionId
string
It is recommended to set this field to a transaction id from the payment processor used for this purchase.
NoBillingInfo.SpendCredits bool Whether or not to apply the consumer's credits (if available) on this purchase. Default is to apply the credits (true). 
Yes
ConsumerInfo.UserKey
string The publisher assigned userKey.  Typically a Guid or one way hash of the email address.  A user key uniquely identifies a consumer.
Yes*
ConsumerInfo.Email
string The email address for the consumer.
* Not required for existing consumers.
* Not required if NoEmail is set to True.
Yes*
ConsumerInfo.FirstName
string The first name of the consumer.
* Not required for existing consumers.
Yes*
ConsumerInfo.LastName
string The last name of the consumer.
* Not required for existing consumers.
No
ConsumerInfo.ReferredByUserKey
string The user key of the consumer who referred the current consumer to the website.  The referrer may get a reward for the purchase, depending on the publisher.
NoConsumerInfo.NoEmailbool Indicates if this consumer does not have a email address. By default, this value is false (which means this consumer has an email address).
No AffiliateInfo.AffiliateId int32 When recording affiliate tracking, the id of the affiliate.
No AffiliateInfo.AffiliateSource string When recording affiliate tracking, the source of the affiliate.
No* AffiliateInfo.CreateUnixTimestamp int64 When recording affiliate tracking, the Unix time or POSIX time the affiliate tracking started recording. 
* CreateUnixTimestamp is required if the AffiliateId is provided
No PurchaseTrackingInfo.
    AdditionalFields[0...n].Key
string The list of keys for the additional purchase tracking fields, useful for third party purchase tracking.
No PurchaseTrackingInfo.
    AdditionalFields[0...n].Value
string The list of values for the additional purchase tracking fields, useful for third party purchase tracking.
    
No PromoCodes stringA list of promo codes (strings) to apply to the purchase.  The promo codes are applied in order, starting with the first promo code in the list.  If any of the codes are invalid, the purchase will not be completed and an error will be returned.
No UsePromotionalPrice bool If this offer has a promotional price, this field determines whether or not it will be used.  UsePromotionalPrice is not related to promo codes.
Yes OrderDetails list A list of order detail objects.
No SendEmail boolIndicates whether or not emails should be sent in relation to this offer purchase. By default, SendEmail is true.
NoCustomTrackingInfostringAny custom tracking information that is associated with this purchase.

OrderDetail Model

An OrderDetail contains information about the specifics of a purchase.  It contains the shipping address (if applicable), gifting information (if applicable), offer information, and quantity information.

These are the fields for an OrderDetail model. The required fields change depending on whether or not the OrderDetail is a gift, and depending on whether or not the offer being purchased requires shipping information.  The form post follows this format:

OrderDetails[0].IsGift=false
OrderDetails[0].OfferId=123
OrderDetails[0].OfferOptionId=456
OrderDetails[0].Quantity=7
OrderDetails[0].SegmentKey=new-york

Scenario 1: OrderDetail is not a gift (a standard purchase), offer does not require shipping info

Post
Required Form Name Data Type Explanation
 No IsGift boolWhether or not the order detail is a gift (defaults to false).  If you supply IsGift, set it to false in this scenario.
Yes
OfferId
int32
The id of the offer being purchased.
Yes
OfferOptionId
int32
The id of the offer option being purchased.
Yes
Quantity
int16
The quantity being purchased.
Yes
SegmentKey
string The segment the offer is being purchased from.

Scenario 2: OrderDetail is not a gift (a standard purchase), offer requires shipping info

Post
Required Form Name Data Type Explanation
 No IsGift boolWhether or not the order detail is a gift (defaults to false).  If you supply IsGift, set it to false in this scenario.
Yes
OfferId
int32
The id of the offer being purchased.
Yes
OfferOptionId
int32
The id of the offer option being purchased.
Yes
Quantity
int16
The quantity being purchased.
Yes
SegmentKey
string The segment the offer is being purchased from.
Yes AddressstringThe shipping address
NoAddress2stringThe optional second shipping address line
YesCitystring The shipping city
YesCountrystringThe shipping country (two letter abbreviation)
YesPostalCodestringThe shipping postal code
YesShippingName
string
The shipping name
NoShippingPhonestring             The phone number that will be passed to the shipping provider.
YesStatestringThe shipping state (two letter abbreviation)

Scenario 3: OrderDetail is a gift, offer does not require shipping info

Post
Required Form Name Data Type Explanation
 Yes IsGift boolWhether or not the order detail is a gift.  Should be set to true in this scenario.
Yes
OfferId
int32
The id of the offer being purchased.
Yes
OfferOptionId
int32
The id of the offer option being purchased.
Yes
Quantity
int16
The quantity being purchased.
Yes
SegmentKey
string The segment the offer is being purchased from.
YesEmailAddress
stringThe email address of the gift recipient
NoFromNamestringObsolete - no longer used.  The order's consumer's name is used as the name of the gifter.
YesFirstNamestringThe first name of the gift recipient
NoLastNamestringThe last name of the gift recipient
NoMessagestringA message from the gift sender to the gift recipient to include with the gift

Scenario 4: OrderDetail is a gift, offer requires shipping info

Post
Required Form Name Data Type Explanation
 Yes IsGift boolWhether or not the order detail is a gift.  Should be set to true in this scenario.
Yes
OfferId
int32
The id of the offer being purchased.
Yes
OfferOptionId
int32
The id of the offer option being purchased.
Yes
Quantity
int16
The quantity being purchased.
Yes
SegmentKey
string The segment the offer is being purchased from.
YesEmailAddress
stringThe email address of the gift recipient
NoFromNamestringObsolete - no longer used.  The order's consumer's name is used as the name of the gifter.
YesFirstNamestringThe first name of the gift recipient
NoLastNamestringThe last name of the gift recipient
NoMessagestringA message from the gift sender to the gift recipient to include with the gift
YesAddressstringThe shipping address
NoAddress2stringThe optional second shipping address line
YesCitystringThe shipping city
YesCountrystringThe shipping country (two letter abbreviation)
YesPostalCodestringThe shipping postal code
Yes
ShippingName
string
The shipping name
NoShippingPhone string The phone number that will be passed to the shipping provider.
YesStatestringThe shipping state (two letter abbreviation)

Returns
base response fields
chargeAmount - the amount that will be charged to the consumer's credit card
creditValueUsed - the value of the consumer's credits that were used to pay for some or all of the order
currencySymbol - the symbol for the currency of the order (e.g. $)
duplicateOrderId - If the AllowDuplicateOrder flag is false and the order appears to be a duplicate, this will contain the previous order id.
isoCurrencyCode - the three character ISO currency code for the order (e.g. USD)
orderId - The orderId for a successful order.
pendingCreditValueAwarded - The value of the credit(s) (pending credit trigger types ForNextPurchase + AfterNextPurchase) that will be awarded to the consumer of the order when the purchase is made.

Sample Request:

POST http://api.groupcommerce.com/api/v3/publisher/order

Form: ConsumerInfo.Email=consumertest%40groupcommerce.com&ConsumerInfo.UserKey=consumertest%40groupcommerce.com&ConsumerInfo.FirstName=consumer&ConsumerInfo.LastName=test&ConsumerInfo.ReferredByUserKey=rbuk%40groupcommerce.com&BillingInfo.NameOnCard=cardname&BillingInfo.CardNumber=4111111111111111&BillingInfo.PaymentType=Unknown&BillingInfo.CVV=111&BillingInfo.ExpirationMonth=7&BillingInfo.ExpirationYear=2020&BillingInfo.BillingPhone=2165615908&BillingInfo.BillingAddress=628+Broadway&BillingInfo.BillingCity=New+York&BillingInfo.BillingState=NY&BillingInfo.BillingZip=10010&BillingInfo.BillingCountry=US&BillingInfo.StoreCreditCard=False&OrderDetails%5b0%5d.FirstName=Jon&OrderDetails%5b0%5d.LastName=Lastn&OrderDetails%5b0%5d.EmailAddress=giftrecipient%40groupcommerce.com&OrderDetails%5b0%5d.FromName=Someone&OrderDetails%5b0%5d.Quantity=2&OrderDetails%5b0%5d.Message=Message+content&OrderDetails%5b0%5d.OfferId=9033&OrderDetails%5b0%5d.OfferOptionId=9173&OrderDetails%5b0%5d.SegmentKey=new-york&OrderDetails%5b0%5d.IsGift=True&OrderDetails%5b0%5d.Address=123+Road&OrderDetails%5b0%5d.Address2=Apt.+6K&OrderDetails%5b0%5d.City=Cleveland&OrderDetails%5b0%5d.Country=US&OrderDetails%5b0%5d.PostalCode=44122&
OrderDetails%5b0%5d.ShippingName=ShipToMe&OrderDetails%5b0%5d.State=OH&OrderDetails%5b1%5d.EmailAddress=apisupport%40groupcommerce.com&OrderDetails%5b1%5d.Quantity=1&OrderDetails%5b1%5d.OfferId=9035&OrderDetails%5b1%5d.OfferOptionId=9123&OrderDetails%5b1%5d.SegmentKey=new-york&OrderDetails%5b1%5d.IsGift=False&UsePromotionalPrice=False

Authorization: OAuth oauth_signature="IzOMx8CARFdiW5jkL01awFDGWRk%3d", oauth_nonce="1531951", oauth_timestamp="1322675790", oauth_consumer_key="eeb6b959-b854-4ad1-b563-e801c83cf81d", oauth_signature_method="HMAC-SHA1", oauth_version="1.0"


Sample JSON Response:

{
    "errors": [],
    "lastPublished": "/Date(1347991686361)/",
    "success": true,
    "version": "3",
    "chargeAmount": 133.92,
    "creditValueUsed": 12.13,
    "currencySymbol": "$",
    "duplicateOrderId": null,
    "isoCurrencyCode": "USD",
    "orderId": 117342
    "pendingCreditValueAwarded": 0 
}


Sample XML Response:

<purchaseResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <errors />
  <lastPublished>2012-09-18T18:08:43.801025Z</lastPublished>
  <success>true</success>
  <version>3</version>
  <chargeAmount>133.92</chargeAmount>
  <creditValueUsed>12.13</creditValueUsed>
  <currencySymbol>$</currencySymbol>
  <duplicateOrderId i:nil="true" />
  <isoCurrencyCode>USD</isoCurrencyCode>
  <orderId>117343</orderId>
  <pendingCreditValueAwarded>0</pendingCreditValueAwarded> 
</purchaseResponse>
Comments