Create return orders

POST

/merchants/{merchantCode}/returnOrders

curl --request POST \
  --url https://order.shopgate.io/v1/merchants/example/returnOrders \
  --header 'Content-Type: application/json' \
  --data '{ "returnOrders": [ { "externalCode": "000000274", "salesOrderNumber": "1293747", "type": "return", "customerId": "55c98b8e-1100-497c-8df6-4b4f0353ab2a", "externalCustomerNumber": "C1756793", "status": "draft", "expedited": true, "localeCode": "example", "currencyCode": "EUR", "notes": "Please wrap each item individually.", "specialInstructions": "House behind the dumpster", "data": {}, "primaryBillToAddressSequenceIndex": 1, "primaryShipToAddressSequenceIndex": 1, "addressSequences": [ { "type": "pickup", "customerContactId": "0b475af4-7ed9-4065-b4bb-7d76c537d820", "firstName": "Max", "middleName": "René", "lastName": "Muster", "company": "Shopgate GmbH", "address1": "Schloßstr. 10", "address2": "Haus B", "address3": "erste Etage", "address4": null, "city": "Butzbach", "region": "HE", "postalCode": "\"35510\"", "country": "DE", "phone": "+49 12345 6789 001", "fax": "+49 12345 6789 002", "mobile": "+49 12345 6789 003", "emailAddress": "max.muster@shopgate.com" } ], "subTotal": 0, "discountAmount": 0, "promoAmount": 0, "taxAmount": 0, "tax2Amount": 0, "shippingSubTotal": 1, "shippingDiscountAmount": 1, "shippingPromoAmount": 1, "shippingTotal": 1, "taxExempt": true, "taxSummary": [ { "code": "default_19", "name": "19%", "amount": 1.5 } ], "total": 1, "submitDate": "2019-09-02T09:02:57.733Z", "completeDate": "2019-09-03T15:02:57.733Z", "dropOffType": "inPerson", "dropOffLocationCode": "DERetail001", "os": "ios", "imported": false, "lineItems": [ { "code": "R386", "salesOrderLineItemCode": "386", "status": "open", "quantity": 5, "returnReason": { "code": "example" }, "productCondition": { "code": "example" }, "product": { "code": "24-MB02", "name": "Fusion Backpack", "image": "https://myawesomeshop.com/images/img1.jpg", "price": 59.99, "salePrice": 39.99, "currencyCode": "EUR", "identifiers": { "mfgPartNum": "100-440-0.750-3434-A", "upc": "\"72527273070\"", "ean": "\"401234567890\"", "isbn": "978-3-16-148410-0", "sku": "UGG-BB-PUR-06", "distiPartNum": "\"235454356363\"" }, "options": [ { "code": "color", "name": "Color", "value": { "code": "red", "name": "Red" } } ] }, "currencyCode": "EUR", "price": 1, "shippingAmount": 1, "taxAmount": 1, "tax2Amount": 1, "taxExempt": true, "unitPromoAmount": 0, "unitDiscountAmount": 0, "discountAmount": 0, "promoAmount": 0, "overrideAmount": 1, "extendedPrice": 72, "note": "example" } ] } ] }'

Create return orders

Parameters

Path Parameters

merchantCode

required

string

Unique merchant code which represents the unique “merchant account”.

Request Body

Media typeapplication/json

object

returnOrders

required

Array<object>

>= 1 items

object

externalCode

External order id

string

>= 1 characters

Example

000000274

salesOrderNumber

required

string

Example

1293747

type

string

Allowed values: return

customerId

required

Customer identifier

string

Example

55c98b8e-1100-497c-8df6-4b4f0353ab2a

externalCustomerNumber

A customer number / reference to an external system.

string | null

Example

C1756793

status

string

default: new

Allowed values: draft new inTransit arrived inReview accepted rejected canceled completed

expedited

boolean

localeCode

string

>= 2 characters <= 5 characters

currencyCode

string

>= 3 characters <= 3 characters

Example

EUR

notes

Customer notes where the shopper can provide special instructions. The notes are shown in the In-Store App & Admin.

string | null

<= 1000 characters

Example

Please wrap each item individually.

specialInstructions

Special instructions of the order. It can contain special shipping or fulfillment instructions

string | null

Example

House behind the dumpster

data

object

primaryBillToAddressSequenceIndex

number

primaryShipToAddressSequenceIndex

number

addressSequences

Array<object>

object

type

required

string

Allowed values: pickup shipping billing

customerContactId

string | null

Example

0b475af4-7ed9-4065-b4bb-7d76c537d820

firstName

required

string

Example

Max

middleName

string | null

Example

René

lastName

required

string

Example

Muster

company

string | null

Example

Shopgate GmbH

address1

This field is required if used as shipping address for direct ship

string | null

Example

Schloßstr. 10

address2

string | null

Example

Haus B

address3

string | null

Example

erste Etage

address4

string | null

Example

null

city

This field is required if used as shipping address for direct ship

string | null

Example

Butzbach

region

string | null

Example

HE

postalCode

This field is required if used as shipping address for direct ship

string | null

Example

"35510"

country

ISO 3166 ALPHA-2 / ISO 3166-2 Country Code. This field is required if used as shipping address for direct ship

string | null

<= 2 characters

Example

DE

phone

Validated according to country code

string | null

Example

