Reference - IOM REST API - Order State 1.0


Product Version

2.15

Product To Version


Status

final

Download Specification 

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

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

GET
/states Get orders states by search criteria

Request Path

/states

Description

Obtain the order states of the orders which are matching the given search criterias

Request Body

--

Request Parameters

LocationNameFormatDescription
in queryshopIdintegerRequired | The id of the IOM shop instance | Format: int64 | Example: 200
in queryorderNumberarrayOrder number as used by the shop | Example: ["2019-17891","2019-21432"]
in querycustomerNumberarrayCustomer number as used by the shop | Example: ["CUST-930293","283102"]
in queryproductNumberarrayProduct number as used by the shop | Example: [100120,200230]
in queryorderStatearrayOrder state as used by the shop if configured, otherweise the IOM internal names of order states | Example: [STATE_COMMISSIONED, STATE_DISPATCHED]
in queryorderCreationDate[gte]stringThe earliest 'shop order creation date' of an order | Format: date | Example: 2019-01-31T00:00:00.000Z
in queryorderCreationDate[lte]stringThe latest 'shop order creation date' of an order | Format: date | Example: 2019-10-31T00:00:00.000Z
in queryorderBystring
in querysortDirectionstringDefault: ASC
in queryoffsetintegerThe starting row (index) of the first element to return | Format: int32 | Example: 50 | Default: 0
in querylimitintegerThe number of items to return | Format: int32 | Example: 25 | Default: 50

Response

200 - OK

OrderStateReport application/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
      Required | Shop related information | Format: int64
    • "shop":
      object
      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
        [
        OrderStateOrderPositionReturned: Information about returned products Can be one of the following object types: OrderStateOrderPositionReturnedQuantities, OrderStateOrderPositionReturnedUnits.
        {
        • "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
        }
        ]
      • "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. Id of the invoice / billing address. This references the id of an OrderStateAddress at addresses
      [
      OrderStateAddress: Order related address
      {
      • "id":
        integer
        Required | Id of the address. This will be referenced in OrderStateOrderPostion 'shipToAddressId' and OrderStateOrder 'invoiceAddressId' | Format: int64 | Example: 10496
      • "type":
        string
      }
      ]
    }
    ]
  • "meta":
    object
    Meta-information e.g. 'totalCount'
  • "links":
    object
    Link section
}

400 - Bad Request

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

401 - Unauthorized

Authentication information is missing or invalid

403 - Forbidden

406 - Not Acceptable

500 - Internal Server Error

An unexpected error occured

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.

Customer Support
Knowledge Base
Product Resources
Support Tickets