Guides

Inventory Mapper

Send data between your inventory management tools and Nacelle.

Suggest Edits

Use the Inventory Mapper to link your inventory management tools to Nacelle, like NetSuite and Square.

Custom connector

To begin the data mapping process, start by granting your inventory management tool permission to send and pull data to and from Nacelle with the custom connector token. Set up a custom connector in the Nacelle dashboard.

Validate contract

Description: This API is used to retrieve or validate cart item quantities during the checkout session.

📘

Note: Nacelle returns the mutated checkout object to the merchant after all other validations have run. You can then transform the model as needed in the front end.

REST API contract:

Merchant Supplied Endpoint: Start by finding the endpoint your inventory management tool uses to send and receive data.

Example: 

https://merchant-mapper.com/inventory/validate

HTTP Method: POST

Request Format:

  • Headers:
    • Content-Type: application/json: Specifies that the request body contains JSON data
    • x-nacelle-signature-sha256: The signed payload signature. This is an HMAC signature. The secret can be retrieved from the Nacelle dashboard.
    • (Optional authentication headers)
  • Request Body (JSON): Based on the (Checkout) endpoint
{
   ...
   "items": [
     {
       ...
       "product_id": "...",
       "variant_id": "...",
       "quantity": 10
     }
   ]
 }

Response format

  • Status Code:
    • 200 OK - The request was successful, and the checkout has been updated.
    • 400 Status Bad Request - If the object is missing required data
    • 401 Unauthorized - If authentication is required and not provided.
    • 403 Forbidden - If the user does not have permission to update the task.
    • 422 Unprocessable Content - if the merchant mapper is returning an error for out of stock issues
    • 500 Internal Server Error - The merchant mapper encountered an internal error like not being able to access the inventory system.
Response Body (JSON)

Based on the(Response Model Reference )

{
  "checkout": {
    ...
    "items": [
      {
        ...
        "product_id": "...",
        "variant_id": "...",
        "quantity": 10,
        "available": 8
      }
    ]
    "meta_data": [] // <- Add any merchant notes to be used in the frontend
  }
 }

The response body contains the updated cart object specifying the quantity available.

Error Handling (JSON)

Based on the (Response Model Reference )

{
  "checkout": {},
  "error": {
    "error": "Inventory service not responding",
    "category": "inventory_service",
    "details": {}
  }
}

The response body includes an error field containing a descriptive error message, and a category with optional details. The category should be used to give the client information on how to parse the details section. For more information, see Error Responses in the Response model reference.

Consume contract

Consumption of inventory happens when an order is created. The process is similar to validation. Nacelle sends the entire order to an inventory consumption endpoint built by the inventory management tool. The difference here is that consumption is expected to reduce the inventory count. If there’s not enough inventory, then an error is returned.

Description: This API is used to decrease the inventory counts after the payment is processed. It is run as part of the order creation process.

REST API contract:

Merchant Supplied Endpoint:

Example

https://merchant-mapper.com/inventory/consume

HTTP Method: POST

Request format

  • Headers:
    • Content-Type: application/json: Specifies that the request body contains JSON data
    • x-nacelle-signature-sha256: The signed payload signature. This is an HMAC signature. The secret can be retrieved from the Nacelle dashboard.
    • (Optional authentication headers)
  • Request Body (JSON): Based on the (Create a multi-order) endpoint
{
   ...
   "order_items": [
     {
       ...
       "product_id": "...",
       "variant_id": "...",
       "quantity": 10,
       "available": 8
     }
   ]
 }

Response format

  • Status Code:
    • 200 OK - The request was successful, and the inventory was reduced.
    • 400 Status Bad Request - If the object is missing required data
    • 401 Unauthorized - If authentication is required and not provided.
    • 403 Forbidden - If the user does not have permission to update the task.
    • 422 Unprocessable Content - if the merchant mapper is returning an error for out of stock issues
    • 500 Internal Server Error - The merchant mapper encountered an internal error like not being able to access the inventory system.
Response body (JSON)

Based on the (Response Model Reference )

{
  "order": {...},
}

The response body indicates that the inventory is decreased.

Error handling (JSON)

Based on the (Response Model Reference )

{
  "order": {},
  "error": {
    "error": "Inventory service not responding",
    "category": "inventory_service",
    "details": {}
  }
}

