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
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
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.
Refund Assist is a fully automated process that runs continuously in the background:
- Automatic detection - Refund Assist monitors USPS labels that remain unscanned for 21 days from the print date
- Scheduled for refund - Eligible labels are marked with status
request_scheduled. You have 5 days to exclude any labels you don't want refunded - Automatic voiding and submission - After 5 days, Refund Assist automatically voids the label and submits the refund request to USPS. Status changes to
pending - Carrier processing - USPS reviews the request (typically 1-4 weeks)
- Refund applied - Once approved by USPS, 70% of the approved amount is credited to your ShipStation account balance with status
approved
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 |
- 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_detailsresponse for reasons
Refund Assist works automatically in the background, but you can monitor which labels are being processed through the API.
Retrieve a label to see if it's enrolled in Refund Assist:
GET /v2/labels/{label_id}
GET /v2/labels/se-421351 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__Response (label scheduled for Refund Assist)
{
"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)
{
"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
}
}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
Use the refund_status query parameter to filter labels by their refund status:
GET /v2/labels?refund_status=pending
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:
GET /v2/labels?refund_status=pending,approved HTTP/1.1The refund_status query parameter can be combined with other filters like created_at_start, carrier_id, and service_code to narrow your results.
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_scheduledstatus - You can only exclude labels with
refund_statusofrequest_scheduled - Once a refund is
pendingor 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
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_statuschanged to"excluded"- Label remains unvoided (since Refund Assist hadn't voided it yet)
{
"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
}
}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.
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 |
Request Scheduled:
{
"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:
{
"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:
{
"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:
{
"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
}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
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
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.
- Detection: Labels are detected as eligible after remaining unscanned for 21 days
- Scheduled period: You have 5 days to exclude labels from
request_scheduledstatus - 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
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
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.
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.
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
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.
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.
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.
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.
- Void Labels - Learn about manual voiding (note: manually voided labels are not eligible for Refund Assist)
- Create Labels - How to create USPS labels
- List Labels - Query and filter labels with various parameters