Product Lists API Documentation

The Affiliate.com Product Lists API allows you to store and manage lists of products that can be retrieved at any time without having to create and manage your own database infrastructure.

Metadata Object

One of the versatile aspects of this endpoint is that it allows up to 16 key:value pairs for you to use however you see fit. These are queryable fields to get specific results and are returned in the results so you can programatically use these however you need.

Metadata key max length is 64 characters, value max length 512 characters.

Endpoints

Create Product List

Creates a new product list with specified products.

POST /v1/products/lists

Headers

Header	Required	Description
Authorization	Yes	Bearer token
Content-Type	Yes	application/json

Request Body

{
  "pool_id": 456,
  "metadata": {
    "category": "tech_products"
  },
  "name": "Smart Home Devices",
  "product_ids": [
    "1234567890123456789",
    "2345678901234567890"
  ]
}

Response

{
  "data": {
    "id": "d345e67f-89g0-1h2i-3j45-6k7891lm2345",
    "name": "Smart Home Devices",
    "metadata": {
      "category": "tech_products"
    },
    "products_count": 2,
    "products": [
      {
        "id": "1234567890123456789",
        "barcode": 123456,
        "name": "Smart Thermostat Pro",
        "description": "Wi-Fi enabled thermostat with voice control",
        "commission_url": "https://www.example-affiliate.net/click-123-456789?url=https%3A%2F%2Fwww.example-store.com%2Fproducts%2Fsmart-thermostat-pro",
        "direct_url": "https://www.example-store.com/products/smart-thermostat-pro",
        "image_url": "https://assets.example-store.com/images/products/thermostat-pro.jpg",
        "currency": "USD",
        "regular_price": 129.99,
        "final_price": 99.99,
        "on_sale": true,
        "sale_discount": 23,
        "availability": "In Stock",
        "sku": 123456,
        "brand": "SmartHome",
        "category": "Home & Garden > Smart Home > Climate Control",
        "network": {
          "id": 5,
          "name": "AffiliateNetwork",
          "logo_url": "https://img.affiliate.com/logos/networks/5/logo.png"
        },
        "merchant": {
          "id": 1234,
          "name": "Example Store",
          "logo_url": "https://img.affiliate.com/logos/merchants/1234/logo.png"
        }
      },
      {
        "id": "2345678901234567890",
        "barcode": 123456,
        "name": "Smart Security Camera",
        "description": "1080p HD security camera with night vision",
        "commission_url": "https://www.example-affiliate.net/click-123-456789?url=https%3A%2F%2Fwww.example-store.com%2Fproducts%2Fsmart-security-camera",
        "direct_url": "https://www.example-store.com/products/smart-security-camera",
        "image_url": "https://assets.example-store.com/images/products/security-camera.jpg",
        "currency": "USD",
        "regular_price": 89.99,
        "final_price": 89.99,
        "on_sale": false,
        "sale_discount": 0,
        "availability": "In Stock",
        "sku": 123456,
        "brand": "SecureTech",
        "category": "Home & Garden > Smart Home > Security",
        "network": {
          "id": 5,
          "name": "AffiliateNetwork",
          "logo_url": "https://img.affiliate.com/logos/networks/5/logo.png"
        },
        "merchant": {
          "id": 1234,
          "name": "Example Store",
          "logo_url": "https://img.affiliate.com/logos/merchants/1234/logo.png"
        }
      }
    ]
  },
  "meta": {
    "trace_id": "a98b7c65-4d32-1e0f-9g87-6h5432i10j9k"
  }
}

Get Product Lists

Retrieves all product lists associated with API key.
NOTE: This will return the lists associated with your key/token. It will not show each product within the list.

GET /v1/products/lists

Headers

Header	Required	Description
Authorization	Yes	Bearer token

Example: https://api.affiliate.com/v1/products/lists

Response

