Create Return

POST 
https://api.goodsdelivery.io/v1/returns

Authorization: x-api-key

name: x-api-keytype: apiKeyscopes: brandin: header

To create a return pick-up, use this endpoint. Your request body should include a JSON object with several required fields. The endpoint also checks whether the provided zip codes for pick-up and destination are within the Goods coverage area.

Request

application/json

Body

required

jobDetails objectrequired

serviceType ServiceTyperequired

Possible values: [SAME_DAY, NEXT_DAY, SCHEDULED]

Determine the delivery date, including pick-up and drop-off times.

scheduledDate date-time

Required if serviceType is SCHEDULED. Date in ISO 8601 format

externalId stringrequired

External reference - an ID that uniquely identifies the order in your systems.

brandId stringrequired

This is the Goods-provided brand ID. It represents the brand for which the delivery is being made and may vary for multi-brand setups.

packagesTotalValueUsd doublerequired

Total package value (USD).

packages object[]

Array [

volumeFt3 number

Volume of the package in cubic foot (ft3), if known

weightLbs number

Package weight in pounds (lbs), if known.

lengthIn number

Length of the pack in inches, if known.

widthIn number

Width of the pack in inches, if known.

heightIn number

Height of the pack in inches, if known.

]

addons Addon[]

Possible values: [EXTRA_INSURANCE, SIGNATURE_REQUIRED, WITHOUT_LABEL]

Optional add-ons specifically for the delivery. Please note that these add-ons typically incur an additional cost.

note string

These are optional notes regarding the specific delivery. However, please note that any specific pick-up, drop-off, or delivery instructions belong in separate sections.

contactlessPreferred boolean

Defines if the consumer prefers contactless delivery.

consumer objectrequired

firstName stringrequired

lastName stringrequired

phone phone

Phone is required when email is not provided

email email

Email is required when phone is not provided

pickUp objectrequired

name string

Company name

address1 stringrequired

address2 string

city stringrequired

zipCode stringrequired

state stringrequired

2 letter state code - ISO 3166-2

country stringrequired

2 letter country code - ISO 3166-2

note string

Address note - how to get there, etc.

dropOff objectrequired

name string

Company name

address1 stringrequired

address2 string

city stringrequired

zipCode stringrequired

state stringrequired

2 letter state code - ISO 3166-2

country stringrequired

2 letter country code - ISO 3166-2

note string

Address note - how to get there, etc.

Responses

201

If all required fields are provided and the zip codes are valid, a success response with a code of 201, as well as an ID and Short ID, will be returned.

application/json

Schema

Schema

success booleanrequired
object objectrequired
id stringrequired
Unique ID of the delivery.
shortId stringrequired
The short ID is a more readable and consumer-friendly delivery ID.
trackingUrl stringrequired
labelUrl stringrequired

Example (from schema)

{
  "success": true,
  "object": {
    "id": "string",
    "shortId": "string",
    "trackingUrl": "string",
    "labelUrl": "string"
  }
}

Example

{
  "success": true,
  "object": {
    "id": "7vSVMvvj8VKLLUWuPZTa",
    "shortId": "R23D21",
    "trackingUrl": "https://tracking.goodsdelivery.io/R23D21",
    "labelUrl": "https://storage.googleapis.com/goods-sandbox.appspot.com/labels%2FNjY2MWIyMTZkNjYxNmViZGM4NmI4YzMz"
  }
}

400

Bad request

application/json

Schema

Schema

message stringrequired

Human readable error message.

code stringrequired

Machine readable error message.

more url

More help on the error here.

Example (from schema)

{
  "message": "string",
  "code": "string",
  "more": "string"
}

401

Unauthorized

application/json

Schema

Schema

message stringrequired

Human readable error message.

code stringrequired

Machine readable error message.

more url

More help on the error here.

Example (from schema)

{
  "message": "string",
  "code": "string",
  "more": "string"
}

403

Forbidden

application/json

Schema

Schema

message stringrequired

Human readable error message.

code stringrequired

Machine readable error message.

more url

More help on the error here.

Example (from schema)

{
  "message": "string",
  "code": "string",
  "more": "string"
}

• curl
• python
• go
• nodejs
• ruby
• csharp
• php
• java
• powershell

• CURL

curl -L -X POST 'https://api.goodsdelivery.io/v1/returns' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'x-api-key: <API_KEY_VALUE>' \
--data-raw '{
  "jobDetails": {
    "serviceType": "SAME_DAY",
    "scheduledDate": "2023-06-02",
    "externalId": "string",
    "brandId": "string",
    "packagesTotalValueUsd": 0,
    "packages": [
      {
        "volumeFt3": 0,
        "weightLbs": 0,
        "lengthIn": 0,
        "widthIn": 0,
        "heightIn": 0
      }
    ],
    "addons": [
      "EXTRA_INSURANCE"
    ],
    "note": "string",
    "contactlessPreferred": true
  },
  "consumer": {
    "firstName": "string",
    "lastName": "string",
    "phone": "string",
    "email": "user@example.com"
  },
  "pickUp": {
    "name": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "zipCode": "string",
    "state": "string",
    "country": "string",
    "note": "string"
  },
  "dropOff": {
    "name": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "zipCode": "string",
    "state": "string",
    "country": "string",
    "note": "string"
  }
}'

Request Collapse all

Base URL

https://api.goodsdelivery.io/v1

Auth

Security Scheme

APIKeyHeaderAuthorizationHeader

APIKeyHeader

Body required

{
  "jobDetails": {
    "serviceType": "SAME_DAY",
    "scheduledDate": "2023-06-02",
    "externalId": "string",
    "brandId": "string",
    "packagesTotalValueUsd": 0,
    "packages": [
      {
        "volumeFt3": 0,
        "weightLbs": 0,
        "lengthIn": 0,
        "widthIn": 0,
        "heightIn": 0
      }
    ],
    "addons": [
      "EXTRA_INSURANCE"
    ],
    "note": "string",
    "contactlessPreferred": true
  },
  "consumer": {
    "firstName": "string",
    "lastName": "string",
    "phone": "string",
    "email": "user@example.com"
  },
  "pickUp": {
    "name": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "zipCode": "string",
    "state": "string",
    "country": "string",
    "note": "string"
  },
  "dropOff": {
    "name": "string",
    "address1": "string",
    "address2": "string",
    "city": "string",
    "zipCode": "string",
    "state": "string",
    "country": "string",
    "note": "string"
  }
}

ResponseClear

Click the Send API Request button above and see the response here!