External Shipping Engine Draft

warning

This document is a draft and what it contains is not available yet in any environment, and is subject to change.

This API integrates an external shipping service into Centra via a single-endpoint webhook system.

High Level Flow

Configuring/Installing the Integration

This has yet to be decided. In the MVP, this will likely require manual configuration by the Centra team.

Available Configuration Options

Some options will be available to configure.

Option	Description
API URL	Endpoint the API will talk to.
Signing secret	Shared secret used for signing.
Markets	Which Markets this ESE serves.
Ship-to countries	Which destination countries this ESE serves.
Mode	`Replace` or `Augment`. Replace: ESE options replace Centra's built-in shipping. Augment: ESE options are shown alongside built-in shipping options.

Attribute configuration

note

More detailed information to come, currently lists some expectations.

The integration will support defining multiple types of attributes. For products, these can provide shipping-related information not already available in the Centra product model. Order and delivery group attributes let you decide which data should be persisted on a Centra order for use by other integrated systems.

Request Structure

Centra sends all requests as HTTP POST to your configured endpoint URL.

Request Signature

Centra signs every request using HMAC-SHA512. The signature is computed over the JSON-encoded request body using the shared signing secret configured in the plugin settings.

signature = HMAC-SHA512(JSON-encoded-request-body, signing-secret)

The signature is sent in the X-Request-Signature header. Your endpoint MUST verify this signature to authenticate requests from Centra. If verification fails, return a HTTP 401 Unauthorized response and do not process the request.

Request Payload Fields

Request payload is a JSON object.

Field	Required	Type	Description
requestType	Y	string	The type of request.
requestContext	N	string	Additional context information per requestType
data	Y	object	The request data; structure varies based on `requestType`

Request Types

All requests are sent to your configured endpoint URL. The requestType field in the request body determines which operation is being performed:

Request Type	Must Implement	Description
shippingOptions	Y	Calculate and return shipping options for a selection
optionLocations	N	Return a list of pickup locations near a given address
orderCreated	Y	Selection using a shipping option from this integration was completed and is now an order to be shipped.
testConnection	Y	Verify the endpoint is reachable and credentials are valid

Request Headers

Every request includes these headers:

Header	Description
Content-Type	`application/json`
X-Client-Id	Centra client instance identifier
X-Request-Id	Unique request identifier
X-Correlation-Id	Correlation identifier for tracing
X-Request-Signature	HMAC-SHA512 signature of the request body.
User-Agent	Centra version information

Persisting Data For Orders

As a provider, you can configure attributes that Centra will store per order or delivery group. These attributes are set by you in the orderCreated request.

Request Type: shippingOptions

Called by Centra when shipping options are needed for a customer to choose from.

Idempotency / Concurrency

This call has no idempotency requirements. Centra ensures that only one request per selectionId is in flight at any time.

shippingOptions: Request Context

To allow for a stateful integration optimized for speed, Centra provides the context the request is made from. Each context has varying requirements.

Value	Description
NOTIFY	This request is a notification to you about an ongoing selection, response payload is optional.
EXPRESS	This request needs to initialize or update express payments, response payload should ideally contain express optimized options, or some options for us to configure.
CHECKOUT	This request was made as part of checkout and a full response payload is expected.

Caching

Centra may cache your response for sequential calls with an identical selection, address, and items, provided your last response used responseState = COMPLETE and none of the returned options have expired. Cached responses are kept for up to 5 minutes.

Error Handling

For any response code other than HTTP 200 OK, Centra will fall back to the internal Centra shipping options. For signature verification errors, return HTTP 401 Unauthorized. For any of the following error codes, return HTTP 400 Bad Request.

Error Code	Description
ADDRESS_INCOMPLETE	Address is missing fields that are mandatory for rate calculation in this country.
ADDRESS_INVALID	Address fields are present but fail validation.
UNSUPPORTED_DESTINATION	Destination is correct but not shippable.
NO_RATES_AVAILABLE	Provider serves this destination but no shipping services are available for this specific request

Request Data Fields

Field	Required	Type	Description
selectionId	Y	string	Unique identifier for the current selection, useful for identifying a checkout session.
storeId	Y	int	Centra store identifier
market	Y	object	Market object
currencyCode	Y	string	Currency code
locale	Y	string	Locale code
totalValue	Y	number	Total item value of all the delivery groups combined
discounts	N	array	Array of discounts
optimizeFor	N	array	Array of display targets to optimize for
deliveryGroups	Y	array	Array of delivery groups to be sent
customer	N	object	Customer object for known customers

shippingOptions / Request: Discount

Describes a discount that should give some form of free shipping to the customer.

Field	Required	Type	Description
type	Y	string	Type of discount, always `FREE` in this version
level	Y	enum	Discount tier configured per Centra voucher. One of `BASIC` or `PREMIUM`.

shippingOptions / Request: Market

Field	Required	Type	Description
id	Y	int	Market identifier
name	Y	string	Name of the market

shippingOptions / Request: Customer

Field	Required	Type	Description
type	Y	string	Customer type. Always `customer` in B2C contexts.
id	Y	string	Customer identifier
email	Y	string	Customer email address
phoneNumber	N	string	Customer phone number

shippingOptions / Request: OptimizeFor

Express payments might have fewer options; this allows you to control what is seen in them.

Field	Required	Type	Description
type	Y	string	String describing what system this is for, eg. `applepay`, `googlepay`
optionsShown	N	int	How many options will be shown, if this is not given there is no set limit.
pickupSelectSupported	N	boolean	`false` = first location of each option will be used, if not given or true a pickup selector can be shown.
customerChoicesSupported	N	boolean	`false` = no customer choices will be shown, if not given or true customer choices can be shown.

shippingOptions / Request: DeliveryGroup

Field	Required	Type	Description
id	Y	string	Unique identifier for this delivery group
value	Y	number	Total item value of this specific delivery group
origin	Y	object	Address items will be shipped from
destination	Y	object	Address items will be shipped to
items	Y	array	Array of items included in the delivery group

Shared: Address

Field	Required	Type	Description
lines	Y	array	Street address lines
locality	Y	string	City or locality name
administrativeArea	N	string	State or province
postalCode	Y	string	Postal or ZIP code
countryCode	Y	string	ISO 3166-1 alpha-2 country code

Shared: Item

Field	Required	Type	Description
lineId	Y	string	Unique identifier for this item in the delivery group
sku	Y	string	SKU of the item
variantName	Y	string	Name of the variant
productName	Y	string	Name of the product
productId	Y	string	Centra product identifier
variantId	Y	string	Centra variant identifier
quantity	Y	int	Quantity of the item in the delivery group
unitPrice	Y	number	Unit price of the item in the delivery group
unitOriginalPrice	Y	number	Original unit price of the item in the delivery group
weightGrams	N	number	Weight of the item in grams, if configured
lengthMm	N	number	Length of the item in millimetres, if configured
widthMm	N	number	Width of the item in millimetres, if configured
heightMm	N	number	Height of the item in millimetres, if configured
harmonizedCommodityCode	Y	string	Harmonized System (HS) commodity code for customs purposes
countryOfOrigin	Y	string	Country code where the item was manufactured
attributes	N	object	Dynamic object with configurable product attributes related to shipping

Success Response

Field	Required	Type	Description
responseState	Y	enum	NOTICE, PARTIAL or COMPLETE
data	N	object	Shipping options for the requested selection

shippingOptions / Response: responseState

Value	Description
NOTICE	Only accepted for requestContext = NOTIFY, signals response is otherwise empty, a follow-up call will be made later to retrieve options.
PARTIAL	Accepted for all requestContext, at least one option available but more can exist shortly. Centra never caches this response.
COMPLETE	Accepted for all requestContext. The response is considered complete. Centra may cache the response for identical selections so long as the option expiry has not passed, up to 5 minutes.

shippingOptions / Response: Success

The response supports two mutually exclusive modes for providing shipping options. Set either flat or perGroup — not both.

flat — one set of options shared across all delivery groups. Use when the same options apply to every shipment.
perGroup — separate options per delivery group. Use when different shipments need different choices.

optimizeFor and customData are available in both modes.

Field	Required	Type	Description
flat	N	object	Flat options — a single set of options for all delivery groups.
perGroup	N	object	Per-group options — options broken down per delivery group.
optimizeFor	N	array	Per-target option overrides for express payment contexts (e.g. Apple Pay). Each entry replaces the standard options for a specific display target. See OptimizeFor.
customData	N	array	Arbitrary key/value metadata to attach to the response.

shippingOptions / Response: Flat

Field	Required	Type	Description
options	Y	array	Shipping options applied to all delivery groups
preselectedOption	N	string	ID of the option to preselect. Defaults to the first option if not specified.

shippingOptions / Response: PerGroup

Field	Required	Type	Description
deliveryGroups	Y	array	Delivery groups with options per group
omniOptions	N	array	Shipping options backed by Centra brick-and-mortar stores. Not bound to delivery groups — use when a physical store can fulfill or accept pickup for the entire order.

shippingOptions / Response: DeliveryGroup

Field	Required	Type	Description
id	Y	string	Unique identifier for this delivery group, matching the request
options	Y	array	Shipping options for this delivery group
preselectedOption	N	string	ID of the option to preselect. Defaults to the first option if not specified.

shippingOptions / Response: OptimizeFor

Field	Required	Type	Description
type	Y	string	Unique identifier for this service
options	Y	array	shipping options for a specific service
preselectedOption	N	string	ID of the option to preselect. Defaults to the first option if not specified.

shippingOptions / Response: Option

Field	Required	Type	Description
id	Y	string	Unique identifier for the shipping option
displayName	Y	string	Display name for the shipping option
price	Y	number	Price of the shipping option
originalPrice	N	number	Pre-discount price. Defaults to price if omitted.
currencyCode	Y	string	Currency code for the shipping option
carrierName	Y	string	Name of the carrier for the shipping option
serviceCode	Y	string	Code for the shipping service
deliveryType	Y	string	Delivery type. Centra accepts any string value; recommended values: `TO_DOOR`, `PICKUP`, `STANDARD_SHIPMENT`, `LOCKER`, `MAILBOX`.
description	N	string	Description of the shipping option
iconUrl	N	string	URL to an icon for the shipping option
etd	N	object	Estimated time of delivery for the shipping option
requiresLocation	Y	boolean	Indicates that the customer must select a pickup location for this option.
locations	N	array	Nearby pickup locations
labels	N	array	labels to show on the option
customerChoices	N	array	Choices that can be made by the customer.
expireAfter	N	string	ISO 8601 datetime after which this option should no longer be offered.
brickAndMortar	N	number	ID of a Centra brick-and-mortar store that may fulfill the order.
customData	N	array	Array of custom key/value pairs to attach to the option.

shippingOptions / Response: Custom Data

Field	Required	Type	Description
key	Y	string	Data key
value	Y	string	Data value

shippingOptions / Response: ETD

Your estimate of when the delivery group will arrive. This is your broad estimate, not a customer-chosen slot.

