Return API

Overview

Loyalty provides a purpose-built Program API endpoint to handle the return of items a member purchased previously. The endpoint is intended to be integrated with Point of Sale (POS), Ecommerce, Inventory Management and other systems that process purchases and the return of any purchased items.

The Return API provides several benefits for programs that process returned items:

  • Return Validation: Invalid returns are prevented. Returns are linked back to the original order, the system validates returned item SKUs, and quantities are aligned. Returns of items not in the original order, or quantities of items that exceed those in the original order, are prevented.

  • Return Period Enforcement: The system allows only returns that align with the configured return period.

  • Metric Calculation Accuracy: The system calculates the Metrics to deduct from the Member’s account as a result of a return; this calculation is more accurate than other techniques. By linking the return to the original order, the system considers the original Metrics awarded and the rules in the system at the time to determine Metric values to deduct based on the items returned.

  • Handles Partial or Complete Returns: Validation and Metric calculations are based on the items in the return, and both full and partial return scenarios are supported.

Note: For technical documentation, please see the Loyalty API developer portal. A username / password is required to access this API documentation. Please contact your Marigold team if you need assistance.

Prerequisites and Feature Setup

The Return API can be used without any extensive setup process. It requires some familiarity with Loyalty API integration, and a set of API keys scoped for the Program API.

An optional Program Setting called “Return API - Order Return Period” can be configured if the program prefers to limit the period the system accepts a return, but the API can be used if the setting is not configured. To avoid performance impacts related to retrieving very old orders, Marigold recommends choosing a reasonably short return period (e.g. 30-90 days for example).

Note that no Order Rule or Earn Rule changes are needed to allow Metrics from requests processed through the Return API to be deducted from Members’ accounts.

Use Cases

The Return API supports two primary use cases: a full return or a partial return.

Both types of returns require the request to include the original order integration_id (mapped as original_transaction_identifier in the request) to link the return to the original order, a return unique identifier (mapped as return_transaction_id), and the return date and time (mapped as returned_at) to specify when the return is processed.

Several additional optional parameters can be passed in the return to help characterize additional details of the return. These parameters include: the location the return occurred (mapped as place_integration_id), the terminal (terminal_id), the employee operator (mapped as operator_id), the return business date (mapped as return_business_date that is used to determine compliance with the return period), and the return type (mapped as return_type and supported by “full_return” and “partial_return”).

A full return means that all quantities of all items on the original order are returned. A full return can be accomplished in the API via two methods:

  • Submit a request with the return_type argument set to “full_return” with or without the items array included. In this case the system assumes ALL items in the original order are returned (it ignores the details of the items array submitted when it sees the return_type as “full_return”), and will process the request by deducting all Metrics associated with the original order. Using the return_type parameter is a shortcut for systems that know when a complete return has occurred and who prefer not to send the item details in the request.

  • Submit a request with all original items with at least the SKU and quantities reflecting the same values in the original order. Similar to the prior method, the system will validate that all quantities of all SKUs included in the original order are in the return, and will deduct all Metric values awarded to the original order to the return.

With both of the above methods, the system will treat the original order as fully returned, and subsequent return attempts against the original order will be rejected as invalid.

A partial return means that a subset of items or a subset of quantities of items on the original order are being returned. When submitting a request with a subset of items or item quantities, the system will reference the original order to assess the Metrics that were awarded. Based on the rules in the system at the time of the original order, and what the original order would have earned without the returned items, the system calculates the appropriate amount to deduct from the Member’s Metric balances. The system applies validation to returns, including multiple partial returns so that the quantity of items assigned to a specific SKU is not exceeded.

Caveats and Limitations

The accuracy of the Metric calculation in return processing depends on the rules implemented at the time of the original order not being changed or deleted. This situation can happen if a Base Order Rule or Bonus Order Rule is changed, or if one or more Earn Rules is changed, unpublished, or deleted. The best practice is to end-date Bonus Order Rules and Earn Rules, and introduce new rules with new conditions or calculations as needed with start dates reflecting the time the rule should take effect. Earn Rules should generally be end-dated instead of being unpublished or deleted to avoid differences in Metric calculations in the return versus the original order.

Additionally, when fixed amount Earn Rules are utilized, Metric deductions will not be applied unless / until a full return is processed. In this scenario, partial returns will deduct only the portion of the Metric amount awarded related to the returned items, and will exclude any fixed Metrics the Member earned. If all items and all quantities in the order are eventually returned, then the fixed amount portion of the Metric amount will also be deducted.

Consider the following example which illustrates this scenario:

  • Earn Rule 1: 1 point per dollar based on subtotal

  • Earn Rule 2: 100 points for any purchase this week

Original Order

  • line 1 - SKU 123, 1 qty @ $20.00 = $20

  • line 2 - SKU 456, 2 qty @ $5.00 = $10

Subtotal: $30

Points earned: 130 (30 points for Earn Rule 1, 100 points for Earn Rule 2)

Partial Return 1

  • line 1 - SKU 456, 1 qty@ $5.00 = $5.00

Subtotal: $5.00

Points deducted: 5 points (only the points related to Earn Rule 1)

Partial Return 2

  • line 1 - SKU 456, 1 qty@ $5.00 = $5.00

  • line 2 - SKU 123, 1 qty @$20 = $20

Subtotal: $25.00

Points deducted: 125 points (the remaining points related to Earn Rule 1, plus all points related to Earn Rule 2, because the order is now fully returned)

The return handling should calculate sl_value based on Order Rules when present, and sl_subtotal and sl_total when submitted in the return. The accuracy of these values will determine the accuracy of the return Metric calculation.