Integrate a shipping carrier or rate service

A shipping integration connects commercetools to a carrier, a multi-carrier rate-shopping engine, or a label and shipping-execution platform. This guide covers two flows: a synchronous rate quote that puts a carrier's price on the Cart during checkout, and an asynchronous write-back that books a shipment and records its tracking number on the Order.

Three facts shape the work before you plan any of it, and each is the opposite of what a payment integration would lead you to expect.

• Checkout defines no shipping Connector contract. Checkout defines Connector contracts for two categories only, payment Connectors and gift card Connectors. A shipping integration has no enabler, no processor, and no session handshake to conform to. It is a plain Connect Connector built from service, event, and job applications.
• No application template models shipping. Review the Application templates overview to confirm whether a suitable starting point exists.
• shipping is a valid IntegrationType. The IntegrationType classifies a Connector in the registry and is how you search for one, but it prescribes nothing about the shape of the Connector.

Some shipping vendors provide a hosted integration rather than an installable Connector. Confirm the deployment model before deciding whether to configure an existing integration or build a Connector.

This guide does not cover order orchestration or fulfillment. Draw that boundary before you start.

Rule out built-in Shipping Methods first

Most requests for a shipping integration are Shipping Method modeling problems. commercetools ships Zones, per-zone and per-currency rates, free-shipping thresholds, predicates, and tiered rates. Answer this question explicitly and record the answer, because a design that uses only those capabilities has no service to deploy, no latency budget, and no failure mode on the checkout path.

Match the requirement to a built-in mechanism

Check the two constraints that close the built-in route

Two Project-level constraints decide borderline cases.

Define the shipping integration requirements

The integration path and the design both follow from these decisions. Record them before you evaluate a Connector or write code.

Decide what the integration owns

Two flows can be in scope independently, and this is the largest scope lever in the project.

Scope the flows

Answer and record the following questions, because each one changes the design:

• Which service, and what does it do? A single carrier's API, a multi-carrier aggregator, a rate or checkout-rules engine, or a label and shipping-execution platform. These need different applications and different credentials.
• Must quoted options appear in the shopper's shipping-options list? Get matching ShippingMethods for a Cart returns Shipping Methods only. If the storefront reads that endpoint and you land carrier prices as custom Shipping Methods, the quoted options never appear. This determines the landing mechanism, so get the answer now.
• Single or Multiple ShippingMode? Multiple mode supports split shipments with per-Line Item methods and addresses, and it changes every update action the integration emits. No update action changes shippingMode after the Cart is created, so this is a requirements decision. For a worked example, see Multiple Shipping Addresses and Methods.
• What granularity does a rate apply to? The whole Cart, a shipment group, or a Line Item. Are pickup points or parcel lockers in scope, which is address selection rather than pricing?
• What happens when the carrier is slow or unavailable? Block the Cart, or fall back to a Shipping Method already defined in the Project. This is a business decision about pricing risk, not a technical default.
• Which event means ready to ship? Order creation alone rarely does. Booking a label the moment an Order exists buys labels for unpaid Orders.
• Which Region and Project? Connect hosts and API hosts are Region-specific.

Record special requirements

Capture anything the list above does not cover as its own requirement, because each one can move the decision in the next section from configuring a Connector toward building one:

• dimensional weight, oversize surcharges, or hazardous-goods restrictions
• duties, delivery-duty-paid pricing, or other cross-border charges
• insurance, signature on delivery, or carrier cut-off times
• delivery-date promises that the storefront displays
• return labels, which are modeled as a Parcel whose tracking data has isReturn set to true
• multi-origin or multi-warehouse routing, where the ship-from address varies per Cart
• negotiated account rates that differ from a carrier's published rates

Choose an integration path

Work through these options in order and stop at the first one that meets your requirements. Each later option is more to build and more to maintain.

Check for an existing shipping Connector

GET https://connect.{region}.commercetools.com/connectors/search?integrationTypes=shipping&private=false

Confirm that a candidate is Connect-deployable

