Manage Your Recommendations Catalog using APIs
While ensuring that you meet the requirements to use the use the Recommendations API, you learned how to generate an access token using the JWT authentication flow to use the Adobe Target Admin APIs on the Adobe Developer Console.
You can now use the Recommendations APIs to add, update, or delete items in your recommendations catalog. As with the rest of the Adobe Target Admin APIs, the Recommendations APIs require authentication.
Before proceeding, get the Recommendations Postman collection.
Creating and updating items with the Save Entities API
To populate your Recommendations product database using the API rather than a CSV product feed or Target requests firing on product pages, use the Save Entities API. This request adds or updates an item in a single Target environment. The syntax is:
POST https://mc.adobe.io/{{TENANT_ID}}/target/recs/entities
For example, Save Entities may be used to update items whenever certain thresholds are met—such as thresholds for inventory or price—in order to flag those items and prevent them from being recommended.
-
Navigate to Target > Setup > Hosts > CONTROL Environments to obtain the Target Environment ID in which you want to add or update an item.
-
Verify
TENANT_IDandAPI_KEYreference the Postman environment variables established earlier. Use the image below for comparison. If necessary, modify the Headers and path in your API request to match those in the image below.
-
Enter your JSON as raw code in the Body. Don’t forget to specify your environment ID, using the
environmentvariable. (In the example below, the environment ID is 6781.)
Below is sample JSON that adds entity.id kit2001 with associated entity values for a Toaster Oven product, into environment 6781.
code language-none { "entities": [{ "name": "Toaster Oven", "id": "kit2001", "environment": 6781, "categories": [ "housewares:appliances" ], "attributes": { "inventory": 77, "margin": 23, "message": "crashing helicopter", "pageUrl": "www.foobar.foo.com/helicopter.html", "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg", "value": 19.2 } }] } -
Click Send. You should receive the following response.
The JSON object can be scaled to send multiple products. For example, this JSON specifies two entities.
code language-none { "entities": [{ "name": "Toaster Oven", "id": "kit2001", "environment": 6781, "categories": [ "housewares:appliances" ], "attributes": { "inventory": 89, "margin": 11, "message": "Toaster Oven", "pageUrl": "www.foobar.foo.com/helicopter.html", "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg", "value": 102.5 } }, { "name": "Blender", "id": "kit2002", "environment": 6781, "categories": [ "housewares:appliances" ], "attributes": { "inventory": 36, "margin": 5, "message": "Blender", "pageUrl": "www.foobar.foo.com/helicopter.html", "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg", "value": 54.5 } } ] } -
Now it’s your turn! Use the Save Entities API to add the following items to your catalog. Use the sample JSON above as a starting point. (You will need to extend the JSON to include additional entities.)
Looks like those last two items don’t belong. Let’s inspect them using the Get Entity API, and if necessary, delete them using the Delete Entities API.
Getting item details with the Get Entity API
To retrieve the details of an existing item, use the Get Entity API. The syntax is:
GET https://mc.adobe.io/{{TENANT_ID}}/target/recs/entities/[entity.id]
Entity details can only be retrieved for a single entity at a time. You can use Get Entity to confirm updates were made in the catalog as expected, or to otherwise audit the contents of the catalog.
-
In the API request, specify the entity ID, using the variable
entityId. The following example will return details for the entity whose entityId=kit2004.
-
Verify
TENANT_IDandAPI_KEYreference the Postman environment variables established earlier. Use the image below for comparison. If necessary, modify the Headers and path in your API request to match those in the image below.
-
Send the request.
If you receive an error stating the entity was not found, as shown in the example above, verify you are submitting the request to the correct Target environment.note note NOTE If no environment is explicitly specified, Get Entity attempts to get the entity from your default environment only. If you wish to pull from any environment other than your default environment, you must specify the environment ID. -
If necessary, add the
environmentIdparameter, and re-send the request.
-
Send another Get Entity request, this time to inspect the entity whose entityId=kit2005.
Suppose you decide these entities need to be removed from your catalog. Let’s use the Delete Entities API.
Deleting items with the Delete Entities API
To remove items from your catalog, use the Delete Entities API. The syntax is:
DELETE https://mc.adobe.io/{{TENANT_ID}}/target/recs/entities?ids=[comma-delimited-entity-ids]&environment=[environmentId]
-
Navigate to Target > Setup > Hosts > Environments to obtain the Target Environment ID from which you want to delete items.
-
In the API request, specify the entity IDs of the entities you want to delete, using the syntax
&ids=[comma-delimited-entity-ids](a query parameter). When deleting more than one entity, separate the IDs using commas.
-
Specify the environment ID, using the syntax
&environment=[environmentId], otherwise entities across all environments will be deleted.
-
Verify
TENANT_IDandAPI_KEYreference the Postman environment variables established earlier. Use the image below for comparison. If necessary, modify the Headers and path in your API request to match those in the image below.
-
Send the request.
-
Verify your results using Get Entity, which should now indicate the deleted entities cannot be found.
Congratulations! You can now use the Recommendations APIs to create, update, delete, and obtain details on the entities in your catalog. In the next section, you will learn how to manage custom criteria.