Commission Packages

In this example we take you through how to work with Commission Packages using the Operator API.

  6 minute read  

What you’ll learn

  • What are Commission Packages
  • API Queries and mutations related to Commission Packages
  • Commission Package FAQ

What are Commission Packages

Commission packages can be created and defined by operators, allowing the Operator to have control over the commission that is charged to the sellers operating on the marketplace. Operators can use the Operator API to:

  • Create Commission Packages & assign them to sellers
  • Change the Commission Package assigned to a seller
  • Schedule bulk changes to the commission package

Operators can also subscribe to the Commission Package webhook to be alerted to create, update and destroy events.

Example use-case

An example use case may be a two package system where you create a “Gold Package” with lower rates on specific categories for your high performing sellers. Followed by a “Silver Package” which has a simpler 15% global rate for your newer sellers.

API Queries and Mutations

The following queries and mutations can be used to manipulate Commission Packages using the Operator API.

Querying all Commission Packages

Returns a collection of commission packages available on the marketplace.

query {
  commissionPackages {
    totalCount
    nodes {
      id
      name
      rate
      appliesToPostage
      sellers {
        totalCount
        nodes {
          id
          businessName
        }
      }
      customCommissionRates {
        totalCount
        nodes {
          id
          rate
          taxon {
            id
            displayName
          }
          thresholdPrice
          overThresholdRate
        }
      }
    }
  }
}

Querying Commission Packages with a filter

query {
  commissionPackages(
    createdSince: "2023-02-10T00:00:00+11:00"
    createdUntil: "2023-02-14T00:00:00+11:00"
    retailerIds: ["U2VsbGVyLTI="]
    sort: { fields: CUSTOM_RATES_COUNT, ordering: ASCENDING }
  ) {
    totalCount
    edges {
      node {
        id
        name
        rate
        appliesToPostage
        sellers {
          totalCount
          edges {
            node {
              id
              businessName
              isRetailer
            }
          }
        }
        customCommissionRates {
          totalCount
          edges {
            node {
              id
              rate
              taxon {
                id
                displayName
              }
              thresholdPrice
              overThresholdRate
            }
          }
        }
      }
    }
  }
}

Creating a Commission Package

mutation commissionPackageCreate {
  commissionPackageCreate(
    input: {
      attributes: {
        name: "AAA packages"
        rate: "10.1"
        appliesToPostage: true
        customCommissionRates: [
          { rate: "1.5", taxonId: "VGF4b24tMjA4NQ==" }
          { rate: "1.4", taxonId: "VGF4b24tMjA5MQ==" }
          { rate: "1.3", taxonId: "VGF4b24tMjA5Mw==" }
        ]
      }
    }
  ) {
    errors {
      field
      messages
    }
    commissionPackage {
      id
      name
      rate
      appliesToPostage
      sellers {
        totalCount
        nodes {
          id
          businessName
        }
      }
      customCommissionRates {
        nodes {
          id
          rate
          taxon {
            displayName
          }
          thresholdPrice
          overThresholdRate
        }
      }
    }
  }
}

Updating a Commission Package

mutation commissionPackageUpdate {
  commissionPackageUpdate(
    input: {
      commissionPackageId: "Q29tbWlzc2lvblBhY2thZ2UtMTY="
      attributes: {
        name: "Fifteenth Gold"
        rate: "11"
        appliesToPostage: false
        customCommissionRates: [
          { 
            # New custom rate
            rate: "1.7", 
            taxonId: "VGF4b24tMjAyOA==" }
          {
            # Existing custom rate
            id: "Q3VzdG9tQ29tbWlzc2lvblJhdGUtMTc="
            rate: "1.6"
            thresholdPrice: "500.00"
            overThresholdRate: "1.8"
          }
          { 
            # Delete custom rate
            id: "Q3VzdG9tQ29tbWlzc2lvblJhdGUtMTY=" 
            delete: true }
        ]
      }
    }
  ) {
    errors {
      field
      messages
    }
    commissionPackage {
      id
      name
      rate
      appliesToPostage
      sellers {
        totalCount
        nodes {
          id
          businessName
        }
      }
      customCommissionRates {
        nodes {
          id
          rate
          taxon {
            displayName
          }
          thresholdPrice
          overThresholdRate
        }
      }
    }
  }
}

Delete a Commission Package