An advertised commercetools integration can be a hosted service, an endpoint that your code calls, or a listing in the vendor marketplace. None of those options necessarily installs through Connect.

When the fit turns out to be a vendor-hosted integration, follow the vendor's onboarding rather than the Connect deployment model. The alternative is a Connect Connector that calls the same vendor API, which is the build described in the rest of this guide.

Prove that a gap is not configuration

Fork or build

commercetools connect init my-shipping-connector
commercetools connect application add --type service
commercetools connect application add --type event

Two existing templates are structurally close enough to provide starting points. Neither template implements a complete shipping integration.

Whichever option you choose, the design in the following sections is the same. Only the question of who implements it changes.

Decide how a quoted rate lands on the Cart

A carrier returns a number. Three mechanisms turn that number into the shipping price on a Cart, and they differ in what the storefront can see. This decision is expensive to reverse, because it determines which endpoint the checkout UI calls.

Compare the three landing mechanisms

Combining both mechanisms in one integration is legitimate, such as tiered rates for standard delivery and a quoted rate for an express option. Say so explicitly in your design, because the storefront then merges two sources of options.

Supply tax on the shipping line

Quote once late in checkout

Build the rate application

The application never writes the Cart itself. It returns update actions, and commercetools applies them inside the same operation.

Size the Extension budget before the carrier call

Set the outbound carrier timeout below the configured Extension timeout, with headroom for your own mapping work, and make both configuration values rather than constants. When you rate-shop across carriers, issue the requests in parallel and return the carriers that answered rather than waiting for the slowest. Measure the carrier's actual latency and size the timeout from that measurement.

Avoid the carrier call when nothing rate-relevant changed

Most Cart updates in a checkout flow cannot change a shipping price. Adding a note, setting an email address, or applying a discount code leaves the origin, destination, weight, and contents unchanged.

The short-circuit matters more than it first appears. When the shopper selects an option, the storefront applies it with a fresh Cart update, which triggers the Extension again. Without the hash comparison, every selection costs a second carrier call inside the same budget.

Decide fail-open or fail-closed

A carrier outage must not make Carts unusable, but a fail-open integration can price a Cart below cost. This is a business decision about pricing risk. Take it explicitly, record it, and state it in the Connector documentation.

If the business chooses to fail open, provision a fallback Shipping Method whose predicate always matches and whose rates cover every currency in scope. Apply it when the carrier does not answer, and log the degradation with the correlation identifier. Scope the fallback globally or to every Store in scope. A Cart that belongs to a Store matches only globally scoped Shipping Methods and those scoped to that Store. Choose fail-closed behavior when an incorrect shipping price is worse than a blocked checkout.

Do not use an Extension error to signal that no shipping is available. Model unavailability as an empty option list or a non-matching predicate, and reserve errors for genuine failures.

Serve the option list when rates are not Shipping Methods

Sequence the rate against other Extensions

API Extensions for the same resource and action run concurrently by default. A tax Extension can therefore calculate against a Cart state that does not yet carry the shipping rate and record tax that does not match the persisted result.

Test the decisions, not the carrier

Mock the carrier boundary and assert on what your code decided rather than on what the carrier returned. The suite must run without a deployment and without secrets.

Cover the quote selection when several carriers answer, the update actions emitted for each landing mechanism, the short-circuit returning no actions for a Cart whose rate-relevant inputs are unchanged, the fallback path when the carrier exceeds its timeout, and the tax field supplied for the TaxMode of the Cart.

Write labels and tracking back to the Order

Trigger on the Message that means ready to ship

Make the write-back idempotent

Guard against overshipment

Configure and deploy the Connector

Grant only the permissions the enabled applications use

Declare scopes and let Connect provision the API Client rather than supplying credentials by hand.

Separate configuration from secrets

Carrier API keys and account identifiers belong in secured configuration. Everything an operator changes without a code change belongs in standard configuration: the enabled carriers, the enabled service levels, the origin address, the default package dimensions, the dimensional-weight divisor, the markup, the carrier timeout, the quote cache lifetime, the fallback Shipping Method key, the Order state that gates label creation, and whether the Connector calls the carrier's sandbox or its live account.

