Overview

Endpoint: https://commissions.api.cj.com/query

The Commission Detail API is a GraphQL API available to both advertisers and publishers to access near real-time commission data from their accounts. This is useful for anyone who wants the freshest commission data available, or for anyone who needs commission data updated on a regular basis. A variety of search criteria are supported, including posting date range, ad IDs, action statuses, and more.

Sample Requests and Responses

Publisher Request

curl -H "Authorization: Bearer <your-personal-access-token>" \
  -XPOST https://commissions.api.cj.com/query \
  -d '{
    publisherCommissions(
      forPublishers: ["999"],
      sincePostingDate: "2018-08-08T00:00:00Z",
      beforePostingDate: "2018-08-09T00:00:00Z"
    ) {
      count
      payloadComplete
      records {
        actionTrackerName
        websiteName
        advertiserName
        postingDate
        pubCommissionAmountUsd
        items {
          quantity
          perItemSaleAmountPubCurrency
          totalCommissionPubCurrency
        }
      }
    }
  }'

Publisher Response

{
  "data": {
    "publisherCommissions": {
      "count": 2,
      "payloadComplete": true,
      "records": [
        {
          "actionTrackerName": "Advanced Sale Test",
          "websiteName": "Donuts and Denim",
          "advertiserName": "Visit Canada",
          "commissionId": "2292067663",
          "postingDate": "2018-05-03T22:31:48Z",
          "pubCommissionAmountUsd": "7.781",
          "items": [
            {
              "quantity": 1,
              "perItemSaleAmountPubCurrency": "75.474",
              "totalCommissionPubCurrency": "7.548"
            }
          ]
        },
        {
          "actionTrackerName": "Advanced Sale Test",
          "websiteName": "Donuts and Denim",
          "advertiserName": "Visit Canada",
          "commissionId": "2292491812",
          "postingDate": "2018-05-04T19:00:21Z",
          "pubCommissionAmountUsd": "3.89",
          "items": [
            {
              "quantity": 1,
              "perItemSaleAmountPubCurrency": "37.737",
              "totalCommissionPubCurrency": "3.773"
            }
          ]
        }
      ]
    }
  }
}

Encoding / Compression

Compression is not available at this time.

Errors

Pagination

This API uses cursor-based paging.

If the value of payloadComplete is false, there is more data to retrieve. Read the value of maxCommissionId to get the current cursor position. In your next query call, set sinceCommissionId to this value. Repeat until payloadComplete is true.

API Usage Caps and Limits

• Date range: No more than 31 days per query.
• Payload size: No more than 10,000 commissions per call. Use maxCommissionId from each call as sinceCommissionId in subsequent calls to retrieve all data.
• Concurrent connections: Maximum 120. If all connections are busy, your query will fail — try again later.
• Call limit: 200 calls per 5 minutes.

Corrections

To identify whether a transaction was the original or a correction, request the original field in the body of your query. It returns true for an original transaction and false for a non-original (corrected) transaction. Both the original and corrected records share the same orderId but have different commissionId values.

Original and corrected records are delta records — combine their values to get the final order amounts:

• Simple sale: Combine the amount values from both records.
• Advanced sale (item-level): Combine quantities by item from both records, then multiply the final quantity by the per-item amount and commission fields.

Example of a fully corrected/cancelled order:

{ "original": true,  "pubCommissionAmountUsd": "1.852",  "saleAmountUsd": "61.742",  "orderId": "69461063" }
{ "original": false, "pubCommissionAmountUsd": "-1.852", "saleAmountUsd": "-61.742", "orderId": "69461063" }

Best Practices

• Implied date range defaults: If you specify only one bound of a date range (e.g. sinceEventDate but not beforeEventDate), the corresponding bound defaults to 24 hours from the specified bound. If no arguments are specified, data from the past 24 hours by posting date is returned.
• Optimize field selection: Some fields take longer to resolve than others — for example, the situations field at both the parent and item levels. Omit fields you do not need to improve query performance.

Object: Item

A record of an item that was purchased as part of a commissionable event.

Computed fields: situations

Object: Situation

Situation used for commissioning.

Enum: CorrectionReason

List of reasons for correcting a transaction.

Values: INVALID_CREDIT_CARD, RETURNED_MERCHANDISE, DUPLICATED_ORDER, CANT_SHIP_OR_SOLD_OUT, UNQUALIFIED_LEAD, QUALIFIED_LEAD, OTHER_REASON

Enum: LockingMethod

Locking Method for commissions.

Enum: ValidationStatus

Indicates whether an order is pending validation or has been validated by advertiser.

Scalar: ActionStatus

Possible values: closed, extended, locked, new.

• New: All transactions that have recently taken place begin in this status. These transactions remain 'new' until you either correct/reverse them, extend them, or they lock (normally 2am PST on the 11th of each month).
• Extended: In the standard transaction lifecycle, you are allowed to extend any or all transactions to the next payment cycle (one-time only), a fairly common practice for advertisers with lengthy product return periods/policies. If you extend a transaction, it will move from a status of New to Extended and will remain as such until either you correct/reverse the transaction or it locks on the 11th of the month after the extension ends.
• Locked: In the standard transaction lifecycle, transactions lock at 2am PST on the 11th of each month. Once a transaction has a status of locked, you can no longer correct or extend it - it has moved into the publisher payout cycle.
• Closed: Transaction has been prepared for payment.

Scalar: ActionType

Possible values: bonus, click, imp, item_lead, item_sale, perf_inc, sim_lead, sim_sale.

• Sim_sale (Simple Sale): Traditional sale type transaction, doesn't usually include product/item level detail.
• Sim_lead (Simple Lead): Lead based transaction type, doesn't usually include product/item level detail.
• Item_sale (Item Sale): Traditional sale transaction but includes item level details (i.e. quantity, sku, etc.).
• Item_lead (Item Lead): Lead based transaction with item level details.
• Imp (Impression): This will be used if an advertiser tracks/pays out on the impression.
• Click: This will be used if an advertiser tracks/pays out on the click.
• Perf_inc (Performance Incentive): Some advertisers will add performance incentives to their program terms and pay out if certain thresholds are met.
• Bonus: This will be used if the Advertiser needs to bonus a publisher a one time amount.

Scalar: Boolean

The Boolean scalar type represents true or false.

Scalar: DecimalNumber

A numerical value, rendered in JSON as a string. This allows for a greater range of expression than GraphQL's default Float type supports. For reliable client-side parsing, the string value will always match the regex pattern (-)?[0-9]+(\.[0-9]+)?

Scalar: Instant

A Datetime in UTC ISO 8601 format with Z as the zone designator for the zero UTC offset, rendered in JSON as a string.

Scalar: Int

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Scalar: String

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.