At least one field must be provided. If custom is present, it takes precedence and is shown to the customer in place of any derived label from relative or absolute.

Field	Required	Type	Description
relative	N*	object	Transit time as a range of time units.
absolute	N*	object	Arrival as a date/time range.
custom	N*	string	Free-form delivery estimate shown to the customer, e.g. `"Delivered by Christmas"`. Takes precedence over `relative` and `absolute` when present.

shippingOptions / Response: ETD Relative

Transit time as a range, e.g. "1–3 business days".

Field	Required	Type	Description
units	Y	enum	`HOURS`, `DAYS`, `BUSINESS_DAYS`, or `WEEKS`
min	Y	int	Minimum transit time
max	Y	int	Maximum transit time

shippingOptions / Response: ETD Absolute

Arrival as an absolute date/time range.

Field	Required	Type	Description
from	Y	string	Earliest estimated arrival (ISO 8601 with timezone)
to	Y	string	Latest estimated arrival (ISO 8601 with timezone)

shippingOptions / Response: Location

Field	Required	Type	Description
id	Y	string	Unique identifier for the pickup location
displayName	Y	string	Name of the location
address	N	object	Address of the pickup location
latitude	N	number	Geographic latitude
longitude	N	number	Geographic longitude
distanceMeters	N	number	Distance in meters from the shipping address to this location
openingHours	N	array	List of opening hours per day.
openingHoursText	N	string	Opening hours text
brickAndMortar	N	number	ID of a Centra brick-and-mortar store that may fulfill the order.

shippingOptions / Response: Location Opening Hours

Field	Required	Type	Description
day	Y	string	day of week
open	Y	string	open time
close	N	string	close time

shippingOptions / Response: Label

Field	Required	Type	Description
type	Y	string	Label type name
displayName	Y	string	Short display name for the label
description	N	string	Description of what the label means
iconUrl	N	string	URL for icon to show on option

shippingOptions / Response: Customer Choice

Field	Required	Type	Description
id	Y	string	Choice identifier
displayName	Y	string	Customer-facing label.
description	Y	string	Explanatory text.
type	Y	enum	One of `INPUT`, `CHECKBOX`, or `CHOICE`
default	N	string	For `INPUT` value will be shown in input box, defaults to empty. For `CHOICE` the option with the given `key` will be selected, defaults to first option. For `CHECKBOX` `"1"` for checked, defaults to unchecked.
options	N*	array	List of choices. Required when `type` is `CHOICE`.
price	N	number	Additional price added if the customer selects a non-default value.

shippingOptions / Response: Customer Choice Option

Field	Required	Type	Description
key	Y	string	Choice identifier.
displayName	Y	string	Customer-facing label.
description	Y	string	Explanatory text.
price	N	number	Overrides the price on the parent Customer Choice if set.

shippingOptions / Response: Error

Field	Required	Type	Description
code	Y	string	Error code, e.g. `NO_RATES_AVAILABLE`
message	Y	string	Human-readable error message

Example Request

Example request with two delivery groups.

{
  "requestType": "shippingOptions",
  "requestContext": "CHECKOUT",
  "data": {
    "selectionId": "sel-abc123def456",
    "storeId": 1,
    "market": {
      "id": 3,
      "name": "US Market"
    },
    "currencyCode": "USD",
    "locale": "en-US",
    "discounts": [
      {"type": "FREE", "level": "BASIC"},
      {"type": "FREE", "level": "PREMIUM"}
    ],
    "optimizeFor": [
      {"type": "applePay", "optionsShown": 5, "pickupSelectSupported": false}
    ],
    "totalValue": 89.97,
    "deliveryGroups": [
      {
        "id": "shipment-1",
        "value": 59.98,
        "origin": {
          "countryCode": "US",
          "administrativeArea": "NJ",
          "locality": "East Hanover",
          "postalCode": "07936",
          "lines": ["27 Merry Ln", "apt. 111"]
        },
        "destination": {
          "countryCode": "US",
          "administrativeArea": "CA",
          "locality": "San Francisco",
          "postalCode": "94105",
          "lines": ["123 Market St"]
        },
        "items": [
          {
            "lineId": "line-1",
            "sku": "TSHIRT-BLK-M",
            "variantName": "Classic T-Shirt — Black, Medium",
            "productName": "Classic T-Shirt",
            "productId": "product-101",
            "variantId": "variant-501",
            "quantity": 2,
            "unitPrice": 29.99,
            "unitOriginalPrice": 39.99,
            "weightGrams": 200,
            "lengthMm": 300,
            "widthMm": 250,
            "heightMm": 50,
            "harmonizedCommodityCode": "6109.10",
            "countryOfOrigin": "PT",
            "attributes": {}
          }
        ]
      },
      {
        "id": "shipment-2",
        "value": 29.99,
        "origin": {
          "countryCode": "US",
          "administrativeArea": "OR",
          "locality": "Florence",
          "postalCode": "97439",
          "lines": ["3281 Center Street"]
        },
        "destination": {
          "countryCode": "US",
          "administrativeArea": "CA",
          "locality": "San Francisco",
          "postalCode": "94105",
          "lines": ["123 Market St"]
        },
        "items": [
          {
            "lineId": "line-2",
            "sku": "TSHIRT-BLK-M",
            "variantName": "Classic T-Shirt — Black, Medium",
            "productName": "Classic T-Shirt",
            "productId": "product-101",
            "variantId": "variant-501",
            "quantity": 1,
            "unitPrice": 29.99,
            "unitOriginalPrice": 39.99,
            "weightGrams": 200,
            "lengthMm": 300,
            "widthMm": 250,
            "heightMm": 50,
            "harmonizedCommodityCode": "6109.10",
            "countryOfOrigin": "PT",
            "attributes": {}
          }
        ]
      }
    ],
    "customer": {
      "type": "customer",
      "id": "12345",
      "email": "customer@example.com",
      "phoneNumber": "+14155551234"
    }
  }
}