Make the landing mechanism an explicit configuration value rather than an implicit consequence of the code. It is the decision most likely to be revisited, and it is the one an operator most needs to be able to read.

Register resources idempotently and verify the registration

The deployment script has more to do here than in most integrations, because the applications depend on platform resources existing before the first shopper arrives:

• the fallback Shipping Method, created only when absent, with a predicate that always matches and rates in every currency in scope
• the Custom Types for the Cart quote hash and the Delivery shipment identifier
• the Cart API Extension, registered at the rate application's endpoint with an authenticated destination
• the Order Subscription, registered at the label application's endpoint

Write each registration as a read followed by a create or update so that a redeployment does not fail on a resource that already exists, and have the undeployment script remove what the deployment script created.

Verify the registration rather than inferring it from a successful deployment. Query the Extensions and Subscriptions in the Project after deploying and confirm that the destinations and triggers are the ones you expect. A deployment script that only installs dependencies registers no platform resources, so no quote or Message delivery occurs.

Validate carrier credentials at deploy time

Make one inexpensive carrier call, such as an account lookup or a rate ping, in the deployment script. Incorrect credentials then fail the deployment instead of failing the first shopper's Cart.

Verify the round trip

Verify against a Project with a real carrier account. A shipping integration that passes its unit tests can still fail in three ways that only appear against a running Project: the shopper cannot see the option, the shopper cannot check out at all, or the price on the Order is not the price the carrier will invoice.

Run these in order, because each one fails differently:

1. Confirm the Extension is registered. Query the Extensions in the Project and check that yours is present with the destination and trigger you expect. A deployment script that did not run is the most common cause of nothing happening at all.
2. Trigger a quote. Create a Cart, set a shipping address, and confirm from the application logs that exactly one carrier call was made, with the origin, destination, and weight you expect.
3. Check that the option is visible to the shopper. For a tiered rate, confirm that matching Shipping Methods returns the method with the correct tier flagged isMatching. For a custom Shipping Method, confirm that your option-list endpoint returns the quoted options. Verify whichever endpoint the storefront actually calls, because this is the failure unit tests never catch.
4. Verify the price on the Cart. Apply the chosen option and read shippingInfo on the Cart. The amount must match the carrier quote exactly, and the tax on the shipping line must be present and correct.
5. Confirm the rate survives to the Order. Create the Order and check that shippingInfo.price equals the quoted amount. A rate that changes between quote and Order is a cache lifetime or re-quote defect.
6. Update the Cart in a way that cannot change the price. Change a Custom Field or set an email address and confirm that no carrier call was made. The short-circuit is what keeps the Extension inside its budget in production.
7. Book one label. Trigger the Order Message, confirm a shipment exists at the carrier, and check that the durable booking record points to one Delivery containing the expected items.
8. Check that tracking reaches the Parcel. Confirm that the Parcel on the Order carries the carrier tracking identifier and carrier name, and that the number resolves on the carrier tracking page.
9. Redeliver the same Message. Confirm that no second label and no second Delivery are created, and that the handler acknowledges.

Exercise the failure paths deliberately

These paths only prove themselves when you break something on purpose.

• Carrier unreachable. Point the integration at an unreachable host. The Cart update must still succeed and the agreed fallback must apply. If Carts fail, the integration is fail-closed, so confirm that is what was chosen.
• Carrier slow. Inject latency above the configured carrier timeout. The Extension must return on the fallback path within its own budget rather than riding the carrier's timeout into an ExtensionNoResponse.
• Incorrect credentials. Deploy with a wrong API key. The deployment must fail rather than deferring the failure to the first shopper.
• An address the carrier rejects. Use an undeliverable postal code or an address the service level does not cover. The shopper must see no available option rather than an error that blocks the Cart.

Confirm the rates against a production carrier account before go-live. Sandbox and production carrier accounts can use different pricing configurations.

Troubleshoot observable symptoms