Store Connect Transactions

Transactions API for Store Connect

Note: Every call made to the Transaction API's must be made via the signed URL process. Any request without a valid signature will be rejected.

Begin Transaction

This method is to initiate a single transaction from the Point-of-Sale (POS) to Koupon Media. The information exchanged within this call identifies the originating POS so that the transaction can be tied to that specific store and that specific register. This method returns a transactionId which is used to keep track of this transaction. The storeId is attached as a query parameter and must be sent with the request.
POSThttp://storeconnect.kouponmedia.com/v1/transaction?storeId=storeId

POST Body Options

Parameter Required/Optional Description
posTransactionId required The universally unique Identifier assigned to the Transaction by the POS. This is an ID that is generated by the Point of Sale.
store required Contains identification information about the Store of the POS initiating the transaction.
store.name optional The human-readable name of the store.
store.address optional The street address where the Store is located.
store.city optional The city name where the Store is located.
store.state optional The state/province abbreviation where the Store is located.
store.zip optional The ZIP Code/Postal Code where the Store is located.
pos optional Contains information identifying the Point-of-Sale (POS) initiating the transaction.
pos.id optional An Identifier for the POS initiating the transaction.
pos.register optional An Identifier for the register of the POS initiating the transaction.
pos.cashier optional An Identifier for the cashier initiating the transaction.

Example POST Body

    
{
  "posTransactionId":  SimpleId,
  "store":  {
      "name":  String,
      "address":  String,
      "city":  String,
      "state":  Alpha,
      "zip":  Alphanumeric
  },
  "pos":  {
      "id":  String,
      "register":  String,
      "cashier":  String
  }
}
    

Example Response

    
{
  "version":  String,
  "transactionId":  UniqueId
}
    

Apply Offers To Transaction

Updates the currently active Transaction for the given Store Connect Transaction Id, which allows for Offer discounts to be applied (or removed). The POS would invoke this API on events that impact the application of discounts, including adding/removal of a Discount Asset (i.e. Offer barcode/PLU, Koupon Loyalty barcode, etc.), Sub-total, and Total before Tender. It is NOT RECOMMENDED that this API be invoked for each product scan, product quantity change, or product void, to avoid excess communication; rather, it is recommended the POS defer invoking it until a Sub-total or Total event, and trigger a final Total event on Tender to force a final discount assessment. This API will fail if the request fails to authenticate, if the Transaction is not recognized for the given POS Transaction Id, or if required content is missing or invalid.
PUThttp://storeconnect.kouponmedia.com/v1/transaction/transactionId

PUT Body Options

Parameter Required/Optional Description
posTransactionId required The universally unique Identifier assigned to the Transaction by the POS. This is an ID that is generated by the Point of Sale.
currency required The currency type indicated in the Transaction. Only "USD" supported currently. "USD" is assumed if absent.
products required An array of products that have been scanned by the POS ("basket"). May be empty.
products[x].index required The index of the product in the basket. Must be unique and incrementing. This index is used so that applied discounts can be placed as a line item in the receipt below the product being discounted.
products[x].description required The human-readable details of the product.
products[x].scanCode required The UPC/PLU of the product.
products[x].price required The selling price of the product.
products[x].quantity required The quantity of the products.
products[x].discounts required An array of discounts that have been applied to the product. Required; may be empty.
products[x].discounts[y].id required A unique identifier assigned to this discount by the Transaction Service.
products[x].discounts[y].amount required The total amount of the discount applied to this product.
products[x].discounts[y].discountAsset required The scanned barcode or UPC associated with this discount.
summary required Contains summary information about the Transaction
summary.subTotal required The gross subtotal of all the products scanned, before application of discounts.
summary.totalDiscounts optional The gross subtotal of all of the discounts applied.
summary.total optional The net total of the basket, with discounts applied and tax added.
discountAssets required An array of barcodes representing Offers or Loyalty Cards that were scanned to apply discounts for. May be empty.

Example PUT Body Request

    
{
  "posTransactionId":  SimpleId,
  "currency":  Enum,
  "products":  [
    {
      "index":  Digits,
      "description":  String,
      "scanCode":  String,
      "price":  Decimal,
      "quantity":  NonNegNumber,
      "discounts":  [
          {
              "id":  SimpleId,
              "amount":  Decimal,
              "discountAsset":  String
          }  ...
      ]
    }  ...
  ],
  "summary": {
     "subTotal":  Decimal,
     "totalDiscounts":  Decimal,
     "total":  Decimal
  },
  "discountAssets":  [  String,  ...  ]
}

Example Response

    
{
  "removeDiscounts":  [
    {
       "productIndex":  Digits,
       "discountId":  UniqueId,
       "discountName": String,
       "amount":  Decimal
    }  ...
  ],
  "addDiscounts":  [
    {
       "productIndex":  Digits,
       "discountId":  UniqueId,
       "discountName": String,
       "amount":  Decimal,
       "discountAsset":  String,
       "tags": String
    }  ...
  ],
  "exceptions":  [
    {
       "discountAsset":  String,
       "exceptionCode":  String,
       "exceptionHeader": String,
       "exceptionMessage": String
    }  ...
  ]
}
    

End Transaction

Ends the currently active Transaction for the given Store Connect Transaction Id. The POS would invoke this API with endType of "Tender" when a transaction is completed with a tender. The POS would invoke this API with endType of "Cancel" if the entire Transaction was cancelled without a tender. If endType is "Tender", any Offer discounts that had been applied are committed. If endType is "Cancel", any Offer discounts that had been applied are rolled back and the PUT body can contain a key of "reason" with a string containing why the transaction was cancelled. The PUT body options are the same as the API for Applying Offers to a Transaction (see above).
PUThttp://storeconnect.kouponmedia.com/v1/transaction/transactionId/endType

Example PUT Body Request

    
{
  "posTransactionId":  SimpleId,
  "currency":  Enum,
  "products":  [
    {
      "index":  Digits,
      "description":  String,
      "scanCode":  String,
      "price":  Decimal,
      "quantity":  NonNegNumber,
      "discounts":  [
          {
              "id":  SimpleId,
              "amount":  Decimal,
              "discountAsset":  String
          }  ...
      ]
    }  ...
  ],
  "summary": {
     "subTotal":  Decimal,
     "totalDiscounts":  Decimal,
     "total":  Decimal
  },
  "discountAssets":  [  String,  ...  ]
}

Example Response

    
{
  "version":  String,
  "errorCode":  String,
  "errorMessage":  String
}