Authentication

Basic Authentication

Please configure your clients to use this authentication method to submit user name and password.

Bearer Token Authentication

To generate a valid JWT, just log into the OMT, inspect the browser cookies and use the value of the cookie called 'OMS_IDENTITY' as JWT. Within a UI-client (e.g., Postman) choose Bearer Token and just type in a valid JSON Web Token (JWT).

Authorization

The permission 'Order status web service' is required to use the GET endpoints and must be assigned to a shop that has a relation to the order.

API Specification

Introduction

OpenAPI Version: 3.0.1

IOM Order State REST API Version: 1.0

The IOM Order State REST API supports the obtaining of order details and order status information.

Order State Service API

/states

GET: Get orders states by search criteria Deprecated.

Description

Deprecated for removal. Use the Order REST API instead.
Obtain the order states of the orders which are matching the given search criterias

Request Body

Request Parameters

Location	Name	Format	Default	Example	Description
in query	shopId	integer `int64`		`200`	Required \| The id of the IOM shop instance
in query	orderNumber	array		`2019-17891 \| 2019-21432`	Order number as used by the shop
in query	customerNumber	array		`CUST-930293 \| 283102`	Customer number as used by the shop
in query	productNumber	array		`100120 \| 200230`	Product number as used by the shop
in query	orderState	array		`[STATE_COMMISSIONED, STATE_DISPATCHED]`	Order state as used by the shop if configured, otherweise the IOM internal names of order states
in query	orderCreationDate[gte]	string `date`		`2019-01-31T00:00:00.000Z`	The earliest 'shop order creation date' of an order
in query	orderCreationDate[lte]	string `date`		`2019-10-31T00:00:00.000Z`	The latest 'shop order creation date' of an order
in query	orderBy	string
in query	sortDirection	string	`ASC`
in query	offset	integer `int32`	`0`	`50`	The starting row (index) of the first element to return
in query	limit	integer `int32`	`50`	`25`	The number of items to return

Response

200 - OK

OrderStateReport application/vnd.intershop.order-state.v1+json

400 - Bad Request

ErrorReport application/json

401 - Unauthorized Authentication information is missing or invalid

403 - Forbidden

406 - Not Acceptable

500 - Internal Server Error An unexpected error occured

Request and Response Object Schemata

ErrorReport application/json

{

"status":
integer
The HTTP status code applicable to this problem, expressed as a string value | Format: int32 | Example: 400
"errors":
array
An array of Error objects.
[
Error
{
- "code":
  string
  Required | Exception / Error code | Example: VALIDATION_EXCEPTION
- "message":
  string
  Required | Exception / Error message | Example: Attribute XYZ is mandatory
- "value":
  object
  Value which caused the exception / error
}
]

}

OrderStateReport application/vnd.intershop.order-state.v1+json

