--- schema_version: "1" id: b0822f0e1dd7b48beb939bd4d9f92f13f1646faa7e310b590d5c1f7ad5feec52 title: Gift Registry 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/gift-registry-spi.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/gift-registry-spi source_site: developer.salesforce.com content_type: documentation content_hash: 4fd59a15d16c0fb9421dbaedaffe53bf6cada00aba75237ac754364988c6cfdd products: - Point of Sale for Developers - Salesforce APIs --- Gift Registry SPI # Gift Registry SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/gift-registry-spi/gift-registry-spi-oas-public.yaml) Merchant SPI to implement and provide an endpoint for POS to perform Gift registry actions such as registry lookup, buy / return registry items. 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:** `GIFT_REGISTRY` * **API Endpoint:** Provide the common external endpoint for registry APIs, for example: [https://sample/external/endpoint/giftregistry](https://sample/external/endpoint/giftregistry) 2. Under **JSON Config**: * **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"}` Merchant to implement below APIs and use the same ending keyword for the individual APIs. **Version:** 2.3.4 ## Tags ### Gift Registry SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/gift-registry-spi/gift-registry-spi-oas-public.yaml) Merchant SPI to implement and provide an endpoint for POS to perform Gift registry actions such as registry lookup, buy / return registry items. 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:** `GIFT_REGISTRY` * **API Endpoint:** Provide the common external endpoint for registry APIs, for example: [https://sample/external/endpoint/giftregistry](https://sample/external/endpoint/giftregistry) 2. Under **JSON Config**: * **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"}` Merchant to implement below APIs and use the same ending keyword for the individual APIs. ## Operations ### GET Retrieve products for registry ID. `GET /merchant/spi/sample/endpoint/giftregistry/{identifier}` Operation ID: `getRegistryProducts`. Tags: Gift Registry SPI. Retrieve the list of all products belonging to the particular registry ID. The list is available for the customer to select from. The identifier is the registryId, which is a path parameter. #### Parameters * `identifier` (path, string, required) #### Responses * **default** Default response. Media type: `application/json`. Schema: `SpiRegistryDetailResponse`. ### POST Return gift registry product. `POST /merchant/spi/sample/endpoint/giftregistry/returnRegistryItem` Operation ID: `searchGiftRegistry`. Tags: Gift Registry SPI. Retrieve a gift registry product based on the registryId, productId, and quantity passed in the request, which can be added to cart to initiate the NRR flow. #### Request body Media type: `application/json`. Schema: `ReturnRegistryRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `SpiRegistryReturnResponse`. ### POST Search gift registries. `POST /merchant/spi/sample/endpoint/giftregistry/searchRegistries` Operation ID: `searchGiftRegistry_1`. Tags: Gift Registry SPI. Fetch the list of gift registries from the external system based on the search criteria, allowing customers to select products from the registry to add to the order. Please provide one or more query parameters. #### Request body Media type: `application/json`. Schema: `SearchRegistryRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `SpiGiftRegistryResponse`. ## Schemas ### SpiRegistryDetailResponse * `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`. * `registryId` (_string_, required) The unique ID of the registry. * `firstName` (_string_, required) The First name of the Registrant. * `lastName` (_string_, required) The last name of the Registrant. * `coRegistrantName` (_string_, nullable) The Co-Registrant name for the registry if available. * `eventType` (_string_, required) The event type for which the registry was created. For example, Wedding, Engagement, Housewarming. * `eventDate` (_integer (int64)_, required) The event date in epoch milliseconds, to be shown in a suitable format on the app. * `preEventAddress` (_SPIAddress_, required) * `postEventAddress` (_SPIAddress_, required) * `productList` (_array of SpiRegistryProduct_, required) The list of gift products that are present with this registry, with all the availability details. * `error` (_boolean_) ### ReturnRegistryRequest * `registryId` (_string_, required) The unique ID of the registry. * `productId` (_string_, required) Product Identifier. * `gtin` (_string_, nullable) Item's GTIN, alternate field to product ID. * `storeId` (_string_, nullable) Store ID of the current store. * `quantity` (_integer (int32)_, required) Quantity of the product to be returned. The response returns an error if the requested quantity isn't available. Default: `1`. ### SpiRegistryReturnResponse * `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`. * `items` (_array of RegistryLineItem_, required) The list of line items corresponding to the product Id sent in request, where each line can be of differing prices, quantities, belonging to different orders. * `error` (_boolean_) ### SearchRegistryRequest * `registryId` (_string_, nullable) The unique ID of the registry. * `firstName` (_string_, nullable) The First name of the Registrant. * `lastName` (_string_, nullable) The last name of the Registrant. * `storeId` (_string_, nullable) Store ID of the current store. * `email` (_string_, nullable) The email ID of the registrant. * `phone` (_string_, nullable) The Phone number of the Registrant. ### SpiGiftRegistryResponse * `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`. * `giftRegistries` (_array of GiftRegistry_, required) The list of gift registries matching the search. * `error` (_boolean_) ### 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. ### SpiRegistryProduct The list of gift products that are present with this registry, with all the availability details. * `productId` (_string_, required) Product Identifier. * `quantityWanted` (_integer (int32)_, required) The quantity of this item that the registrant is looking for. * `quantityPurchased` (_integer (int32)_, required) Quantity of the item that have already been purchased as a gift. * `preEventAvailability` (_boolean_, required) Flag indicating whether item is available for Ship to the Pre event address. * `postEventAvailability` (_boolean_, required) Flag indicating whether item is available for Ship to the Post event address. * `inStoreAvailability` (_boolean_, required) Flag indicating whether item is available to take with / In Store order. * `quantity` (_integer (int32)_, required) Quantity of the product that is available to purchase. ### RegistryLineItem The list of line items corresponding to the product Id sent in request, where each line can be of differing prices, quantities, belonging to different orders. * `eligibleForReturn` (_boolean_, required) Flag to indicate whether product is eligible for return. * `productId` (_string_, required) Product Identifier. * `price` (_number_, required) Product price inclusive of quantity. * `quantity` (_integer (int32)_, required) Quantity of the product. * `taxAmount` (_number_, required) Tax amount inclusive of quantity. * `externalReferenceId` (_string_, required) The orderId or reference ID associated with the registry item being returned. Pass this when adding the item to the cart for NRR. ### GiftRegistry The list of gift registries matching the search. * `imageUrl` (_string_, required) The URL of the image to be shown along with the Registry details. * `registryId` (_string_, required) The unique ID of the registry. * `firstName` (_string_, required) The First name of the Registrant. * `lastName` (_string_, required) The last name of the Registrant. * `coRegistrantName` (_string_, nullable) The Co-Registrant name for the registry if available. * `state` (_string_, required) The state where the event is taking place. * `eventType` (_string_, required) The event type for which the registry was created. For example, Wedding, Engagement, Housewarming. * `eventDate` (_integer (int64)_, required) The event date in epoch milliseconds, to be shown in a suitable format on the app.