{
  "meta": {
    "total": 1,
    "from": 1,
    "to": 1,
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "fields": [],
    "trace_id": "0195cde4-325d-7376-ab52-48b8f1256dd0"
  },
  "data": [
    {
      "id": "9e8465d7-2095-4a9d-8453-73ed666dc14e",
      "name": "listnamehere",
      "owner_identifier": "ownernamehere",
      "metadata": {
        "key1": "metavalueiwantreturned"
      },
      "products_count": 2
    }
  ]
}

Get Single Product List

Retrieves a specific product list by its ID.

GET /v1/products/lists/{list_id}

Path Parameters

Parameter	Required	Description
list_id	Yes	ID of the product list

Headers

Header	Required	Description
Authorization	Yes	Bearer token

Response

{
  "data": {
    "id": "d345e67f-89g0-1h2i-3j45-6k7891lm2345",
    "name": "Smart Home Devices",
    "metadata": {
      "category": "tech_products"
    },
    "products_count": 2,
    "products": [
      {
        "id": "1234567890123456789",
        "barcode": 123456,
        "name": "Smart Thermostat Pro",
        "description": "Wi-Fi enabled thermostat with voice control",
        "commission_url": "https://www.example-affiliate.net/click-123-456789?url=https%3A%2F%2Fwww.example-store.com%2Fproducts%2Fsmart-thermostat-pro",
        "direct_url": "https://www.example-store.com/products/smart-thermostat-pro",
        "image_url": "https://assets.example-store.com/images/products/thermostat-pro.jpg",
        "currency": "USD",
        "regular_price": 129.99,
        "final_price": 99.99,
        "on_sale": true,
        "sale_discount": 23,
        "availability": "In Stock",
        "sku": 123456,
        "brand": "SmartHome",
        "category": "Home & Garden > Smart Home > Climate Control",
        "network": {
          "id": 5,
          "name": "AffiliateNetwork",
          "logo_url": "https://img.affiliate.com/logos/networks/5/logo.png"
        },
        "merchant": {
          "id": 1234,
          "name": "Example Store",
          "logo_url": "https://img.affiliate.com/logos/merchants/1234/logo.png"
        }
      },
      {
        "id": "2345678901234567890",
        "barcode": 123456,
        "name": "Smart Security Camera",
        "description": "1080p HD security camera with night vision",
        "commission_url": "https://www.example-affiliate.net/click-123-456789?url=https%3A%2F%2Fwww.example-store.com%2Fproducts%2Fsmart-security-camera",
        "direct_url": "https://www.example-store.com/products/smart-security-camera",
        "image_url": "https://assets.example-store.com/images/products/security-camera.jpg",
        "currency": "USD",
        "regular_price": 89.99,
        "final_price": 89.99,
        "on_sale": false,
        "sale_discount": 0,
        "availability": "In Stock",
        "sku": 123456,
        "brand": "SecureTech",
        "category": "Home & Garden > Smart Home > Security",
        "network": {
          "id": 5,
          "name": "AffiliateNetwork",
          "logo_url": "https://img.affiliate.com/logos/networks/5/logo.png"
        },
        "merchant": {
          "id": 1234,
          "name": "Example Store",
          "logo_url": "https://img.affiliate.com/logos/merchants/1234/logo.png"
        }
      }
    ]
  },
  "meta": {
    "trace_id": "b12c3d45-e67f-89a0-1b2c-3d4567e8f90a"
  }
}

Get Product Lists By Metadata

Retrieves product lists that have specific metadata key:value pairs that you identified upon creation of the list.

GET /v1/products/lists

Query Parameters

Parameter	Required	Description
metadata[{metadatakey1}]	Yes	Metadata key:value pairs

Headers

Header	Required	Description
Authorization	Yes	Bearer token

Example: https://api.affiliate.com/v1/products/lists?metadata[metadatakey1]=metadatavalue1&[metadatakey2]=metadatavalue2...

Response

