Integrations Overview
A core responsibility of the ShipStream platform is to integrate effectively with other systems. We believe an effective integration:
- Is easy to set up yet configurable to meet the needs of most users
- Uses "sane defaults" to reduce complexity
- Requires zero maintenance
- Handles errors automatically where possible and otherwise as gracefully as possible
- Scales as much as you could conceivably need it to
- Protects customer data
- Keeps your systems secure
ShipStream strives to provide the above for the most popular technology partners and provide support for third-party integrations into ShipStream for anyone else.
Integration Types
ShipStream can integrate with many third-party systems out of the box. Most of these integrations will fall under one of these categories:
- Merchant Integrations - connections that have their scope limited to that of a single merchant such as a shopping cart
- Global Integrations - connections that do not have a limited scope such as a shipping provider or integration aggregator
- Webhooks - arbitrary HTTP endpoints to which the system will send small payloads of data when an event occurs
- EDI Documents - the documents that are received from or sent to a third-party as part of an EDI integration
- ShipStream-managed integrations such as address validation and cubing services
Some integrations may overlap more than one of the above categories. For example, with UPS a 3PL user may create a Global Integration to establish a connection for the default shipping account but then also allow their clients to create Merchant Integrations to establish connections for shipping on their own accounts.
Merchant Integrations
As there can be many instances of a Merchant Integration, we refer to each instance as a subscription. Subscriptions are managed under System > Integrations > Merchant Integrations.
Merchant integration subscriptions may be created by both organization users and client users depending on whether the permission is granted by the User Roles. Organization users can create a subscription for any merchant whereas client users can, of course, only create one for themselves.
Shopping Carts
- Shopify
- Magento 1 / OpenMage
Shipping Carriers
Solutions Providers
Global Integrations
As Global Integrations can access the data of all merchants, there is only one instance of each. These often work in conjunction with Merchant Integrations where there is configuration that needs to exist at the merchant scope but the connection authentication is shared among all merchants. For example, with SPS Commerce there is one connection established as a Global Integration, and then one can create any number of Merchant Integration subscriptions to configure the merchant and brand-specific rules for processing the EDI documents.
You can manage your Global Integrations at System > Integrations > Global Integrations.
Shipping Carriers
Solutions Providers
Error Handling
In a perfect world there would be no errors, but since they are inevitable, making them as easy as possible to handle is what sets a "good" integration apart from a "great" one. In ShipStream, all errors generated by Global and Merchant Integrations are managed at System > Integrations > Errors.
Integration errors are typically associated with a specific integration instance (Entity Type and Entity ID) as well as a specific "subject" which is for example an Order or Webhook. Errors specific to a Merchant Integration or Webhook assigned to a merchant can be filtered by the Merchant Name.
Client Visibility
Errors generated by Merchant Integrations are also visible to client users so that your clients can easily access them (if their User Roles allow) and potentially self-serve their resolutions.
When there are unresolved errors, client users with permission to view integration errors will see a notice in the page header alerting them to the fact that there are unresolved errors.
Exceptions
As many errors are often repeated either automatically (such as webhook retries) or manually (such as after clicking a "Sync" button) we record only one error per day for a unique combination of integration and subject. This helps reduce "noise" so you can easily manage the actual errors and not have to wade through duplicates. The errors grid shows the number of occurrences of the same error (each is called an exception) as well as the first seen timestamp and the updated at timestamp which is typically when it last occurred.
Clicking on an error from the grid, you can see the details of the most recent exception that occurred as well as a summary of the last 10 occurrences. From this, you can hopefully determine the issue.
If you can determine the cause of the issue, have addressed it, and are ready for the system to retry the action that generated the error you can click Retry to immediately have the system try again. Errors that are successfully retried, either automatically or manually are automatically marked as Resolved. If the error is somehow resolved externally (for example, an order with invalid data was canceled) you can simply click Resolved to mark it resolved as well.
EDI Documents
EDI (Electronic Data Interchange) documents can be viewed at System > Integrations > EDI Documents. They are processed in stages depending on if they are inbound or outbound:
- Inbound documents
- Receive and store the document locally and delete it remotely
- Parse it to make sure it is readable and valid
- Associate it to a specific merchant
- Process the data
- Outbound documents
- Generate the document body
- Transmit it to the correct endpoint
See SPS Commerce for more information on EDI integrations.
