Sales Opportunities

Search

The following example fetches the first page of Sales Opportunities in the UK region, retrieving their total value and the list, type and amount of each Opportunity Interest

query{
  opportunities(filters:[
    {field: regionName, operation: eq, value: "UK"}
  ]) {
    edges{
      node{
        id 
        name
        value{
          grandTotal
        }
        interests{
          edges{
            node{
              id
              __typename
              totalAmount
            }
          }
        }
      }
    }
  }
}

For the full range of available filters see the OpportunityField API Reference.

Create

The following creates an opportunity in the specified region:

mutation{
  opportunities{
    create(input:{
      name: "First Aid course"
      regionId:"UmVnaW9uOkRS"
    }) {
      errors{
        label 
        message 
        value
      }
      opportunity{
        id
        step{
          id
          name
          stage{
            id
            name
            state
          }
        }
      }
    }
  }
}

The response will contain the ID of the newly created opportunity and will inform us that it has been created in the "Proposed" step of the "Proposed" stage:

{
  "data": {
    "opportunities": {
      "create": {
        "errors": [],
        "opportunity": {
          "id": "T3Bwb3J0dW5pdHk6Mg==",
          "step": {
            "id": "T3Bwb3J0dW5pdHlTdGVwOjM=",
            "name": "Proposed",
            "stage": {
              "id": "T3Bwb3J0dW5pdHlTdGFnZToz",
              "name": "Proposed",
              "state": "Open"
            }
          }
        }
      }
    }
  }
}

For the full range of available create parameters see the OpportunityCreateInput API Reference.

Update

The following updates the previous opportunity with the specified currency and assigns it to an account

mutation{
  opportunities{
    update(input:{
      id: "T3Bwb3J0dW5pdHk6MQ=="
      financialUnitId: "USD"
      accountId: "T3JnYW5pc2F0aW9uOjI="
    }) {
      errors{
        label 
        message 
        value
      }
      opportunity{
        id
        account{
          id 
          name
        }
        financialUnit{
          name
          ... on Currency{
            code
            symbol
          }
        }
      }
    }
  }
}

The response confirms that account and currency have been updated:

{
  "data": {
    "opportunities": {
      "update": {
        "errors": [],
        "opportunity": {
          "id": "T3Bwb3J0dW5pdHk6MQ==",
          "account": {
            "id": "T3JnYW5pc2F0aW9uOjI=",
            "name": "Administrate"
          },
          "financialUnit": {
            "name": "U.S. Dollars",
            "code": "USD",
            "symbol": "$"
          }
        }
      }
    }
  }
}

For the full range of available update parameters see the OpportunityUpdateInput API Reference.

Transitions

An Opportunity will typically progress from an initial entry step through intermediate steps to a final step in the Won, Lost or Archived state.

Progressing an opportunity executes a transition, which can be configured in the TMS to perform certain actions such as: create account, contact, registration, invoice etc.

The following progresses the opportunity to the specified step:

mutation{
  opportunities{
    progress(input:{
      opportunityId: "T3Bwb3J0dW5pdHk6Mg=="
      stepId: "T3Bwb3J0dW5pdHlTdGVwOjQ="
    }) {
      errors{
        label 
        message 
        value
      }
      opportunity{
        id
        step{
          id
          name
        }
      }
    }
  }
}

The response will confirm the Opportunity has transitioned:

{
  "data": {
    "opportunities": {
      "progress": {
        "errors": [],
        "opportunity": {
          "id": "T3Bwb3J0dW5pdHk6Mg==",
          "step": {
            "id": "T3Bwb3J0dW5pdHlTdGVwOjQ=",
            "name": "Opportunity"
          }
        }
      }
    }
  }
}

Attention: there must be a transition configured in the TMS from the current step to the desired step, otherwise the following error response will be returned

{
  "data": {
    "opportunities": {
      "progress": {
        "errors": [
          {
            "label": "Transition Not Found",
            "message": "Transition from step T3Bwb3J0dW5pdHlTdGVwOjM= to step T3Bwb3J0dW5pdHlTdGVwOjQ= not found",
            "value": null
          }
        ],
        "opportunity": null
      }
    }
  }
}

