--- schema_version: "1" id: d871b88cd73b295f0e6adf8bb571ecf4b32a90d2884481820e6c059290bfaa25 title: Activation Code 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/activation-code-spi.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/activation-code-spi source_site: developer.salesforce.com content_type: documentation content_hash: 25251fc15567745c2fd12ca8a9d31b93c93152f51c2f04daa15ce515f6a63368 products: - Point of Sale for Developers - Salesforce APIs --- Activation Code SPI # Activation Code SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/activation-code-spi/activation-code-spi-oas-public.yaml) Merchant SPI to implement and provide an endpoint for the POS. This endpoint must be configured in the POS system so that the POS can use it to get activation codes and details. **Version:** 2.3.4 ## Tags ### Activation Code SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/activation-code-spi/activation-code-spi-oas-public.yaml) Merchant SPI to implement and provide an endpoint for the POS. This endpoint must be configured in the POS system so that the POS can use it to get activation codes and details. ## Operations ### POST Retrieve activation code. `POST /merchant/spi/sample/endpoint/sa/activation/code/activation/code/from/external/system` Operation ID: `getActivationCode`. Tags: Activation Code SPI. Retrieve activation code from merchant's system based on provided input. 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:** `ACTIVATION_CODE` * **API Endpoint:** Provide the external endpoint to get activation code and details, for example: /merchant/spi/sample/endpoint/sa/activation/code 2. Under **JSON Config**: * **Integration Type:** `HTTP_POST` * **JSON Headers:** Provide the header for the API. Headers can be Content-Type, for example: {"contentType": "application/json"} **Invoke:** The SPI is invoked during the order checkout flow or submit order only if the order has a product that needs population of activation code from the external service (i.e., **CMS** > **Product Class** > **Requires Activation Code via External Source is enabled**). **Response:** If the SPI has an empty response or error, the order checkout or submit order flow is not completed and the associate sees an error. For more details, refer to [Point of Sale SPI Error Handling](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-spi-error-handling.html) #### Request body Media type: `application/json`. Schema: `ActivationCodeRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `ActivationCodeResponse`. ## Schemas ### ActivationCodeRequest * `orderId` (_string_, required) The order ID of the customer order. * `storeId` (_string_, required) The store ID of the store where the transaction is happening. * `transactionId` (_string_, required) Sale transaction ID. Example: `1-test-20240612131829-4-1`. * `productList` (_array of ExternalProduct_, required) List of products that need serialized-unit attributes. For example, activation code, context code, etc. ### ActivationCodeResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `serializedUnitDetailList` (_array of ExternalSerializedUnitDetail_) The list of attributes about a serialized unit, for example, activation code or context code. * `error` (_boolean_) ### ExternalProduct Products. * `productId` (_string_, required) Product ID. Unique identifier of an item. All the variations of an item will have distinct product ID, hence it is equivalent to SKU. * `variantGroupId` (_string_, required) Variant Group ID. All the variants of an item are grouped together under the same variant ID. * `name` (_string_, required) Name of the item. * `price` (_number_, required) Price of the item. * `quantity` (_integer (int32)_, required) Item's Quantity. * `orderItemId` (_string_, required) Item sequence/System generated item ID assigned to this line item. Must be unique within this order and should have numerical value in string. Example: `It can have values like 1, 2, 3, etc... which represents line item number within the order.`. * `imageURL` (_string_, required) Image URL of the item. * `subTotal` (_number_, required) Item's total excluding discounts, shipping costs and taxes but inclusive of VAT. * `discount` (_number_) Total discount amount applied on the item, including all discount types (manual price override, transaction discount, coupon, rewards, and auto promotions). Required if any discounts are applied. * `total` (_number_, required) Item's total — final amount charged for this item, inclusive of tax/VAT and discounts. * `size` (_string_, required) Item's size. Example: `39-42 or M or 38 etc...`. * `color` (_string_, required) Item's color. Example: `Light Grey or Black etc...`. * `itemStatus` (_string_, required) Below is the list of statuses for in-store purchases and BORIS. The statuses are applicable for both the order and its items. The significance of each status is described in detail below. The eligibility of an item for returns is determined by its current status and the status of the order. Moreover, the **returnsEligibility** attribute at the item level (productList) can also be used to regulate the return eligibility of an item. To learn more about returns eligibility, please refer to the table below and productList.returnsEligibility | Order Status | Display Name in Order History Filter | Significance for Order | Significance for Item | Return Eligibility | | --- | --- | --- | --- | --- | | COMPLETED | Completed | Successful sale transaction. | Item sold successfully. | Both the order and item are eligible for return. | | RETURNED | Returned | Successful return or exchange of all items with refund to customer. | Successful return of an item - whole quantity and is not eligible for return. | Both the order and item are not eligible for return. | | PARTIALLY\_REFUNDED | Partially Returned | Successful return or exchange of partial items with refund to customer. | Successful return of an item - partial quantity | Further returns are allowed on order as well as on item. | | EXCHANGED | Exchanged | Successful transaction that exchanges all items with no refund to customer | Successful exchanges of an item - whole quantity | Both the order and item are not eligible for return. | | PARTIALLY\_EXCHANGED | Partially Exchanged | Successful transaction that exchanges partial items with no refund to customer | Successful exchanges of an item - partial quantity | Further returns are allowed on order as well as on item. | | FAILED | Failed | Failed sale transaction. | Not applicable | Both the order and item are not eligible for return. | | PENDING | Pending | Sale transaction awaiting payment confirmation. For example, Remote Pay By Link | Not applicable | Both the order and item are not eligible for return. | Allowed values: `COMPLETED`, `FAILED`, `RETURNED`, `PARTIALLY_REFUNDED`, `PENDING`, `CANCELLED_WITH_REFUND`, `EXCHANGED`, `PARTIALLY_EXCHANGED`, `CANCELED`. Default: `COMPLETED`. * `gtin` (_string_, required) Item's GTIN. * `fulfillmentType` (_string_, required) Item's fulfillment type. It can be either IN\_STORE (in-store purchase) or ONLINE (delivery item). Allowed values: `IN_STORE`, `ONLINE`, `MIXED_CART`. * `fulfillmentSubType` (_string_, required) 1. DEFAULT: Either item will be available from the current store for  cash & carry or for delivery to shipping address from a warehouse.   Fulfillment Type:IN\_STORE, Fulfillment Sub Type: DEFAULT : Cash & carry item 2\. TRY\_AT\_STORE: An item will be made available in the selected store for the trial.  The taxes and promotion will not be applied on the try at store items. 3\. PICKUP\_LATER: An item will be made available for pickup from the selected store.  The fulfillment will be done the current store itself, or another store. 4\. SHIP\_TO\_HOME: An item will be delivered to provided shipping address.  The fulfillment will be done by the current store itself,  or another store or a warehouse. 5\. SHIP\_TO\_STORE: An item will be delivered to a store from where it can be picked up. 6. PICKUP\_NEARBY: An item will be made available for pickup in near by store. \---------------------------------------------------------------------------------- | Fulfillment Type | Fulfillment SubType | Item | | --- | --- | --- | | IN\_STORE | DEFAULT | Cash & carry | | ONLINE | DEFAULT | Ship to home from warehouse | | ONLINE | TRY\_AT\_STORE | Ship to store from warehouse to try out | | IN\_STORE | PICKUP\_LATER | Pickup from current store | | IN\_STORE | SHIP\_TO\_HOME | Ship to home from store | | IN\_STORE | SHIP\_TO\_STORE | Ship to a store from another store for pickup | | ONLINE | SHIP\_TO\_STORE | Ship to store from warehouse for pickup (buy online ship to store) | | IN\_STORE | PICKUP\_NEARBY | Pickup from another store | . Allowed values: `DEFAULT`, `TRY_AT_STORE`, `PICKUP_LATER`, `SHIP_TO_HOME`, `SHIP_TO_STORE`, `PICKUP_NEARBY`. * `salesAssociateAttributionList` (_array of ExternalStoreAssociateAttribution_) Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate. * `epc` (_string_, nullable) Electronic product code. Mandatory for items having epc/RFID. * `masterProductId` (_string_, nullable) Outfit Identification that groups together a set of items from a cart. Commonly used in case product customizations like DYO (i.e. Customization Identification) or Alteration etc...Mandatory for alteration or DYO items. * `subProducts` (_array of ExternalProduct_, nullable) The other items from the cart related to the current item. Commonly used in case of customizations like Alteration as well as for add-on products. Mandatory for alteration or add-on items. * `productClass` (_string_, required) Product class of the item. * `serialNumber` (_string_) Serial number of the item (if applicable). * `productCondition` (_string_) Product condition. Allowed values: `NEW`, `USED`, `REFURBISHED`. Default: `NEW`. * `reasons` (_array of Reason_, nullable) List of reasons pertaining to the actions performed on the item. For example, reason for price override applied on the item or reason for returning the item. * `dateTimeSlot` (_DateTimeSlot_) * `priceCorrection` (_ExternalProductPriceCorrection_) * `deliveryGroupId` (_string_) Delivery group ID. It is an identifier to the shipping details of the item. It links the item to one of the delivery groups available under transaction. It is applicable for delivery items. Maximum length: 32. * `formAttributes` (_array of ProductFormAttribute_, nullable) New form data to be set on the product. * `pickupDetailId` (_string_) Link to pickup person detail corresponding to the product. Points to the corresponding pickup details from pickupDetailList in the transaction. Maximum length: 128. * `productTax` (_ExternalProductTax_) * `priceAdjustmentList` (_array of ExternalPriceAdjustment_, nullable) Price adjustments applied on the item. It includes all the price adjustments like transaction discount, price override etc... Mandatory if any type of price adjustments is applied. * `returnsEligibility` (_string_, nullable) Returns eligibility of the item. Allowed values: `ELIGIBLE_FOR_RETURNS`, `EXPIRED_RETURNS`, `CANNOT_BE_RETURNED`, `ELIGIBLE_FOR_CANCELS`, `INELIGIBILITY_FOR_RETURN_CROSS_CHANNEL`. Default: `ELIGIBLE_FOR_RETURNS`. * `returnsEligibilityText` (_string_) Returns eligibility information for the product, describing why it's ineligible for return. For example, BOFIS items that haven't shipped can't be returned. In that case, this field says 'Item not shipped yet' (applies when BOFIS orders are sent to PS Queue, that is, STH from CS enabled in Omni V2 settings). When an item can't be returned, this field says 'Cannot be returned'. Maximum length: 128. * `pickupStoreId` (_string_, nullable) Pickup store ID. * `fulfillmentStoreId` (_string_, nullable) Fulfillment store ID. * `totalAdditionalCharge` (_number_, nullable) Total additional charges. * `tlogCustomProductAttributes` (_string_, nullable) Custom attributes. * `externalId` (_string_, nullable) External ID of the product. Maximum length: 128. * `productBundleId` (_string_, nullable) If the product is part of outfit or a product bundle, then provide the id which groups together all the items from the bundle. * `noteList` (_array of ExternalNote_, nullable) Note associated with the product. * `customAttributeList` (_array of ProductFormAttribute_, read-only) Custom attributes related to the product. All these attributes will be available at item level that are configured in Store Setting: spiCustomProductAttributes. _Example_ ``` [ { "key": "color", "value": "red" } ] ``` * `registryId` (_string_, nullable) The unique ID of the registry. This is required when the item being purchased or returned is a gift registry item. * `requiredDeposit` (_number_) Required deposit for the product if deposit configuration is enabled for the store. * `paidDeposit` (_number_) Paid deposit for the product if deposit configuration is enabled for the store. ### ExternalSerializedUnitDetail The list of attributes about a serialized unit, for example, activation code or context code. * `activationCode` (_string_) The activation code of the serialized unit detail. * `contextCode` (_string_) The context code of the serialized unit detail. * `orderItemId` (_string_) The order item id of the serialized unit detail. ### ExternalStoreAssociateAttribution Sales associate attribution. If unspecified, then attribute the whole sale transaction to the logged-in associate. * `storeAssociateId` (_string_, required) ID of the associate that completed the sale transaction. * `contributionPercentage` (_number_, required) Associate's contribution towards sales. * `attributionNote` (_string_) Note related to attribution. * `firstName` (_string_, required) Associate's first name. * `lastName` (_string_, required) Associate's last name. ### 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. ### DateTimeSlot Backup delivery date if slots are unavailable. Default can be set via 'deliveryDatePickerWillCall' in Store settings. * `slotId` (_string_) Slot ID. Example: `1234`. * `slotDate` (_integer (int64)_, required) Delivery date in epoch. * `selectedTimeSlot` (_string_, required) Time slot. Example: `09:00 - 12:00`. * `dateTimeSlotType` (_string_, nullable) Time slot type. Allowed values: `Delivery`, `Pickup`. Default: `Delivery`. ### ExternalProductPriceCorrection Price correction applied on the item with information like the approval manager ID and original price. Sale price becomes new corrected price. * `originalPrice` (_number_) Original price of the item. * `approvingManagerId` (_string_) ID of the manager who approved the price correction request. ### ProductFormAttribute Details about a product form attribute. * `key` (_string_) The identifier of the attribute. Example: `color`. * `value` (_string_) The value associated with the key. Example: `blue`. _Example_ ``` [ { "key": "color", "value": "red" } ] ``` ### ExternalProductTax Tax/Vat details. * `totalTax` (_number_, required) Total tax. Required in case of tax countries. * `taxExemption` (_number_, nullable) Tax Exemption. * `taxRateList` (_array of ProductTaxRate_, nullable) Tax Rates. * `vatRateList` (_array of ProductTaxRate_, nullable) VAT Rates. * `valueAddedTax` (_number_, nullable) Total VAT. Required in case of VAT countries. * `taxableAmount` (_number_, required) Taxable amount. ### ExternalPriceAdjustment Price adjustments applied on the item. It includes all the price adjustments like transaction discount, price override etc... Mandatory if any type of price adjustments is applied. * `description` (_string_, required) Price adjustment description. * `adjustment` (_string_, required) Price adjustment. * `id` (_string_) Promotion Id for applied coupon or auto promotion. * `price` (_number_, required) Price adjustment amount. * `priceAdjustmentType` (_string_, required) Price adjustment type. Allowed values: `PRICE_OVERRIDE`, `PROMOTION`, `FEES`, `REWARDS`, `TRANSACTION_DISCOUNT`. * `reason` (_Reason_) * `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. * `promoCode` (_string_, nullable) Coupon code corresponding to promotion applied. Not applicable for auto promotions, manual price adjustments like price override & transaction discount. * `auto` (_boolean_, nullable) Applied promotion is auto or not. * `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`. * `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. ### ExternalNote Notes for the transaction. * `cartId` (_string_) * `noteId` (_string_) * `noteText` (_string_) * `transactionId` (_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.