Skip to main content

Register a return

In Engage, a return is viewed as just another transaction, but with a different transactional status. There is no direct connection between a purchase and a return that comes after, it’s considered a new transaction and handled accordingly.

Some important points to remember:

  • The quantity field has to be negative, reflecting the number of returned items.

  • The line item type needs to have the value “RETURN”.

  • The grossPaidPrice on a return should be sent as a positive value of type "decimal".

  • The taxAmount should be sent as a positive value of type "decimal".

In the same way as for a purchase, the payload is sent to the following endpoint:

POST /api/v3/receipts

Example payload

This example transaction is a return for a customer with contact type “Member”. Note that quantity is negative, the price is positive and the line item type is “RETURN”.

{
  "contact": {
     "matchKey": "1c277c0a-ed93-4928-86cb-b0820090c111",
     "matchKeyType": "contactId"
  },
  "uniqueReceiptId": "20180909468464496",
  "receiptNumber": "468464496",
  "createdDate": "2018-09-09T12:05:23Z",
  "storeExternalId": "321",
  "currency": "NOK",
  "exchangeRateToGroupCurrency": 1.0,
  "totalGrossPrice": -400.00,
  "paymentMethods": [{
    "type": "card",
    "description": "Debit Card",
    "value": -400.00
  }],
  "items": [{
    "type": "RETURN",
    "quantity": -2,
    "grossPaidPrice": 400.00,
    "taxAmount": 80.00,
    "taxPercent": 25.00,
    "sku": "10015563434",
    "articleNumber": "2324234",
    "articleName": "Ipsum Wool Jacket",
    "articleGroup": "Jackets",
    "marginPercent": "25.00",
    "awardsBonus": false
  }]
}

Return matching logic

When a customer returns an item, Engage needs to match that returned item with the original purchase to display it in the GUI but also to ensure the correct adjustment of points. If the purchase awarded points, for example, the return should then remove them again.

The process of return matching involves retrieving potential matches and confirming them like this:

  1. Fetch all returned items for a specific import.

  2. Attempt to find purchase items that match the returned items by SKU. Or, if an SKU is not found, by ArticleNumber.

  3. If no matching purchase item can be found, exit the process here. If a matching purchase can be found then update the purchase item in the Engage database to indicate that it has been returned. 

    If there are multiple purchases that match the return, the return will be connected to the latest purchase made before the return date.

  4. If points are being used, the points total will have to be adjusted. If the price differs between the purchase and the return, the points deduction will be based on the points earned from the purchase, not those calculated from the return price.

    For example: A purchase with value 299 SEK awards 299 points. A return is made and the matching purchase is located. However the return value, for whatever reason, is 250 SEK. The points removed will be 299 since that's what was originally earned for that purchase.

In this section: