--- schema_version: "1" id: dcb19ae48e6223311a75eef484d1d0adcb09a05ddce149164bcbdaa48bd2d81f title: Shipment SPI collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/shipment-spi.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/shipment-spi source_site: developer.salesforce.com content_type: documentation content_hash: 035eb98952bc90a79fc17433331a0584f2e59a2d664313e14c95905b97a32f88 products: - Point of Sale for Developers - Salesforce APIs --- Shipment SPI # Shipment SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/shipment-spi/shipment-spi-oas-public.yaml) Merchant SPI to implement and provide an endpoint for the POS to trigger and get applicable shipping options and shipping labels. Merchants must provide an implementation of this API if they want the POS to trigger and get applicable shipping methods via their endpoint. **Version:** 2.3.4 ## Tags ### Shipment Spi [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/shipment-spi/shipment-spi-oas-public.yaml) Merchant SPI to implement and provide an endpoint for the POS to trigger and get applicable shipping options and shipping labels. Merchants must provide an implementation of this API if they want the POS to trigger and get applicable shipping methods via their endpoint. ## Operations ### POST Retrieve shipping label. `POST /merchant/spi/sample/endpoint/sa/shipping/to/get/shippingLabel/from/external/system` Operation ID: `getShippingLabel`. Tags: Shipment Spi. Retrieve shipping label from merchant's system. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details: 1. Under **API Config**: * **API Key:** `SHIPPING_LABEL` * **API Endpoint:** Provide the external endpoint 2. Under **JSON Config**: * **Integration Type:** `HTTP_POST` * **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the shipping label from an external system during BOFIS fulfillment or Inventory Transfer flows. #### Request body Media type: `application/json`. Schema: `ShipmentSpiRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `ShipmentLabelSpiResponse`. ### POST Retrieve shipping options. `POST /merchant/spi/sample/endpoint/sa/shipping/to/get/shippingOptions/from/external/system` Operation ID: `getShippingOptions`. Tags: Shipment Spi. Retrieve shipping options from merchant's system. Merchants must implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details: 1. Under **API Config**: * **API Key:** `SHIPPING_OPTIONS` * **API Endpoint:** Provide the external endpoint 2. Under **JSON Config**: * **Integration Type:** `HTTP_POST` * **JSON Headers:** Provide the header for the API. Headers can be Content-Type, Authorization attributes like clientId/password, for example: {"Content-Type":"application/json","client\_id":"myClientId","client\_secret":"myClientSecret"} **Use Case:** To fetch the shipping options from an external system during BOFIS fulfillment or Inventory Transfer flows. #### Request body Media type: `application/json`. Schema: `ShipmentSpiRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `ShipmentOptionSpiResponse`. ## Schemas ### ShipmentSpiRequest * `shipmentContext` (_string_, required) Shipment context. Provides the context of the request, indicating whether it is related to a BOFIS order or inventory transfer. Allowed values: `ORDER`, `RETURN_TO_VENDOR`, `STORE_TO_STORE_TRANSFER`, `CORP_TRANSFER`. * `requestTime` (_integer (int64)_, required) Request time in epoch milliseconds. * `storeId` (_string_, required) ID of the store that fulfills the shipment. * `storeAssociateId` (_string_, required) ID of the store associate. * `orderId` (_string_) Order number of BOFIS order or inventory transfer. * `customerName` (_string_) Customer name. * `fromAddress` (_SPIAddress_, required) * `shippingAddress` (_SPIAddress_, required) * `store` (_Store_) * `packageDimension` (_PackageDimension_) * `itemWeight` (_number_) Total weight of all items in the package. * `items` (_array of ShipmentItem_) Items in the package. * `packageValue` (_number_) Cost of the package (item total). ### ShipmentLabelSpiResponse * `errorMessage` (_string_) Error Message. * `errorCode` (_string_) Error Code. * `shippingLabelLink` (_string_, required) Link to shipping label image. The image must be in PNG format. * `trackingNumber` (_string_) Tracking number corresponding to the shipping label link. * `shippingMethod` (_ShippingOption_, required) * `packageDimension` (_PackageDimension_, required) * `itemWeight` (_number_, required) Replay the provided item weight. ### ShipmentOptionSpiResponse * `errorMessage` (_string_) Error Message. * `errorCode` (_string_) Error Code. * `shippingMethodList` (_array of ShippingOption_, required) Shipping method options. ### SPIAddress The full address of the destination of transaction. * `firstName` (_string_) Customer first name saved for address. * `lastName` (_string_) Customer last name saved for address. * `addressLine1` (_string_, required) Address Line 1. * `addressLine2` (_string_) Address Line 2. * `city` (_string_, required) City. * `state` (_string_) State. * `postalCode` (_string_, required) Postal Code. * `countryCode` (_string_, required) Country Code. * `phone` (_string_) Phone. * `storeId` (_string_) Store ID if it is store address. * `emailAddress` (_string_) Customer Email Address. ### Store Pickup location - POS enables the store to place an order in one store and allow the customer to pick up the order from another store (i.e., IN\_STORE/SHIP\_TO\_STORE). In such a case, pickup store information is maintained here. * `storeId` (_string_, required) Store ID field to be provided by app. * `name` (_string_, required) Store name. * `addressLine1` (_string_, required) Store Address Line1. * `addressLine2` (_string_, nullable) Store Address Line2. * `city` (_string_, required) City. * `state` (_string_, required) State. * `postalCode` (_string_, nullable) Postal code. Mandatory if the store is configured in CMS with postal code. * `countryCode` (_string_, required) Country Code. * `email` (_string_, nullable) Store's email ID. Mandatory if the store is configured in CMS with email ID. * `phone` (_string_, nullable) Store's phone. Mandatory if the store is configured in CMS with phone. * `fax` (_string_, nullable) Store's fax. Mandatory if the store is configured in CMS with fax. * `hours` (_array of Hours_, nullable) Store's operational hours. Mandatory if the store is configured in CMS with operational hours. * `latitude` (_number (double)_, nullable) Store's latitude. Mandatory if the store is configured in CMS with latitude. * `longitude` (_number (double)_, nullable) Store's longitude. Mandatory if the store is configured in CMS with longitude. * `storeType` (_string_, nullable) Store type. Allowed values: `Regular`, `Popup`, `Outlet`, `Ecomm`, `Warehouse`, `DistributionCenter`, `Vendor`. Default: `Regular`. * `timeZoneId` (_string_, nullable) Store's timezone ID. Mandatory if the store is configured in CMS with timezone ID. * `storeGroupID` (_string_) ### PackageDimension Dimension of package being shipped. * `length` (_number_, required) Length of the package. Example: `12.2`. * `height` (_number_, required) Height of the package. Example: `12.2`. * `width` (_number_, required) Width of the package. Example: `12.2`. ### ShipmentItem Items in the package. * `productId` (_string_) Product ID. * `quantity` (_integer (int32)_) Number of items. * `orderItemId` (_string_) Item sequence or system-generated item ID assigned to this line item. Must be unique within this order. Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`. * `shippingMethodId` (_string_) Unique Identifier for the Shipping Method. * `shippingCarrier` (_string_) Shipping carrier, for example, UPS, USPS, FedEx, or DHL. * `deliveryDate` (_integer (int64)_) Expected delivery date in epoch in millis. * `deliveryTimeSlot` (_string_) Expected delivery time slot. Example: `09:00 - 12:00`. ### ShippingOption Shipping method options. * `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method. * `name` (_string_) Shipping Method Name. * `description` (_string_) Description. * `shippingCarrier` (_string_, required) Shipping carrier, for example, UPS, USPS, FedEx, or DHL. * `serviceLevel` (_string_) Service-level description. This is shown on the POS app. For example, 3-5 Days, 1-Day, Express, Standard, Overnight. * `price` (_number_, required) Shipping Method Price. * `sortOrder` (_integer (int32)_, required) Display rank. Helps determine display sequence of shipping methods on screen. For example, a shipping method with display rank of 1 will be displayed beforea method with display rank 2 and so on. * `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis. * `deliveryTimeSlot` (_string_, required) Expected delivery time slot. Example: `09:00 - 12:00`. ### Hours Store's operational hours. Mandatory if the store is configured in CMS with operational hours. * `day` (_string_) * `open` (_string_) * `close` (_string_)