Skip to main content
POST
/
shipments
/
returns
cURL
curl --request POST \
  --url https://api.atlast.co/v1/shipments/returns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "<string>",
  "carrier": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "serviceId": "<string>"
  },
  "shipment": {
    "reference": "<string>",
    "reference2": "<string>",
    "from": {
      "name": "<string>",
      "email": "jsmith@example.com",
      "phoneNumber": "<string>",
      "address": {
        "line1": "<string>",
        "line2": "<string>",
        "line3": "<string>",
        "city": "<string>",
        "postCode": "<string>"
      }
    },
    "return": {
      "dimensions": {
        "width": 1,
        "height": 1,
        "length": 1,
        "unit": "CM"
      },
      "orderIdentifier": "<string>",
      "items": [
        {
          "quantity": 2,
          "value": {
            "value": 1,
            "currency": "<string>"
          },
          "weight": {
            "value": 1,
            "unit": "GRAMS"
          },
          "reason": "TOO_LARGE"
        }
      ]
    }
  },
  "sendEmail": false,
  "ignore": [
    "SIZE"
  ]
}'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reference": "<string>",
  "reference2": "<string>",
  "carrier": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "serviceId": "<string>"
  },
  "parcel": {
    "dimensions": {
      "width": 1,
      "height": 1,
      "length": 1,
      "unit": "CM"
    },
    "weight": {
      "value": 1,
      "unit": "GRAMS"
    },
    "items": [
      {
        "description": "<string>",
        "quantity": 2,
        "value": {
          "value": 1,
          "currency": "<string>"
        },
        "weight": {
          "value": 1,
          "unit": "GRAMS"
        }
      }
    ]
  },
  "from": {
    "name": "<string>",
    "email": "jsmith@example.com",
    "phoneNumber": "<string>",
    "address": {
      "line1": "<string>",
      "line2": "<string>",
      "line3": "<string>",
      "city": "<string>",
      "postCode": "<string>"
    }
  },
  "to": {
    "name": "<string>",
    "email": "jsmith@example.com",
    "phoneNumber": "<string>",
    "address": {
      "line1": "<string>",
      "line2": "<string>",
      "line3": "<string>",
      "city": "<string>",
      "postCode": "<string>"
    }
  },
  "labels": [
    {
      "url": "<string>",
      "type": "PAPERLESS"
    }
  ],
  "trackingNumber": "<string>",
  "trackingUrl": "<string>",
  "statusDescription": "<string>",
  "failureReason": "<string>",
  "latestDeliveryEvent": "BOOKED",
  "state": "AWAITING_BOOKING",
  "deliveryState": "AWAITING_BOOKING",
  "metadata": {
    "returnId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "externalId": "<string>",
    "merchant": {
      "id": "<string>"
    },
    "user": {
      "email": "jsmith@example.com"
    },
    "items": [
      {
        "itemId": "<string>",
        "reason": "TOO_LARGE",
        "quantity": 2
      }
    ]
  },
  "collectionRequestedTimeSlot": {
    "date": "<string>",
    "time": "<string>"
  },
  "collection": {
    "bookedTimeSlot": {
      "date": "<string>",
      "time": "<string>"
    },
    "rebooked": true
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "hasDelivery": true,
  "hasCollection": true
}
Shipments are composed of a delivery and optionally a collection.

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

Create return shipment request

​
id
string
required
​
carrier
object
required

Carrier details

​
shipment
object
required

Return Shipment details Create return shipment request

​
sendEmail
boolean
default:false

Send customer email communications flag. Setting this to true will make At Last send any return related emails to the end user. This only impact return creation emails when using the API. This flag defaults to false.

​
ignore
enum<string>[]

Response

The request has succeeded.

Return Shipment resource

​
id
string<uuid>
required

At last shipment id

​
carrier
object
required
​
parcel
object
required
​
from
object
required

Data used to specify address and receiver/sender details to create a shipment and collection. The data send in these address details are NOT verified. It's the responsibility of the caller to ensure the address data is correct or shipment/collection requests can fail.

​
to
object
required

Data used to specify address and receiver/sender details to create a shipment and collection. The data send in these address details are NOT verified. It's the responsibility of the caller to ensure the address data is correct or shipment/collection requests can fail.

​
state
enum<string>
required
Available options:
AWAITING_BOOKING,
READY,
ONGOING,
COMPLETE,
CANCELED,
FAIL
​
metadata
object
required
​
createdAt
string<date-time>
required
​
hasDelivery
boolean
required
​
hasCollection
boolean
required
​
reference
string

Shipment Reference.

Required string length: 1 - 20
​
reference2
string

Optional shipping reference (might not be suported by all carriers)

Required string length: 1 - 20
​
labels
object[]
​
trackingNumber
string
​
trackingUrl
string<uri>
​
statusDescription
string
​
failureReason
string
​
latestDeliveryEvent
enum<string>
Available options:
BOOKED,
COLLECTED,
AT_HUB,
IN_TRANSIT,
OUT_FOR_DELIVERY,
FAILED_ATTEMPT,
DELIVERED,
ON_HOLD,
ADDRESS_ISSUE,
RETURNED_TO_SENDER,
TRACKING_EXPIRED,
CANCELLED,
AWAITING_CUSTOMER_COLLECTION,
PACKING,
MISSING,
DAMAGED
​
deliveryState
enum<string>
Available options:
AWAITING_BOOKING,
READY,
ONGOING,
COMPLETE,
CANCELED,
FAIL
​
collectionRequestedTimeSlot
object

Resovled collection time slot

​
collection
object