Order Processing with REST API on MSI

Order Processing with REST API on MSI

This is the simplest example of Order Processing that takes into account all the new features that are specific for Multi-Source Inventory. This step-by-step guide is written in the form of a tutorial.

Before you begin

Each step in this tutorial provides the following information:

Endpoint
This section lists the HTTP verb and full path to the endpoint. The basic structure of a REST call in Magento is
<HTTP verb> http://<host>/rest/<scope>/<endpoint>
where:

Element	Description
HTTP verb	One of GET, POST, PUT, or DELETE
host	The hostname or IP address (and optionally, port) of the Magento installation.
scope	Specifies which store the call affects. In this tutorial, this value is default.
endpoint	The full URI (Uniform Resource Identifier) to the endpoint. These values always start with /V1. For example, /V1/orders/4.

HTTP headers
This section indicates which key/value pairs you must specify in the HTTP headers. All calls require one or more HTTP headers.

Payload
This section lists the information that is sent to Magento. All payload samples are valid and can be copied and pasted into your calls, but you might need to change the id values that Magento returns.

Response
This section lists the information that Magento sends to the REST client. These values are often referenced in other steps in the tutorial. The values Magento returns might be different than the values listed in the examples provided in this tutorial.

Complete cURL request sample This section contains the code that can be copied and pasted to UNIX-like console emulator (Bourne Shell for example) with cURL support. The information that should be modified by user will be enclosed between angle brackets. Example:

endpoint="http://<host>/rest"
curl -X GET "$endpoint/V1/directory/countries" \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer $admin_token" | json_pp | grep -in -B3 -A3 "United States"

where:

• endpoint is a temporary variable set to Bourne Shell environment. You have access to it only during this terminal session. It is not reachable in other tab or window or if the terminal is reopened.
• <host> is the Magento Base URL
• json_pp is the prettifier (only humans need it)
• grep is used for search and highlighting information

Complete these prerequisites

• Install a Magento 2.3.0 MSI (or later) instance.
• Install a REST client. You can use any REST client to send calls to Magento. Postman is recommended.
• Know how to construct a REST call in Magento. See Construct a request for details.
• Generate a local API reference.
• Find the Magento MSI WebAPI wiki on Github.

Step 1. Get the admin token

Most REST calls to Magento require an authorization token. The token allows Magento to verify that the caller is authorized to access a system resource. To get a token, you must specify the user’s username and password in the payload.

By default, an admin token is valid for 4 hours. To change this value, log in to Admin and go to Configuration > Services > OAuth > Access Token Expiration.

See Token-based authentication for more information about authorization tokens.

Endpoint
POST http://<host>/rest/default/V1/integration/admin/token

Headers
Content-Type application/json
Authorization: Bearer <admin_token>

Payload
{ "username": "admin", "password": "123123q" }

Response
Magento returns the admin’s access token.
5r8cvmpr11j6gmau8990rcj2qk7unh8i

This token must be specified in the authorization header of every call that requires admin permissions. This token is not displayed in Admin.

Complete cURL request sample

endpoint="http://<host>/rest"
admin_token=$(curl -X POST "$endpoint/V1/integration/admin/token" \
 -H "Content-Type: application/json" \
 -d '{"username":"admin","password":"123123q"}') && echo $admin_token && admin_token=$(echo $admin_token | tr -d '"')

Step 2. Configure the store

If your Magento MSI was successfully deployed it doesn't mean that now you can enjoy all the benefits of the Multi-Source Inventory functionality. By default, Magento MSI is configured to use Single Stock Mode. This configuration doesn't differ much from usual Magento Open Source. The most recognizable difference of Magento MSI in Single Stock Mode is Salable Quantity. The main goal of this tutorial is to show Magento MSI working with different Sources, Stocks and Sales Channels.
The Default store needs additional configuration to run the REST calls mentioned in this tutorial.

Create additional Source

Endpoint
POST http://<host>/rest/all/V1/inventory/source

Headers
Content-Type application/json
Authorization: Bearer <admin_token>

Payload

{
   "source" : {
      "description" : " Source #17",
      "source_code" : "txspeqs",
      "phone" : "(555) 555-5555",
      "email" : "[email protected]",
      "postcode" : "77010",
      "longitude" : -95.383056,
      "enabled" : true,
      "contact_name" : "Ethan Carter",
      "latitude" : 29.762778,
      "region_id" : 57,
      "region" : "Texas",
      "name" : "Texas Sport Equipment Source #017",
      "country_id" : "US",
      "city" : "Houston"
   }
}

Response
Magento returns empty array.
[]

Complete cURL request

source_code_1="txspeqs" && curl -X POST "$endpoint/V1/inventory/source/" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $admin_token" \
-d '{"source":{"source_code":"'"$source_code_1"'","name":"Texas Sport Equipment Source #017","email":"[email protected]","contact_name":"Ethan Carter","enabled":true,"description":" Source #17","latitude":29.762778,"longitude":-95.383056,"country_id":"US","region_id":57,"region":"Texas","city":"Houston","postcode":"77010","phone":"(555) 555-5555"}}'

It is possible to Create a Source without Web API.

Create additional Stock

Endpoint
POST http://<host>/rest/all/V1/inventory/stock

Headers
Content-Type application/json
Authorization: Bearer <admin_token>

Payload

{
   "stock" : {
      "name" : "Stock 1"
   }
}

Response
Magento returns a number.

Complete cURL request

stock_id_1=$(curl -X POST "$endpoint/all/V1/inventory/stock/" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $admin_token" \
-d '{"stock":{"name":"Stock 1"}}') && echo $stock_id_1

Assign Source to Stock

Don't forget to perform full reindex and flush cache after this step is complete!
php bin/magento indexer:reindex && php bin/magento cache:flush

Endpoint
POST http://<host>/rest/all/V1/inventory/stock-source-link

Headers
Content-Type application/json
Authorization: Bearer <admin_token>

Payload

{
   "links" : [
      {
         "source_code" : "txspeqs",
         "stock_id" : "2",
         "priority" : 1
      }
   ]
}

Response
Magento returns empty array.
[]

Complete cURL request

curl -X POST "$endpoint/all/V1/inventory/stock-source-link/" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $admin_token" \
-d '{"links":[{"stock_id": "'"$stock_id_1"'","source_code":"'"$source_code_1"'","priority":1}]}'

Set the payment method

Payment type	Configuration name	Enabled by default?
Check/Money Order	checkmo	Yes
Bank Transfer Payment	banktransfer	No
Cash on Delivery	cashondelivery	No
Purchase Order	purchaseorder	No
Zero Subtotal Checkout	free	No

Magento default configuration is not configured to handle credit card payments out from the box. If you want to change which offline payments (or any other online payment method) are configured as a payment method, log in to Admin and select Stores > Configuration > Sales > Payment Methods. Then enable the payment method and click Save.

Configure supported shipping methods (optional)

Shipping type	Configuration name	Enabled by default?
Flat rate	flatrate	Yes
Table rate	tablerate	Yes
Free shipping	freeshipping	No

If you want to change which offline shipping methods are available, select Stores > Configuration > Sales > Shipping Methods in Admin. Enable or disable the shipping methods as desired, then click Save. Upon clicking Save, a notification message states that the cache needs to be refreshed. Click the Cache Management link to refresh the cache.

Step 3. Create a customer

Endpoint
POST http://<host>/rest/all/V1/customers

Headers
Content-Type application/json
Authorization: Bearer <admin_token>

Payload

{
   "password" : "Password1",
   "customer" : {
      "lastname" : "Doe",
      "email" : "[email protected]",
      "firstname" : "Jane",
      "addresses" : [
         {
            "postcode" : "10755",
            "firstname" : "Jane",
            "region" : {
               "regionCode" : "NY",
               "regionId" : 43,
               "region" : "New York"
            },
            "defaultBilling" : true,
            "defaultShipping" : true,
            "city" : "Purchase",
            "telephone" : "512-555-1111",
            "countryId" : "US",
            "street" : [
               "123 Oak Ave"
            ],
            "lastname" : "Doe"
         }
      ]
   }
}

Response
Magento assigned this user id value of 1.

Complete cURL request

curl -X POST $endpoint/V1/customers \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $admin_token" \
-d '{"customer":{"default_billing":true,"default_shipping":true,"email":"[email protected]","firstname":"Jane","lastname":"Doe","store_id":1,"website_id":1,"addresses":[{"defaultShipping":true,"defaultBilling":true,"firstname":"Jane","lastname":"Doe","region":{"regionCode":"NY","region":"New York","regionId":43},"postcode":"10755","street":["123 Oak Ave"],"city":"Purchase","telephone":"512-555-1111","countryId":"US"}]},"password":"Password1"}' | json_pp

Step 4. Get the customer token

To get a customer token, you must specify the user’s username and password in the payload.

Endpoint
POST http://<host>/rest/default/V1/integration/customer/token

Headers
Content-Type application/json

Payload
{ "username": "[email protected]", "password": "Password1" }

Response
Magento returns the customer's access token.
5r8cvmpr11j6gmau8990rcj2qk7unh8i

Complete cURL request sample

customer_token=$(curl -X POST "$endpoint/default/V1/integration/customer/token" \
 -H "Content-Type: application/json" \
 -d '{"username":"[email protected]","password":"Password1"}') && echo $customer_token $ && customer_token=$(echo $customer_token | tr -d '"')

Step 5. Create a quote

Endpoint
POST http://<host>/rest/default/V1/carts/mine

Headers
Content-Type application/json Authorization Bearer <customer token>

Payload
None

Response The response is the 1

Complete cURL request sample

curl -X POST "$endpoint/default/V1/carts/mine" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $customer_token"

Step 6. Add items to the cart

This article shows how to add a simple product, a configurable product, a downloadable product and a virtual product to the cart. Magento MSI has no full support for bundle product and grouped product until these issues are not resolved:
#458
#459
There are also some known bugs with products of this type in Multi-Stock Mode when products are assigned to non-default stock.

Add a simple product to a cart

Add a configurable product to a cart

Add a downloadable product to a cart

Add a virtual product to a cart

Step 7. Prepare for checkout

Step 8. Create an order

Step 9. Create an invoice

Step 10. Create a shipment

Step 11. Issue a partial refund