mutation commissionPackageDelete {
  commissionPackageDelete(
    input: {
      id: "Q29tbWlzc2lvblBhY2thZ2UtNA=="
      moveToPackageId: "Q29tbWlzc2lvblBhY2thZ2UtMw=="
    }
  ) {
    errors {
      field
      messages
    }
    commissionPackage {
      id
      name
      rate
      appliesToPostage
      sellers {
        totalCount
        nodes {
          id
          businessName
        }
      }
      customCommissionRates {
        nodes {
          id
          rate
          taxon {
            displayName
          }
        }
      }
    }
  }
}

Initiate task to upload Schedule

This call allows you to associate Sellers with Commission Packages through the use of a scheduled batch assignment. The process works in the following way:

  1. Create a CSV with the Package to Seller assignments (further detail below)
  2. Upload the CSV specifying the day you want it to take effect
  • In this case we’ll use the commissionPackageScheduleSpreadsheetUpload mutation
  1. When the scheduled day is reached, the assignments in the CSV will take effect.

CSV File Creation

An example CSV template can be downloaded from the Operator Portal in in the following way:

  • Select Commission Package Scheduling from the Operator Portal main menu
  • Select Create schedule
  • You can then download an example template from this location

You then assign Sellers to Commission Packages by listing the Commission Package name against the Seller ID, an example “raw” CSV file is shown below for 1 seller:

"Package Name","Seller Id"
"Gold Package",660119

Note: Only include double quotes (") when you have to enclose white-space, do not use double quotes to contain the Seller Id for example.


Uploading the csv file

To upload the file you will then need to Base64 encode it, an example of the Base64 encoded file above is shown below:

IlBhY2thZ2UgTmFtZSIsIlNlbGxlciBJZCIKIkdvbGQgUGFja2FnZSIsNjYwMTE5

The call the commissionPackageScheduleSpreadsheetUpload as follows:

mutation {
  commissionPackageScheduleSpreadsheetUpload(
    input: {
      activationDate: "2023-04-08T00:00:00+10:00"
      spreadsheet: { 
        dataBase64: ""IlBhY2thZ2UgTmFtZSIsIlNlbGxlciBJZCIKIkdvbGQgUGFja2FnZSIsNjYwMTE5", 
        filename: "schedule1.csv" }
    }
  ) {
    errors {
      field
      messages
    }
    import {
      id
      className
      createdAt
      expectedResultCount
      failedCount
      file {
        id
        filename
        size
        url
      }
      humanClassName
      processedCount
      status
      updatedAt
    }
  }
}

The Commission Package scheduler runs daily at around ~12am, so you can only specify the day that you want to apply the uploaded assignments (the time component will be ignored).

Querying Package Schedules

query cps {
  commissionPackageSchedules {
    totalCount
    edges {
      node {
        id
        status
        activationDate
        commissionPackageScheduleItems {
          totalCount
          nodes {
            id
            seller {
              businessName
            }
            commissionPackage {
              id
              name
              rate
              default
              appliesToPostage
              customCommissionRates {
                totalCount
                nodes {
                  id
                  rate
                  taxon {
                    displayName
                  }
                }
              }
              sellers {
                edges {
                  node {
                    businessName
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Deleting a schedule

mutation ($id: ID!) {
  commissionPackageScheduleDelete(input: { id: $id }) {
    errors {
      field
      messages
    }
  }
}

Initiate task to download schedule

mutation ($id: ID!) {
  commissionPackageScheduleSpreadsheetDownload(
    input: {
      commissionPackageScheduleId: $id
      format: XLSX
      invalidOnly: false
    }
  ) {
    errors {
      field
      messages
    }
    export {
      createdAt
      expectedResultCount
      failedCount
      file {
        id
        filename
        size
        url
      }
      className
      humanClassName
      id
      legacyId
      processedCount
      status
      updatedAt
    }
  }
}

Commission Package Version Logs

query ($sellerId: ID!) {
  commissionPackageVersionLogs(retailerId: $sellerId) {
    totalCount
    edges {
      node {
        id
        startedOn
        commissionPackageVersion {
          id
          legacyId
          name
          active
          defaultRate
          appliesToPostage
          createdAt
          customRates {
            totalCount
            edges {
              node {
                id
                rate
                taxon {
                  id
                  title
                }
              }
            }
          }
        }
      }
    }
  }
}

FAQ

  • Why would an Operator move from Commission Rules to Commission Packages?
    • Commission Packages can be manipulated via the Operator API
    • Commission Packages support webhooks
    • Commission Packages allow for scheduling changes on future dates
    • Commission Packages allow us to store the CommissionRate at the Variant level
    • Commission Packages include UI components in the Seller Portal 2.0 so a Seller can tell what Commission Package they are on
    • Commission Packages support versioning, so an operator and seller can observe the history of the packages