Example Response

Example Response: Per-DeliveryGroup with Optimizations

{
  "responseState": "COMPLETE",
  "data": {
    "perGroup": {
      "deliveryGroups": [
        {
          "id": "shipment-1",
          "preselectedOption": "opt-dhl-express",
          "options": [
            {
              "id": "opt-dhl-express",
              "displayName": "DHL Express",
              "price": 12.99,
              "currencyCode": "USD",
              "carrierName": "DHL",
              "serviceCode": "EXPRESS",
              "deliveryType": "TO_DOOR",
              "requiresLocation": false,
              "description": "Next business day delivery",
              "iconUrl": "https://cdn.provider.com/icons/dhl.svg",
              "etd": {
                "relative": { "units": "BUSINESS_DAYS", "min": 1, "max": 1 },
                "absolute": { "from": "2026-02-25T08:00:00-05:00", "to": "2026-02-25T18:00:00-05:00" }
              },
              "customerChoices": [
                {
                  "id": "doorcode",
                  "displayName": "Doorcode",
                  "description": "Enter the doorcode for delivery",
                  "type": "INPUT"
                }
              ]
            },
            {
              "id": "opt-ups-pickup",
              "displayName": "UPS Access Point",
              "price": 5.99,
              "currencyCode": "USD",
              "carrierName": "UPS",
              "serviceCode": "EXPRESS",
              "deliveryType": "PICKUP",
              "requiresLocation": true,
              "description": "Next business day delivery",
              "iconUrl": "https://cdn.provider.com/icons/ups.svg",
              "etd": {
                "relative": { "units": "BUSINESS_DAYS", "min": 1, "max": 1 },
                "absolute": { "from": "2026-02-25T08:00:00-05:00", "to": "2026-02-25T18:00:00-05:00" }
              },
              "locations": [
                {
                  "id": "opt-ups-pickup-loc-1",
                  "displayName": "UPS Access Point — Fitzgerald Ave",
                  "address": {
                    "lines": ["1215 Fitzgerald Ave"],
                    "locality": "San Francisco",
                    "administrativeArea": "CA",
                    "postalCode": "94124",
                    "countryCode": "US"
                  },
                  "latitude": 37.7320,
                  "longitude": -122.3891,
                  "distanceMeters": 320,
                  "openingHoursText": "Mon–Fri 07–22, Sat 09–14 / 15–18, Sun 10–16",
                  "openingHours": [
                    { "day": "monday", "open": "07:00", "close": "22:00" },
                    { "day": "tuesday", "open": "07:00", "close": "22:00" },
                    { "day": "wednesday", "open": "07:00", "close": "22:00" },
                    { "day": "thursday", "open": "07:00", "close": "22:00" },
                    { "day": "friday", "open": "07:00", "close": "22:00" },
                    { "day": "saturday", "open": "09:00", "close": "14:00" },
                    { "day": "saturday", "open": "15:00", "close": "18:00" },
                    { "day": "sunday", "open": "10:00", "close": "16:00" }
                  ]
                },
                {
                  "id": "opt-ups-pickup-loc-2",
                  "displayName": "UPS Access Point — Diamond St",
                  "address": {
                    "lines": ["1228 Diamond St"],
                    "locality": "San Francisco",
                    "administrativeArea": "CA",
                    "postalCode": "94131",
                    "countryCode": "US"
                  },
                  "latitude": 37.7410,
                  "longitude": -122.4338,
                  "distanceMeters": 850,
                  "openingHoursText": "Mon–Fri 08–22, Sat 09–17, Sun 10–17"
                }
              ]
            }
          ]
        },
        {
          "id": "shipment-2",
          "preselectedOption": "opt-dhl-express",
          "options": [
            {
              "id": "opt-dhl-express",
              "displayName": "DHL Express",
              "price": 8.99,
              "currencyCode": "USD",
              "carrierName": "DHL",
              "serviceCode": "EXPRESS",
              "deliveryType": "TO_DOOR",
              "requiresLocation": false,
              "description": "Next business day delivery",
              "iconUrl": "https://cdn.provider.com/icons/dhl.svg",
              "etd": {
                "relative": { "units": "BUSINESS_DAYS", "min": 1, "max": 1 },
                "absolute": { "from": "2026-02-25T08:00:00-05:00", "to": "2026-02-25T18:00:00-05:00" }
              },
              "customerChoices": [
                {
                  "id": "doorcode",
                  "displayName": "Doorcode",
                  "description": "Enter the doorcode for delivery",
                  "type": "INPUT"
                }
              ]
            }
          ]
        }
      ],
      "omniOptions": [
        {
          "id": "opt-bike-express",
          "displayName": "Bike Express",
          "price": 20.99,
          "currencyCode": "USD",
          "carrierName": "BKE",
          "serviceCode": "EXPRESS",
          "deliveryType": "TO_DOOR",
          "requiresLocation": false,
          "description": "Same day delivery",
          "iconUrl": "https://cdn.provider.com/icons/bke.svg",
          "etd": {
            "relative": { "units": "HOURS", "min": 2, "max": 4 }
          },
          "expireAfter": "2026-02-24T11:00:00Z",
          "customerChoices": [
            {
              "id": "doorcode",
              "displayName": "Doorcode",
              "description": "Enter the doorcode for delivery",
              "type": "INPUT"
            }
          ],
          "brickAndMortar": 123
        },
        {
          "id": "opt-store-pickup",
          "displayName": "Client Store San Francisco",
          "price": 0.00,
          "currencyCode": "USD",
          "carrierName": "",
          "serviceCode": "PICKUP",
          "deliveryType": "PICKUP",
          "requiresLocation": true,
          "description": "Pickup from store",
          "iconUrl": "https://cdn.provider.com/icons/pickup.svg",
          "brickAndMortar": 123,
          "locations": [
            {
              "id": "opt-store-pickup-loc-2",
              "displayName": "Client Store — Diamond St",
              "address": {
                "lines": ["1228 Diamond St"],
                "locality": "San Francisco",
                "administrativeArea": "CA",
                "postalCode": "94131",
                "countryCode": "US"
              },
              "latitude": 40.7527,
              "longitude": -73.9772,
              "distanceMeters": 850,
              "openingHoursText": "Mon–Fri 10–17, Sat 11–14",
              "brickAndMortar": 123
            }
          ]
        }
      ]
    },
    "optimizeFor": [
      {
        "type": "applePay",
        "preselectedOption": "opt-dhl-express",
        "options": [
          {
            "id": "opt-dhl-express",
            "displayName": "DHL Express",
            "price": 18.99,
            "currencyCode": "USD",
            "carrierName": "DHL",
            "serviceCode": "EXPRESS",
            "deliveryType": "TO_DOOR",
            "requiresLocation": false,
            "description": "Next business day delivery",
            "iconUrl": "https://cdn.provider.com/icons/dhl.svg",
            "etd": {
              "relative": { "units": "BUSINESS_DAYS", "min": 1, "max": 1 },
              "absolute": { "from": "2026-02-25T08:00:00-05:00", "to": "2026-02-25T18:00:00-05:00" }
            }
          }
        ]
      }
    ]
  }
}

