--- schema_version: "1" id: 00093888f12bb3e756873ea86366bc3df2fc827cfd52c579c170a76d46af196d title: Shipping Method 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/shipping-method-spi.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/shipping-method-spi source_site: developer.salesforce.com content_type: documentation content_hash: d3a5eda644b153047b6aa68c4d4f14f96a7ec7b4dd026d6afbc1faaaccf0d437 products: - Point of Sale for Developers - Salesforce APIs --- Shipping Method SPI # Shipping Method SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/shipping-method-spi/shipping-method-spi-oas-public.yaml) Merchant SPI to implement and provide an endpoint for the POS to trigger and get applicable shipping methods with respect to items and shipping address of a particular cart. 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 ### Shipping Method SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/shipping-method-spi/shipping-method-spi-oas-public.yaml) Merchant SPI to implement and provide an endpoint for the POS to trigger and get applicable shipping methods with respect to items and shipping address of a particular cart. 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 Return applicable shipping methods. `POST /merchant/spi/sample/endpoint/sa/shipping/methods` Operation ID: `shippingMethods`. Tags: Shipping Method SPI. Return applicable shipping options. This merchant-provided API takes in cart items that are marked for shipping or delivery, customerId, address, etc. as input and provides applicable shipping options. **Note:** Only the items marked for shipping or delivery are sent in the request. In-store or Pick Up Later items are not sent as part of this request. #### Request body Media type: `application/json`. Schema: `ShippingMethodsRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `ShippingMethodsResponse`. ## Schemas ### ShippingMethodsRequest * `customerId` (_string_) Identifier of the customer associated with this cart. * `cartItemList` (_array of ShippingSPIProduct_, required) List of items in cart which require shipping to a particular address. ### ShippingMethodsResponse * `shippingMethods` (_array of ShippingMethod_) List of all shipping methods that can be applied to cart. ### ShippingSPIProduct Details of an item available in the cart. Includes mandatory and optional item attributes. The optional attributes are provided only if they are configured with product field mapping. Product field mapping is available under **CMS** > **Feeds** > **Field Mappings** > **Products**. To learn more about field mapping, salesforce.com/docs/commerce/retail-cloud/guide/clienteling-spi-field-mapping.html. * `productId` (_string_, required) Distinct product ID for each combination of variations, for example, size or color. Example: `3661601595547`. * `title` (_string_, required) Product title. Example: `E18PENDANT1`. * `description` (_string_, required) Product description. Example: `Number 1 medallion`. * `productClass` (_string_, required) Product class of the item. Example: `Merchandise`. * `categories` (_array of string_) Merchant categories of the product. A pipe-separated list of category names belongs to this product. Items: Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`. Example: `Accessories > Categories > Jewelry, New Arrival > Jewelry`. * `googleCategory` (_string_) Product categories for Google search. Example: `Accessories > Categories > Jewelry`. * `imageUrl` (_string_) Image url of the product. Example: `https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html`. * `additionalImageUrls` (_array of string_) Additional image urls of the product. Items: Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`. Example: `['https://us.ps.com/en/categories/jewelry/numero1/3661601595547.html','https://us.ps.com/en/categories/jewelry/numero1/3661601595548.html']`. * `condition` (_string_) Product condition. Allowed values: `NEW`, `USED`, `REFURBISHED`, `NEW, USED, REFURBISHED` . Example: `NEW`. * `availability` (_string_) Free text value that provides information about the availability of the product. Example: `Available`. * `listPrice` (_number (double)_, required) Listing price of the product. Example: `60`. * `salePrice` (_number (double)_, required) Sale price of the product. It can be same as listing price. Example: `60`. * `storePrice` (_number (double)_) Store specific price of the product. Example: `55`. * `currencyCode` (_string_) ISO currency code. Default: `USD`. Minimum length: 3. Maximum length: 3. Example: `USD`. * `brand` (_string_) Product's brand. Example: `Gucci`. * `gtin` (_string_) Product's GTIN. It can be one of UPC, EAN, JAN, ISBN, or ITF-14. Minimum length: 12. Maximum length: 14. Example: `065100004327`. * `mpn` (_string_) Manufacturer part number. Example: `100-440-0.750-3434-A`. * `gender` (_string_) Free text to provide gender related to the product. Example: `Unisex`. * `ageGroup` (_string_) Free text to provide age group related to the product. Example: `10-45`. * `subVariantGroupId` (_string_) Sub variant group id. * `variantGroupId` (_string_, required) Group id of the product. All the different variations of the product are grouped together under a single group id. Example: `E18PENDANT1`. * `color` (_string_) Product color. Example: `Silver`. * `colorSwatchUrl` (_string_) The image link for color swatches. * `size` (_string_) Product size. Example: `M`. * `pattern` (_string_) Free text to provide the product pattern. Example: `Oval`. * `sku` (_string_) SKU Id of the product. It can be same as product Id and unique per variation of the product. Example: `3661601595547`. * `isOnSale` (_boolean_, required) Specifies whether the product is on sale. Example: `false`. * `promotionTitle` (_string_, nullable) Promotion title applicable to the product. Example: `Summer22`. * `promotionPrice` (_number (double)_, nullable) Discounted price after applying promotion corresponding to the promotion title. Example: `55`. * `customString0` (_string_, nullable) Custom field of type String. * `customString1` (_string_, nullable) Custom field of type String. * `customString2` (_string_, nullable) Custom field of type String. * `customString3` (_string_, nullable) Custom field of type String. * `customString4` (_string_, nullable) Custom field of type String. * `customString5` (_string_, nullable) Custom field of type String. * `customString6` (_string_, nullable) Custom field of type String. * `customString7` (_string_, nullable) Custom field of type String. * `customString8` (_string_, nullable) Custom field of type String. * `customString9` (_string_, nullable) Custom field of type String. * `customString10` (_string_, nullable) Custom field of type String. * `customString11` (_string_, nullable) Custom field of type String. * `customString12` (_string_, nullable) Custom field of type String. * `customInt0` (_integer (int32)_, nullable) Custom field of type Integer. * `customInt1` (_integer (int32)_, nullable) Custom field of type Integer. * `customDecimal0` (_number (float)_, nullable) Custom field of type Decimal. * `customDecimal1` (_number (float)_, nullable) Custom field of type Decimal. * `customDateTime0` (_integer (int64)_, nullable) Custom field of type Epoch time in millis. * `customDateTime1` (_integer (int64)_, nullable) Custom field of type Epoch time in millis. * `onlineInventory` (_integer (int32)_, nullable) The current online inventory. Provide a value if online inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**). * `material` (_string_, nullable) Product material. Example: `Metal`. * `manufacturer` (_string_, nullable) Manufacturer of the product. Example: `ABC Jewellers`. * `sizeGuideUrl` (_string_, nullable) Image url of the size guide. * `manufacturerDetails` (_string_, nullable) Manufacturer details. * `manufacturerLocation` (_string_, nullable) Location of product manufacturer. * `productLocation` (_string_, nullable) Product manufacturing location. * `banner` (_string_, nullable) Banner text. If provided, it will be shown on PLP and PDP screens. * `availableStores` (_array of string_, nullable) List of stores where the product is available. * `lastUpdate` (_string (date-time)_) * `storeInventory` (_integer (int32)_, nullable) The current store inventory. Provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**). * `isVirtual` (_boolean_, nullable) Specifies whether the product is available only in online mode (true) or not (false). * `multipleGTINs` (_array of string_, nullable) If the product supports multiple GTINs, provide all of them. * `storeProductDetails` (_StoreProductDetails_) * `onlineAvailableStores` (_array of string_, nullable) List of stores where online products are available. * `costPrice` (_number (double)_, nullable) Cost of per item. * `casePackQuantity` (_integer (int32)_, nullable) Number of items per case pack. * `additionalCharges` (_string_, nullable) Additional charges for CA, FR. * `casePackID` (_string_, nullable) Identifier for case pack. * `availabilityStartTime` (_string (date-time)_, nullable) Start time, when product is visible on POS. * `availabilityEndTime` (_string (date-time)_, nullable) End time, when product will not be visible on POS. * `price` (_number_, required) Unit price of this line item. * `quantity` (_integer (int32)_, required) Quantity of this line item. * `fulfillmentLocation` (_Store_, required) * `shippingAddress` (_SPIAddress_) * `deliveryDate` (_integer (int64)_) Expected delivery date in epoch in millis. * `deliveryTimeSlot` (_string_) Expected delivery time slot. Example: `09:00 - 12:00`. ### ShippingMethod Available shipping methods corresponding to this delivery group. * `shippingMethodId` (_string_, required) Unique Identifier for the Shipping Method. Maximum length: 45. Example: `001`. * `name` (_string_, required) Shipping Method Name. Maximum length: 128. Example: `Standard Shipping`. * `description` (_string_, nullable) Shipping Method Description. Maximum length: 128. * `carrier` (_string_, nullable) Shipping carrier, for example, UPS, USPS, FedEx, or DHL. Maximum length: 32. Example: `UPS`. * `serviceLevel` (_string_, nullable) Service Level Description. E.g. 3-5 Days, 1-Day, Express, Standard, Overnight. Maximum length: 128. Example: `3-5 Days`. * `price` (_number_, required) Shipping cost. * `priceAdjustments` (_array of PriceAdjustment_, nullable) Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType - PROMOTION only. * `priceAfterShippingDiscount` (_number_, nullable) Price after applying shipping discount. * `sortOrder` (_integer (int32)_) Display Order. Default: `0`. * `taxRates` (_array of ProductTaxRate_, nullable) Tax breakdown for the shipping cost. Applicable for tax countries and if the shipping cost is taxable. * `vatRates` (_array of ProductTaxRate_, nullable) VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable. * `shippingTax` (_number_, nullable) Tax amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable. * `shippingValueAddedTax` (_number_, nullable) VAT amount for the shipping cost. Applicable for vat countries and if the shipping cost is taxable. * `taxClass` (_string_, deprecated) Refer taxRates or vatRates instead to know the tax class. * `taxExemption` (_number_, nullable) Tax exemption amount for the shipping cost. Applicable for tax countries and if the shipping cost is taxable and tax exemption is applied. * `deliveryDate` (_integer (int64)_, required) Expected delivery date in epoch in millis. * `deliveryTimeSlot` (_string_, required) Expected delivery time slot. Example: `09:00 - 12:00`. * `itemLevelCharges` (_array of ItemLevelCharge_, nullable) Item level breakdown for the shipping cost and shipping discount. ### StoreProductDetails Provide details about products in the store. This includes store-level inventory, store level pricing, store level promotions, etc. You must provide a value if store inventory tracking is enabled in CMS (**CMS** > **Store Settings** > **Inventory**). * `storeId` (_string_) Store or warehouse ID. * `productId` (_string_) Product ID. * `storeInventory` (_integer (int32)_) Product sellable quantity. * `storePrice` (_number_) Product price at the store. * `storePromoText` (_string_) Product promotion text applicable to this store. * `listPrice` (_number_) Product list price. * `salesPrice` (_number_) Product sale price. * `storePromoBanner` (_string_) Product promotion banner text. * `clearanceItems` (_array of ClearanceItem_) Product location within the store. * `allocatedQuantity` (_integer (int32)_) Product quantity allocated for shipment or BOPIS orders. * `safetyStockQuantity` (_integer (int32)_) Product safety stock quantity. * `quantityOnHand` (_integer (int32)_) Product quantity on hand. * `quantityInTransit` (_integer (int32)_) Product quantity in transit to this store. * `quantityOnOrder` (_integer (int32)_) Product quantity on order for this store. * `notForSaleQuantity` (_integer (int32)_) Damaged product quantity that isn't for sale. * `returnedItemsQuantity` (_integer (int32)_) Returned product quantity that isn't for sale. * `floorDemoQuantity` (_integer (int32)_) Floor/Demo product quantity that isn't for sale. * `fullPriceSerialNumbers` (_array of string_) Full price serial numbers. * `storeOnlineQuantity` (_integer (int32)_) Online product quantity available for sale in store. * `customString0` (_string_) Custom string attribute of the product for the store. * `customString1` (_string_) Custom string attribute of the product for the store. * `quantity` (_integer (int32)_) ### 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_) ### 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. ### PriceAdjustment Price adjustments after applying shipping level promotion. Supported PriceAdjustmentType is PROMOTION only. * `description` (_string_, nullable) The price adjustment description will display the promotion name for coupon codes and the reason text for transaction discounts and price overrides. While importing an order from an external system, it is optional. Maximum length: 1500. * `adjustment` (_string (-XX.XXX or XX.XXX)_) The discount amount for display purposes. It will be negative for sold items and shipping charges and positive for returned items. Example: `-155.5`. * `price` (_number (-XX.XXX or XX.XXX)_) The discount amount. It will be negative for sold items and shipping charges and positive for returned items. Example: `-155.5`. * `id` (_string_) Price adjustment ID. In case of promotions, it is promotion ID. For price override and transaction discount, it is GUID. * `priceAdjustmentType` (_string_) Price adjustment type. Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`. * `auto` (_boolean_, nullable) Specifies whether the promotion is automatically applied or not. Applicable only for promotions. * `fulfillmentType` (_string_) Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`. * `promoCode` (_string_, nullable) Promotion code provided by customer to apply specific promotion. Applicable only for promotions. * `merchantPromotionId` (_string_, nullable) External promotion ID corresponding applied promotion. It is used to identify the promotion in external system and is relevant only if it is configured in CMS Applicable only for promotions. * `reasons` (_array of Reason_, read-only, nullable) List of reasons pertaining to the price adjustment. Applicable only for PRICE\_OVERRIDE or TRANSACTION\_DISCOUNT. * `quantity` (_integer (int32)_, read-only, nullable) Applicable only for Product level Promotion price adjustments. * `discountValue` (_number_, nullable) Applicable only for PRICE\_OVERRIDE OR TRANSACTION\_DISCOUNT.It will hold discount value either in percentage or in amount format. * `discountType` (_string_, nullable) Discount types 1. Amount: Item price or transaction-total reduced by provided amount, 2. PERCENT: Item price or transaction-total reduced by amount calculated based on provided percentage and item price/transaction-total, 3. FLAT\_PRICE: Item price is reduced to the provided amount. Not applicable to transaction discounts. The discount amount is then calculated by subtracting entered flat\_price from item-price. Allowed values: `AMOUNT`, `PERCENT`, `FLAT_PRICE`. * `rewardId` (_string_, nullable) The ID of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts. * `rewardName` (_string_, nullable) The name of the loyalty reward discount. Applicable only for loyalty coupons and loyalty discounts. * `externalId` (_string_, nullable) This identifier is used when an order is imported from an external system. If an order is placed directly in the POS, this identifier will not be available. The external system provides this identifier, which will then be replayed to that external system during order posting for any subsequent modifications like returns. Maximum length: 128. * `adjustmentAmount` (_number_) * `referenceAdjustmentId` (_string_) * `referenceAdjustmentID` (_string_, write-only) * `adjustmentType` (_string_) Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`. * `reasonText` (_string_) ### ProductTaxRate VAT breakdown for the shipping cost. Applicable for VAT countries and if the shipping cost is taxable. * `countryCode` (_string_, required) Country Code. Maximum length: 2. Example: `US`. * `state` (_string_, nullable) State. Applicable if the tax rate is specific to state. Maximum length: 128. * `postalCode` (_string_, nullable) Postal Code. Applicable if the tax rate is specific to postal code. Maximum length: 10. * `taxType` (_string_, required) Indicates the tax type, such as COUNTRY, CITY, or STATE. The following tax types are specific to the Vertex tax engine: PROVINCE, TERRITORY, APO, BOROUGH, FPO, LOCAL\_IMPROVEMENT\_DISTRICT, PARISH, SPECIAL\_PURPOSE\_DISTRICT, TOWNSHIP, TRADE\_BLOCK, and TRANSIT\_DISTRICT. Allowed values: `CLASS`, `CITY`, `DISTRICT`, `COUNTY`, `STATE`, `COUNTRY`, `ITEM_OVERRIDE`, `STORE_OVERRIDE`, `TRANSACTION_OVERRIDE`, `SPECIAL`, `PROVINCE`, `TERRITORY`, `APO`, `BOROUGH`, `FPO`, `LOCAL_IMPROVEMENT_DISTRICT`, `PARISH`, `SPECIAL_PURPOSE_DISTRICT`, `TOWNSHIP`, `TRADE_BLOCK`, `TRANSIT_DISTRICT`. * `chargeType` (_string_) Indicates if the charge is for tax or fee - TAX/FEE. Allowed values: `TAX`, `FEE`. Default: `TAX`. * `nonRefundable` (_boolean_) Specifies whether the charge (tax or fee) is refundable. Default: `false`. * `taxRate` (_number (float)_, required) % tax/vat rate. Example: `7.25`. * `taxClass` (_string_, required) The tax engine uses tax classes to apply specific tax rates to different product categories. Each product is linked to a tax class, which determines its applicable tax rate. Example: `Tax Class for Shoes and Clothing - PS0001`. * `taxCode` (_string_, required) Unique identifier for a tax rate, unique per item. * `taxAmount` (_number_, required) Total tax amount for the item corresponding to the item's tax rate. Example: `7.25`. * `perUnitTaxAmount` (_number_, required) Per unit tax amount of the item corresponding to the tax rate. Example: `1.25`. * `taxName` (_string_, required) Tax name, for example, Jurisdiction, MTA, BTW Hoog, or BTW Laag. Maximum length: 64. * `displayTaxName` (_string_, required) Display tax name, for example, Jurisdiction - 7.25%, BTW Hoog - 21%, or BTW Laag - 9%. * `corporateTaxId` (_string_, nullable) Merchant's Tax Identification Number. Example: `HST-74252RT0001`. * `printTaxName` (_string_, nullable) Print tax name for receipts. Includes merchant's tax identification number. For example: HST-74252RT0001 - 7.25%. * `externalTaxId` (_string_, nullable) Additional Tax Identifier for external systems. * `isExempt` (_boolean_, nullable) Indicates if tax is exempted. Default: `false`. * `taxDescription` (_string_, nullable) Tax Description text. * `jurisdiction` (_string_, nullable) Jurisdiction. Maximum length: 128. * `registrationNumber` (_string_, nullable) Registration Number. Maximum length: 128. * `externalId` (_string_, nullable) Identifies the current tax record in the external system. This is a record identifier, not a tax identifier. Used when an order is imported from an external system. Orders placed directly through POS don't populate this identifier. The external system provides this identifier and POS replays it during order posting for subsequent modifications such as returns. Maximum length: 128. ### ItemLevelCharge Item level breakdown for the shipping cost and shipping discount. * `orderItemId` (_string_, required) Unique sequence number assigned to cart item that belongs to the order or delivery group. Example: `It can have values like 1, 2, 3, etc...
which represents line item number within the order or Delivery Group.`. * `itemShippingCharge` (_number_) Item level shipping charge. * `itemShippingDiscountAmount` (_number_, nullable) Shipping discount that can be applied on item level shipping price due to promotion or reward. * `discountText` (_string_, nullable) Discount text of an applied promotion. Maximum length: 1500. * `promotionId` (_string_, nullable) External Merchant promotion ID corresponding applied promotion. ### ClearanceItem Product location within the store. * `serialNumber` (_string_) Serial number of the item (if applicable). * `clearancePrice` (_number_) * `itemLocationWithinStore` (_string_) * `instructionText` (_string_) ### Hours Store's operational hours. Mandatory if the store is configured in CMS with operational hours. * `day` (_string_) * `open` (_string_) * `close` (_string_) ### Reason Reason for returning the item. * `reasonCodeType` (_string_, required) Type for reason codes. It can be one of TRANSACTION\_DISCOUNT, PRICE\_OVERRIDE, RETURNS, BANK\_DEPOSIT, TILL\_RECONCILIATION, TILL\_CASH\_OUT. Allowed values: `TRANSACTION_DISCOUNT`, `PRICE_OVERRIDE`, `RETURNS`, `BANK_DEPOSIT_VARIANCE`, `TILL_RECONCILIATION_VARIANCE`, `TILL_CASH_OUT`, `PRICE_CORRECTION`, `RETURN_PRICE_CORRECTION`, `EXCLUDE_ITEM_FROM_CYCLE_COUNT`, `INVENTORY_ADJUSTMENT`, `SAFE_FLOAT_UPDATE`, `TILL_FLOAT_UPDATE`, `TILL_CASH_IN`, `TILL_NO_SALE`, `VOID_CART`, `EXPENSE_UPDATE`, `MISC_EXPENSE1_UPDATE`, `MISC_EXPENSE2_UPDATE`, `INVENTORY_ITEM_RECEIVE_MISMATCH`, `OFFLINE_GHOST_TILL`, `DELETE_ITEM`, `CORP_CANCELLATION`, `FULFILLMENT_CANCELLATIONS`. Maximum length: 64. * `reasonCode` (_string_, required) Reason code. Maximum length: 64. * `reasonText` (_string_, nullable) Reason text. Maximum length: 256.