Magento Integration

This Magento Integration leverages standard Magento endpoints and is separate of the Happy Returns Retailer API Spec. Some features that are supported by the Happy Return Retailer API Spec are not supported in this Magento Integration such as exchanges, store credit, and processing fees.

Happy returns supports the Magento 2 REST API endpoints for integration into the Happy Returns return flow. Below is a list of all Magento 2 endpoints that are utilized by the Happy Returns return flow in order to ensure a rich customer experience. There is a group of endpoints that are part of the Magento 2 API out of the box, and there is a group of custom endpoints if custom endpoints are deemed required by the retailer for their return flow (note that if a custom refund endpoint is needed, the custom preview endpoint must also be created). Please review the documentation below for what customizations can be included for certain endpoints.

If you have any question about the stock Magento 2 REST endpoints that is not covered here, please refer to the Magento 2 REST API documentation found here.

Out of the Box Endpoints

/index.php/rest/V1/integration/admin/token

Admin Token [POST]

The admin token endpoint is used for Happy Returns to log into the Magento Admin API to get purchases and submit returns. There is no need to modify this endpoint for integrating with Happy Returns.

/index.php/rest/V1/orders

Get Orders [GET]

The get orders endpoint is used for Happy Returns to get a list of orders for a customer. This information is used to show a list of purchases that may be returned through the Happy Returns return flow.

There is no need to modify this endpoint for integrating with Happy Returns, unless you wish to return custom data about the orders. Please check the list below for custom data fields already being parsed so that you can match the format. If you have custom data to return that is not listed below, please provide documentation about the custom fields you are returning about the orders so that it can be processed as expected.

Order Item Custom Fields
  • returnable (boolean) - Whether or not the purchase is returnable
  • returnable_reason (string) - The reason that the purchase is not returnable, if returnable is set to false. This should be a human-readable value that can be displayed to the customer.

/index.php/rest/V1/invoices

Get Invoices [GET]

The get invoices endpoint is used for Happy Returns to get a list of invoices for a customer’s order. This information is used when submitting a return for a customer’s order. There is no need to modify this endpoint for integrating with Happy Returns.

/index.php/rest/V1/products

Get Products [GET]

The get products endpoint is used for Happy Returns to get additional information about purchased products to be display in the return flow. There is no need to modify this endpoint for integrating with Happy Returns.

/index.php/rest/V1/products/attributes/{{attribute}/options

Get Product Attribute Options [GET]

The get product attribute options endpoint is used for Happy Returns to get a list product attributes, such as color and size, to be displayed in the return flow. There is no need to modify this endpoint for integrating with Happy Returns. However, prior to integration, please provide a list of attribute names that are used by your products (e.g. color, size, etc.) to the Happy Returns product manager that is handling onboarding your retailer.

/index.php/rest/V1/invoice/{{invoiceID}/refund

Refund Invoice [POST]

The refund invoice endpoint is used by Happy Returns to refund purchases from orders.

There is no need to modify this endpoint for integrating with Happy Returns. This endpoint will be used for refunding returns unless the custom endpoints are implemented in the section below.

Custom Endpoints

/index.php/rest/V1/happyreturns/creditmemo/preview

Preview Return (Custom) [POST]

The preview return endpoint is a custom endpoint that is implemented to generate a preview of the credit memo before it is actually submitted, whereas without the custom integation, all preview amounts will be displayed as ‘TBD’. This custom endpoint replaces the need for the refund invoice endpoint in the return flow. This endpoint request body and response body schemas follows the Magento 1 format for convenience when retailers upgrade from Magento 1 to Magento 2. This endpoint does intentionally differ from the stock Magento 2 creditmemo/refund endpoint’s request and response body schemas for convenience in porting custom code forward to the upgraded platform version.

  • Request (application/json)

    • Body

      {
    "orderIncrementId": "50001",
    "creditmemoData":
    {
        "invoice_id": "80001",
        "qtys":
        [
            {
                "order_item_id": 1020,
                "qty": 1
            }
        ]
    }
}

  • Response 200 (application/json)

    • Body

      {
  "subtotal": 89.00,
  "grand_total": 98.13,
  "shipping_amount": 0.00,
  "discount_amount": 0.00,
  "tax_amount": 9.13
}

/index.php/rest/V1/happyreturns/creditmemo/create

Submit Return (Custom) [POST]

The create credit memo endpoint is implemented to allow Happy Returns to process a return from the customer and is expected to trigger the refund to the customer when completed. This endpoint request body and response body schemas follows the Magento 1 format for convenience when retailers upgrade from Magento 1 to Magento 2. This endpoint does intentionally differ from the stock Magento 2 creditmemo/refund endpoint’s request and response body schemas for convenience in porting custom code forward to the upgraded platform version.

  • Request (application/json)

    • Body

      {
    "orderIncrementId": "50001",
    "creditmemoData":
    {
        "invoice_id": "80001",
        "qtys":
        [
            {
                "order_item_id": 1020,
                "qty": 1
            }
        ]
    }
}

  • Response 200 (application/json)

    • Body

      {
    "subtotal": 89.00,
    "grand_total": 98.13,
    "shipping_amount": 0.00,
    "discount_amount": 0.00,
    "tax_amount": 9.13
}