Skip to content
ShopgateShopgateShopgate Documentation

Update sales order

POST
/merchants/{merchantCode}/orders/{orderNumber}
curl --request POST \
  --url https://order.shopgate.io/v1/merchants/example/orders/example \
  --header 'Content-Type: application/json' \
  --data '{ "externalCode": "000000274", "notes": "Please wrap each item individually.", "lineItems": [ { "code": "386", "parentLineItemCode": "286", "status": "open", "subStatus": "replaced", "quantity": 1, "routedQuantity": 1, "fulfillmentMethod": "directShip", "fulfillmentLocationCode": "DERetail001", "shipToAddressSequenceIndex": 1, "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", "shippingAmount": 1, "taxAmount": 0, "tax2Amount": 0, "taxExempt": true, "unitPromoAmount": 0, "unitDiscountAmount": 0, "discountAmount": 0, "promoAmount": 0, "overrideAmount": 1, "extendedPrice": 72, "price": 1, "substitutionAllowed": true, "fulfillmentSlot": { "id": "5_2019-09-03", "date": "2019-09-03", "weekday": "fri", "from": "08:00", "to": "08:59", "status": "active", "orderCount": 10 }, "appliedPromotions": [ { "code": "2020summerPromotion", "name": "Summer Promotion for 2020", "model": "simpleDiscount", "description": "This promotion is for our summer coupons", "promotionalText": "This coupons gives you 10% off to celebrate the summer 2020", "status": "active", "startDate": "2020-07-01T00:00:000", "endDate": "2020-07-01T00:00:000", "target": "order", "type": "coupon", "discount": { "type": "percentage", "amount": 10 }, "conditions": { "$and": [ { "subTotal": { "gte": 100 } }, { "$or": [ { "fulfillmentMethod": { "$in": [ "directShip", "BOPIS", "ROPIS" ] } }, { "customer.segment.code": { "$in": [ "employees", "contractors" ] } } ] } ] }, "impact": { "conditions": { "lineItem.product.categoryCode": { "$in": [ "shirts" ] }, "lineItem.quantity": 1 }, "automaticallyAddedToCart": false }, "coupon": { "code": "summer2020", "name": "Coupon 10off for the summer 2020", "limits": { "overall": 10, "maxPerCustomer": null } }, "couponSet": null, "limitConditions": { "maxOverallUsageCount": 100, "maxCustomerUsageCount": 1, "maxUsagePerOrder": 1, "cantBeCombinedWithPromotionCode": { "$in": [ "bogo1" ] } } } ], "replacedLineItemId": 1, "quantityChangeReason": "wrongItem" } ], "specialInstructions": "House behind the dumpster", "data": { "collectedLoyaltyPoints": 10 }, "fulfillmentStatus": "open", "addressSequences": [ { "type": "pickup", "firstName": "Max", "middleName": null, "lastName": "Muster", "mobile": "+49 12345 6789 003", "emailAddress": "max.muster@shopgate.com" }, { "type": "billing", "customerContactId": "0b475af4-7ed9-4065-b4bb-7d76c537d820" }, { "type": "shipping", "firstName": "Max", "middleName": null, "lastName": "Muster", "company": "Awesome Company Inc", "address1": "1234 Main Street", "city": "Butzbach", "region": "HE", "postalCode": "35510", "country": "DE", "mobile": "+49 12345 6789 003", "emailAddress": "max.muster@shopgate.com", "orderSegment": { "selectedShippingMethod": { "code": "express", "serviceLevel": { "code": "express", "carrier": { "code": "DHL" } } } } } ], "paymentTransactions": [ { "externalCode": "pi_GTS8a787uuRMaC86GBxpDABYn", "paymentMethod": { "code": "stripe" }, "authorizedAmount": 1 } ], "primaryBillToAddressSequenceIndex": 0, "primaryShipToAddressSequenceIndex": 1, "status": "new", "sourceIp": "85.45.62.2", "userAgent": "Mozilla/5.0 (Android 4.4; Mobile; rv:41.0) Gecko/41.0 Firefox/41.0", "domain": "www.mydomain.com", "platform": "engage", "os": "ios", "subTotal": 1, "discountAmount": 0, "promoAmount": 0, "shippingSubTotal": 1, "shippingDiscountAmount": 1, "shippingPromoAmount": 1, "shippingTotal": 1, "taxAmount": 0, "tax2Amount": 0, "taxSummary": [ { "code": "default_19", "name": "19%", "amount": 1.5 } ], "total": 1, "customer": { "attributes": [ { "code": "tshirtSize", "value": "L" } ] } }'