Interests

An Opportunity typically will have Interests that the prospect is intending to purchase. These can be Events, Courses, Learning Paths and Training Tokens.

Course Templates

A published course template can be added as an interest. The below example:

• adds a course as an interest (the provided id is a Course Template)
• sets a quantity of 1 and a unit amount of 199.90
• optionally specifies a named learner

mutation{
  opportunities{
    addInterest(input:{
      opportunityId: "T3Bwb3J0dW5pdHk6Mg=="
      interestDetails:{
        id: "Q291cnNlVGVtcGxhdGU6MTE="
        quantity: 1
        unitAmount: "199.90"
        courseDetails: {
          existingLearners:[]
          newLearners: [{
            firstName: "Melissa"
            lastName: "Green"
            email: "melissa@example.com"
          }]
        }
      }
    }) {
      errors{
        label 
        message 
        value
      }
      interests{
        id
        item{
          id
          __typename
          ... on CourseTemplate{
            code
            title
          }
        }
      }
    }
  }
}

The response confirms the course has been selected

{
  "data": {
    "opportunities": {
      "addInterest": {
        "errors": [],
        "interests": [
          {
            "id": "T3Bwb3J0dW5pdHlJbnRlcmVzdDox",
            "item": {
              "id": "Q291cnNlVGVtcGxhdGU6MTE=",
              "__typename": "CourseTemplate",
              "code": "ABC-123",
              "title": "My New Course"
            }
          }
        ]
      }
    }
  }
}

Events

Event interests can be added in exactly the same way by supplying the id of an Event.

The reserve flag reserves a number of spaces on the Event matching the interest quantity. This is useful to ensure the event does not sell out before the Opportunity Registration is generated.

mutation {
  opportunities {
    addInterest(input: {
      opportunityId: "T3Bwb3J0dW5pdHk6Mg==",
      interestDetails: {
        id: "Q291cnNlOjE=",
        reserve: true,
        quantity: 1,
        unitAmount: "199.90",
        eventDetails: {
          existingLearners: [],
          newLearners: [{
            firstName: "Melissa", lastName: "Green", email: "melissa@example.com"
          }]
        }
      }
    }) {
      errors {
        label
        message
        value
      }
      interests {
        id
        item {
          id
          __typename
          ... on CourseTemplate {
            code
            title
          }
        }
      }
    }
  }
}

Learning Paths

Like the above examples, Learning Paths follow the same pattern:

mutation {
  opportunities {
    addInterest(input: {
      opportunityId: "T3Bwb3J0dW5pdHk6Mg==",
      interestDetails: {
        id: "TGVhcm5pbmdQYXRoOjE=",
        quantity: 1,
        unitAmount: "199.90",
        learningPathDetails:{
          existingLearners: [],
          newLearners: [{
            firstName: "Melissa", lastName: "Green", email: "melissa@example.com"
          }]
        }
      }
    }) {
      errors {
        label
        message
        value
      }
      interests {
        id
        item {
          id
          __typename
          ... on LearningPath {
            code
            name
          }
        }
      }
    }
  }
}

Training Tokens

Training Token interests allow specifying the expiry time

mutation {
  opportunities {
    addInterest(input: {
      opportunityId: "T3Bwb3J0dW5pdHk6Mg==",
      interestDetails: {
        id: "VG9rZW5UeXBlOjg4NDhhM2IzOGFkZjQ1ZGI4ZmY2MGZhZmNiZDNiM2Y2",
        quantity: 10,
        unitAmount: "19.90",
        trainingTokenDetails:{
          expiresAt: "2023-12-31T23:59:59"
        }
      }
    }) {
      errors {
        label
        message
        value
      }
      interests {
        id
        item {
          id
          __typename
          ... on TrainingTokenType {
            name
          }
        }
      }
    }
  }
}