Example Response: Flat Options

{
  "responseState": "COMPLETE",
  "data": {
    "flat": {
      "preselectedOption": "opt-dhl-express",
      "options": [
        {
          "id": "opt-dhl-express",
          "displayName": "DHL Express",
          "price": 18.99,
          "currencyCode": "USD",
          "carrierName": "DHL",
          "serviceCode": "EXPRESS",
          "deliveryType": "TO_DOOR",
          "requiresLocation": false,
          "description": "Next business day delivery",
          "etd": {
            "relative": { "units": "BUSINESS_DAYS", "min": 1, "max": 3 },
            "absolute": { "from": "2026-02-25T08:00:00-05:00", "to": "2026-02-27T18:00:00-05:00" }
          },
          "customerChoices": [
            {
              "id": "doorcode",
              "displayName": "Doorcode",
              "description": "Enter the doorcode for delivery",
              "type": "INPUT"
            }
          ],
          "expireAfter": "2026-02-24T10:10:00Z",
          "customData": [
            { "key": "service-level-id", "value": "SLA-NEXT-DAY-US" }
          ]
        }
      ]
    },
    "customData": [
      { "key": "provider-session-id", "value": "sess-abc123" }
    ]
  }
}

Example Response: Partial options to a EXPRESS request context

{
  "responseState": "PARTIAL",
  "data": {
    "optimizeFor": [
      {
        "type": "applePay",
        "preselectedOption": "opt-dhl-express",
        "options": [
          {
            "id": "opt-dhl-express",
            "displayName": "DHL Express",
            "price": 18.99,
            "currencyCode": "USD",
            "carrierName": "DHL",
            "serviceCode": "EXPRESS",
            "deliveryType": "TO_DOOR",
            "requiresLocation": false,
            "description": "Next business day delivery",
            "etd": {
              "relative": { "units": "BUSINESS_DAYS", "min": 1, "max": 3 },
              "absolute": { "from": "2026-02-25T08:00:00-05:00", "to": "2026-02-27T18:00:00-05:00" }
            },
            "customerChoices": [
              {
                "id": "doorcode",
                "displayName": "Doorcode",
                "description": "Enter the doorcode for delivery",
                "type": "INPUT"
              }
            ],
            "expireAfter": "2026-02-24T10:10:00Z"
          }
        ]
      }
    ]
  }
}

Example Response: Error

No available rates for the given address and items — returns HTTP 400:

{
  "data": {
    "code": "NO_RATES_AVAILABLE",
    "message": "No rates found"
  }
}

Request Type: optionLocations

Called by Centra to retrieve pickup locations near a given address, for example to populate a location picker before the customer has selected a shipping option.

Idempotency / Concurrency

This call has no idempotency requirements. Centra may issue concurrent requests for different addresses.

Error Handling

For any response code other than HTTP 200 OK, Centra will show no pickup locations for the given address. For signature verification errors, return HTTP 401 Unauthorized.

Request Data Fields

Field	Required	Type	Description
selectionId	Y	string	Unique identifier for the current selection
optionId	Y	string	ID of the shipping option to retrieve pickup locations for
address	N	object	Address to find nearby pickup locations for
latitude	N	number	Geographic latitude of the customer for distance calculation
longitude	N	number	Geographic longitude of the customer for distance calculation

Success Response

Field	Required	Type	Description
data	Y	object	Response data
data.locations	Y	array	Array of location objects near the address

Example Request