Update sales order

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
merchantCode
required
string

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

orderNumber
required
string

Unique order number

Request Body

Section titled “Request Body”
Media typeapplication/json
object
externalCode

External order id

string
>= 1 characters
Example
000000274
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.
lineItems
Array<object>
object
code
required

Identifier for the line item. Needs to be unique within the sales order.

string
Example
386
parentLineItemCode

Identifier for the parent line item. Needs to be unique within the sales order.

string | null
Example
286
status
string
Allowed values: open inProgress rejected canceled fulfilled
Example
inProgress
subStatus
string | null
Allowed values: replaced substituted
Example
null
quantity
number format: float
Example
1
routedQuantity

Sum of this line item in fulfillment orders.

number
Example
1
fulfillmentMethod
string
Allowed values: directShip BOPIS ROPIS
Example
ROPIS
fulfillmentLocationCode
string | null
Example
DERetail001
shipToAddressSequenceIndex

Index of the address in the address sequence array where it should be shipped to

integer
product
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
shippingAmount
number format: float
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
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
price

Price of the line item

number format: float
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
}
appliedPromotions

Applied promotions of the order. If the order is in the status new this parameter will be ignored. The system will automatically calc the promotions for the order

Array<object>
object
code
required
string
Example
2020summerPromotion
name
required
string
Example
Summer Promotion for 2020
model
string
default: simpleDiscount
Allowed values: simpleDiscount BOGO
description
string | null
Example
This promotion is for our summer coupons
promotionalText

Promotional text that will be displayed to the customer

string | null
Example
This coupons gives you 10% off to celebrate the summer 2020
status
string
default: active
Allowed values: active inactive
startDate
required
string | null format: date-time
Example
2020-07-01T00:00:000
endDate
string | null format: date-time
Example
2020-07-01T00:00:000
target
string
default: order
Allowed values: order product orderShipping productShipping
type
string
Allowed values: coupon promotion
Example
coupon
discount
required
object
type
required
string
Allowed values: percentage absolute fixedPrice
amount
required
number format: float
Example
10
conditions
object
Example
{
  "$and": [
    {
      "subTotal": {
        "gte": 100
      }
    },
    {
      "$or": [
        {
          "fulfillmentMethod": {
            "$in": [
              "directShip",
              "BOPIS",
              "ROPIS"
            ]
          }
        },
        {
          "customer.segment.code": {
            "$in": [
              "employees",
              "contractors"
            ]
          }
        }
      ]
    }
  ]
}
impact

Describes the impact of the promotion to specific line items. This only applies to BOGO promotions

object
conditions
required

Condition for products which should be impacted by the promotion This only applies to BOGO promotions.
Available condition fields are:

  • lineItem.product.code
  • lineItem.product.categoryCode
  • lineItem.product.price
  • lineItem.product.salePrice
  • lineItem.product.quantity
  • lineItem.product.options.<optionsCode>
  • lineItem.product.properties.<propertyCode>
The condition lineItem.quantity is always required. It needs to be set in the first level or in the $and condition on the first level
object | null
automaticallyAddedToCart

Indicates if the product which the customer would receive is automatically added to the cart. This only applies if the condition has one rule with a single product code

