Create fulfillment orders

POST

/merchants/{merchantCode}/fulfillmentOrders

curl --request POST \
  --url https://order.shopgate.io/v1/merchants/example/fulfillmentOrders \
  --header 'Content-Type: application/json' \
  --data '{ "fulfillmentOrders": [ { "orderNumber": "1293747-0001", "externalCode": "000000274", "salesOrderNumber": "1293747", "locationCode": "DERetail001", "customerId": "55c98b8e-1100-497c-8df6-4b4f0353ab2a", "externalCustomerNumber": "C1756793", "channel": { "code": "USRTL" }, "type": "directShip", "routeType": "standardDirectShip", "status": "new", "sequenceId": 1, "expedited": true, "subTotal": 0, "taxAmount": 0, "tax2Amount": 0, "shippingTotal": 1, "total": 1, "localeCode": "example", "currencyCode": "EUR", "notes": "Please wrap each item individually.", "specialInstructions": "House behind the dumpster", "fulfillmentOrderAddress": { "orderIndex": 1, "type": "pickup", "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", "additionalFields": { "dhlPostBoxNumber": "example", "dhlPostNumber": "example" }, "phone": "+49 12345 6789 001", "fax": "+49 12345 6789 002", "mobile": "+49 12345 6789 003", "emailAddress": "max.muster@shopgate.com" }, "fulfillments": [ { "status": "open", "carrier": "DHL", "serviceLevel": "sameDay", "tracking": "JJD000390007882823450", "fulfillmentPackages": [ { "status": "open", "serviceLevel": "sameDay", "package": "small", "fulfilledFromLocationCode": "DERetail001", "weight": 2000, "weightUnit": "g", "dimensions": { "length": 25, "lengthUnit": "mm", "width": 17.5, "widthUnit": "mm", "height": 10, "heightUnit": "mm" }, "tracking": "JJD000390007882823450", "pickUpBy": "Kim Muster", "labelUrl": "https://documentserver.internal/label/label.pdf", "labelType": "pdf", "fulfillmentDate": "2026-04-15T12:00:00Z", "packageItems": [ { "salesOrderLineItemCode": "386", "quantity": 1 } ] } ] } ], "lineItems": [ { "salesOrderLineItemCode": "386", "lineItemGroupId": "386-1", "sku": "1337-hoodie-dark-green", "quantity": 1, "status": "new", "currencyCode": "EUR", "price": 79.99, "salePrice": 65.99, "shippingAmount": 1, "unitPromoAmount": 0, "unitDiscountAmount": 0, "taxAmount": 1, "tax2Amount": 1, "taxExempt": false, "discountAmount": 0, "promoAmount": 0, "overrideAmount": 1, "extendedPrice": 72, "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" } } ] }, "substitutionAllowed": true } ], "fulfillmentSlot": { "id": "5_2019-09-03", "date": "2019-09-03", "weekday": "fri", "from": "08:00", "to": "08:59", "status": "active", "orderCount": 10 }, "submitDate": "2019-09-02T09:02:57.733Z", "acceptDate": "2019-09-02T14:02:57.733Z", "readyDate": "2019-09-02T14:03:57.733Z", "completeDate": "2019-09-03T15:02:57.733Z" } ] }'

Create fulfillment orders

Parameters

Path Parameters

merchantCode

required

string

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

Request Body

Media typeapplication/json

object

fulfillmentOrders

required

Array<object>

object

orderNumber

Unique fulfillment order number

string

<= 50 characters

Example

1293747-0001

externalCode

External order id

string

>= 1 characters

Example

000000274

salesOrderNumber

required

string

Example

1293747

locationCode

required

Location code which should fulfill the order

string

Example

DERetail001

customerId

required

Customer identifier

string

Example

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

externalCustomerNumber

A customer number / reference to an external system.

string

Example

C1756793

channel

object

code

required

string

Example

USRTL

type

required

string

Allowed values: directShip BOPIS ROPIS

routeType

required

string

Allowed values: standardDirectShip standardPickup standardReserve

status

string

default: new

Allowed values: new requested accepted inProgress picked packed ready hold checkedIn canceled rejected fulfilled

sequenceId

If not provided it will automatically be set to the highest so far incremented by 1.

