Typical OMS integrations | Magento Order Management Documentation

This section explains typical integrations you can find in your Order Management System (OMS). For specific information on the messages, check the Specifications topic.

Order New

Topic: magento.sales.order_management.create

Header: (need to add “to” in the headers with value*)

The Create Order Commands are sent by the Sales Channel to Magento OMS when a purchase is completed. The order information will include information about order lines, payments if available and shipping method. The addresses need to be referenced from the payment and order lines nodes.

See the below example for more information.

JSON example

{
    "order": {
        "id": "000000063",
        "store": "CLIENT",
        "ip": "172.17.0.2",
        "language": "es_MX",
        "vat_country": "MX",
        "origin": "FRONTEND",
        "origin_date": "2016-08-17T09:25:48+00:00",
        "customer_service_agent": "",
        "customer": {
            "id": "1",
            "type": "REGISTERED",
            "segment": "B2C"
        },
        "addresses": [{
            "reference": "104",
            "address_type": "customer",
            "first_name": "Christophe",
            "last_name": "Trichet",
            "address1": "6 Championship Dr",
            "address2": "",
            "city": "Auburn Hills",
            "state": "Michigan",
            "zip": "48326",
            "country_code":  "US",
            "phone": "123456789",
            "email": "1469095459@example.com"
        }, {
            "reference": "103",
            "address_type": "customer",
            "first_name": "Christophe",
            "last_name": "Trichet",
            "address1": "6 Championship Dr",
            "address2": "",
            "city": "Auburn Hills",
            "state": "Michigan",
            "zip": "48326",
            "country_code": "US",
            "phone": "123456789",
            "email": "1469095459@example.com"
        }],
        "payments": [{
            "reference": "52",
            "currency": "USD",
            "transactions": [{
                "payment_method": "ZEROPAY",
                "payment_submethod": "ZEROPAY",
                "amount": 255,
                "gateway_information": {
                    "gateway_id": "OFFLINE",
                    "authorization_status": "AUTHORIZED"
                },
                "billing_address_reference": "104"
            }]
        }],
        "lines": [{
            "id": "56",
            "line_number": 1,
            "product_type": "PHYSICAL",
            "sku": "WB-WD7S",
            "product_name": "Wasburn WD7S",
            "shipping_address_reference": "103",
            "payment_reference": "52",
            "amount": {
                "net_amount": "121",
                "gross_amount": "100",
                "tax_amount": "21",
                "tax_rate": "21",
                "taxes": [{
                    "type": "VAT",
                    "amount": "21",
                    "rate": "21"
                }],
                "currency": "USD"
            },
            "promotions_info": {
                "original_price": 250,
                "promotions": [{
                    "code": "Q2AI26QUQPEH",
                    "discount": 12.1,
                    "name": "Push it to the limit",
                    "percentage": 10
                }]
            }
        }, {
            "id": "54-103",
            "line_number": 2,
            "product_type": "SHIPPING",
            "sku": "STANDARD",
            "product_name": "Shipping",
            "shipping_address_reference": "103",
            "payment_reference": "52",
            "amount": {
                "net_amount": 5,
                "gross_amount": 6.05,
                "tax_amount": 0,
                "tax_rate": 0,
                "taxes": [{
                    "type": "VAT",
                    "amount": 1.05,
                    "rate": 21
                }],
                "currency": "USD"
            }
        }]
    }
}

Order Status

Topic: magento.sales.order_management.updated

Header: (need to add “to” in the headers with value*)

The Order Status Message is generated by the OMS every time there is an order status update in an order or order line, to inform external systems of the update. Once the order is sourced, each line will indicate the source_id of the source that will fulfill the order.

Order Status and Description

NEW—As soon as the order is imported in the OMS the order status is set to NEW.
RECEIVED—After some basic validation of the order the status is updated to RECEIVED.
ERROR—In case there is any error, and the order cannot be processed further the status is ERROR.
ONHOLD—This status is indicating the order is on remorse time.
LOGISTICS—All steps such as sourcing, picking, packing, and shipping are represented with this order status.
LOGISTICSCOMPLETE—Once all the lines of an order are either shipped or canceled. This status only lasts few seconds and is updated almost immediately to complete.
COMPLETE—Means that all the order lines of the orders are in a final status (canceled or shipped).

Order Line Status and Description