{
  "meta": {
    "total": 1,
    "from": 1,
    "to": 1,
    "current_page": 1,
    "last_page": 1,
    "per_page": 100,
    "fields": [],
    "trace_id": "f12a3d45-6b78-90c1-2d3e-4f5678901234"
  },
  "data": [
    {
      "id": "c234a56b-78c9-4d0e-1f23-456789abcdef",
      "name": "Summer Collection",
      "metadata": {
        "metadatakey1": "metadatavalue1"
      },
      "products_count": 2
    },
    {
      "id": "c234a56b-78c9-4d0e-1f23-456789agedf",
      "name": "Winter Collection",
      "metadata": {
        "metadatakey2": "metadatavalue2"
      },
      "products_count": 5
    }
  ]
}

Delete Product List

Deletes a specific product list by its ID.

DELETE /v1/products/lists/{list_id}

Path Parameters

Parameter	Required	Description
list_id	Yes	ID of the product list

Headers

Header	Required	Description
Authorization	Yes	Bearer token

Response

{
  "id": "d345e67f-89g0-1h2i-3j45-6k7891lm2345",
  "status": "deleted",
  "meta": {
    "trace_id": "c1d2e3f4-5g6h-7i8j-9k10-l1m2n3o4p5q6"
  }
}

Add Products to a List

Adds products to an existing list.
NOTE: If you attempt to add product IDs that are already in the list, you will see those product IDs listed in the ignored_product_ids array.

POST /v1/products/lists/{list_id}/items

Path Parameters

Parameter	Required	Description
list_id	Yes	ID of the product list

Headers

Header	Required	Description
Authorization	Yes	Bearer token
Content-Type	Yes	application/json

Request Body

{
  "product_ids": [
    "3456789012345678901",
    "4567890123456789012"
  ]
}

Response

{
  "list_id": "d345e67f-89g0-1h2i-3j45-6k7891lm2345",
  "added_product_ids": [
    "3456789012345678901"
  ],
  "ignored_product_ids": [
    "4567890123456789012"
  ],
  "meta": {
    "trace_id": "d1e2f3g4-5h6i-7j8k-9l10-m1n2o3p4q5r6"
  }
}

Remove Products from a List

Removes products from an existing list.
NOTE: If you attempt to remove product IDs that are not in the list, you will see those product IDs listed in the ignored_product_ids array.

DELETE /v1/products/lists/{list_id}/products

Path Parameters

Parameter	Required	Description
list_id	Yes	ID of the product list

Headers

Header	Required	Description
Authorization	Yes	Bearer token
Content-Type	Yes	application/json

Request Body

{
  "product_ids": [
    "1234567890123456789",
    "9876543210987654321"
  ]
}

Response

{
  "list_id": "d345e67f-89g0-1h2i-3j45-6k7891lm2345",
  "removed_product_ids": [
    "1234567890123456789"
  ],
  "ignored_product_ids": [
    "9876543210987654321"
  ],
  "meta": {
    "trace_id": "e1f2g3h4-5i6j-7k8l-9m10-n1o2p3q4r5s6"
  }
}

Product List

Product Lists API Documentation#

Metadata Object#

Endpoints#

Create Product List#

Headers#

Request Body#

Response#

Get Product Lists#

Headers#

Response#

Get Single Product List#

Path Parameters#

Headers#

Response#

Get Product Lists By Metadata#

Query Parameters#

Headers#

Response#

Delete Product List#

Path Parameters#

Headers#

Response#

Add Products to a List#

Path Parameters#

Headers#

Request Body#

Response#

Remove Products from a List#

Path Parameters#

Headers#

Request Body#

Response#

Product Lists API Documentation

Metadata Object

Endpoints

Create Product List

Headers

Request Body

Response

Get Product Lists

Headers

Response

Get Single Product List

Path Parameters

Headers

Response

Get Product Lists By Metadata

Query Parameters

Headers

Response

Delete Product List

Path Parameters

Headers

Response

Add Products to a List

Path Parameters

Headers

Request Body

Response

Remove Products from a List

Path Parameters

Headers

Request Body

Response