Skip to main content

FedEx Returns RMA QR Code Integration

Updated

Overview

The FedEx Returns 2.0 RMA (Return Merchandise Authorization) QR Code Integration enables customers to generate QR codes for label-free returns through the EasyPost Forms API. 

Customers can present the QR code at a participating FedEx location to complete a return without printing a label.

This integration is currently available for supported FedEx shipments on accounts enabled for FedEx Returns 2.0.

How RMA QR Codes Work

  1. A shipment is purchased using a supported FedEx carrier account.
  2. A return is initiated through the platform.
  3. The EasyPost Forms API is called with type: “rma_qr_code” and order details.
  4. A QR code is generated and attached to the shipment.
  5. The QR code PNG is returned via a form_url.
  6. The customer presents the QR code at a FedEx location.

Prerequisites

The following requirements must be met before generating an RMA QR code:

  • Purchased shipment: The shipment must be purchased before requesting a form.
  • FedEx carrier account: The shipment must be purchased using a supported FedEx carrier account:
    • FedexAccount
    • FedexPlatformAccount
    • FedexSmartpostAccount
    • FedexDefaultAccountPlatformAccount
  • Fedex Fulfillment sidecar carrier account: The user must have a FedexFulfillmentAccount configured.
  • Account eligibility: The requesting user must be authorized (configured for onboarding).

Generating an RMA QR Code

Endpoint

POST /v2/shipments/{shipment_id}/forms

Authentication

Basic Auth using an EasyPost API key.

Headers

Authorization: Basic YOUR_API_KEY
Content-Type: application/json

Request Body

{
  "form": {
    "type": "rma_qr_code",
    "rma": {
      "order": { 
        "line_items": [
          {
            "description": "Blue T-Shirt"
          },
          {
            "description": "Red Hoodie"
          }
        ]
      }
    }
  }
}

Parameters

Top-Level Fields

form   object   required

Container for form parameters.

form.type   string   required

Must be ”rma_qr_code”.

form.rma   object   required

Container for RMA-specific parameters.

Order Fields

rma.order   object   required

Container for order information.

rma.include_packing_slip   boolean

Whether to include a packing slip with the return. Defaults to false. If true, at least one line item must include a valid SKU.

rma.pack_and_return   boolean

Enables FedEx's Pack & Return program. Defaults to false. Requires the account's pack-return and packaging accounts to be configured.

rma.label_image_data   string 

Base64-encoded label image (PDF) to embed in the return. If omitted, the shipment's existing postage label is used.

rma.order.order_number   string

The original order number/identifier from the merchant system. Defaults to shipment’s tracking code.

rma.order.order_date   string

Date of the original order in YYYY-MM-DD format. Defaults to today’s date.

rma.order.line_items   array 

Array of items being returned.

Line Item Fields

Each object in line_items must include:

description   string

Product description for display purposes.

sku   string 

SKU (Stock Keeping Unit) identifier. Only required if include_packing_slip is true.

return_reason  string

Reason for returning the item (e.g., “Wrong size”, “Defective item”, “Changed mind”). Defaults to “Customer return”.

quantity  integer

Quantity of the item being returned. Defaults to 1.

Response

On success, the API returns the updated Shipment object with the new form attached.

Success Response (201 Created)

{
  "id": "shp_abc123def456",
  "object": "Shipment",
  "mode": "production",
  "tracking_code": "794613053922",
  "status": "in_transit",
  "is_return": false,
  "to_address": {
    "id": "adr_xyz789",
    "name": "John Doe",
    "street1": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US",
    "email": "customer@example.com"
  },
  "from_address": {
    "id": "adr_abc456",
    "name": "Example Store",
    "street1": "456 Commerce Ave",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102",
    "country": "US"
  },
  "forms": [
    {
      "object": "Form",
      "id": "form_123abc",
      "form_type": "rma_qr_code",
      "form_url": "https://easypost-files.s3.amazonaws.com/files/form/...",
      "submitted_electronically": null
    }
  ]
}

The QR code is returned as a PNG image and can be displayed to the customer.

Form Object Fields

object  string  

Always ”Form”.

id  string  

Unique identifier for the form (e.g., ”form_123abc”).

form_type   string  

Type of form; will be ”rma_qr_code”.

form_url   string 

URL to download the QR code image (PNG format).

submitted_electronically  boolean/null 

Not applicable for QR codes.

Error Handling

400 Bad Request

Missing required fields:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "form.rma is required but missing"
  }
}

Other validation errors may include:

  • Missing retailer_account

422 Unprocessable Entity

Shipment not purchased:

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Shipment must be purchased before generating RMA form"
  }
}

User not eligible or unsupported carrier:

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "RMA QR codes can only be generated for FedEx, CanadaPost, and UPS shipments"
  }
}

FedEx Returns API failure:

{
  "error": {
    "code": "DOCUMENT.RMA_QR_CODE.FAILURE",
    "message": "Unable to create RMA QR Code.",
    "errors": ["ERR-RMA-0011: RMA number already in use"]
  }
}

404 Not Found

Invalid shipment ID:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource could not be found."
  }
}

Best Practices

  • Ensure the shipment is purchased before requesting a QR code.
  • Provide complete order and line item data for accurate return processing.
  • Include a valid customer email in either the shipment or request.
  • Store the returned form_url for display or retrieval.
  • Generate the QR code only after confirming return eligibility on the platform.
  • Ensure a FedEx Returns/Fulfillment account (FedexFulfillmentAccount) is configured before generating a QR code.

Additional Resources

EasyPost Forms API Documentation

EasyPost Form Guide

On this page

    Related to