# Refund Assist Refund Assist takes the hassle out of getting refunds for unused USPS labels. Instead of manually tracking down and submitting refund requests, Refund Assist automatically identifies eligible labels, voids them, and submits refund requests to USPS on your behalf. You'll receive effortless refunds of up to 70% of the USPS-approved amount as credits to your ShipStation account balance. **Key Benefits:** - Automatic detection and voiding of unused USPS labels - Automatic refund request submission to USPS - Receive 70% of the USPS-approved refund amount as account credit - Real-time tracking of refund status through the API - Eliminates manual refund request workflows ## Requirements For labels to be eligible for Refund Assist, they must meet the following criteria: - **US home-based ShipStation account** - Currently available only for US-based accounts - **Stamps.com wallet carrier** - The label must be purchased through a connected Stamps.com wallet carrier - **USPS labels with tracking numbers** - Labels must have valid tracking numbers - **Unused for 21 days** - Labels must remain unscanned by USPS for 21 days from the print date - **Not manually voided** - Labels that were manually voided by users are not eligible for Refund Assist Check Your Eligibility Not all ShipStation accounts or carriers support Refund Assist. If your labels show `refund_details` as null, your account or carrier may not be eligible for automatic refunds. ## How Refund Assist Works Refund Assist is a fully automated process that runs continuously in the background: 1. **Automatic detection** - Refund Assist monitors USPS labels that remain unscanned for 21 days from the print date 2. **Scheduled for refund** - Eligible labels are marked with status `request_scheduled`. You have 5 days to exclude any labels you don't want refunded 3. **Automatic voiding and submission** - After 5 days, Refund Assist automatically voids the label and submits the refund request to USPS. Status changes to `pending` 4. **Carrier processing** - USPS reviews the request (typically 1-4 weeks) 5. **Refund applied** - Once approved by USPS, 70% of the approved amount is credited to your ShipStation account balance with status `approved` ### Refund Status Lifecycle The `refund_status` field tracks where your refund request is in the process: | Status | Description | Final Status | | --- | --- | --- | | `request_scheduled` | Label is scheduled for automatic voiding and refund. You have 5 days to exclude this label if you don't want it refunded | No | | `pending` | Refund request has been submitted to USPS and is awaiting approval (typically 1-4 weeks) | No | | `approved` | Refund request has been approved by the carrier and the amount has been credited to your account balance | Yes | | `rejected` | Refund request was denied by the carrier (see rejection reason in response) | Yes | | `excluded` | Refund request has been excluded by the user or system. Labels in this status were not sent to the carrier for a refund request | Yes | Important Notes - Labels manually voided by users (via PUT /v2/labels/{label_id}/void) are **not eligible** for Refund Assist - You receive 70% of the USPS-approved refund amount; ShipStation retains 30% as a service fee - If a refund is rejected, check the `refund_details` response for reasons ## Monitoring Labels in Refund Assist Refund Assist works automatically in the background, but you can monitor which labels are being processed through the API. ### Check a Specific Label Retrieve a label to see if it's enrolled in Refund Assist: **GET /v2/labels/{label_id}** ```http GET /v2/labels/se-421351 HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ ``` **Response (label scheduled for Refund Assist)** ```json { "label_id": "se-421351", "voided": false, "voided_at": null, "void_type": null, "refund_details": { "refund_status": "request_scheduled", "request_date": null, "amount_paid": { "currency": "usd", "amount": 7.5 }, "amount_requested": { "currency": "usd", "amount": 7.5 }, "amount_approved": null, "amount_credited": null } } ``` **Response (after Refund Assist voids and submits)** ```json { "label_id": "se-421351", "voided": true, "voided_at": "2026-03-23T10:30:00Z", "void_type": "refund_assist", "refund_details": { "refund_status": "pending", "request_date": "2026-03-23T10:30:00Z", "amount_paid": { "currency": "usd", "amount": 7.5 }, "amount_requested": { "currency": "usd", "amount": 7.5 }, "amount_approved": null, "amount_credited": null } } ``` Understanding void_type The `void_type` field indicates how a label was voided: - `"refund_assist"` - Label was automatically voided by Refund Assist - `"manual"` - Label was manually voided by the user (not eligible for Refund Assist) - `null` - Label has not been voided ## Filtering Labels by Refund Status Use the `refund_status` query parameter to filter labels by their refund status: **GET /v2/labels?refund_status=pending** ```http GET /v2/labels?refund_status=pending&page_size=50 HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ ``` **Available Filter Values:** | Filter Value | Description | | --- | --- | | `request_scheduled` | Labels with scheduled refund requests not yet submitted | | `pending` | Labels with refund requests submitted and awaiting carrier approval | | `approved` | Labels with approved refunds | | `rejected` | Labels with rejected refund requests | | `excluded` | Labels that have been excluded from Refund Assist process by the user. | You can filter by multiple statuses using a comma-separated list: ```http GET /v2/labels?refund_status=pending,approved HTTP/1.1 ``` The `refund_status` query parameter can be combined with other filters like `created_at_start`, `carrier_id`, and `service_code` to narrow your results. ## Excluding Labels from Refund Assist When labels are detected as eligible for Refund Assist, they enter the `request_scheduled` status. You have **5 days** to exclude any labels you don't want Refund Assist to process before they're automatically voided and submitted to USPS. **When to Exclude:** - You only have 5 days from when the label enters `request_scheduled` status - You can only exclude labels with `refund_status` of `request_scheduled` - Once a refund is `pending` or in any other status, it cannot be excluded through the API - After 5 days, the label is automatically voided and the refund request is submitted **POST /v2/labels/{label_id}/cancel_refund** ```http POST /v2/labels/se-421351/cancel_refund HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ ``` **Response** The response returns the updated label object with: - `refund_details.refund_status` changed to `"excluded"` - Label remains unvoided (since Refund Assist hadn't voided it yet) ```json { "label_id": "se-421351", "voided": false, "voided_at": null, "void_type": null, "refund_details": { "refund_status": "excluded", "request_date": null, "amount_paid": { "currency": "usd", "amount": 7.5 }, "amount_requested": { "currency": "usd", "amount": 7.5 }, "amount_approved": null, "amount_credited": null } } ``` 5-Day Window You can only exclude labels within 5 days of them entering `request_scheduled` status. After that, Refund Assist automatically voids the label and submits the refund request to USPS. If you attempt to exclude a label with a different status, you'll receive a 400 error response. ## Understanding Refund Details The `refund_details` object provides comprehensive information about the refund request lifecycle and monetary amounts: | Field | Type | Description | | --- | --- | --- | | `refund_status` | string | Current status of the refund request: `request_scheduled`, `pending`, `approved`, `rejected`, or `excluded` | | `request_date` | string (ISO 8601) | Date and time when the refund request was submitted to the carrier. `null` if not yet submitted | | `amount_paid` | monetary_value | Original amount paid for the label | | `amount_requested` | monetary_value | Amount requested to be refunded (typically same as amount_paid) | | `amount_approved` | monetary_value | Amount the carrier approved for refund. May differ from amount_requested due to carrier fees or adjustments. `null` until approved | | `amount_credited` | monetary_value | Actual amount credited back to your account balance. `null` until credit is applied | ### Sample refund_details for Each Status **Request Scheduled:** ```json { "refund_status": "request_scheduled", "request_date": null, "amount_paid": { "currency": "usd", "amount": 7.5 }, "amount_requested": { "currency": "usd", "amount": 7.5 }, "amount_approved": null, "amount_credited": null } ``` **Pending:** ```json { "refund_status": "pending", "request_date": "2026-03-23T12:00:00Z", "amount_paid": { "currency": "usd", "amount": 7.5 }, "amount_requested": { "currency": "usd", "amount": 7.5 }, "amount_approved": null, "amount_credited": null } ``` **Approved:** ```json { "refund_status": "approved", "request_date": "2026-03-23T12:00:00Z", "amount_paid": { "currency": "usd", "amount": 7.5 }, "amount_requested": { "currency": "usd", "amount": 7.5 }, "amount_approved": { "currency": "usd", "amount": 7.0 }, "amount_credited": { "currency": "usd", "amount": 4.9 } } ``` Note: `amount_credited` is 70% of `amount_approved` (7.00 × 0.70 = 4.90) **Rejected:** ```json { "refund_status": "rejected", "request_date": "2026-03-23T12:00:00Z", "amount_paid": { "currency": "usd", "amount": 7.5 }, "amount_requested": { "currency": "usd", "amount": 7.5 }, "amount_approved": null, "amount_credited": null } ``` ## Eligibility and Exclusions ### Labels Eligible for Refund Assist To be eligible for automatic refunds through Refund Assist, a label must: - Be a USPS label with a tracking number - Be purchased through a Stamps.com wallet carrier - Be on a US home-based ShipStation account - Remain unscanned by USPS for 21 days from the print date - Not be manually voided by a user ### Labels not eligible for Refund Assist The following labels will show `refund_status` of `excluded` or `refund_details` of `null`: - **Manually voided labels** - Labels voided through PUT /v2/labels/{label_id}/void are not eligible - **Labels without tracking numbers** - Refund tracking requires a valid tracking number - **Non-Stamps.com carriers** - Only Stamps.com wallet carriers support Refund Assist - **International labels** - Currently limited to domestic US shipments - **Scanned labels** - Labels that were picked up or scanned by USPS before the 21-day window - **Labels excluded by user** - Labels you explicitly excluded using the cancel_refund endpoint - **Test labels** - Test mode labels are not eligible for refunds - **Post-billed carriers** - Post-billed accounts don't charge for unused labels Manual Voiding vs Refund Assist **When to manually void:** If you need to void a label immediately (within 21 days), use PUT /v2/labels/{label_id}/void. However, manually voided labels are not eligible for Refund Assist, and you'll need to request refunds through the carrier's standard process. **Let Refund Assist handle it:** For unused labels, wait for Refund Assist to automatically detect and process them after 21 days to receive the 70% credit. ## Refund Timeline & Amounts ### Timeline Expectations - **Detection:** Labels are detected as eligible after remaining unscanned for 21 days - **Scheduled period:** You have 5 days to exclude labels from `request_scheduled` status - **Automatic submission:** After 5 days, label is automatically voided and submitted to USPS - **USPS processing:** Typically 1-4 weeks for USPS to approve or reject - **Credit to account:** Usually immediate once approved by USPS ### Amount Considerations **Service Fee:** You receive **70% of the USPS-approved refund amount** as credit to your ShipStation account balance. ShipStation retains 30% as a service fee. The USPS-approved amount may differ from the original label cost due to: - **USPS adjustments** - USPS may adjust the refund amount based on their refund policy - **Carrier fees** - USPS may retain processing fees - **Partial approvals** - In some cases, USPS approves partial refunds Monitor Your Balance Check your ShipStation account balance regularly to see when refunds are credited. The `amount_credited` field shows the exact amount (70% of USPS-approved refund) added back to your balance. Email Notifications ShipStation sends email notifications when your first refund request is scheduled. Each week that a refund request is sent, you'll receive an email with updates on all Refund Assist activity. If there are no refunds scheduled, submitted, or processed during a given week, no update email will be sent. ## Troubleshooting ### Label Not Showing in Refund Assist **Issue:** My label is unused but doesn't have `refund_details`. **Solution:** Check that: - The label has been unscanned for at least 21 days from print date - It's a USPS label purchased through a Stamps.com wallet carrier - It wasn't manually voided (manually voided labels are not eligible) - Your account has Refund Assist enabled ### Refund Status Stuck on Pending **Issue:** Refund status hasn't changed from `pending` for several weeks. **Solution:** This is normal. USPS processing typically takes 1-4 weeks. If it's been more than 4 weeks, contact ShipStation support. ### Refund Was Rejected **Issue:** The refund status changed to `rejected`. **Solution:** Check the refund details for reasons. Common causes include: - Label was scanned by USPS before the 21-day window elapsed - Label had issues or irregularities discovered by USPS - USPS refund policy restrictions Contact ShipStation support for assistance with rejected refunds. ### Label Shows Excluded Status **Issue:** The label shows `refund_status` of `excluded`. **Solution:** This happens when: - You manually excluded the label using POST /cancel_refund Labels excluded from Refund Assist won't receive automatic refunds. ### Refund Amount is 70% of Label Cost **Issue:** The `amount_credited` is only 70% of `amount_paid`. **Solution:** This is expected behavior. Refund Assist credits **70% of the USPS-approved refund amount** to your ShipStation account balance. ShipStation retains 30% as a service fee for managing the automatic refund process. ## Related Resources - [Void Labels](/void-labels) - Learn about manual voiding (note: manually voided labels are not eligible for Refund Assist) - [Create Labels](/create-labels) - How to create USPS labels - [List Labels](/list-labels) - Query and filter labels with various parameters