The Returns resource allows a user to retrieve a list of returned shipments processed at a BoxC facility. Users may verify, reship, or discard their returns. Discarding a return is irreversible.

Verify

Users have the option to verify a return before reshipping it. The facility operator will take additional pictures of the contents inside the return and add messages if necessary. To verify a return the user should PUT a status of "Verify". This will change the status of the return to "Verifying" which cannot be reversed. Only returns in the "Processed" state can be verified.

Actions

GET /returns Retrieves a paginated list of returns
GET /returns/{id} Retrieves a return
POST /returns/{id}/messages Adds a message to a return
PUT /returns/{id} Updates a return
DELETE /returns/{id} Discards a return

Properties

created

{"created": "2016-09-02 12:00:15"}

Datetime - The UTC date and time the return was processed at a facility. Set by the system.
id

{"id": 13489}

Integer - The unique ID for this return. Set by the system.
images

{
    "images": [
        "https:\/\/api.boxc.com\/i\/32e186166912f18072645e793933904a115f23ce3d33108853640d1d3f94c6b6.jpg",
        "https:\/\/api.boxc.com\/i\/032b960ff67c0fe830e78cb60a2a1b09df18c216a15cacddfbcbfaed33da473e.jpg"
    ]
}

Array - A list of images taken for this return. Set by the system. Only present when retrieving a single return. Images are removed when the return is discarded.
message

{
    "message": {
        "author": "user",
        "body": "Please handle with care",
        "created": "2016-09-03 08:43:56",
        "id": 40119
    }
}

Object - This property is used for creating a new message. A message can be a question or comment about a return left by the user or facility operator.

author: The creator of the message. Can be either "user" or "operator". Set by the system.
body: The content body of the message. Max length: 200.
created: The UTC date and time the message was created. Set by the system.
id: The unique ID for this message. Set by the system.
messages

{
    "messages": [
        {
            "author": "user",
            "body": "Please handle with care",
            "created": "2016-09-03 08:43:56",
            "id": 40119
        }
    ]
}

Array - A list of message objects left by the user or operater for this return. Messages are sorted by created in descending order. If searching, the number of messages will be returned instead. See message for details about each property.
process_fee

{"process_fee": 1.00}

Decimal - The fee in USD for processing this return. Set by the system.
reshipment_id

{"reshipment_id": 102910}

Integer - The unique ID for this return's reshipment if available. Set by the system. Default: null.
rma_number

{"rma_number": "RMA10293021"}

String - The return merchandise authorization (RMA) for this return if available. Set by the system. Default: null.
status

{"status": "Processed"}

String - The status of the return. Set by the system. Can be one of:
  • Processed
  • Verifying
  • Verified
  • Reshipping
  • Reshipped
tracking_number

{"tracking_number": "9261299997140101431920"}

String - The tracking number that was used by the sender for this return. Set by the system.
verify_fee

{"verify_fee": 0.00}

Decimal - The fee in USD for verifying this return. Only applies to returns that were verified. Set by the system. Default: 0.
weight

{"weight": 0.128}

Decimal - The measured weight of this return in KG. Set by the system.
GET
/returns/{id}
Retrieves a return
request
GET /returns/11431

        
response

HTTP/1.1 200 OK

{
    "return": {
        "created": "2016-06-30 12:12:12",
        "id": 11431,
        "images": [
            "https:\/\/api.boxc.com\/i\/32e186166912f18072645e793933904a115f23ce3d33108853640d1d3f94c6b6.jpg",
            "https:\/\/api.boxc.com\/i\/032b960ff67c0fe830e78cb60a2a1b09df18c216a15cacddfbcbfaed33da473e.jpg"
        ],
        "messages": [
            {
                "author": "operator",
                "body": "Package is damaged on the outside",
                "created": "2016-07-01 08:50:22",
                "id": 513120
            }
        ],
        "process_fee": 1,
        "reshipment_id": null,
        "rma_number": null,
        "status": "Processed",
        "tracking_number": "9261299997140101431920",
        "verify_fee": 0,
        "weight": 0.314
    }
}
POST
/returns/{id}/messages
Adds a message to a return
request
POST /returns/11431/messages
{
    "message": {
        "body": "Forward to John Doe, Order ID #123458-10"
    }
}
response

HTTP/1.1 201 Created

{
    "return": {
        "created": "2016-06-30 12:12:12",
        "id": 11431,
        "images": [
            "https:\/\/api.boxc.com\/i\/32e186166912f18072645e793933904a115f23ce3d33108853640d1d3f94c6b6.jpg",
            "https:\/\/api.boxc.com\/i\/032b960ff67c0fe830e78cb60a2a1b09df18c216a15cacddfbcbfaed33da473e.jpg"
        ],
        "messages": [
            {
                "author": "user",
                "body": "Forward to John Doe, Order ID #123458-10",
                "created": "2016-07-02 18:30:01",
                "id": 513444
            },
            {
                "author": "operator",
                "body": "Package is damaged on the outside",
                "created": "2016-07-01 08:50:22",
                "id": 513120
            }
        ],
        "process_fee": 1,
        "reshipment_id": null,
        "rma_number": "MYRMA1234567890",
        "status": "Verifying",
        "tracking_number": "9261299997140101431920",
        "verify_fee": 0,
        "weight": 0.314
    }
}
PUT
/returns/{id}
Updates a return
request
PUT /returns/11431
{
    "return": {
        "status": "Verify"
    }
}
response

HTTP/1.1 200 OK

{
    "return": {
        "created": "2016-06-30 12:12:12",
        "id": 11431,
        "images": [
            "https:\/\/api.boxc.com\/i\/32e186166912f18072645e793933904a115f23ce3d33108853640d1d3f94c6b6.jpg",
            "https:\/\/api.boxc.com\/i\/032b960ff67c0fe830e78cb60a2a1b09df18c216a15cacddfbcbfaed33da473e.jpg"
        ],
        "messages": [
            {
                "author": "operator",
                "body": "Package is damaged on the outside",
                "created": "2016-07-01 08:50:22",
                "id": 513120
            }
        ],
        "process_fee": 1,
        "reshipment_id": null,
        "rma_number": null,
        "status": "Verifying",
        "tracking_number": "9261299997140101431920",
        "verify_fee": 0,
        "weight": 0.314
    }
}
DELETE
/returns/{id}
Discards a return
request
DELETE /returns/11431

        
response

HTTP/1.1 20O OK