This API specification is available for download as an Open API 3.0 YAML file:
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
/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
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
}
"orderNumber":
string
Order number as used by the shop customer | Example: BST:09037
"type":
string
Possible Values: PERSON
COMPANY
}
"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: STANDARD
FIXED_DELIVERY_DATE
EARLIEST_DELIVERY_DATE
EXPRESS
}
"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
}
"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
"kind":
string
Required | Kind of the immaterial address - delivery via email or mobile / cell phone | Example: EMAIL
| Possible Values: EMAIL
MOBILE
OTHER
}
]
}
]
"meta":
object
Meta-information e.g. 'totalCount'
"links":
object
Link section
}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.