Guides
Guides

Shipping Mapper

Send data between your shipping tools and Nacelle.

Suggest Edits

Use the Shipping Mapper to link your shipping management tools to Nacelle, like ShipStation and Shippo.

Custom connector

To begin the data mapping process, start by granting your shipping 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 the contract

Description: This API retrieves or validates shipping rates 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 shipping tool uses to send and receive data.

https://merchant-mapper.com/shipping_rates/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
{
  ...
  "shipping_address":{
      "country_iso2": "US",
      "province": "California",
      "state": "CA",
      ...
  }
}

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 encountered an issue accessing shipping rates
Response body (JSON)

Based on the (Response Model Reference )

{
  "checkout": {
    ...
    "shipping_address":{
      "country_iso2": "US",
      "province": "California",
      "state": "CA",
      ...
    },
    "items": [...],
    "shipping_rates":[...]
    "shipping_rate":{...}
 }
}

The response body contains the updated cart object specifying the shipping_rates and adjusting the price as required.

Error handling (JSON)

Based on the(Response Model Reference )

{
  "checkout": {},
  "error": {
    "error": "Shipping Rates Missing",
    "category": "shipping_rates",
    "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 parsing the details section. For more information, see Error Responses in the Response model reference.

Consume the contract

Description: This API is leveraged to consume the shipping rates 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/shipping_rates/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
{
  ...
  "shipping_address":{
    "country_iso2": "US",
    "province": "California",
    "state": "CA",
    ...
  },
  "order_items": [...],
  "shipping_rate":{...}
 }

Response Format

  • Status Code:
    • 200 OK - The request was successful, and the customer session has been closed.
    • 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.
    • 500 Internal Server Error - if the shipping rate engine encountered an issue
Response Body (JSON)

Based on the(Response Model Reference )

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

The response body indicates that the shipping rate is valid based on the 3rd party system.

Error Handling (JSON)

Based on the(Response Model Reference )

{
  "order": {},
  "error": {
    "error": "Shipping Rate Missing",
    "category": "shipping_rate_missing",
    "details": {
      "message": "Please select a shipping rate"
    }
  }
}

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 shipping rates 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 '{  
  ...  
  "shipping_price":"0",
  "shipping_address":{
      "country_iso2": "US",
      "province": "California",
      "state": "CA",
      ...
    }
}'

[Nacelle] Call the merchant mapper

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

https://merchant-mapper.com/shipping_rates/validate
--header 'Secret: some secret header'  
--header 'Content-Type: application/json'  
--data-raw '{  
  ...  
  "shipping_price":"0",
  "shipping_address":{
      "country_iso2": "US",
      "province": "California",
      "state": "CA",
      ...
  ]
}'

[Merchant] Merchant mapper convert the checkout object

You then need to convert the checkout object into the required format for the 3rd party shipping engine.

[Merchant] Call the shipping engine

Then call your shipping engine to retrieve shipping rates. If needed, use checkout cart contents to determine weights or required sizes.

[Merchant] Handle the shipping engine response

Once the response returns from the shipping engine, update the checkout object's shipping_rates field.

[Merchant] Reconstruct the checkout object

Once you have successfully retrieved the response from the shipping engine endpoint as the response body, use the data returned to set the shipping_rates array in the checkout object. Default to a selected option by setting a specific shipping rate in the shipping_rate field on the checkout object.

{
  "checkout": {
    ...
    "shipping_address":{
      "country_iso2": "US",
      "province": "California",
      "state": "CA",
      ...
    },
    "items": [...],
    "shipping_rates": [
      {
        "external_id": "rate-id1",
        "service_name": "UPS",
        "display_name": "Ground shipping",
        "description": "Standard ground shipping using trucks and horses",
        "amount": "10.25",
        "currency": "USD",
        "delivery_estimate_unit": "week",
        "delivery_estimate_min": 1,
        "delivery_estimate_max": 3,
        "tax_behavior": "exclusive"
      },
      {
        "external_id": "rate-id2",
        "service_name": "Fedex",
        "display_name": "Air priority",
        "description": "Air priority shipping, useful for business deliveries",
        "amount": "49.99",
        "currency": "USD",
        "delivery_estimate_unit": "hour",
        "delivery_estimate_min": 4,
        "delivery_estimate_max": 72,
        "tax_behavior": "exclusive"
      }
    ],
    "shipping_rate":{
      "external_id": "rate-id1",
      "service_name": "UPS",
      "display_name": "Ground shipping",
      "description": "Standard ground shipping using trucks and horses",
      "amount": "10.25",
      "currency": "USD",
      "delivery_estimate_unit": "week",
      "delivery_estimate_min": 1,
      "delivery_estimate_max": 3,
      "tax_behavior": "exclusive"
    },
 }
}

[Nacelle] Continue with the orchestration flow

checkoutWithShippingRateChanges, err := merchantMapperConfig.shipping_rates.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

Once all the steps in the orchestration layer finish, Nacelle returns the updated checkout to the merchant as the data requested from the GraphQL mutation.

[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 shipping rates 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": [...],  
  "shipping_rate":{
    "external_id": "rate-id1",
    "service_name": "UPS",
    "display_name": "Ground shipping",
    "description": "Standard ground shipping using trucks and horses",
    "amount": "10.25",
    "currency": "USD",
    "delivery_estimate_unit": "week",
    "delivery_estimate_min": 1,
    "delivery_estimate_max": 3,
    "tax_behavior": "exclusive"
  },
}'

[Nacelle] Call the merchant mapper

Nacelle then uses its orchestration layer to call an endpoint:

<https://merchant-mapper.com/shipping_rates/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": [...],  
    "shipping_rate":{
      "external_id": "rate-id1",
      "service_name": "UPS",
      "display_name": "Ground shipping",
      "description": "Standard ground shipping using trucks and horses",
      "amount": "10.25",
      "currency": "USD",
      "delivery_estimate_unit": "week",
      "delivery_estimate_min": 1,
      "delivery_estimate_max": 3,
      "tax_behavior": "exclusive"
    }
}'

[Merchants] Merchant mapper convert the order

You then need to convert the checkout object into the format that your promotion engine requires.

[Merchants] Call the shipping provider

You then call your shipping provider to confirm that the selected shipping rate is appropriate for the given cart.

[Nacelle] Continue with the orchestration flow

order, err := merchantMapperConfig.shipping_rates.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 7 months ago