Returns

Working with returns.

List Order Returns

GET /v1/orders/returns

List order returns

Return Type

array<OrderReturns>

Filters

Field	Operators	Value List URL
search	`LIKE`	fuzzy search across selected attributes
status	`IN`, `NOT_IN`
order.channel.organisation.id	`IN`, `NOT_IN`
order.channel.id	`IN`, `NOT_IN`
warehouse.id	`IN`
tags.shortcode	`IN`, `NOT_IN`
created	`LESS_THAN`, `ON_DATE`, `MORE_THAN`

Sortings

Results can be sorted by the following keys: id, received_date.

Available expands

Field	Return Type	Description
`order`	`Orders`	Customer order groups.
`order.channel`	`OrderChannels`	Customer order groups.
`order.channel.organisation`	`Organisations`	Organisation data.
`order_return_items`	`array<OrderReturnItems>`	Order Return Items.
`order_return_items.component`	`ProductComponents`	Product component.
`order_return_items.exchange_component`	`ProductComponents`	Product component.
`order_return_items.reason`	`OrderReturnItemReasons`	Order Return Item Reasons.
`tags`	`array<SummarisedTag>`	A tag.
`warehouse`	`Warehouses`	A warehouse.

Rate limit cost

Each call to this endpoint deducts 1 credit from your request bucket.

Scopes

This endpoint is only available for users with scope APP::RETURNS::READ.

<?php

// Instantiate a GuzzleHttp client
$client = new \GuzzleHttp\Client();

// Make the request
$response = $client->request("GET", "https://public-api.bladepro.io/v1/orders/returns?expand=*", [
    "headers" => [
        "Content-Type" => "application/json",
        "Access-Token" => "my-token-from-login",
    ],
]);

// Process the response
$responseBody = json_decode($response->getBody(), true);

require 'rest-client'
require 'json'

# Make the request
response = RestClient.get 'https://public-api.bladepro.io/v1/orders/returns?expand=*', {
  access_token: 'my-token-from-login',
  content_type: :json,
  accept: :json
}

# Process the response
puts response.body

// Require the node HTTP module
var request = require("request");

// Make the request
request({
    method: "GET",
    json: true,
    uri: "https://public-api.bladepro.io/v1/orders/returns?expand=*",
    headers: {
        "Access-Token": "my-token-from-login",
        "Content-Type": "application/json",
    },
    (error, response, body) => {
        // Process the response
        console.log(body);
    },
});

# Make the request
curl --location --request GET 'https://public-api.bladepro.io/v1/orders/returns?expand=*' \
--header 'Content-Type: application/json' \
--header 'Access-Token: my-token-from-login'

Example result:

{
    "meta": {
        "request_reference": "235chjz9h-c893v86",
        "paging": {
            "page": 1,
            "records": 1,
            "per_page": 250,
            "total_records": 1,
            "total_pages": 1
        }
    },
    "data": [
        {
            "id": 1,
            "order_id": 1,
            "shipping_address_id": 1,
            "warehouse_id": 1,
            "status": "pending",
            "created": "2019-11-25T14:52:56.000Z",
            "modified": "2019-11-25T14:52:56.000Z",
            "warehouse": {
                "id": 1,
                "name": "Christchurch",
                "short_code": "CHR",
                "latitude": 50.739492,
                "longitude": -1.734224,
                "country_id": 1,
                "active": true,
                "currency_id": 1,
                "virtual": false,
                "return_warehouse_id": 1,
                "created": "2019-11-25T14:52:56.000Z",
                "modified": "2019-11-25T14:52:56.000Z"
            },
            "order": {
                "id": 1234567,
                "reference": "#154254",
                "status": "open",
                "channel": {
                    "id": 321,
                    "organisation_id": 321,
                    "name": "Demo Channel",
                    "short_code": "DEMO",
                    "status": "active",
                    "created": "2019-11-25T14:52:56.000Z",
                    "modified": "2019-11-25T14:52:56.000Z",
                    "organisation": {
                        "id": 1,
                        "name": "Demo",
                        "active": true,
                        "vat_number": "GB999 9999 73",
                        "notes": "Demo account...",
                        "contact_name": "Mr Joe Bloggs",
                        "contact_phone": "+44 01425 000 000",
                        "contact_mobile": "+44 00000000",
                        "contact_email": "joe.bloggs@example.com",
                        "created": "2019-11-25T14:52:56.000Z",
                        "modified": "2019-11-25T14:52:56.000Z"
                    }
                }
            },
            "order_return_items": [
                {
                    "id": 1,
                    "order_return_id": 1,
                    "order_goodsout_line_item_id": 1,
                    "order_goodsout_line_id": 1,
                    "product_component_id": 1,
                    "sku": "DEMO-SKU-01",
                    "exchanged_product_component_id": 1,
                    "expected_quantity": 2,
                    "received_quantity": 2,
                    "expiry_date": "2019-11-25T14:52:56.000Z",
                    "received_date": "2019-11-25T14:52:56.000Z",
                    "action": "refund",
                    "order_return_item_reason_id": 1,
                    "description": "Damaged in box",
                    "correct_item": "YES",
                    "resellable": "NO",
                    "status": "pending",
                    "authorisation_required": "NO",
                    "rejected_reason": "Outside agreed return window",
                    "created": "2019-11-25T14:52:56.000Z",
                    "modified": "2019-11-25T14:52:56.000Z"
                }
            ],
            "tags": [
                {
                    "name": "Processed",
                    "shortcode": "processed",
                    "description": "Processed by a 3rd party system"
                }
            ]
        }
    ]
}

View Order Return

GET /v1/orders/returns/:id

View order return

Parameter Regular Expressions

:id: [1-9][0-9]{0,}

Return Type

OrderReturns

Available expands

Field	Return Type	Description
`order`	`Orders`	Customer order groups.
`order.channel`	`OrderChannels`	Customer order groups.
`order.channel.organisation`	`Organisations`	Organisation data.
`order_return_items`	`array<OrderReturnItems>`	Order Return Items.
`order_return_items.component`	`ProductComponents`	Product component.
`order_return_items.exchange_component`	`ProductComponents`	Product component.
`order_return_items.reason`	`OrderReturnItemReasons`	Order Return Item Reasons.
`warehouse`	`Warehouses`	A warehouse.

Rate limit cost

Each call to this endpoint deducts 1 credit from your request bucket.

Scopes

This endpoint is only available for users with scope APP::RETURNS::READ.

<?php

// Instantiate a GuzzleHttp client
$client = new \GuzzleHttp\Client();

// Make the request
$response = $client->request("GET", "https://public-api.bladepro.io/v1/orders/returns/1234567?expand=*", [
    "headers" => [
        "Content-Type" => "application/json",
        "Access-Token" => "my-token-from-login",
    ],
]);

// Process the response
$responseBody = json_decode($response->getBody(), true);

require 'rest-client'
require 'json'

# Make the request
response = RestClient.get 'https://public-api.bladepro.io/v1/orders/returns/1234567?expand=*', {
  access_token: 'my-token-from-login',
  content_type: :json,
  accept: :json
}

# Process the response
puts response.body

// Require the node HTTP module
var request = require("request");

// Make the request
request({
    method: "GET",
    json: true,
    uri: "https://public-api.bladepro.io/v1/orders/returns/1234567?expand=*",
    headers: {
        "Access-Token": "my-token-from-login",
        "Content-Type": "application/json",
    },
    (error, response, body) => {
        // Process the response
        console.log(body);
    },
});

# Make the request
curl --location --request GET 'https://public-api.bladepro.io/v1/orders/returns/1234567?expand=*' \
--header 'Content-Type: application/json' \
--header 'Access-Token: my-token-from-login'

Example result:

