Skip to content
ShopgateShopgateShopgate Documentation

Get sales orders

GET
/merchants/{merchantCode}/orders
curl --request GET \
  --url 'https://order.shopgate.io/v1/merchants/example/orders?includeInternalIds=false&limit=100&offset=0'

Get sales orders

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
merchantCode
required
string

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

Query Parameters

Section titled “Query Parameters”
filters
string

Filter string. Supported filters: id, orderNumber, externalCode, name, customerId, contactType, status, date, submitDate, updateDate, fulfillDate, completeDate, fulfillmentStatus

fields
string format: csv

Available fields: lineItems

includeInternalIds
boolean

The entity gets extended with the internal ID of Shopgate, this query cannot be used by external clients.

limit
integer format: int32
default: 100 <= 100

Items per page, for pagination, default is 10, max is 100

offset
integer format: int32
0

Offset for pagination, default is 0

Responses

Section titled “Responses”

200

Section titled “200”

Return sales orders

Media typeapplication/json
object
orders
Array
object
orderNumber

Number of the Order. Its need to be unique in the system

string
shopCode

Code of the source shop.

string
externalCode

External order id

string
>= 1 characters
type
string
default: standard
Allowed values: standard
customerId

Customer identifier

string
externalCustomerNumber

A customer number / reference to an external system.

string
status
string
Allowed values: new open rejected canceled ready fulfilled completed inProgress
expedited

Indicates if the order needs to be threated expediently

boolean
localeCode
string
>= 2 characters <= 5 characters
currencyCode
string
>= 3 characters <= 3 characters
taxExempt
boolean
notes

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

string | null
<= 1000 characters
specialInstructions

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

string | null
data
object
fulfillmentStatus
string
Allowed values: open inProgress completed actionRequired
primaryBillToAddressSequenceIndex

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

number
primaryShipToAddressSequenceIndex

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

number
addressSequences
Array<object>
object
type
string
Allowed values: pickup shipping billing
customerContactId
string | null
firstName
string
middleName
string | null
lastName
string
companyName
string | null
address1
string | null
address2
string | null
address3
string | null
address4
string | null
city
string | null
region
string | null
postalCode
string | null
country

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

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

Validated according to country code

string | null
mobile

Validated according to country code

string | null
emailAddress
string | null format: email
orderSegment
object
selectedShippingMethod
object
code
string
name
string
serviceLevel
object
code
string
name
string
cost
number format: float
iconUrl
string
carrier
object
code
string
name
string
availableShippingMethods

Contains all shipping method which are available fro this order segment. This property is only set if the order was not placed yet and is in the new status

Array<object>
object
code
string
name
string
serviceLevels
Array<object>
object
code
string
name
string
cost
number format: float
iconUrl
string
carrier
object
code
string
name
string
subTotal

Subtotal of the order

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
promoAmount
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
shippingSubTotal

Shipping total without any discounts. Its based on the line items in the order

number format: float
shippingDiscountAmount

Sum of discounts applied to the shipping total

number format: float
shippingPromoAmount
number format: float
shippingTotal

Shipping total including all discounts

number format: float
taxSummary
Array<object>
object
code
string
name
string
amount
number
total

Total sum of the order including tax, shipping and discounts

number format: float
date

Date of the order when it was created in the Shopgate system

string format: date-time
submitDate

Date when the order was submitted by the customer

string | null format: date-time
fulfillDate

Date when the order status was changed to fulfilled

string | null format: date-time
completeDate

Date when the order status was changed to completed

string | null format: date-time
sourceIp

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

string
userAgent

The UserAgent string from headers of the incoming request.

string | null
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,})$/
platform

The platform from which the order came.

string
Allowed values: engage desktop mobile checkoutPage inStoreApp other
os

Operation system of the source device

string
Allowed values: ios android other
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
campaignAttribution

Campaign the order should be attributed to

object
campaignCode
required
string
channel
required
string
distributionIndex
required
number
lineItemCount
number
lineItems
Array<object>
object
id

Line Item id of the item to update. In case of an insert this field is not required

number
status
string
Allowed values: new requested accepted rejected canceled picked packed ready hold fulfilled
quantity
number
returnQuantity
number
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
product
object
code
string
meta
object
limit
number
offset
number
totalItemCount
number
Example
{
  "orders": [
    {
      "orderNumber": "1293747",
      "shopCode": "shop_12345",
      "externalCode": "000000274",
      "type": "standard",
      "customerId": "55c98b8e-1100-497c-8df6-4b4f0353ab2a",
      "externalCustomerNumber": "C1756793",
      "status": "new",
      "expedited": false,
      "localeCode": "de-de",
      "currencyCode": "EUR",
      "taxExempt": false,
      "notes": "Some note",
      "specialInstructions": "House behind the dumpster",
      "data": {},
      "fulfillmentStatus": "open",
      "primaryBillToAddressSequenceIndex": 0,
      "primaryShipToAddressSequenceIndex": 0,
      "addressSequences": [
        {
          "type": "shipping",
          "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",
          "additionalFields": {
            "dhlPostBoxNumber": 12345,
            "dhlPostNumber": 1234567890
          },
          "phone": "+49 12345 6789 001",
          "fax": "+49 12345 6789 002",
          "mobile": "+49 12345 6789 003",
          "emailAddress": "max.muster@shopgate.com",
          "orderSegment": {
            "selectedShippingMethod": {
              "code": "standardShipping",
              "serviceLevel": {
                "code": "standard",
                "carrier": {
                  "code": "DHL",
                  "name": "DHL International"
                },
                "name": "DHL Standard",
                "cost": 4.99,
                "iconUrl": "https://myserver.com/DHL.png"
              },
              "name": "Standard Shipping"
            },
            "availableShippingMethods": [
              {
                "code": "standardShipping",
                "name": "Standard Shipping",
                "serviceLevels": [
                  {
                    "code": "string",
                    "name": "DHL Standard",
                    "cost": 4.99,
                    "iconUrl": "https://myserver.com/DHL.png",
                    "carrier": {
                      "code": "DHL",
                      "name": "DHL International"
                    }
                  }
                ]
              }
            ]
          }
        }
      ],
      "subTotal": 65.99,
      "discountAmount": 0,
      "promoAmount": 0,
      "taxAmount": 12.54,
      "tax2Amount": 0,
      "shippingSubTotal": 4.99,
      "shippingDiscountAmount": 0,
      "shippingPromoAmount": 0,
      "shippingTotal": 4.99,
      "taxSummary": [
        {
          "code": "default_19",
          "name": "19%",
          "amount": 12.54
        }
      ],
      "total": 70.98,
      "date": "2021-12-16T16:05:21.342Z",
      "submitDate": "2019-09-02T09:02:57.733Z",
      "fulfillDate": "2019-09-03T15:02:32.733Z",
      "completeDate": "2019-09-03T15:02:57.733Z",
      "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",
      "imported": false,
      "campaignAttribution": {
        "campaignCode": "CMP-1",
        "channel": "push",
        "distributionIndex": 0
      },
      "lineItemCount": 1
    }
  ],
  "meta": {
    "limit": 100,
    "offset": 0,
    "totalItemCount": 1
  }
}