boolean
Example
{
  "conditions": {
    "lineItem.product.categoryCode": {
      "$in": [
        "shirts"
      ]
    },
    "lineItem.quantity": 1
  },
  "automaticallyAddedToCart": false
}
coupon
object
code
required

Unique coupon code. This code can be used by the end customer to activate a promotion in his cart.

string
Example
summer2020
name
required

Name of the Coupon

string
Example
Coupons 10off
limits
object
overall

Limit for the overall usage of this coupon

number | null
Example
10
maxPerCustomer

Indicates how often this coupon can be used per customer

number | null
Example
1
Example
{
  "code": "summer2020",
  "name": "Coupon 10off for the summer 2020",
  "limits": {
    "overall": 10,
    "maxPerCustomer": null
  }
}
couponSet
object
code
required
string
Example
2020summerSaleCoupons
type
required
string
Allowed values: generated custom
count

Only available and must be set for generated couponSet type.

number
<= 50000
Example
20
name
required
string
Example
All summer sale coupons for 2020
description
string
Example
This coupon set contains all coupons for 2020
prefix
string
Example
summer2020-
suffix
string
Example
-covid
Example
null
limitConditions

Set the limits how often the promotion can be used by a customer and with which other promotion it can be combined. For the field cantBeCombinedWithPromotionCode promotion code(s) can be given or a special code anyProductPromotions|anyOrderPromotions that will exclude any product|order promotion when it gets calculated. Available condition fields are:

  • maxOverallUsageCount
  • maxCustomerUsageCount
  • maxUsagePerOrder (only works for target=product)
  • cantBeCombinedWithPromotionCode
object | null
Example
{
  "maxOverallUsageCount": 100,
  "maxCustomerUsageCount": 1,
  "maxUsagePerOrder": 1,
  "cantBeCombinedWithPromotionCode": {
    "$in": [
      "bogo1"
    ]
  }
}
replacedLineItemId
number | null
quantityChangeReason

Reason for a quantity change. Needs to be set if a new quantity is set. Deprecated reasons:

  • wrongAttribute
  • wrongProduct
  • changedMind
  • brokenOrDamaged
  • outOfStock
string
Allowed values: wrongItem wrongProduct wrongAttribute wrongQuantity changedMind customerCanceled brokenOrDamaged itemDamaged outOfStock outdatedStockInfo unavailable substituted other
specialInstructions

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

string | null
Example
House behind the dumpster
data
object | null
Example
{
  "collectedLoyaltyPoints": 10
}
fulfillmentStatus
string
Allowed values: open inProgress completed actionRequired
addressSequences

If the array is set it will replace all addresses

Array<object>
object
type
required
string
Allowed values: pickup shipping billing
customerContactId

“addressSequences” must include either a “customerContactId” or all of “firstName”, “lastName” and “emailAddress”

string | null
Example
0b475af4-7ed9-4065-b4bb-7d76c537d820
firstName

“addressSequences” must include either a “customerContactId” or all of “firstName”, “lastName” and “emailAddress”

string | null
Example
Max
middleName
string | null
Example
René
lastName

“addressSequences” must include either a “customerContactId” or all of “firstName”, “lastName” and “emailAddress”

string | null
Example
Muster
company
string | null
Example
Shopgate GmbH
address1
string | null
Example
Schloßstr. 10
address2
string | null
Example
Haus B
address3
string | null
Example
erste Etage
address4
string | null
Example
null
city
string | null
Example
Butzbach
region
string | null
Example
HE
postalCode
string | null
Example
"35510"
country

ISO 3166 ALPHA-2 / ISO 3166-2 Country Code

string | null
<= 2 characters
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

“addressSequences” must include either a “customerContactId” or all of “firstName”, “lastName” and “emailAddress”

