Create an Opportunity

POST https://api.chartmogul.com/v1/opportunities

Creates an opportunity object for a specified customer in ChartMogul.

curl -X POST "https://api.chartmogul.com/v1/opportunities" \
     -u YOUR_API_KEY: \
     -H "Content-Type: application/json" \
     -d '{
            "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
            "owner": "[email protected]",
            "pipeline": "New Business",
            "pipeline_stage": "Discovery",
            "estimated_close_date": "2024-04-21",
            "currency": "USD",
            "amount_in_cents": 100000,
            "type": "recurring",
            "forecast_category": "best_case",
            "win_likelihood": 40,
            "custom":[
              {"key": "seats","value":3},
              {"key":"marketing_campaign","value":"Facebook"}
            ]
        }'

ChartMogul::Opportunity.create!(
  customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  owner: "[email protected]",
  pipeline: "New Business",
  pipeline_stage: "Discovery",
  estimated_close_date: "2024-03-30",
  currency: "USD",
  amount_in_cents: 100_000,
  type: "one-time",
  forecast_category: "best_case",
  win_likelihood: 30,
  custom: [
    { key: "seats", value: 3 },
    { key: "marketing_campaign", value: "Facebook" },
  ],
)

ChartMogul.Opportunity.create(config, {
  customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  owner: "[email protected]",
  pipeline: "New Business",
  pipeline_stage: "Discovery",
  estimated_close_date: "2024-03-30",
  currency: "USD",
  amount_in_cents: 100_000,
  type: "one-time",
  forecast_category: "best_case",
  win_likelihood: 30,
  custom: [
    { key: "seats", value: 3 },
    { key: "marketing_campaign", value: "Facebook" },
  ],
});

ChartMogul\Opportunity::create([
  "customer_uuid" => "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "owner" => "[email protected]",
  "pipeline" => "New Business",
  "pipeline_stage" => "Discovery",
  "estimated_close_date" => "2023-12-22",
  "currency" => "USD",
  "amount_in_cents" => 100,
  "type" => "recurring",
  "forecast_category" => "pipeline",
  "win_likelihood" => 3,
  "custom" => [
    ["key" => "seats", "value" => 3],
    ["key" => "marketing_campaign", "value" => "Facebook"],
  ]
]);

api.CreateOpportunity(&cm.NewOpportunity{
  CustomerUUID:       "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  Owner:              "[email protected]",
  Pipeline:           "New Business",
  PipelineStage:      "Discovery",
  EstimatedCloseDate: "2023-12-22",
  Currency:           "USD",
  AmountInCents:      100,
  Type:               "recurring",
  ForecastCategory:   "pipeline",
  WinLikelihood:      3,
  Custom: []cm.Custom{
    {
      Key:   "seats",
      Value: 3,
    },
    {
      Key:   "marketing_campaign",
      Value: "Facebook",
    },
  },
})

chartmogul.Opportunity.create(
  config,
  data={
    "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
    "owner": "[email protected]",
    "pipeline": "New Business",
    "pipeline_stage": "Discovery",
    "estimated_close_date": "2023-12-22",
    "currency": "USD",
    "amount_in_cents": 100,
    "type": "recurring",
    "forecast_category": "pipeline",
    "win_likelihood": 3,
    "custom": [
        {"key": "seats", "value": 3},
        {"key": "marketing_campaign", "value": "Facebook"},
    ],
  },
)

{
  "uuid": "4ee13ca4-e7fe-11ee-fa7f-f303abf41acc",
  "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "owner": "[email protected]",
  "pipeline": "New Business",
  "pipeline_stage": "Discovery",
  "estimated_close_date": "2024-04-21",
  "currency": "USD",
  "amount_in_cents": 10000,
  "type": "recurring",
  "forecast_category": "best_case",
  "win_likelihood": 40,
  "custom": {
    "seats": 3,
    "marketing_campaign": "Facebook"
  },
  "created_at": "2024-03-20T09:55:50.156Z",
  "updated_at": "2024-03-20T09:55:50.156Z"
}

#<ChartMogul::Opportunity:0x00000001058a8210
  @uuid="2f0b0748-e54b-11ee-81c1-5bf123d9787a", 
  @created_at="2024-03-18T17:15:56.960Z", 
  @updated_at="2024-03-18T17:15:56.960Z",
  @customer_uuid="cus_f466e33d-ff2b-4a11-8f85-417eb02157a7", 
  @owner="[email protected]",
  @pipeline="New Business", 
  @pipeline_stage="Discovery", 
  @estimated_close_date="2024-03-30", 
  @currency="USD", 
  @amount_in_cents=100000, 
  @type="one-time", 
  @forecast_category="best_case", 
  @win_likelihood=30, 
  @custom={
    :seats=>3,
    :marketing_campaign=>"Facebook",
  }
>

{
  uuid: "4ee13ca4-e7fe-11ee-fa7f-f303abf41acc",
  customer_uuid: "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  owner: "[email protected]",
  pipeline: "New Business",
  pipeline_stage: "Discovery",
  estimated_close_date: "2024-04-21",
  currency: "USD",
  amount_in_cents: 10000,
  type: "recurring",
  forecast_category: "best_case",
  win_likelihood: 40,
  custom: {
    seats: 3,
    marketing_campaign: "Facebook"
  },
  created_at: "2024-03-20T09:55:50.156Z",
  updated_at: "2024-03-20T09:55:50.156Z"
}

