Order API - Create Return

Create return

Endpoint: POST *base*/return
Authentication: API Key

This will create return for given shipment and items. Return will be created even if some of the provided items cannot be returned.

Parameters

shipment
string
required

The shipmentId from Get shipments or Create shipment.

products
object
optional

Key is lineID from the Get shipments and value is the quantity. Example: {"products":{"1441":2}} will create a return of 2 products from item 1441.

key in object
string
required

lineID from the Get shipments referring to a specific product item in the order.

value in object
int
required

Quantity of the item that should be returned.

returnStock
boolean
optional

Insert returned items into stock. If not provided Default stock action on return setting on the store will be used.

handlingCost
float
optional

Handling cost.

handlingCostFromShipment
boolean
optional

Default false. Set to true to use Handling cost from Shipment. You cannot provide handlingCost at the same time this option is used.

shippingCost
float
optional

Shipping cost.

shippingCostFromShipment
boolean
optional

Default false. Set to true to use Shipping cost from Shipment. You cannot provide shippingCost at the same time this option is used.

returnCost
float
optional

Return cost. If the return itself should have a cost to it. Providing a value here will deduct the amount of money to refund.

voucherValue
float
optional

Voucher value, should always be positive value.

voucherValueFromShipment
boolean
optional

Default false. Set to true to use Voucher value from Shipment. You cannot provide voucherValue at the same time this option is used.

comment
string
optional

Additional comment for return, for reference.

xml
boolean
optional

Response in xml format instead of json.

createdAt
date/datetime
optional

Additional datetime one of the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS like 2015-12-24 13:25:01. Timezone is system-wide and decided by the company using Centra.

refund
object
optional

Refund object. Example: {"refund":{"refundPayment": true}} will make refund from return.

refundPayment
boolean
optional

If this is set to true the payment provider will get a refund request to pay back the money to the customer. The amount that will be refunded is the amount for the products, the handling, shipping and return costs. If the refund is successful against the payment provider, the returnCompleted will be true in the response.

sendEmail
boolean
optional

Send refund email. Default value is false.

Request example

POST <base>/return HTTP/1.1
Content-type: application/json

{
  "shipment": "120276-1",
  "returnStock": 1,
  "comment": "Return created with Order Api",
  "products": {
    "268871": "1",
    "268870": "1"
  }
}

Request example including refund

POST <base>/return HTTP/1.1
Content-type: application/json

{
  "shipment": "120276-1",
  "returnStock": 1,
  "comment": "Return created with Order Api",
  "products": {
    "268871": "1",
    "268870": "1"
  },
  "refund": {
    "refundPayment": true,
    "sendEmail": true
  }
}

Response

200 Content-type: application/json

status
string
required

ok if success, else no.

order
int
optional

Order ID that was captured.

return
int
optional

Return ID that was created.

returnCompleted
boolean
optional

If the return was completed directly on creation, this can only happen if a successful refund was made when return was created.

returnedItems
array
optional

Array of Line IDs of returned Products.

msg
string
optional

If status returns no, this value should send back a message why it failed.

Response example

{
  "status": "ok",
  "return": 5397,
  "returnCompleted": false,
  "returnedItems": [
    "268871"
  ]
}

Response example including refund

{
  "status": "ok",
  "return": 5397,
  "returnCompleted": true,
  "returnedItems": [
    "268871"
  ],
  "refund": {
    "status": "ok"
  }
}

Error example

{
  "status": "no",
  "msg": "return could not be created."
}