{

"data":
array
An array of OrderStateOrder objects.
[
OrderStateOrder: Information about the order
{
- "state":
  string
  Required | State of the order - shop-specific name if configured, otherwise the IOM internal name of the state | Example: STATE_DISPATCHED
- "invoiceAddressId":
  integer
  Id of the invoice / billing address. This references the id of an OrderStateAddress at addresses | Format: int64
- "shop":
  object
  Required | A OrderStateShop object. Shop related information of an order
  {
  "name":
  string
  Required | Name of shop / channel | Example: Demo-Shop
  "orderCreationDate":
  string
  Required | Order creation date at the shop system. Note: Conform to the ISO 8601 format. | Format: date-time | Example: 2019-09-14T14:22:32.123Z
  "orderNumber":
  string
  Order number as used by the shop | Example: 2019-089013
  "customerNumber":
  string
  Customer number as used by the shop | Example: CUST-0815
  "companyNumber":
  string
  Company number as used by the shop. The company will be the receiver of the order. | Example: CP7411
  "invoiceNumbers":
  array
  An array of string literals. Invoice numbers belonging to the order | Example: 2716000126
  }
- "customer":
  object
  Required | A OrderStateCustomer object. Information about the customer of the order. A customer can be a person or a company with a contact person.
  {
  "contact":
  object
  A OrderStateContact object. Contact information
  {
  "email":
  string
  Required | Email address
  "telephone":
  string
  Phone number
  "mobile":
  string
  Mobile phone number
  "fax":
  string
  Fax number
  }
  "orderNumber":
  string
  Order number as used by the shop customer | Example: BST:09037
  "type":
  string
  Possible Values: PERSONCOMPANY
  }
- "sales":
  object
  A OrderStateSales object. Sales prices of an order
  {
  "paymanetMethod":
  string
  Payment method of the order - shop-specific name if configured, otherwise the IOM internal name of the payment | Example: CREDITCARD
  "currency":
  string
  Currency of the order - ISO 4217 code | Example: EUR
  "sum":
  object
  A OrderStateSumPrice object. Sum of prices
  {
  "netAmount":
  number
  Net amount | Example: 42.1
  "grossAmount":
  number
  Gross amount | Example: 47.6
  "tax":
  array
  An array of OrderStateTax objects.
  [
  OrderStateTax: VAT (value added tax) by type of VAT
  {
  "type":
  string
  Required | Type of tax - shop-specific name if configured, otherwise the IOM internal name of the tax type | Example: FullTax
  "amount":
  number
  Required | Tax amount | Example: 1.7
  }
  ]
  }
  "total":
  object
  A OrderStateSumPrice object. Sum of prices
  {
  "netAmount":
  number
  Net amount | Example: 42.1
  "grossAmount":
  number
  Gross amount | Example: 47.6
  "tax":
  array
  An array of OrderStateTax objects.
  [
  OrderStateTax: VAT (value added tax) by type of VAT
  {
  "type":
  string
  Required | Type of tax - shop-specific name if configured, otherwise the IOM internal name of the tax type | Example: FullTax
  "amount":
  number
  Required | Tax amount | Example: 1.7
  }
  ]
  }
  "charges":
  array
  An array of OrderStateSalesCharge objects. Charges / fees including delivery etc.
  [
  OrderStateSalesCharge: Charge of an order
  {
  "type":
  string
  Required | Type of charge / fee - shop-specific name if configured, otherwise the IOM internal name of the charge type | Example: DELIVERYCHARGE
  "tax":
  object
  A OrderStateTax object. VAT (value added tax) by type of VAT
  {
  "type":
  string
  Required | Type of tax - shop-specific name if configured, otherwise the IOM internal name of the tax type | Example: FullTax
  "amount":
  number
  Required | Tax amount | Example: 1.7
  }
  "netAmount":
  number
  Net amount | Example: 5
  "grossAmount":
  number
  Gross amount | Example: 6.7
  }
  ]
  }
- "positions":
  array
  Required | An array of OrderStateOrderPostion objects.
  [
  OrderStateOrderPostion: Order position / line item
  {
  "number":
  string
  Required | Order position number as used by the shop | Example: 1
  "state":
  string
  Required | State of order position - shop-specific name if configured, otherwise the IOM internal name of the state | Example: STATE_DO_APPROVE
  "shipToAddressId":
  integer
  Id of the shipping address. This references the id of an OrderStateAddress at addresses | Format: int64 | Example: 10497
  "product":
  object
  Required | A OrderStateOrderPostionProduct object. Product information of an order position / line item
  {
  "name":
  string
  Required | Short name of the product | Example: Demo Product
  "productNumber":
  string
  Required | Shop specific product number, if not available the the IOM internal product number | Example: 100-0001
  "ean":
  string
  International Article Number (also known as European Article Number or EAN) | Example: 9783161484100
  "isbn":
  string
  International Standard Book Number | Example: 978-3-16-148410-0
  "supplierProductNumber":
  string
  Product number as used by the supplier | Example: 902312a
  }
  "supplier":
  object
  A OrderStateOrderPostionSupplier object. Supplier specific information of the order position
  {
  "name":
  string
  Required | Name of the supplier as used by the shop | Example: Demo Supplier US
  "commissionDate":
  string
  Timestamp indicating when the order position was commissioned to the supplier | Format: date-time | Example: 2019-05-28T12:36:17.158Z
  }
  "ordered":
  object
  A OrderStateOrderPositionOrdered object. Ordered details of an order position
  {
  "quantity":
  integer
  Required | Ordered quantity | Example: 1
  "deliveryDays":
  integer
  Required | Expected availability of ordered product in days | Example: 0
  "sales":
  object
  A OrderStateOrderPositionPrice object. Order position price
  {
  "sum":
  object
  Required | A OrderStateOrderPositionPricePosPrice object. Price detailed
  {
  "netAmount":
  number
  Net price | Example: 10.2
  "grossAmount":
  number
  Gross price including VAT (value added tax) | Example: 12.99
  "tax":
  object
  A OrderStateTax object. VAT (value added tax) by type of VAT
  {
  "type":
  string
  Required | Type of tax - shop-specific name if configured, otherwise the IOM internal name of the tax type | Example: FullTax
  "amount":
  number
  Required | Tax amount | Example: 1.7
  }
  }
  "unit":
  object
  Required | A OrderStateOrderPositionPricePosPrice object. Price detailed
  {
  "netAmount":
  number
  Net price | Example: 10.2
  "grossAmount":
  number
  Gross price including VAT (value added tax) | Example: 12.99
  "tax":
  object
  A OrderStateTax object. VAT (value added tax) by type of VAT
  {
  "type":
  string
  Required | Type of tax - shop-specific name if configured, otherwise the IOM internal name of the tax type | Example: FullTax
  "amount":
  number
  Required | Tax amount | Example: 1.7
  }
  }
  }
  "delivery":
  object
  Required | A OrderStateOrderPositionOrderedDelivery object. Kind of delivery
  {
  "type":
  string
  Possible Values: STANDARDFIXED_DELIVERY_DATEEARLIEST_DELIVERY_DATEEXPRESS
  }
  "deliveryOptions":
  array
  An array of string literals. Extra delivery conditions - shop-specific name if configured, otherwise the IOM internal name | Example: Delivery on same day
  }
  "confirmed":
  object
  A OrderStateOrderPositionConfirmed object. Confirmed / available products of an order position
  {
  "type":
  string
  Required | Type of confirmation of supplier - shop-specific name if configured, otherwise the IOM internal name of the response state
  "confirmationDate":
  string
  Required | Date of confirmation of supplier | Format: date-time
  "quantities":
  array
  An array of OrderStateOrderPositionConfirmedQuantity objects. Confirmed quantities
  [
  OrderStateOrderPositionConfirmedQuantity: Confirmed quantity related to 'plannedDeliveryDate' of available products
  {
  "value":
  integer
  Required | Quantity related to the planned delivery date | Format: int32 | Example: 1
  "plannedDeliveryDate":
  string
  Planned delivery date | Format: date
  }
  ]
  "cancelled":
  array
  An array of OrderStateOrderPositionConfirmedCancelled objects. Product(s) not available - already cancelled or recalled
  [
  OrderStateOrderPositionConfirmedCancelled: Confirmed cancelled products / products not available
  {
  "quantity":
  integer
  Required | Cancelled quantity | Format: int32 | Example: 1
  "cancelDate":
  string
  Date of cancellation / recall | Format: date-time
  "reason":
  object
  A OrderStateOrderPositionConfirmedCancelledReason object. Cancellation reason
  {
  "id":
  string
  Required | Code of reason of cancellation / recall | Example: RCL021
  "value":
  string
  Reason of cancellation / recall (free text)
  }
  }
  ]
  }
  "dispatched":
  array
  An array of OrderStateOrderPositionDispatched objects. Information about delivered products
  [
  OrderStateOrderPositionDispatched: Already shipped / delivered products of an order position
  {
  "quantity":
  integer
  Required | Dispatched quantity | Format: int32 | Example: 1
  "deliveryNoteNumber":
  string
  Delivery note number | Example: 980392-481
  "dispatchDate":
  string
  Required | Timestamp of the hand over of the package to the carrier | Format: date-time
  "carrier":
  object
  A OrderStateOrderPositionDispatchedCarrier object. Carrier of the shipment
  {
  "name":
  string
  Required | Shop-specific name of the carrier | Example: DHL
  "packages":
  integer
  Required | Number of packages | Format: int32 | Example: 1
  "shipmentTracking":
  object
  A OrderStateOrderPositionDispatchedCarrierTracking object. Tracking information of the shipment
  {
  "number":
  string
  Required | Tracking number of the package | Example: 929-912-03013
  "url":
  string
  Tracking URL | Format: uri
  }
  }
  "units":
  array
  An array of OrderStateOrderPositionDispatchedUnit objects. There are further information for each single product
  [
  OrderStateOrderPositionDispatchedUnit: Further information (serial number) for each single product
  {
  "serialNumber":
  string
  Required | Serial number of the product | Example: 89712007
  }
  ]
  }
  ]
  "returned":
  array
  An array of OrderStateOrderPositionReturned objects. Information about returned products
  [
  Either OrderStateOrderPositionReturnedQuantities: Combined / quantity based return informationen of an order position
  {
  "state":
  string
  Required | State of the return - shop-specific name if configured, otherwise the IOM internal name of the return state | Example: CLOSED
  "supplierEntryDate":
  string
  Timestamp of the entry of the return at the supplier | Format: date-time
  "quantity":
  integer
  Required | Number of returned products of the related order position | Format: int32 | Example: 2
  "returnReason":
  object
  A OrderStateOrderPositionReturnedReason object. Return reason
  {
  "value":
  string
  Required | The return reason - shop-specific name if configured, otherwise the IOM internal name of the return reason | Example: RET990
  "type":
  string
  Required | The return type of the reason - shop-specific name if configured, otherwise the IOM internal name of the return type | Example: RET
  }
  "payment":
  object
  A OrderStateOrderPositionReturnedReturnPayment object. Return payment
  {
  "reduction":
  object
  Required | A OrderStateOrderPositionReturnedReturnPaymentReduction object. Reason / class for price reduction
  {
  "reduceText":
  string
  Required | Reduction reason (from supplier) as text
  "reduceReason":
  string
  Required | Name of reduction class as used by the shop | Example: AK-0
  }
  "refundNet":
  number
  Required | Net amount of refund | Example: 12.87
  }
  }
  Or OrderStateOrderPositionReturnedUnits: Unit /separately based return informationen of an order position
  {
  "state":
  string
  Required | State of the return - shop-specific name if configured, otherwise the IOM internal name of the return state | Example: CLOSED
  "supplierEntryDate":
  string
  Timestamp of the entry of the return at the supplier | Format: date-time
  "units":
  array
  Required | An array of OrderStateOrderPositionReturnedUnitsUnit objects. Information about return of individual products
  [
  OrderStateOrderPositionReturnedUnitsUnit: Return information for a single product
  {
  "serialNumber":
  string
  Required | Serial number of single item / product | Example: 9834JJ-43
  "returnReason":
  object
  A OrderStateOrderPositionReturnedReason object. Return reason
  {
  "value":
  string
  Required | The return reason - shop-specific name if configured, otherwise the IOM internal name of the return reason | Example: RET990
  "type":
  string
  Required | The return type of the reason - shop-specific name if configured, otherwise the IOM internal name of the return type | Example: RET
  }
  "payment":
  object
  A OrderStateOrderPositionReturnedReturnPayment object. Return payment
  {
  "reduction":
  object
  Required | A OrderStateOrderPositionReturnedReturnPaymentReduction object. Reason / class for price reduction
  {
  "reduceText":
  string
  Required | Reduction reason (from supplier) as text
  "reduceReason":
  string
  Required | Name of reduction class as used by the shop | Example: AK-0
  }
  "refundNet":
  number
  Required | Net amount of refund | Example: 12.87
  }
  }
  ]
  }
  ]
  "properties":
  array
  An array of OrderStatePropertyGroup objects. Additional attributes / properties of the order position
  [
  OrderStatePropertyGroup: Additional attributes / properties
  {
  "id":
  string
  Required | Identifier of the property group | Example: Customer-Information
  "properties":
  array
  An array of OrderStateProperty objects. A list of properties / key-value pairs
  [
  OrderStateProperty: Property as key-value pair
  {
  "key":
  string
  Key of the property
  "value":
  string
  Value of the property
  }
  ]
  }
  ]
  }
  ]
- "notes":
  array
  An array of OrderStateOrderNote objects. Notes regarding the order
  [
  OrderStateOrderNote: Order note
  {
  "message":
  string
  Required | Content of the note | Example: Unsatisfied customer
  "type":
  string
  Type of note - shop-specific name if configured, otherwise the IOM internal name of the order node | Example: ESCALATION
  "creationDate":
  string
  Creation date of the note | Format: date-time | Example: 2019-10-28T07:22:44.838Z
  }
  ]
- "payment":
  object
  A OrderStatePayment object. Payment status and history information of an order
  {
  "paymentStatus":
  object
  A OrderStatePaymentStatus object. Payment status of an order
  {
  "invoicingDebitAmount":
  number
  Required | Amount of all invoices for this order
  "invoicingCreditAmount":
  number
  Required | Amount of all credit notes for this order
  "chargedDebitAmount":
  number
  Required | Amount of all captured amounts for this order
  "chargedCreditAmount":
  number
  Required | Amount of all refunded amounts for this order
  "chargedOpenAmount":
  number
  Required | Positive amount: amount of open refunds - Negative amount: amount of open captures
  "bookedDebitAmount":
  number
  Required | Amount of all inbound payments for this order
  "bookedCreditAmount":
  number
  Required | Amount of all outbound payments for this order
  "bookedOpenAmount":
  number
  Required | Positive amount: amount of open outbound payments - Negative amount: amount of open inbound payments
  "creationDate":
  string
  Required | Creation date of the payment status | Format: date-time | Example: 2019-12-28T17:46:49.838Z
  "lastCaptureDate":
  string
  Date of the last payment capture | Format: date-time | Example: 2019-12-10T20:16:23.838Z
  "lastRefundDate":
  string
  Date of the last refund | Format: date-time | Example: 2019-12-28T17:46:49.838Z
  "lastCalculationDate":
  string
  Required | Date of last calculation of the payment status | Format: date-time | Example: 2019-11-28T17:46:49.838Z
  "currency":
  string
  Required | Currency of balance amounts - ISO 4217 code | Example: EUR
  }
  "paymentHistory":
  array
  An array of OrderStatePaymentHistoryItem objects. Payment history
  [
  OrderStatePaymentHistoryItem: Payment history item of an order
  {
  "currency":
  string
  Required | Currency - ISO 4217 code | Example: EUR
  "comment":
  string
  Payment comment
  "type":
  string
  Required | Payment notification type: inbound, outbound, action | Example: inbound
  "action":
  string
  Required | Payment action: authorization, reverse, capture, refund | Example: capture
  "paymentMethod":
  string
  Required | Payment method - shop-specific name if configured, otherwise the IOM internal name of the payment | Example: CREDITCARD
  "invoiceNumber":
  string
  Invoice number, if the item relates to an invoice
  "creationDate":
  string
  Required | Payment notification creation date | Format: date-time | Example: 2019-12-28T17:46:49.838Z
  "modificationDate":
  string
  Required | Payment notification modification date | Format: date-time | Example: 2019-12-28T17:46:49.838Z
  "amount":
  number
  Required | Amount | Example: 109.78
  }
  ]
  }
- "documents":
  array
  An array of OrderStateDocument objects. The order related documents as download links
  [
  OrderStateDocument: A download link of an order related document
  {
  "type":
  string
  Required | The type / kind of the document | Example: invoiceNote
  "downloadLink":
  string
  Required | The URI to get the document | Format: uri | Example: http://localhost:8080/servlets/DocumentServlet/v1.0/invoiceNote/InvoiceNote.pdf?k=10218224f70ffdbdfd5d18603ce53424788fe859425056b7e9e058bd94c2410e2e05c43f847fa2dc9cb1fabbc5ae1a899e1f5ec9c93422aa529ecfda79171ed92626c&i=10218&s=200"
  "creationDate":
  string
  Document creation date. Note: Conform to the ISO 8601 format. | Format: date-time | Example: 2018-12-24T14:22:32.123Z
  "mimeType":
  string
  The MIME-type of the document | Example: application/pdf
  }
  ]
- "properties":
  array
  An array of OrderStatePropertyGroup objects. Additional attributes / properties of the order
  [
  OrderStatePropertyGroup: Additional attributes / properties
  {
  "id":
  string
  Required | Identifier of the property group | Example: Customer-Information
  "properties":
  array
  An array of OrderStateProperty objects. A list of properties / key-value pairs
  [
  OrderStateProperty: Property as key-value pair
  {
  "key":
  string
  Key of the property
  "value":
  string
  Value of the property
  }
  ]
  }
  ]
- "addresses":
  array
  An array of OrderStateAddress objects. Order related addresses
  [
  Either OrderStatePostalAddress: Postal address
  {
  "id":
  integer
  Required | Id of the address. This will be referenced in OrderStateOrderPostion 'shipToAddressId' and OrderStateOrder 'invoiceAddressId' | Format: int64 | Example: 10496
  "type":
  string
  Type of address - shop-specific name if configured, otherwise the IOM internal name of the address type. Note: A BILLING address can also be used as SHIPPING address. | Example: BILLING
  "contact":
  object
  A OrderStateContact object. Contact information
  {
  "email":
  string
  Required | Email address
  "telephone":
  string
  Phone number
  "mobile":
  string
  Mobile phone number
  "fax":
  string
  Fax number
  }
  "location":
  object
  Required | A OrderStateAddressLocation object. Location of the address
  {
  "city":
  string
  Required | City | Example: Jena
  "postCode":
  string
  Required | Postal code | Example: 07740
  "district":
  string
  District
  "country":
  string
  Required | ISO 3166-1 alpha-3 country code | Example: DEU
  "additions":
  array
  An array of string literals. Additions to address
  }
  "receiver":
  object
  Required | A OrderStateAddressReceiver object. A receiver can be a natural person or a company
  {}
  }
  Or OrderStateImmaterialAddress: Information about the digital / non-physical shippings
  {
  "id":
  integer
  Required | Id of the address. This will be referenced in OrderStateOrderPostion 'shipToAddressId' and OrderStateOrder 'invoiceAddressId' | Format: int64 | Example: 10496
  "type":
  string
  Type of address - shop-specific name if configured, otherwise the IOM internal name of the address type 'IMMATERIAL' | Example: IMMATERIAL
  "value":
  string
  Required
  "kind":
  string
  Required | Kind of the immaterial address - delivery via email or mobile / cell phone | Example: EMAIL | Possible Values: EMAILMOBILEOTHER
  }
  ]
}
]
"meta":
object
Meta-information e.g. 'totalCount'
"links":
object
Link section

}

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.