{
  "requestType": "optionLocations",
  "data": {
    "selectionId": "sel-abc123def456",
    "optionId": "opt-ups-pickup",
    "address": {
      "lines": ["123 Market St"],
      "locality": "San Francisco",
      "administrativeArea": "CA",
      "postalCode": "94105",
      "countryCode": "US"
    },
    "latitude": 37.7941,
    "longitude": -122.3953
  }
}

Example Response

{
  "data": {
    "locations": [
      {
        "id": "loc-ups-fitzgerald",
        "displayName": "UPS Access Point — Fitzgerald Ave",
        "address": {
          "lines": ["1215 Fitzgerald Ave"],
          "locality": "San Francisco",
          "administrativeArea": "CA",
          "postalCode": "94124",
          "countryCode": "US"
        },
        "latitude": 37.7320,
        "longitude": -122.3891,
        "distanceMeters": 320,
        "openingHoursText": "Mon–Fri 07–22, Sat 09–14 / 15–18, Sun 10–16",
        "openingHours": [
          { "day": "monday", "open": "07:00", "close": "22:00" },
          { "day": "tuesday", "open": "07:00", "close": "22:00" },
          { "day": "wednesday", "open": "07:00", "close": "22:00" },
          { "day": "thursday", "open": "07:00", "close": "22:00" },
          { "day": "friday", "open": "07:00", "close": "22:00" },
          { "day": "saturday", "open": "09:00", "close": "14:00" },
          { "day": "saturday", "open": "15:00", "close": "18:00" },
          { "day": "sunday", "open": "10:00", "close": "16:00" }
        ]
      },
      {
        "id": "loc-ups-diamond",
        "displayName": "UPS Access Point — Diamond St",
        "address": {
          "lines": ["1228 Diamond St"],
          "locality": "San Francisco",
          "administrativeArea": "CA",
          "postalCode": "94131",
          "countryCode": "US"
        },
        "latitude": 37.7410,
        "longitude": -122.4338,
        "distanceMeters": 850,
        "openingHoursText": "Mon–Fri 08–22, Sat 09–17, Sun 10–17"
      }
    ]
  }
}

Request Type: orderCreated

Called when a customer completes checkout using a shipping option provided by you.

Idempotency / Concurrency

This request may be sent multiple times by Centra for various reasons. Your implementation must treat repeated requests with the same selectionId as idempotent.

Caching

This request type is never cached.

Error Handling

In case of an unsuccessful response, Centra will retry the request after a 1-minute delay, up to 5 times. Respond with HTTP 400 Bad Request and error code UNPROCESSABLE to tell Centra to stop retrying.

Reaching the retry limit or responding with the error code UNPROCESSABLE will result in the order being put on hold.

Error Code	Description
UNPROCESSABLE	Not possible to process this order.

Request Data Fields

Field	Required	Type	Description
selectionId	Y	string	Unique identifier for the selection
orderNumber	Y	string	Centra order number
totalValue	Y	number	Total value of the order
currencyCode	Y	string	Currency code
locale	Y	string	Locale code
availableAttributes	Y	array	Array of strings listing attribute keys the provider may set on delivery groups
selectedOptions	Y	array	Array of selected options

orderCreated / Request: Selected Option

Field	Required	Type	Description
id	Y	string	Identifier of the selected shipping option, matching a previously returned option
price	Y	number	Price as provided for the option
finalPrice	Y	number	Final price of the selected option, which may differ from the price provided by the ESE if additional discounts were applied
location	N	object	Location reference, present when a pickup was selected
customerChoices	N	array	Array of customer choice values
deliveryGroups	Y	array	Array of delivery groups covered by this option

orderCreated / Request: DeliveryGroup

Field	Required	Type	Description
id	Y	string	Unique identifier for this delivery group
origin	Y	object	Address items will be shipped from
destination	Y	object	Address items will be shipped to
items	Y	array	Array of items included in the delivery group

orderCreated / Request: Location Reference

Field	Required	Type	Description
id	Y	string	Identifier of the selected pickup location

orderCreated / Request: Customer Choice Value

Field	Required	Type	Description
id	Y	string	Identifier of the customer choice
value	Y	string	Value selected or entered by the customer

Response Data Fields

Field	Required	Type	Description
deliveryGroups	Y	array	Array of delivery groups, one per request delivery group

orderCreated / Response: DeliveryGroup

Field	Required	Type	Description
id	Y	string	Identifier matching the corresponding delivery group in the request
attributes	N	array	Array of attributes to set on the delivery group. Omit if there is nothing to set.

orderCreated / Response: Attribute

Field	Required	Type	Description
key	Y	string	Attribute key; must match one of the values in `availableAttributes` from the request
value	Y	string	Value to set for the attribute

Example Request: Single Option Per Delivery Group

