Integrating a shipping provider
To integrate a
shipping provider, develop an adapter that uses the
NewStore shipping provider Webhooks.
An adapter serves as an intermediary between NewStore Omnichannel Cloud and a specific shipping provider's interface to request shipping time slots, book a slot, track a package, etc. Develop an adapter for each provider and tell NewStore about the shipping providers you want to integrate with. NewStore supports integrations with all shipping providers.
Defining your shipping strategy
To offer shipping options to your customer, create a shipping strategy and select the shipping providers you want to integrate with and the different service levels they offer. For more information, see Shipping . To set up your shipping and fulfillment strategy, see Tutorial: Setting up a fulfillment configuration (Legacy method) .
Ensure that you communicate your shipping strategy to NewStore before you integrate a shipping provider as it requires some configuration in NewStore Omnichannel Cloud.
You can ship orders using a shipping provider and integrate a different provider to manage returns. Develop a different adapter for each provider. Inform NewStore of your strategy so that the settings required to support this are configured in NewStore Omnichannel Cloud.
Developing the adapter
To allow NewStore Omnichannel Cloud to communicate with your shipping provider, implement the Shipping Provider webhooks.
Before you start the integration, ensure your infrastructure offers an HTTPS web URL where the requests from NewStore Omnichannel Cloud can be posted.
Ensure that you understand the data that the shipping provider requires about the customer as soon as possible. This will help you determine the right solution architecture. You might have to customize NewStore Associate App or E-commerce system integration to retrieve this information.
For example, some shipping providers require the customer's email address (traditional carriers), while some others might need the customer's phone number (couriers).
Before you start shipping orders, ensure that you have already created a shipping option token key pair using the Delivery API. For instructions on creating a shipping option token key pair, see the request sample of the Create or update a shipping option token key pair method.
Retrieving shipping offers
Shipping offers represent the shipping options presented to the customer during checkout. This is the time duration within which the shipping provider estimates delivery for the package.
NewStore Omnichannel Cloud calls your adapter's Request shipping offers webhook to retrieve this information.
ready_by value in the request that NewStore Omnichannel Cloud
sends serves as the cut-off time that ensures that the shipping options
that can be offered to the customer are correct and can be met during
fulfillment. NewStore Omnichannel Cloud calculates
ready_by using a
combination of values: the store's
latest_pickup_time. Additionally, if a
packing time duration is set for the retailer in NewStore Omnichannel
Cloud, this is also used.
Return the shipping options from the provider to NewStore Omnichannel Cloud.
Your provider might send you more information about the delivery time
slots than NewStore Omnichannel Cloud needs. You might need some of this
data to book a time slot for
shipment in a later step, so ensure you
store the data that you need. See the request and response samples for
the Request shipping offers webhook
in our API docs.
You can choose to store this data anyway you like, but if you do not have a database, you can use a JWT token.
- Create a JWT token containing all the information you want to retain.
- Insert it in the
offerproperty of the response you send to NewStore Omnichannel Cloud. The
offerproperty being the unique identifier of the shipping option, NewStore Omnichannel Cloud will send it back to you when the shipment is booked.
Booking a shipment
During fulfillment, after the order is packed NewStore Omnichannel Cloud calls your adapter's Book shipment webhook to book a specific delivery time slot.
The request describes the addresses used for this shipment, the time slot required and possibly a description of the package (weight, dimensions, etc.) and its content.
Usually, NewStore Omnichannel Cloud provides package information. If none is provided, get in touch with your contact point at NewStore.
In the following example, notice the
booking_method property. It
allows you to notify the shipping provider about what is expected from
it: the shipment of the package, the return of the package, or both.
Depending on the value of this field, send a request to retrieve:
- a shipping label (
- a return label (
- both labels (
If your strategy involves shipping with the adapter you are developing
but manages returns via another shipping provider, ensure that this
second adapter is able to process
Once the shipping provider has processed the booking request, share some of the shipping information with NewStore. Usually, the provider returns at least a shipping/return label and a tracking code. The tracking code is what is used to identify the package between NewStore and the adapter.
If your strategy involves shipping with the adapter you are developing but manages returns via another shipping provider, the other adapter returns a similar response to NewStore.
See the Book shipment webhook for the request and response examples.
Booking an international shipment
NewStore supports booking international shipments from stores in your business, using the EasyPost adapter. To enable booking international shipments:
country_of_originfields when importing products that you want to ship internationally. See Importing products .
Update your fulfillment configuration to specify which countries you want to ship to, and specify the stores that can ship orders internationally. For more information, see the tutorial or the API reference documentation.
Assign a person in the store, whose name appears in the
commercial invoice. This person is responsible for the accuracy of the information in the invoice and that it is ready for customs processing.
If required, configure the shipping provider to generate the
ITNand submit electronic
commercial invoicedocuments. Refer to the documentation for the related shipping provider.Important
If the shipping provider submits the commercial invoice documents electronically to customs, NewStore does not include the commercial invoice as a document to print when shipping the order.
If the shipping provider does not submit the commercial invoice electronically, it is available to print in:
- NewStore Omnichannel Manager: See Monitoring orders .
Add the shipping provider to EasyPost. See the EasyPost guide for the related shipping provider.
Configure the EasyPost adapter to book shipments with the related shipping providers. To configure the EasyPost adapter, contact the support team.
Canceling a shipment
The customer can cancel a shipment until the package is actually in transit. When a cancel request happens, the NewStore Omnichannel Cloud calls your adapter's Cancel shipment webhook.
The request has no body and you should only the appropriate response code to notify NewStore Omnichannel Cloud of the cancelation success or failure. Refer to the method description for the request schema.
You might also have to cancel the return booking, in case of separate shipping and return bookings.
Updating the shipment status
Once the shipping has been booked, keep track of the shipment's status and notify NewStore Omnichannel Cloud of any changes. Get in touch with your shipping provider to find the best way to do this.
To send the package status to NewStore Omnichannel Cloud, call the Set shipment status method in the Integration API.
Tracking driver location
Depending on the shipping provider you are integrating with, you might be able to track the driver's location. For shipment status updates, get in touch with your shipping provider to find the best way to retrieve the tracking information.
To send tracking information to NewStore Omnichannel Cloud call the Update shipment details method in the Integration API.
Ensure that you don't exceed the rate limit of the shipping provider and of NewStore Omnichannel Cloud when retrieving and sending tracking updates.