{
    "meta": {
        "request_reference": "235chjz9h-c893v86"
    },
    "data": {
        "id": 1,
        "order_id": 1,
        "shipping_address_id": 1,
        "warehouse_id": 1,
        "status": "pending",
        "created": "2019-11-25T14:52:56.000Z",
        "modified": "2019-11-25T14:52:56.000Z",
        "warehouse": {
            "id": 1,
            "name": "Christchurch",
            "short_code": "CHR",
            "latitude": 50.739492,
            "longitude": -1.734224,
            "country_id": 1,
            "active": true,
            "currency_id": 1,
            "virtual": false,
            "return_warehouse_id": 1,
            "created": "2019-11-25T14:52:56.000Z",
            "modified": "2019-11-25T14:52:56.000Z"
        },
        "order": {
            "id": 1234567,
            "reference": "#154254",
            "status": "open",
            "channel": {
                "id": 321,
                "organisation_id": 321,
                "name": "Demo Channel",
                "short_code": "DEMO",
                "status": "active",
                "created": "2019-11-25T14:52:56.000Z",
                "modified": "2019-11-25T14:52:56.000Z",
                "organisation": {
                    "id": 1,
                    "name": "Demo",
                    "active": true,
                    "vat_number": "GB999 9999 73",
                    "notes": "Demo account...",
                    "contact_name": "Mr Joe Bloggs",
                    "contact_phone": "+44 01425 000 000",
                    "contact_mobile": "+44 00000000",
                    "contact_email": "joe.bloggs@example.com",
                    "created": "2019-11-25T14:52:56.000Z",
                    "modified": "2019-11-25T14:52:56.000Z"
                }
            }
        },
        "order_return_items": [
            {
                "id": 1,
                "order_return_id": 1,
                "order_goodsout_line_item_id": 1,
                "order_goodsout_line_id": 1,
                "product_component_id": 1,
                "sku": "DEMO-SKU-01",
                "exchanged_product_component_id": 1,
                "expected_quantity": 2,
                "received_quantity": 2,
                "expiry_date": "2019-11-25T14:52:56.000Z",
                "received_date": "2019-11-25T14:52:56.000Z",
                "action": "refund",
                "order_return_item_reason_id": 1,
                "description": "Damaged in box",
                "correct_item": "YES",
                "resellable": "NO",
                "status": "pending",
                "authorisation_required": "NO",
                "rejected_reason": "Outside agreed return window",
                "created": "2019-11-25T14:52:56.000Z",
                "modified": "2019-11-25T14:52:56.000Z"
            }
        ]
    }
}

Create Return

POST /v1/orders/returns

Creates a return.

Request Body

CreateReturn

Return Type

OrderReturns

Types for the Request Body

CreateReturn (root level)

Key	Description	Types	Restrictions
`reference`	Order specific reference.	`string`	`required` not `null` `min length` is `1`
`third_party_tracking_number`	Third party tracking number.	`string`	`min length` is `1`
`items`	List of items.	`array<Item>`	`required` not `null` `min count` is `1`

Item

Key	Description	Types	Restrictions
`sku`	The product’s stock keeping unit (SKU).	`string`	`required` not `null` `min length` is `1`
`quantity`	The quantity to return.	`integer`	`required` not `null` `min` is `1`
`action`	The return action.	`enum(refund, exchange, stock)`	`required` not `null`
`reason`	The reason for return.	`string`	`required` not `null` `min length` is `1`
`description`	The description of why the item is being returned.	`string`	not `null` `min length` is `1`

Available expands

Field	Return Type	Description
`order_return_items`	`array<OrderReturnItems>`	Order Return Items.

Rate limit cost

Each call to this endpoint deducts 2 credits from your request bucket.

Scopes

This endpoint is only available for users with scope APP::RETURNS::MANAGE.

<?php

// Instantiate a GuzzleHttp client
$client = new \GuzzleHttp\Client();