{
  "requestType": "orderCreated",
  "data": {
    "selectionId": "asd123",
    "orderNumber": "1234567890",
    "totalValue": 123.45,
    "currencyCode": "USD",
    "locale": "en-US",
    "availableAttributes": ["tos-id", "doorcode"],
    "selectedOptions": [
      {
        "id": "opt-ups-pickup",
        "price": 5.99,
        "finalPrice": 5.99,
        "location": { "id": "opt-ups-pickup-loc-2" },
        "deliveryGroups": [
          {
            "id": "shipment-1",
            "origin": {
              "countryCode": "US",
              "administrativeArea": "NJ",
              "locality": "East Hanover",
              "postalCode": "07936",
              "lines": ["27 Merry Ln", "apt. 111"]
            },
            "destination": {
              "countryCode": "US",
              "administrativeArea": "CA",
              "locality": "San Francisco",
              "postalCode": "94105",
              "lines": ["123 Market St"]
            },
            "items": [
              {
                "lineId": "line-1",
                "sku": "TSHIRT-BLK-M",
                "variantName": "Classic T-Shirt — Black, Medium",
                "productName": "Classic T-Shirt",
                "productId": "product-101",
                "variantId": "variant-501",
                "quantity": 2,
                "unitPrice": 29.99,
                "unitOriginalPrice": 39.99,
                "weightGrams": 200,
                "lengthMm": 300,
                "widthMm": 250,
                "heightMm": 50,
                "harmonizedCommodityCode": "6109.10",
                "countryOfOrigin": "PT",
                "attributes": {}
              }
            ]
          }
        ]
      },
      {
        "id": "opt-dhl-express",
        "price": 8.99,
        "finalPrice": 7.99,
        "customerChoices": [
          { "id": "doorcode", "value": "1579" }
        ],
        "deliveryGroups": [
          {
            "id": "shipment-2",
            "origin": {
              "countryCode": "US",
              "administrativeArea": "OR",
              "locality": "Florence",
              "postalCode": "97439",
              "lines": ["3281 Center Street"]
            },
            "destination": {
              "countryCode": "US",
              "administrativeArea": "CA",
              "locality": "San Francisco",
              "postalCode": "94105",
              "lines": ["123 Market St"]
            },
            "items": [
              {
                "lineId": "line-2",
                "sku": "TSHIRT-BLK-M",
                "variantName": "Classic T-Shirt — Black, Medium",
                "productName": "Classic T-Shirt",
                "productId": "product-101",
                "variantId": "variant-501",
                "quantity": 1,
                "unitPrice": 29.99,
                "unitOriginalPrice": 39.99,
                "weightGrams": 200,
                "lengthMm": 300,
                "widthMm": 250,
                "heightMm": 50,
                "harmonizedCommodityCode": "6109.10",
                "countryOfOrigin": "PT",
                "attributes": {}
              }
            ]
          }
        ]
      }
    ]
  }
}

Example Response: Single Option Per Delivery Group

{
  "data": {
    "deliveryGroups": [
      {
        "id": "shipment-1",
        "attributes": [
          { "key": "tos-id", "value": "asd123" }
        ]
      },
      {
        "id": "shipment-2",
        "attributes": [
          { "key": "tos-id", "value": "qwe987" },
          { "key": "doorcode", "value": "1579" }
        ]
      }
    ]
  }
}

Example Request: Single Option for Multiple Delivery Groups

{
  "requestType": "orderCreated",
  "data": {
    "selectionId": "asd123",
    "orderNumber": "1234567890",
    "totalValue": 123.45,
    "currencyCode": "USD",
    "locale": "en-US",
    "availableAttributes": ["tos-id", "doorcode"],
    "selectedOptions": [
      {
        "id": "opt-dhl-express",
        "price": 8.99,
        "finalPrice": 7.99,
        "customerChoices": [
          { "id": "doorcode", "value": "1579" }
        ],
        "deliveryGroups": [
          {
            "id": "shipment-1",
            "origin": {
              "countryCode": "US",
              "administrativeArea": "NJ",
              "locality": "East Hanover",
              "postalCode": "07936",
              "lines": ["27 Merry Ln", "apt. 111"]
            },
            "destination": {
              "countryCode": "US",
              "administrativeArea": "CA",
              "locality": "San Francisco",
              "postalCode": "94105",
              "lines": ["123 Market St"]
            },
            "items": [
              {
                "lineId": "line-1",
                "sku": "TSHIRT-BLK-M",
                "variantName": "Classic T-Shirt — Black, Medium",
                "productName": "Classic T-Shirt",
                "productId": "product-101",
                "variantId": "variant-501",
                "quantity": 2,
                "unitPrice": 29.99,
                "unitOriginalPrice": 39.99,
                "weightGrams": 200,
                "lengthMm": 300,
                "widthMm": 250,
                "heightMm": 50,
                "harmonizedCommodityCode": "6109.10",
                "countryOfOrigin": "PT",
                "attributes": {}
              }
            ]
          },
          {
            "id": "shipment-2",
            "origin": {
              "countryCode": "US",
              "administrativeArea": "OR",
              "locality": "Florence",
              "postalCode": "97439",
              "lines": ["3281 Center Street"]
            },
            "destination": {
              "countryCode": "US",
              "administrativeArea": "CA",
              "locality": "San Francisco",
              "postalCode": "94105",
              "lines": ["123 Market St"]
            },
            "items": [
              {
                "lineId": "line-2",
                "sku": "TSHIRT-BLK-M",
                "variantName": "Classic T-Shirt — Black, Medium",
                "productName": "Classic T-Shirt",
                "productId": "product-101",
                "variantId": "variant-501",
                "quantity": 1,
                "unitPrice": 29.99,
                "unitOriginalPrice": 39.99,
                "weightGrams": 200,
                "lengthMm": 300,
                "widthMm": 250,
                "heightMm": 50,
                "harmonizedCommodityCode": "6109.10",
                "countryOfOrigin": "PT",
                "attributes": {}
              }
            ]
          }
        ]
      }
    ]
  }
}

Example Response: Single Option for Multiple Delivery Groups

{
  "data": {
    "deliveryGroups": [
      {
        "id": "shipment-1",
        "attributes": [
          { "key": "tos-id", "value": "qwe987" },
          { "key": "doorcode", "value": "1579" }
        ]
      },
      {
        "id": "shipment-2",
        "attributes": [
          { "key": "tos-id", "value": "qwe987" },
          { "key": "doorcode", "value": "1579" }
        ]
      }
    ]
  }
}