integer

expedited

boolean

subTotal

required

number format: float

0

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

shippingTotal

number format: float

total

required

number format: float

localeCode

required

string

>= 2 characters <= 5 characters

currencyCode

required

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

fulfillmentOrderAddress

object

orderIndex

required

number

type

required

string

Allowed values: pickup shipping billing

firstName

required

string

Example

Max

middleName

string | null

Example

René

lastName

required

string

Example

Muster

company

string | null

Example

Shopgate GmbH

address1

If used as shipping address for direct ship, this field is required

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

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

string | null

Example

DE

additionalFields

object

dhlPostBoxNumber

Number of a postbox

string | null

>= 1 characters <= 5 characters

dhlPostNumber

Number of a post

string | null

>= 1 characters <= 10 characters

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

Example

max.muster@shopgate.com

fulfillments

Array<object>

object

status

required

string

Allowed values: open canceled inProgress fulfilled

carrier

string

Example

DHL

serviceLevel

string

Example

sameDay

tracking

string

Example

JJD000390007882823450

fulfillmentPackages

required

Array<object>

object

status

string

default: open

Allowed values: open inProgress readyForPickup inTransit fulfilled canceled

serviceLevel

string

Example

sameDay

package

string

Example

small

fulfilledFromLocationCode

required

string

Example

DERetail001

weight

The actual package weight.

number format: float

Example

2000

weightUnit

string

Allowed values: g lb

dimensions

object

length

number format: float

Example

25

lengthUnit

string

Allowed values: mm cm in

Example

cm

width

number format: float

Example

17.5

widthUnit

string

Allowed values: mm cm in

Example

cm

height

number format: float

Example

10

heightUnit

string

Allowed values: mm cm in

Example

cm

tracking

string

Example

JJD000390007882823450

pickUpBy

string

Example

Kim Muster

labelUrl

string

Example

https://documentserver.internal/label/label.pdf

labelType

string

Allowed values: pdf zpl

fulfillmentDate

The date and time of the package entering status “inTransit” or “fulfilled”.

string format: date-time

packageItems

required

Array<object>

object

salesOrderLineItemCode

required

string

Example

386

quantity

required

number

key

additional properties

any

lineItems

required

Array<object>

>= 1 items

object

salesOrderLineItemCode

required

string

Example

386

lineItemGroupId

Used as a group identifier when single-quantity fulfillment is enabled

null | string

<= 255 characters

Example

386-1

sku

string | null

Example

1337-hoodie-dark-green

quantity

required

number format: float

status

string

Allowed values: new requested accepted rejected canceled picked packed ready hold fulfilled

Example

new

currencyCode

required

string

>= 3 characters <= 3 characters

Example

EUR

price

required

number format: float

Example

79.99

salePrice

number format: float

Example

65.99

shippingAmount

number format: float

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

taxAmount

number format: float

tax2Amount

number format: float

taxExempt

boolean

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

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

substitutionAllowed

Determines if a substitution is allowed for this line item.

boolean

default: true

fulfillmentSlot

object

id

Id of the fulfillment slot

string

Example

5_2019-09-03

date

string format: date

weekday

string

Allowed values: sun mon tue wed thu fri sat

from

Hour and minute of the day where the time should start

string

Example

08:00

to

string

Example

08:59

status

string

Allowed values: active busy inactive

orderLimit

Limit of orders which can be placed in this slot. This value can only be set for the type fulfillmentSlot

number | null

Example

20

Example

{
  "id": "5_2019-09-03",
  "date": "2019-09-03",
  "weekday": "fri",
  "from": "08:00",
  "to": "08:59",
  "status": "active",
  "orderCount": 10
}

submitDate

Date when the order was submitted by the customer

string | null format: date-time

Example

2019-09-02T09:02:57.733Z

acceptDate

Date when the order status was changed to accepted

string | null format: date-time

Example

2019-09-02T14:02:57.733Z

readyDate

Date when the order status was changed to ready

string | null format: date-time

Example

2019-09-02T14:03:57.733Z

completeDate

Date when the order status was changed to completed

string | null format: date-time

Example

2019-09-03T15:02:57.733Z

Responses

201

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"
}