Edit in GitHubLog an issue

Manage Your Recommendations Catalog using APIs

At this point, you have 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 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.

JWT3ff

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:

Copied to your clipboard
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.

  1. Navigate to Target > Setup > Hosts > CONTROL Environments to obtain the Target Environment ID in which you want to add or update an item.

    SaveEntities1

  2. Verify TENANT_ID and API_KEY reference 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.

    SaveEntities3

  3. Enter your JSON as raw code in the Body. Don't forget to specify your environment ID, using the environment variable. (In the example below, the environment ID is 6781.)

    SaveEntities4.png

Copied to your clipboard
1 {
2 "entities": [{
3 "name": "Toaster Oven",
4 "id": "kit2001",
5 "environment": 6781,
6 "categories": [
7 "housewares:appliances"
8 ],
9 "attributes": {
10 "inventory": 77,
11 "margin": 23,
12 "message": "crashing helicopter",
13 "pageUrl": "www.foobar.foo.com/helicopter.html",
14 "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg",
15 "value": 19.2
16 }
17 }]
18 }
  1. Click Send. You should receive the following response.

    SaveEntities5.png

The JSON object can be scaled to send multiple products. For example, this JSON specifies two entities.

Copied to your clipboard
1 {
2 "entities": [{
3 "name": "Toaster Oven",
4 "id": "kit2001",
5 "environment": 6781,
6 "categories": [
7 "housewares:appliances"
8 ],
9 "attributes": {
10 "inventory": 89,
11 "margin": 11,
12 "message": "Toaster Oven",
13 "pageUrl": "www.foobar.foo.com/helicopter.html",
14 "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg",
15 "value": 102.5
16 }
17 },
18 {
19 "name": "Blender",
20 "id": "kit2002",
21 "environment": 6781,
22 "categories": [
23 "housewares:appliances"
24 ],
25 "attributes": {
26 "inventory": 36,
27 "margin": 5,
28 "message": "Blender",
29 "pageUrl": "www.foobar.foo.com/helicopter.html",
30 "thumbnailUrl": "www.foobar.foo.com/helicopter.jpg",
31 "value": 54.5
32 }
33 }
34 ]
35 }
  1. 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.)

    SaveEntities6.png

Whoops, 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:

Copied to your clipboard
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.

  1. In the API request, specify the entity ID, using the variable entityId. The following example will return details for the entity whose entityId=kit2004.

    GetEntity1

  2. Verify TENANT_ID and API_KEY reference 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.

    GetEntity2

  3. Send the request.

    GetEntity3 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.

  1. If necessary, add the environmentId parameter, and re-send the request.

    GetEntity4

  2. Send another Get Entity request, this time to inspect the entity whose entityId=kit2005.

    GetEntity5

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:

Copied to your clipboard
DELETE https://mc.adobe.io/{{TENANT_ID}}/target/recs/entities?ids=[comma-delimited-entity-ids]&environment=[environmentId]
  1. Navigate to Target > Setup > Hosts > Environments to obtain the Target Environment ID from which you want to delete items.

    DeleteEntities1

  2. 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.

    DeleteEntities2

  3. Specify the environment ID, using the syntax &environment=[environmentId], otherwise entities across all environments will be deleted.

    DeleteEntities3

  4. Verify TENANT_ID and API_KEY reference 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.

    DeleteEntities4

  5. Send the request.

    DeleteEntities5

  6. Verify your results using Get Entity, which should now indicate the deleted entities cannot be found.

    DeleteEntities6

    DeleteEntities6

Congrats! 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.

Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.