LateShipment.com API Documentation: Returns Experience Management

Welcome to the LateShipment.com API for our Returns Experience Management product. This API allows you to programmatically manage your returns, from initiation to resolution, and integrate return workflows directly into your existing systems.

The base URL for all API endpoints is: https://api.lateshipment.com

Authentication

Authentication is handled via request headers. You will need to include your Account Admin Email and an x-auth-key in every API request. You can find your x-auth-key in your LateShipment.com account under My Profile.

Required Headers:

Endpoints

1. Initiate a New Return Request (RMA)

This endpoint allows you to create a new return request.

• Method: POST

• Endpoint: /v1/returns

Example Request Payload:

{
  "order_number": "LS1001-US",
  "customer_email": "customer@example.com",
  "items": [
    {
      "sku": "SKU-TEE-BLK-M",
      "quantity": 1,
      "reason": "Incorrect size"
    }
  ],
  "return_method": "prepaid_label"
}

Success Response (201 Created):

{
  "status": "success",
  "message": "Return request created successfully.",
  "data": {
    "return_id": "RMA-2025-ABCD123",
    "status": "pending_approval",
    "order_number": "LS1001-US",
    "customer_email": "customer@example.com",
    "items": [
      {
        "item_id": "ITEM-XYZ789",
        "sku": "SKU-TEE-BLK-M",
        "quantity": 1,
        "status": "pending_approval"
      }
    ]
  }
}

Failure Response (400 Bad Request):

{
  "status": "error",
  "message": "Validation failed.",
  "errors": [
    "Order number is required.",
    "At least one item is required for a return."
  ]
}

2. Get Return/RMA Details

Retrieve the full details of a specific return request, including the shipping label if available.

• Method: GET

• Endpoint: /v1/returns/{return_id}

Example Call: GET https://api.lateshipment.com/v1/returns/RMA-2025-ABCD123

Success Response (200 OK):

{
  "status": "success",
  "data": {
    "return_id": "RMA-2025-ABCD123",
    "status": "approved",
    "order_number": "LS1001-US",
    "customer_email": "customer@example.com",
    "items": [
      {
        "item_id": "ITEM-XYZ789",
        "sku": "SKU-TEE-BLK-M",
        "quantity": 1,
        "status": "approved"
      }
    ],
    "shipping_label_url": "https://s3.lateshipment.com/label/..."
  }
}

Failure Response (404 Not Found):

{
  "status": "error",
  "message": "Return with ID 'RMA-2025-ABCD123' not found."
}

3. List/Search/Filter Returns

Fetch a list of all returns, with options to filter by status, date range, etc.

• Method: GET

• Endpoint: /v1/returns

Example Call (with query parameters): GET https://api.lateshipment.com/v1/returns?status=approved&date_from=2025-01-01

Success Response (200 OK):

{
  "status": "success",
  "data": [
    {
      "return_id": "RMA-2025-ABCD123",
      "status": "approved",
      "order_number": "LS1001-US",
      "created_at": "2025-07-18T10:00:00Z"
    },
    {
      "return_id": "RMA-2025-EFGH456",
      "status": "approved",
      "order_number": "LS1002-US",
      "created_at": "2025-07-17T15:30:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 50,
    "page": 1
  }
}

4. Approve a Return Request

Approve a pending return request.

• Method: POST

• Endpoint: /v1/returns/{return_id}/approve

Example Call: POST https://api.lateshipment.com/v1/returns/RMA-2025-ABCD123/approve

Success Response (200 OK):

{
  "status": "success",
  "message": "Return request has been approved.",
  "data": {
    "return_id": "RMA-2025-ABCD123",
    "status": "approved"
  }
}

Failure Response (422 Unprocessable Entity):

{
  "status": "error",
  "message": "Cannot approve a return that is not in 'pending_approval' status."
}

5. Cancel an Entire Return Request

Cancel a return request that has not yet been processed.

• Method: POST

• Endpoint: /v1/returns/{return_id}/cancel

Example Call: POST https://api.lateshipment.com/v1/returns/RMA-2025-ABCD123/cancel

Success Response (200 OK):

{
  "status": "success",
  "message": "Return request has been cancelled.",
  "data": {
    "return_id": "RMA-2025-ABCD123",
    "status": "cancelled"
  }
}

6. Trigger a Refund for a Return

Process a full refund for a received and verified return.

• Method: POST

• Endpoint: /v1/returns/{return_id}/refund

Example Request Payload:

{
  "refund_amount": 49.99,
  "notes": "Refund processed after item inspection."
}

Success Response (200 OK):

{
  "status": "success",
  "message": "Refund processed successfully.",
  "data": {
    "return_id": "RMA-2025-ABCD123",
    "status": "refunded",
    "refund_transaction_id": "txn_123456789"
  }
}

7. Bulk Actions

Perform actions like 'approve', 'cancel', or 'refund' on multiple returns at once.

• Method: POST

• Endpoints:

  • /v1/returns/bulk/approve

  • /v1/returns/bulk/cancel

  • /v1/returns/bulk/refund

Example Request Payload for Bulk Approve:

{
  "return_ids": [
    "RMA-2025-ABCD123",
    "RMA-2025-EFGH456",
    "RMA-2025-IJKL789"
  ]
}

Success Response (200 OK):

{
  "status": "success",
  "message": "Bulk action processed.",
  "results": {
    "successful": [
      "RMA-2025-ABCD123",
      "RMA-2025-EFGH456"
    ],
    "failed": [
      {
        "return_id": "RMA-2025-IJKL789",
        "reason": "Return is already in 'approved' state."
      }
    ]
  }
}

Webhooks

Stay updated on the status of your returns by configuring a webhook endpoint. We will send an HTTP POST request with a JSON payload to your specified URL whenever a critical event occurs.

To configure your webhook, please go to the My Profile > Webhooks section of your LateShipment.com account.

Webhook Events

We will push notifications for the following events:

• return.created

• return.approved

• return.rejected

• return.shipped

• return.delivered

• return.refunded

• return.cancelled

Example Webhook Payload

When a return is approved, we will send a POST request to your endpoint with the following payload:

{
  "event_id": "evt_abc123xyz",
  "event_type": "return.approved",
  "created_at": "2025-07-18T11:00:00Z",
  "data": {
    "return_id": "RMA-2025-ABCD123",
    "status": "approved",
    "order_number": "LS1001-US",
    "customer_email": "customer@example.com",
    "items": [
      {
        "item_id": "ITEM-XYZ789",
        "sku": "SKU-TEE-BLK-M",
        "quantity": 1,
        "status": "approved"
      }
    ],
    "shipping_label_url": "https://carrier.com/label/..."
  }
}

Your endpoint should respond with a 200 OK status to acknowledge receipt of the webhook. If we do not receive a 200 OK, we will retry sending the webhook several times with an exponential backoff.