POST Refund

Catch can process one or more refund events associated with a particular Purchase.

Note that Catch enforces merchant_refund_id uniqueness. As a result:

If multiple requests contain identical values for both the merchant_refund_id and the refund_amount, Catch will treat requests after the first valid one as duplicates and not create new refund events.
Catch will reject requests that reuse a merchant_refund_id value with a refund_amount other than the value in the original, successful request. Catch treats these as invalid refund requests.

Path

POST https://<environment>.getcatch.com/v1/purchases/<purchase_id>/refunds

Variable name	Description	Possible values
`<environment>`	The Catch environment in which you’re making the request.	See Authentication.
`<purchase_id>`	The Catch-provided unique identifier for a given purchase.	See POST Purchase where the id (string) gets created.

Top Level Parameters

The POST Refund request includes four top-level parameters:

Parameter Name	Necessity	Format	Description
`refund_amount`	required	object	The total amount being refunded.
`merchant_refund_id`	required	string	The ID of this refund in the merchant's system which Catch will store for reporting purposes. Note: This value must be unique per refund request.
`items`	required	array	The item(s) involved in the refund.
`appeasement_details`	optional	object	If the refund includes an appeasement, provide details about the appeasement amount.

Refund Amount object

Parameter name	Necessity	Format	Description
`amount`	required	integer	Must be less than or equal to the original `total` specified on the checkout.
`currency`	required	string (ISO 4217)	The currency in which the amounts are represented.

Items array

Parameter name	Necessity	Format	Description
`name`	required	string	The name of the item.
`sku`	required	string	The SKU of the item.
`price`	required	object	The price of item.
`quantity`	required	integer	The quantity of the item.

Price object

Parameter name	Necessity	Format	Description
`amount`	required	integer	The unit price of the item.
`currency`	required	string (ISO 4217)	The currency that the price of the item is in.

Appeasement Details object

Parameter Name	Necessity	Format	Description
`total_amount`	optional	object	Within `appeasement_details`, Contains details on total appeasement amount and currency

Why does Catch ask for appeasement information?

Catch offers a configurable reward option that allows a merchant to set reward offers on specific SKUs. If this configurable reward option is in use, Catch reviews the SKUs returned to understand how to best handle the user's earned rewards. While a returned SKU may indicate the need to cancel a SKU-based reward, appeasements provided to the customer, such as a return of shipping costs, will not impact SKU-based rewards. For clarity of intent, we expect refunds to be itemized across the order's SKUs (via the Items array) and any appeasements (via the Appeasement Details object).

Total Amount object

Parameter Name	Necessity	Format	Description
`amount`	optional	integer	The sum of all appeasements, in cents.
`currency`	optional	string (ISO 4217)	The currency in which the amounts are represented.

Example request

{
    "refund_amount": {
      "amount":283,
      "currency":"USD"
    },
    "merchant_refund_id": "rKBzEQPLc8J-3375760",
    "items":    [ {
         "name":"wide_leg_jean",
         "sku":"VCqtCk-kQft70",
         "price":{
            "amount":283,
            "currency":"USD"
         },
         "quantity":1
      }],
    "appeasement_details": {
    			"total_amount": {
        			"amount": 0,
        			"currency": "USD"
    		}
		}
}

Example response

Name	Format	Description
id	string	Catch-provided unique identifier for a particular refund request.

201 Created
{
	"id":"rf-59870602-e913-4c49-8b56-994b16dcc88"
}