NEW—All new orders have lines in status NEW until the fulfillment process is initiated.
SHIPPED—The line have been shipped.
CANCELLED—he line have been canceled.
RESOURCED—The line was assigned to a store for picking but is now again pending to be sourced because it was pick declined.
ITEM_PENDING_PICKING—The pick list have been initiated, but this order line has not been picked yet.
PICKDECLINED—This status will last only a few seconds as the pick declined are enqueued again in the sourcing engine and updated to the status RESOURCED.
PICKCONFIRMED—The picking has been confirmed for the item and is now pending shipment.

JSON example

{
  "order": {
    "id": "000000063",
    "status": "COMPLETE",
    "store": "CLIENT",
    "ip": "172.17.0.2",
    "language": "es_MX",
    "vat_country": "MX",
    "origin": "FRONTEND",
    "origin_date": "2016-08-17T09:25:48+00:00",
    "customer_service_agent": "",
    "customer": {
      "id": "1",
      "type": "REGISTERED",
      "segment": "B2C"
    },
    "addresses": [{
      "reference": "104",
      "address_type": "customer",
      "first_name": "Christophe",
      "last_name": "Trichet",
      "address1": "6 Championship Dr",
      "address2": "",
      "city": "Auburn Hills",
      "state": "Michigan",
      "zip": "48326",
      "country_code": "US",
      "phone": "123456789",
      "email": "1469095459@example.com"
    }, {
      "reference": "103",
      "address_type": "customer",
      "first_name": "Christophe",
      "last_name": "Trichet",
      "address1": "6 Championship Dr",
      "address2": "",
      "city": "Auburn Hills",
      "state": "Michigan",
      "zip": "48326",
      "country_code": "US",
      "phone": "123456789",
      "email": "1469095459@example.com"
    }],
    "payments": [{
      "reference": "52",
      "currency": "USD",
      "transactions": [{
        "payment_method": "ZEROPAY",
        "payment_submethod": "ZEROPAY",
        "amount": 255,
        "gateway_information": {
          "gateway_id": "OFFLINE",
          "authorization_status": "AUTHORIZED"
          },
        "billing_address_reference": "104"
      }]
    }],
    "lines": [{
      "id": "56",
      "line_number": 1,
      "status": "SHIPPED",
      "product_type": "PHYSICAL",
      "sku": "WB-WD7S",
      "product_name": "Wasburn WD7S",
      "shipping_address_reference": "103",
      "payment_reference": "52",
      "source_id": "L001",
      "amount": {
        "net_amount": "121",
        "gross_amount": "100",
        "tax_amount": "21",
        "tax_rate": "21",
        "taxes": [{
          "type": "VAT",
          "amount": "21",
          "rate": "21"
        }],
        "currency": "USD"
      },
      "promotions_info": {
        "original_price": 250,
        "promotions": [{
          "code": "Q2AI26QUQPEH",
          "discount": 12.1,
          "name": "Push it to the limit",
          "percentage": 10
        }]
      }
    }, {
      "id": "54-103",
      "line_number": 2,
      "status": "SHIPPED",
      "product_type": "SHIPPING",
      "sku": "STANDARD",
      "product_name": "Shipping",
      "shipping_address_reference": "103",
      "payment_reference": "52",
      "source_id": " L001",
      "amount": {
        "net_amount": 5,
        "gross_amount": 6.05,
        "tax_amount": 0,
        "tax_rate": 0,
        "taxes": [{
          "type": "VAT",
          "amount": 1.05,
          "rate": 21
        }],
        "currency": "USD"
      }
    }]
  }
}

Order Cancelation API

URL structure: /orders/{orderId}/cancel - POST

Parameters:

Order externalid
Userid that performed the cancelation

Response messages:

200: cancellation successful
400: Exception occurred during order cancellation
406: Order cancellation verification failed

Example URL:

http://luma-stg.bcn.magento.com/api/orders/000000140/cancel

Example response messages

{
  "response": {
    "orderId": "000000141"
  }
}

And another example:

{
  "exception": "Order 000000140 is not in a cancellable status: LOGISTICS - READYTOSHIP",
  "code": null
}

Inventory check API

The API expects to receive a request for a list of SKUs in a specific stock aggregate, and the response will provide the quantity available in the stock aggregate. This quantity will be the aggregated count of the stock across the entire network including the safety stocks buffer. http://luma-stg.bcn.magento.com/api/#!/Inventory/get_store_storeExternalId_stock

