Overview

Endpoint: https://graph.cj.com/publishers

The Item List API is a GraphQL API providing publishers programmatic access to advertiser-defined item lists. This is especially useful when working with item list based Program Terms. While commission rates are not included in this dataset, combining item list data with the Program Terms API provides a more complete view of how specific products may influence earnings potential.

Query Usage

Query operations allow you to get data. Large data sets are split into pages, which must be retrieved sequentially using Page Tokens.

Authorization

To authorize yourself when querying, include your personal access token in the HTTP Authorization request header:

Authorization: "Bearer <personal-access-token>"

Initial Request

For your first request, include your query arguments and omit the page argument (or pass null). Use pageSize to specify how many records you want per page. Note that the API may return fewer records than the requested pageSize on any given page — count the records in the response to determine how many were returned.

query ItemList {
  itemList(itemListId: "qwe-123") {
    id
    name
    items(pageSize: 2) {
      nextPage
      records {
        name
        sku
      }
    }
  }
}

Response:

{
  "data": {
    "itemList": {
      "id": "qwe-123",
      "name": "Books",
      "items": {
        "nextPage": "dummy-page-token-1234",
        "records": [
          { "name": "The How To Book on the Zombie", "sku": "QWE-QWERT" },
          { "name": "How to Survive a Zombie Apocalypse", "sku": "QWE-RTY-123" }
        ]
      }
    }
  }
}

The response includes a nextPage token. If nextPage is null, you have reached the last page.

Subsequent Requests

Pass the nextPage token from the previous response as the page argument. All other query arguments must remain the same as the initial request.

query ItemList {
  itemList(itemListId: "qwe-123") {
    id
    name
    items(pageSize: 2, page: "dummy-page-token-1234") {
      nextPage
      records {
        name
        sku
      }
    }
  }
}

Response:

{
  "data": {
    "itemList": {
      "id": "qwe-123",
      "name": "Books",
      "items": {
        "nextPage": "dummy-page-token-for-third-page-123",
        "records": [
          { "name": "The Best Book on Zombies", "sku": "ASD-FGH-456" },
          { "name": "This is not a Zombie Book", "sku": "ZXC-VBN-789" }
        ]
      }
    }
  }
}

Continue querying with each nextPage token until the value is null, indicating you have retrieved all pages.

Error Codes

Errors are returned as a list in an errors entry of the response. Each error contains a message field containing a description of the error. The error's extensions.code field contains an error code that can be used to programmatically identify the type of error. Error codes may include:

• InternalError: An unexpected internal server error occurred; the request may be retryable.
• InvalidArguments: One or more provided arguments are invalid.
• NotFound: The requested resource could not be found.
• Unauthorized: Access denied due to missing or invalid authorization token.

Example Error Response

This is the response format for errors. This example is in response to the itemList query.

{
  "errors": [
    {
      "message": "Internal Server Error",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["itemList"],
      "extensions": {
        "code": "InternalError",
        "classification": "INTERNAL_ERROR"
      }
    }
  ],
  "data": null,
  "extensions": {
    "requestId": "request-id-2cf7513cc919"
  }
}

{
  "errors": [
    {
      "message": "Internal Server Error",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["itemList"],
      "extensions": {
        "code": "InternalError",
        "classification": "INTERNAL_ERROR"
      }
    }
  ],
  "data": null,
  "extensions": {
    "requestId": "request-id-2cf7513cc919"
  }
}