+49 12345 6789 001

fax

Validated according to country code

string | null

Example

+49 12345 6789 002

mobile

Validated according to country code

string | null

Example

+49 12345 6789 003

emailAddress

required

string format: email

Example

max.muster@shopgate.com

subTotal

number format: float

0

discountAmount

Total amount of all applied promotions with coupons on order level. Without line item level promotions, since these are already included in the order subtotal.

number format: float

0

Example

0

promoAmount

Total amount of all applied promotions on order level. Without line item level promotions, since these are already included in the order subtotal.

number format: float

0

Example

-5

taxAmount

Tax amount of the first tax group (e.g. for german taxes this is an absolut number based on either 7% or 19% of the order total; the order total is 10.00 EUR so the taxAmount is 10.00 EUR * 0.19 = 1.9 EUR)

number format: float

0

tax2Amount

Tax amount of the second tax group (can be used for additional taxes like for example US state taxes)

number format: float

0

shippingSubTotal

number format: float

shippingDiscountAmount

number format: float

shippingPromoAmount

number format: float

shippingTotal

number format: float

taxExempt

boolean

taxSummary

Array<object>

object

code

string

Example

default_19

name

string

Example

19%

amount

number

Example

1.5

total

number format: float

submitDate

Date when the order was submitted by the customer

string | null format: date-time

Example

2019-09-02T09:02:57.733Z

completeDate

Date when the order status was changed to completed

string | null format: date-time

Example

2019-09-03T15:02:57.733Z

dropOffType

required

string

Allowed values: inPerson shipped

dropOffLocationCode

Location where the order is returned

string

Example

DERetail001

os

Operation system of the source device

string

Allowed values: ios android other

Example

ios

imported

Indicates if the order has been imported from an external system. Enabling this flag means that there will be no further processes triggered by this order like emitting events, calculating properties like prices, or starting payment transactions.

boolean

Example

false

lineItems

required

Array<object>

>= 1 items

object

code

required

string

Example

R386

salesOrderLineItemCode

required

string

Example

386

status

required

string

Allowed values: open inProgress rejected canceled completed

Example

inProgress

quantity

required

number

Example

5

returnReason

required

object

code

string

productCondition

required

object

code

string

product

required

object

code

required

Product code

string

>= 1 characters

Example

24-MB02

name

required

Product name

string

Example

Fusion Backpack

image

Main image url of the product

string | null format: uri

Example

https://myawesomeshop.com/images/img1.jpg

price

required

Main price of the product

number format: float

Example

59.99

salePrice

Sale price of the product

number | null format: float

Example

39.99

currencyCode

required

string

>= 3 characters <= 3 characters

Example

EUR

identifiers

object

mfgPartNum

null | string

<= 255 characters

Example

100-440-0.750-3434-A

upc

null | string

<= 255 characters

Example

"72527273070"

ean

null | string

<= 255 characters

Example

"401234567890"

isbn

null | string

<= 255 characters

Example

978-3-16-148410-0

sku

null | string

<= 255 characters

Example

UGG-BB-PUR-06

distiPartNum

null | string

<= 255 characters

Example

"235454356363"

options

Array<object>

object

code

required

string

Example

color

name

required

string

Example

Color

value

required

object

code

required

string

Example

red

name

required

string

Example

Red

currencyCode

string

>= 3 characters <= 3 characters

Example

EUR

price

number format: float

shippingAmount

number format: float

taxAmount

number format: float

tax2Amount

number format: float

taxExempt

boolean

unitPromoAmount

Amount of all applied promotions for a single unit (single quantity).

number format: float

0

Example

-4

unitDiscountAmount

Amount of all applied discounts (promotions with coupons) for a single unit (single quantity).

number format: float

0

Example

-3

discountAmount

Total amount of all applied promotions with coupons for the line item. (Formula: lineItem.unitDiscountAmount * lineItem.quantity)

number format: float

0

Example

-6

promoAmount

Total amount of all applied promotions for the line item. (Formula: lineItem.unitPromoAmount * lineItem.quantity)

number format: float

0

Example

-8

overrideAmount

number format: float

extendedPrice

The extended Price is the final price of the line item, including all discounts & promotions that apply to this line item, and also already multiplied with the quantity. Formula: (product.price or product.salePrice if not empty) * quantity + promoAmount + discountAmount. Example: A product original price is 60€ (product.price), but it is on sale for 40€ (product.salePrice). Ordered quantity is 2, there is no discount but there is a promotion that applies to this product and gives 10% additional discount (unitPromoAmount = 4€, promoAmount = 8€). The extended price of this line item should be (40€ * 2) + (-8€) = 72€.

number format: float

Example

72

note

string

Responses

200

Media typeapplication/json

object

ids

Array<string>

errors

Array<object>

object

entityIndex

number

entity

string

entityId

string

code

number

message

string

subentityPath

Array<string | null | number>

Example^generated

{
  "errors": [
    {
      "entityIndex": 1,
      "entity": "example",
      "entityId": "example",
      "code": 1,
      "message": "example",
      "subentityPath": [
        "example"
      ]
    }
  ]
}

404

Order not found

Media typeapplication/json

default

Unexpected error

Media typeapplication/json

object

code

Machine readable error code

string

message

required

Human readable error code

string

Example

{
  "code": "internal.database",
  "message": "Internal Database Error"
}