class ChartMogul\Opportunity (14) {
  protected $uuid => string(36) "4ee13ca4-e7fe-11ee-fa7f-f303abf41acc"
  protected $customer_uuid => string(40) "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7"
  protected $owner => string(15) "[email protected]"
  protected $pipeline => string(14) "New Business"
  protected $pipeline_stage => string(9) "Discovery"
  protected $estimated_close_date => string(10) "2023-12-22"
  protected $currency => string(3) "USD"
  protected $amount_in_cents => int(100)
  protected $type => string(9) "recurring"
  protected $forecast_category => string(8) "pipeline"
  protected $win_likelihood => int(3)
  protected $custom => array(2) {
    ["seats"] => int(3),
    ["marketing_campaign"] => string(8) "Facebook"
  }
  protected $created_at => string(24) "2024-03-13T07:33:28.356Z"
  protected $updated_at => string(24) "2024-03-13T07:33:28.356Z"
}

(*chartmogul.Opportunity)(0x140004032b0)({
  UUID: (string) (len=36) "4ee13ca4-e7fe-11ee-fa7f-f303abf41acc",
  CustomerUUID: (string) (len=40) "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  Owner: (string) (len=15) "[email protected]",
  Pipeline: (string) (len=14) "New Business",
  PipelineStage: (string) (len=9) "Discovery",
  EstimatedCloseDate: (string) (len=10) "2023-12-22",
  Currency: (string) (len=3) "USD",
  AmountInCents: (int) 100,
  Type: (string) (len=9) "recurring",
  ForecastCategory: (string) (len=8) "pipeline",
  WinLikelihood: (int) 3,
  Custom: (map[string]interface {}) (len=1) {
    (string) (len=5) "seats": (int) 3,
    (string) (len=18) "marketing_campaign": (string) (len=8) "Facebook"
  },
  CreatedAt: (string) (len=24) "2024-03-13T07:33:28.356Z",
  UpdatedAt: (string) (len=24) "2024-03-13T07:33:28.356Z"
})

<Opportunity{
  "uuid": "4ee13ca4-e7fe-11ee-fa7f-f303abf41acc",
  "customer_uuid": "cus_f466e33d-ff2b-4a11-8f85-417eb02157a7",
  "owner": "[email protected]",
  "pipeline": "New Business",
  "pipeline_stage": "Discovery",
  "estimated_close_date": "2023-12-22",
  "currency": "USD",
  "amount_in_cents": 100,
  "type": "recurring",
  "forecast_category": "pipeline",
  "win_likelihood": 3,
  "custom": {"seats": 3, "marketing_campaign": "Facebook"},
  "created_at": "2024-03-13T07:33:28.356Z",
  "updated_at": "2024-03-13T07:33:28.356Z"
}>

Access to the Opportunities endpoints. To use the Opportunities endpoints, you need an API key created by a user with a CRM seat.

Body parameters

customer_uuid string required

The ChartMogul UUID of the customer associated with the opportunity.

owner string required

The email address of the ChartMogul user with a CRM seat who is the primary salesperson responsible for this opportunity.

pipeline string required

The sales pipeline name. The pipeline must already exist in ChartMogul. Use one of the default sales pipelines or set up a new one.

pipeline_stage string required

The name of the current deal stage within the sales pipeline. If a stage is not present in ChartMogul, first add it in the app.

estimated_close_date string required

The date when the opportunity is expected to close. Must be an ISO 8601-formatted date.

amount_in_cents integer required

Amount in cents (or pence for GBP, etc.) of expected close value of this opportunity.

currency string required

The three-letter currency code of the currency of the expected close value, e.g. USD, EUR or GBP. Read thefull list of supported currencies.

type string optional

The opportunity type: recurring for opportunities expected to convert into a subscription or one_time for opportunities expected to convert into one-time upsells.

forecast_category string optional

The opportunity’s grouping based on its likelihood of closing. One of five pre-defined forecast categories: pipeline, best_case, committed, lost or won. If not provided, it is set to the default forecast category for a given pipeline stage.

win_likelihood integer optional

An integer between 0 and 100 representing the likelihood (as a percentage) that this opportunity will successfully close. If not provided, it is set to the default win likelihood for a given pipeline stage.

custom array(object) optional

A list of custom attributes (as key and value pairs) you’re adding to the opportunity. The key must match one of the attribute names listed under Settings & Data > Custom Attributes > Opportunities. To add a custom attribute outside of this list, first create it in ChartMogul.

key string required: The name of the custom attribute assigned to this opportunity. Only accepts alphanumeric characters and underscores.
value string required: The value of the custom attribute assigned to this opportunity. Must match one of the five types specified for this custom attribute key when creating the custom attribute.

Response

The response object contains the following data:

uuid: The ChartMogul UUID of the opportunity.
customer_uuid: The ChartMogul UUID of the customer associated with the opportunity.
owner: The email address of the ChartMogul user with a CRM seat who is the primary salesperson responsible for this opportunity.
pipeline: The sales pipeline name.
pipeline_stage: The sales pipeline deal stage name.
estimated_close_date: The date when the opportunity is expected to close as an ISO 8601-formatted string or, in the case of the Ruby and Python libraries, a datetime object.
amount_in_cents: The amount in cents (or pence for GBP, etc.) of the expected close value of this opportunity.
currency: The three-letter currency code of the currency of the expected close value, e.g. USD, EUR or GBP. Read the full list of supported currencies.
type: The opportunity type, either recurring or one_time.
forecast_category: The forecast category. One of pipeline, best_case, committed, lost or won values.
win_likelihood: A percentage (from 0 to 100) representing the likelihood that this opportunity will successfully close.
custom: A list of key/value pairs of custom attributes assigned to this opportunity.
created_at: The date and time when the opportunity was created as an ISO 8601-formatted string or, in the case of the Ruby and Python libraries, a datetime object.
updated_at: The date and time when the opportunity was last updated as an ISO 8601-formatted string or, in the case of the Ruby and Python libraries, a datetime object.