// Make the request
$response = $client->request("POST", "https://public-api.bladepro.io/v1/orders/returns?expand=*", [
    "body" => json_encode([
        "reference" => "#154254",
        "third_party_tracking_number" => "ABC123",
        "items" => [
            [
                "sku" => "GREEN-BALL",
                "quantity" => 4,
                "action" => "Refund",
                "reason" => "Size and fit - too large",
                "description" => "I need a size XL",
            ],
        ],
    ]),
    "headers" => [
        "Content-Type" => "application/json",
        "Access-Token" => "my-token-from-login",
    ],
]);

// Process the response
$responseBody = json_decode($response->getBody(), true);

require 'rest-client'
require 'json'

# Make the request
response = RestClient.post 'https://public-api.bladepro.io/v1/orders/returns?expand=*', {
  reference: "#154254",
  third_party_tracking_number: "ABC123",
  items: [
    {
      sku: "GREEN-BALL",
      quantity: 4,
      action: "Refund",
      reason: "Size and fit - too large",
      description: "I need a size XL",
    },
  ],
}, {
  access_token: 'my-token-from-login',
  content_type: :json,
  accept: :json
}

# Process the response
puts response.body

// Require the node HTTP module
var request = require("request");

// Make the request
request({
    method: "POST",
    json: true,
    uri: "https://public-api.bladepro.io/v1/orders/returns?expand=*",
    body: {
        "reference": "#154254",
        "third_party_tracking_number": "ABC123",
        "items": [
            {
                "sku": "GREEN-BALL",
                "quantity": 4,
                "action": "Refund",
                "reason": "Size and fit - too large",
                "description": "I need a size XL"
            }
        ]
    },
    headers: {
        "Access-Token": "my-token-from-login",
        "Content-Type": "application/json",
    },
    (error, response, body) => {
        // Process the response
        console.log(body);
    },
});

# Make the request
curl --location --request POST 'https://public-api.bladepro.io/v1/orders/returns?expand=*' \
--header 'Content-Type: application/json' \
--header 'Access-Token: my-token-from-login' \
--data-raw '{
    "reference": "#154254",
    "third_party_tracking_number": "ABC123",
    "items": [
        {
            "sku": "GREEN-BALL",
            "quantity": 4,
            "action": "Refund",
            "reason": "Size and fit - too large",
            "description": "I need a size XL"
        }
    ]
}'

Example result:

{
    "meta": {
        "request_reference": "235chjz9h-c893v86"
    },
    "data": {
        "id": 1,
        "order_id": 1,
        "shipping_address_id": 1,
        "warehouse_id": 1,
        "status": "pending",
        "created": "2019-11-25T14:52:56.000Z",
        "modified": "2019-11-25T14:52:56.000Z",
        "order_return_items": [
            {
                "id": 1,
                "order_return_id": 1,
                "order_goodsout_line_item_id": 1,
                "order_goodsout_line_id": 1,
                "product_component_id": 1,
                "sku": "DEMO-SKU-01",
                "exchanged_product_component_id": 1,
                "expected_quantity": 2,
                "received_quantity": 2,
                "expiry_date": "2019-11-25T14:52:56.000Z",
                "received_date": "2019-11-25T14:52:56.000Z",
                "action": "refund",
                "order_return_item_reason_id": 1,
                "description": "Damaged in box",
                "correct_item": "YES",
                "resellable": "NO",
                "status": "pending",
                "authorisation_required": "NO",
                "rejected_reason": "Outside agreed return window",
                "created": "2019-11-25T14:52:56.000Z",
                "modified": "2019-11-25T14:52:56.000Z"
            }
        ]
    }
}

Apply Return Tag

POST /v1/orders/returns/:id/tags

Applies a tag to a return.

Parameter Regular Expressions

:id: [1-9][0-9]{0,}

Request Body

ApplyTag

Return Type

OrderReturnTags

Types for the Request Body

ApplyTag (root level)