Example Error Response

Will place the order on hold in Centra, preventing further processing.

{
  "data": {
    "code": "UNPROCESSABLE",
    "message": "No provider for given destination."
  }
}

Request Type: testConnection

Verifies that request signing is working correctly and that the integration endpoint is reachable and configured. Respond with HTTP 200 OK with empty payload on success.

Request Data Fields

Field	Required	Type	Description
test	Y	string	Unicode test string sent by Centra

Example Request

{
  "requestType": "testConnection",
  "data": {
    "test": "Héllo Wörld Zażółć gęślą jaźń こんにちは世界 Björk säger: ångström är en enhet. Pokój wszystkim! 日本語テスト。"
  }
}

Example Success Response

HTTP 200 OK, with empty payload.

Example Error Response

HTTP 401 Unauthorized with empty payload — returned when the request signature cannot be verified.

High Level Flow​

Configuring/Installing the Integration​

Available Configuration Options​

Attribute configuration​

Request Structure​

Request Signature​

Request Payload Fields​

Request Types​

Request Headers​

Persisting Data For Orders​

Request Type: shippingOptions​

Idempotency / Concurrency​

shippingOptions: Request Context​

Caching​

Error Handling​

Request Data Fields​

shippingOptions / Request: Discount​

shippingOptions / Request: Market​

shippingOptions / Request: Customer​

shippingOptions / Request: OptimizeFor​

shippingOptions / Request: DeliveryGroup​

Shared: Address​

Shared: Item​

Success Response​

shippingOptions / Response: responseState​

shippingOptions / Response: Success​

shippingOptions / Response: Flat​

shippingOptions / Response: PerGroup​

shippingOptions / Response: DeliveryGroup​

shippingOptions / Response: OptimizeFor​

shippingOptions / Response: Option​

shippingOptions / Response: Custom Data​

shippingOptions / Response: ETD​

shippingOptions / Response: ETD Relative​

shippingOptions / Response: ETD Absolute​

shippingOptions / Response: Location​

shippingOptions / Response: Location Opening Hours​

shippingOptions / Response: Label​

shippingOptions / Response: Customer Choice​

shippingOptions / Response: Customer Choice Option​

shippingOptions / Response: Error​

Example Request​

Example Response​

Example Response: Per-DeliveryGroup with Optimizations​

Example Response: Flat Options​

Example Response: Partial options to a EXPRESS request context​

Example Response: Error​

Request Type: optionLocations​

Idempotency / Concurrency​

Error Handling​

Request Data Fields​

Success Response​

Example Request​

Example Response​

Request Type: orderCreated​

Idempotency / Concurrency​

Caching​

Error Handling​

Request Data Fields​

orderCreated / Request: Selected Option​

orderCreated / Request: DeliveryGroup​

orderCreated / Request: Location Reference​

orderCreated / Request: Customer Choice Value​

Response Data Fields​

orderCreated / Response: DeliveryGroup​

orderCreated / Response: Attribute​

Example Request: Single Option Per Delivery Group​

Example Response: Single Option Per Delivery Group​

Example Request: Single Option for Multiple Delivery Groups​

Example Response: Single Option for Multiple Delivery Groups​

Example Error Response​

Request Type: testConnection​

Request Data Fields​

Example Request​

Example Success Response​

Example Error Response​

High Level Flow

Configuring/Installing the Integration

Available Configuration Options

Attribute configuration

Request Structure

Request Signature

Request Payload Fields

Request Types

Request Headers

Persisting Data For Orders

Request Type: shippingOptions

Idempotency / Concurrency

shippingOptions: Request Context

Caching

Error Handling

Request Data Fields

shippingOptions / Request: Discount

shippingOptions / Request: Market

shippingOptions / Request: Customer

shippingOptions / Request: OptimizeFor

shippingOptions / Request: DeliveryGroup

Shared: Address

Shared: Item

Success Response

shippingOptions / Response: responseState

shippingOptions / Response: Success

shippingOptions / Response: Flat

shippingOptions / Response: PerGroup

shippingOptions / Response: DeliveryGroup

shippingOptions / Response: OptimizeFor

shippingOptions / Response: Option

shippingOptions / Response: Custom Data

shippingOptions / Response: ETD

shippingOptions / Response: ETD Relative

shippingOptions / Response: ETD Absolute

shippingOptions / Response: Location

shippingOptions / Response: Location Opening Hours

shippingOptions / Response: Label

shippingOptions / Response: Customer Choice

shippingOptions / Response: Customer Choice Option

shippingOptions / Response: Error

Example Request

Example Response

Example Response: Per-DeliveryGroup with Optimizations

Example Response: Flat Options

Example Response: Partial options to a EXPRESS request context

Example Response: Error

Request Type: optionLocations

Idempotency / Concurrency

Error Handling

Request Data Fields

Success Response

Example Request

Example Response

Request Type: orderCreated

Idempotency / Concurrency

Caching

Error Handling

Request Data Fields

orderCreated / Request: Selected Option

orderCreated / Request: DeliveryGroup

orderCreated / Request: Location Reference

orderCreated / Request: Customer Choice Value

Response Data Fields

orderCreated / Response: DeliveryGroup

orderCreated / Response: Attribute

Example Request: Single Option Per Delivery Group

Example Response: Single Option Per Delivery Group

Example Request: Single Option for Multiple Delivery Groups

Example Response: Single Option for Multiple Delivery Groups

Example Error Response

Request Type: testConnection

Request Data Fields

Example Request

Example Success Response

Example Error Response