The response body includes an error field containing a descriptive error message, and a category with optional details. The category should be used to give the client information on how to parse the details section. For more information, see Error Responses in the Response model reference.

Validating inventory workflow

[Merchant] Call the validation endpoint

The merchant calls an endpoint in Nacelle to validate the checkout using a REST API method which returns the updated checkout after running validation steps:

<https://noms.api.nacelle.com/api/v1/checkout/> 
--header 'Authorization: Bearer <merchant-auth-token>'  
--header 'x-nacelle-space-id: <merchant-space-id>'  
--header 'Content-Type: application/json'  
--data-raw '{  
  ...  
 "items": [
     {
       ...
       "product_id": "...",
       "variant_id": "...",
       "quantity": 10,
     }
   ]
}'

[Nacelle] Call the merchant mapper

Nacelle uses the orchestration layer to call the merchant supplied endpoint:

https://merchant-mapper.com/inventory/validate
--header 'Secret: some secret header'  
--header 'Content-Type: application/json'  
--data-raw '{  
  ...  
 "items": [
     {
       ...
       "product_id": "...",
       "variant_id": "...",
       "quantity": 10,
     }
   ]
}'

[Merchant] Merchant mapper convert checkout

You then need to convert the checkout object into the required format for the 3rd party inventory management tool.

[Merchant] Call the inventory system

Then call your inventory system to retrieve available counts.

[Merchant] Handle the inventory system response

Once the response is returned from your inventory system, update the checkout object's items field with the available quantity.

[Merchant] Reconstruct the checkout object

Once you have successfully retrieved the response from your inventory management tool, use the data returned to set the available field in the checkout object and return it from your endpoint as the response body: 

{
  "checkout": {
    ...
    "items": [
     {
       ...
       "product_id": "...",
       "variant_id": "...",
       "quantity": 10,
       "available": 11
     }
   ]
}

[Nacelle] Continue with the orchestration flow

checkoutWithInventoryChanges, err := merchantMapperConfig.inventory.validate(checkout)

Nacelle continues to process the other steps in the orchestration flow with the updated checkout. If the merchant encounters an error, we return the error back to the client for the merchant to handle the issue.

[Nacelle] Return to the merchant

When all steps in the orchestration layer have completed, Nacelle returns the updated checkout back to the merchant as the response to the validate checkout REST API call.

[Merchant] Final steps

If additional cart changes occur and need to be revalidated, the merchant calls the mutation to validate the cart again. Once a cart is finalized and ready to be converted into an order, the merchant uses this updated checkout to collect payment from their payment provider and send the order details to the Nacelle /multiorders endpoint. Nacelle then runs through the consume orchestration methods.

Consuming inventory workflow

[Merchants] Call the create orders endpoint

Call the /multiorders endpoint in Nacelle to create an order using the REST API:

<https://noms.api.nacelle.com/api/v1/multiorders> 
--header 'Authorization: Bearer <merchant-auth-token>'  
--header 'x-nacelle-space-id: <merchant-space-id>'  
--header 'Content-Type: application/json'  
--data-raw '{
  ...  
  "order_items": [{
       ...
       "product_id": "...",
       "variant_id": "...",
       "quantity": 10,
       "available": 8
     }],  
  
}'

[Nacelle] Call the merchant mapper

Nacelle then uses its orchestration layer to call an endpoint:

https://merchant-mapper.com/inventory/consume  
--header 'Secret: some secret/validation header to tell the merchant this is coming from a trusted source'  
--header 'Content-Type: application/json'  
--data-raw '{  
   ...  
  "order_items": [{
       ...
       "product_id": "...",
       "variant_id": "...",
       "quantity": 10,
       "available": 8
     }],  
}'

[Merchants] Merchant mapper convert the order

You then need to convert the checkout object into the format that your inventory management tool requires.

[Merchants] Call the inventory management tool

Last, call your inventory management tool to decrease the inventory counts for the items in the cart.

[Nacelle] Continue with the orchestration flow

order, err := merchantMapperConfig.inventory.consume(order)

If Nacelle encounters an error during any of the orchestration steps, we stop the orchestration flow and respond to the merchant with the error. Otherwise we continue to process other steps in the orchestration flow with the order.

Updated 3 months ago