Returns

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

Retrieves a paginated list of returns

`date_start`	The inclusive date to begin the search in YYYY-MM-DD format. Default is 90 days ago.
`date_end`	The inclusive date to end the search in YYYY-MM-DD format. Default is now.
`limit`	The number of results to return. Max: 100. Default: 50.
`order`	The order of the results. Options are "asc" for ascending, or "desc" (default) for descending.
`page`	The page number of the results. Default is 1.
`status`	Filter that selects returns with the given status. Default behavior is to return all returns.

request

GET /returns

date_start=2016-06-01&date_end=2016-07-01&page=2=&limit=50&order=desc&status=Processed

response

HTTP/1.1 200 OK

{
    "returns": [
        {
            "created": "2016-06-30 12:12:12",
            "id": 11431,
            "messages": 1,
            "process_fee": 1,
            "reshipment_id": null,
            "rma_number": null,
            "status": "Processed",
            "tracking_number": "9261299997140101431920",
            "verify_fee": 0,
            "weight": 0.314
        },
        {
            "...": "..."
        }
    ],
    "total_pages": 0,
    "total_returns": 0
}

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

Basics

Carriers

Reference

Verify

Actions

Properties