Checklist

Below we describe the necessary steps for a Shipped Shield custom integration.

Integrate widget

We have SDKs available to integrate the Shipped Shield widget on your website (Javascript SDK) and mobile apps (iOS SDK, Android SDK). Please refer to relevant documentation for more information.

Represent Shield in cart

Your backend server/cart must be able to represent Shield in the cart. A common way to achieve this is to add a custom "adjustment" (e.g. a custom shipping fee) that can be added or removed from the cart. Alternatively, it is common to add a custom order item to the cart, with adjustable/dynamic price.

When a customer opts in to Shipped Shield, your backend must add the custom adjustment or order item to the customer's cart. Likewise, when a customer opts out of Shipped Shield, your backend must remove the custom adjustment or order item from the customer's cart.

You can use the Shield Offers endpoint in a server-to-server API call to calculate the correct price for the custom adjustment or order item.

📘

Calculation at checkout

A common approach is to keep the user's Shield selection value in session and only add the custom adjustment or order item when checkout is initiated. This avoids unnecessary server-to-server API calls.

Synchronize orders

Use the /v1/orders endpoint to synchronize each order completed on your platform to Shipped Suite. Also synchronize the order if there are any changes to the order, such as a cancellation, or changes to the order items.

When an order is placed that includes Shipped Shield (as determined by the existence of the custom adjustment or order item as described in the section above), the shield_selected attribute must be set to true.

Synchronize products

Likewise, use the /v1/products endpoint to synchronize your product catalog to Shipped Suite. Submit changes when products are created or updated. And use the /v1/products/{external_id} endpoint to delete products that have been deleted.

Synchronize shipments

When shipments are created, updated, or deleted, use the /v1/shipments and /v1/shipments/{external_id} endpoints to synchronize them to Shipped Suite.

🚧

Courier name mapping

It is important that you map your internal courier name to our list of Couriers exactly to ensure correct shipment tracking.

Handle webhooks

Subscribe to webhook notifications for refund.requested and replacement.requested. See Getting Started for more information.

In your webhook handler, parse the payload, and issue refunds or create replacement orders for the corresponding order and affected_items. external_id will correspond to your system's internal identifier for objects.

Then utilize the /v1/refunds/{id} and /v1/replacements/{id} endpoints to submit confirmation of refunds or replacement order execution.

❗️

Confirmation is required for reimbursement

Refund and replacement requests that are not confirmed via our refund and replacement APIs will not receive reimbursement.