string | null format: email
Example
max.muster@shopgate.com
orderSegment
object
selectedShippingMethod
object
code
required
string
Example
standardShipping
serviceLevel
required
object
code
required
string
Example
standard
cost
number format: float
Example
4.99
carrier
required
object
code
required
string
Example
DHL
Example
[
  {
    "type": "pickup",
    "firstName": "Max",
    "middleName": null,
    "lastName": "Muster",
    "mobile": "+49 12345 6789 003",
    "emailAddress": "max.muster@shopgate.com"
  },
  {
    "type": "billing",
    "customerContactId": "0b475af4-7ed9-4065-b4bb-7d76c537d820"
  },
  {
    "type": "shipping",
    "firstName": "Max",
    "middleName": null,
    "lastName": "Muster",
    "company": "Awesome Company Inc",
    "address1": "1234 Main Street",
    "city": "Butzbach",
    "region": "HE",
    "postalCode": "35510",
    "country": "DE",
    "mobile": "+49 12345 6789 003",
    "emailAddress": "max.muster@shopgate.com",
    "orderSegment": {
      "selectedShippingMethod": {
        "code": "express",
        "serviceLevel": {
          "code": "express",
          "carrier": {
            "code": "DHL"
          }
        }
      }
    }
  }
]
paymentTransactions
Array<object>
object
externalCode

External identifier for this transaction

string
Example
pi_GTS8a787uuRMaC86GBxpDABYn
paymentMethod
object
code
string
Example
stripe
authorizedAmount

Originally authorized amount

number
primaryBillToAddressSequenceIndex

Position in the AddressSequences-Array, mandatory for all fulfillment methods that include billing like directShip and BOPIS

number
Example
0
primaryShipToAddressSequenceIndex

Position in the AddressSequences-Array, mandatory for all fulfillment methods that include shipping like directShip

number
Example
1
status
string
Allowed values: new open rejected canceled ready fulfilled completed inProgress
sourceIp

IP address from the client where the order was placed. It can be a IPv4 or IPv6 address

string
Example
85.45.62.2
userAgent

The UserAgent string from headers of the incoming request.

string | null
Example
Mozilla/5.0 (Android 4.4; Mobile; rv:41.0) Gecko/41.0 Firefox/41.0
domain

The domain from which order came.

string | null
/^(((?!-))(xn--|_{1,1})?[a-z0-9-]{0,61}[a-z0-9]{1,1}\.)*(xn--)?([a-z0-9][a-z0-9\-]{0,60}|[a-z0-9-]{1,30}\.[a-z]{2,})$/
Example
www.mydomain.com
platform

The platform from which the order came.

string
Allowed values: engage desktop mobile checkoutPage inStoreApp other
Example
engage
os

Operation system of the source device

string
Allowed values: ios android other
Example
ios
subTotal
number format: float
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
shippingSubTotal
number format: float
shippingDiscountAmount
number format: float
shippingPromoAmount
number format: float
shippingTotal
number format: float
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
taxSummary
Array<object>
object
code
string
Example
default_19
name
string
Example
19%
amount
number
Example
1.5
total
number format: float
customer

Updates the given attribute for the newly created anonymous customer

object
attributes
Array<object>

Custom customer attribute

object
code
required

Code of the defined customer attribute

string
Example
tshirtSize
value

Value for this attribute. Its a free text field for attributes where no values are set. Attributes which have value set should contains the code in an object. For instance value: { "code": "fish" }

Example
L

Responses

Section titled “Responses”

204

Section titled “204”

Sales order updated

Media typeapplication/json

400

Section titled “400”

Validation failed

Media typeapplication/json
object
errors
Array<object>
object
entityIndex
number
entity
string
entityId
string
code
number
message
string
subentityPath
Array<string | null | number>
Examplegenerated
{
  "errors": [
    {
      "entityIndex": 1,
      "entity": "example",
      "entityId": "example",
      "code": 1,
      "message": "example",
      "subentityPath": [
        "example"
      ]
    }
  ]
}