Key	Description	Types	Restrictions
`shortcode`	The tag shortcode.	`string`	`required` not `null` `min length` is `1`

Rate limit cost

Each call to this endpoint deducts 2 credits from your request bucket.

Scopes

This endpoint is only available for users with scope APP::RETURNS::MANAGE.

<?php

// Instantiate a GuzzleHttp client
$client = new \GuzzleHttp\Client();

// Make the request
$response = $client->request("POST", "https://public-api.bladepro.io/v1/orders/returns/:id/tags", [
    "body" => json_encode([
        "shortcode" => "PROCESSED",
    ]),
    "headers" => [
        "Content-Type" => "application/json",
        "Access-Token" => "my-token-from-login",
    ],
]);

// Process the response
$responseBody = json_decode($response->getBody(), true);

require 'rest-client'
require 'json'

# Make the request
response = RestClient.post 'https://public-api.bladepro.io/v1/orders/returns/:id/tags', {
  shortcode: "PROCESSED",
}, {
  access_token: 'my-token-from-login',
  content_type: :json,
  accept: :json
}

# Process the response
puts response.body

// Require the node HTTP module
var request = require("request");

// Make the request
request({
    method: "POST",
    json: true,
    uri: "https://public-api.bladepro.io/v1/orders/returns/:id/tags",
    body: {
        "shortcode": "PROCESSED"
    },
    headers: {
        "Access-Token": "my-token-from-login",
        "Content-Type": "application/json",
    },
    (error, response, body) => {
        // Process the response
        console.log(body);
    },
});

# Make the request
curl --location --request POST 'https://public-api.bladepro.io/v1/orders/returns/:id/tags' \
--header 'Content-Type: application/json' \
--header 'Access-Token: my-token-from-login' \
--data-raw '{
    "shortcode": "PROCESSED"
}'

Example result:

{
    "meta": {
        "request_reference": "235chjz9h-c893v86"
    },
    "data": {
        "id": 1,
        "name": "Processed",
        "shortcode": "PROCESSED",
        "description": "Marked a as processed by XYZ system",
        "created": "2019-11-25T14:52:56.000Z"
    }
}

Remove Return Tag

DELETE /v1/orders/returns/:id/tags/:tagShortcode

Remove a tag from a return.

Parameter Regular Expressions

:id: [1-9][0-9]{0,}
:tagShortcode: [a-zA-Z0-9]{3,20}

Return Type

Empty.

Rate limit cost

Each call to this endpoint deducts 2 credits from your request bucket.

Scopes

This endpoint is only available for users with scope APP::RETURNS::MANAGE.

<?php

// Instantiate a GuzzleHttp client
$client = new \GuzzleHttp\Client();

// Make the request
$response = $client->request("DELETE", "https://public-api.bladepro.io/v1/orders/returns/1234567/tags/PROCESSED", [
    "headers" => [
        "Content-Type" => "application/json",
        "Access-Token" => "my-token-from-login",
    ],
]);

// Process the response
$responseBody = json_decode($response->getBody(), true);

require 'rest-client'
require 'json'

# Make the request
response = RestClient.delete 'https://public-api.bladepro.io/v1/orders/returns/1234567/tags/PROCESSED', {
  access_token: 'my-token-from-login',
  content_type: :json,
  accept: :json
}

# Process the response
puts response.body

// Require the node HTTP module
var request = require("request");

// Make the request
request({
    method: "DELETE",
    json: true,
    uri: "https://public-api.bladepro.io/v1/orders/returns/1234567/tags/PROCESSED",
    headers: {
        "Access-Token": "my-token-from-login",
        "Content-Type": "application/json",
    },
    (error, response, body) => {
        // Process the response
        console.log(body);
    },
});

# Make the request
curl --location --request DELETE 'https://public-api.bladepro.io/v1/orders/returns/1234567/tags/PROCESSED' \
--header 'Content-Type: application/json' \
--header 'Access-Token: my-token-from-login'

Example result:

null