URL structure: /store/{storeExternalId}/stock - GET

Parameters:

Storeexternalid
SKUs separated by comma

Example URL:

http://luma-stg.bcn.magento.com/api/store/STORE/stock?skus=1111111111%2C%202222222222%2C24-MB01

Example response messages

[
  {
    "sku": "2222222222",
    "quantity": "98"
  },
  {
    "sku": "24-MB01",
    "quantity": "97"
  },
  {
    "sku": "1111111111",
    "quantity": "99"
  }
]

Oauth validation

Oauth2 is used as authorization framework to enable applications to obtain access to user accounts on an HTTP service.

As a first step the application needs to request a token to be generated by the OAuth server:

https://auth-stg.bcn.magento.com/oauth/token [POST]

Payload (form-data):

{
 "access_token": "uivXjfL3n7XlEOeUItUCS7gjuOQDJfakYRpSO48S",
 "token_type": "Bearer",
 "expires_in": 3600
}

The access_token will then be used in the requests made to the APIs. It will have to be provided in the header as follows:

http://luma-stg.bcn.magento.com/api/ -> Authorization: Bearer

Item Master

Topic: magento.catalog.product_management.update

Header: (need to add “to” in the headers with value*)

The Item Master feed/message informs the OMS about the basic set of SKUs that will be sold via Magento Commerce and from the in-store interfaces (POS). The feed/message can include information such as SKU, name, price, status, dimensions, etc.

When updating the catalog, if you send a message without a specified name, the message will not be processed. Use the #magento.catalog.localized_name format when sending messages to create products or update the catalog.

Price and dimensions

The provided price can be used for export declarations and statistics but will not be visible to the end customer as it is different from the store price. The catalog product messages can hold only a single SKU, therefore to send multiple SKUs multiple messages needs to be generated. If the SKU already exist in OMS then the information will be updated.

Product types

The OMS supports these types of SKUs:

PHYSICAL—normal physical products with stock
SERVICE—services such as gift wrap, engraving, hemming, etc
SHIPPING—shipping type
BUNDLE—a SKU which groups other SKUs
VIRTUAL—indicates stock for a product, not the same as the physical SKU

Configurable Products VS Simple Products

Magento OMS supports a catalog structure for items holding one or more options. The JSON example below is currently being refined to show that the final relationship between an item (configurable product) and an option (simple product) is the “children SKUs” array.

JSON example

{
    "product": {
        "created_at": "2016-04-28T11:18:54+00:00",
        "status": "active/inactive/eol",
        "modified_at": "2016-06-28T13:24:42+00:00",
        "type": "PHYSICAL",
        "name": [
            {
                "channel": null,
                "locale": null,
                "value": "Washburn WD7S"
            },
            {
                "channel": "frontend",
                "locale": "es_ES",
                "value": "Guitar Washburn WD7S"
            },
            {
                "channel": "frontend",
                "locale": "en_US",
                "value": "Washburn WD7S Guitar"
            }
        ],
        "sku": "WB-WD7S",
        "price": {
            "currency": "EUR",
            "quantity": "20.00"
        },
        "children_skus": [
            "sku1",
            "sku2",
            "sku3"
        ]
    }
}

Inventory snapshot

Topic: magento.inventory.source_stock_management.update

Header: (need to add “to” in the headers with value*)

The Stock Snapshot is a feed that is used for stock audit and reconciliation purposes, front-ends or the internal client’s system (ERP). The Magento OMS expects a stock-snapshot feed for each one of the stock sources (either warehouses or physical stores). Where necessary, multiple sources feeds will be aggregated and rules applied before the generation of frontend feeds which can be provided for a single web store or a group of web stores.

Name of the file: LUMA_stock-snapshot_sourceid_YYYYMMDDHH.xml The snapshots are sent as either a full, delta or non-zero (which is the same as the full feed but SKUs not included should be assumed to have a stock of zero).

JSON example

{
    "snapshot": {
        "created_on": "2018-10-17T14:29:00+00:00",
        "mode": "DELTA",
        "source_id": "Warehouse_1",
        "stock": [
            {
                "quantity": 0,
                "sku": "UB02-1",
                "unlimited": false
            }
        ]
    }
}