Edit a contract

curl --request POST \
  --url https://api.metronome.com/v2/contracts/edit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
  "contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
  "add_overrides": [
    {
      "type": "MULTIPLIER",
      "starting_at": "2024-11-02T00:00:00Z",
      "product_id": "d4fc086c-d8e5-4091-a235-fbba5da4ec14",
      "multiplier": 2,
      "priority": 100
    }
  ],
  "add_scheduled_charges": [
    {
      "product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
      "schedule": {
        "schedule_items": [
          {
            "timestamp": "2020-02-15T00:00:00.000Z",
            "unit_price": 1000000,
            "quantity": 1
          }
        ]
      }
    }
  ]
}
'

import requests

url = "https://api.metronome.com/v2/contracts/edit"

payload = {
    "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
    "contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
    "add_overrides": [
        {
            "type": "MULTIPLIER",
            "starting_at": "2024-11-02T00:00:00Z",
            "product_id": "d4fc086c-d8e5-4091-a235-fbba5da4ec14",
            "multiplier": 2,
            "priority": 100
        }
    ],
    "add_scheduled_charges": [
        {
            "product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
            "schedule": { "schedule_items": [
                    {
                        "timestamp": "2020-02-15T00:00:00.000Z",
                        "unit_price": 1000000,
                        "quantity": 1
                    }
                ] }
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
    contract_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
    add_overrides: [
      {
        type: 'MULTIPLIER',
        starting_at: '2024-11-02T00:00:00Z',
        product_id: 'd4fc086c-d8e5-4091-a235-fbba5da4ec14',
        multiplier: 2,
        priority: 100
      }
    ],
    add_scheduled_charges: [
      {
        product_id: '2e30f074-d04c-412e-a134-851ebfa5ceb2',
        schedule: {
          schedule_items: [{timestamp: '2020-02-15T00:00:00.000Z', unit_price: 1000000, quantity: 1}]
        }
      }
    ]
  })
};

fetch('https://api.metronome.com/v2/contracts/edit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.metronome.com/v2/contracts/edit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer_id' => '13117714-3f05-48e5-a6e9-a66093f13b4d',
    'contract_id' => 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
    'add_overrides' => [
        [
                'type' => 'MULTIPLIER',
                'starting_at' => '2024-11-02T00:00:00Z',
                'product_id' => 'd4fc086c-d8e5-4091-a235-fbba5da4ec14',
                'multiplier' => 2,
                'priority' => 100
        ]
    ],
    'add_scheduled_charges' => [
        [
                'product_id' => '2e30f074-d04c-412e-a134-851ebfa5ceb2',
                'schedule' => [
                                'schedule_items' => [
                                                                [
                                                                                                                                'timestamp' => '2020-02-15T00:00:00.000Z',
                                                                                                                                'unit_price' => 1000000,
                                                                                                                                'quantity' => 1
                                                                ]
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.metronome.com/v2/contracts/edit"

	payload := strings.NewReader("{\n  \"customer_id\": \"13117714-3f05-48e5-a6e9-a66093f13b4d\",\n  \"contract_id\": \"d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc\",\n  \"add_overrides\": [\n    {\n      \"type\": \"MULTIPLIER\",\n      \"starting_at\": \"2024-11-02T00:00:00Z\",\n      \"product_id\": \"d4fc086c-d8e5-4091-a235-fbba5da4ec14\",\n      \"multiplier\": 2,\n      \"priority\": 100\n    }\n  ],\n  \"add_scheduled_charges\": [\n    {\n      \"product_id\": \"2e30f074-d04c-412e-a134-851ebfa5ceb2\",\n      \"schedule\": {\n        \"schedule_items\": [\n          {\n            \"timestamp\": \"2020-02-15T00:00:00.000Z\",\n            \"unit_price\": 1000000,\n            \"quantity\": 1\n          }\n        ]\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.metronome.com/v2/contracts/edit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer_id\": \"13117714-3f05-48e5-a6e9-a66093f13b4d\",\n  \"contract_id\": \"d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc\",\n  \"add_overrides\": [\n    {\n      \"type\": \"MULTIPLIER\",\n      \"starting_at\": \"2024-11-02T00:00:00Z\",\n      \"product_id\": \"d4fc086c-d8e5-4091-a235-fbba5da4ec14\",\n      \"multiplier\": 2,\n      \"priority\": 100\n    }\n  ],\n  \"add_scheduled_charges\": [\n    {\n      \"product_id\": \"2e30f074-d04c-412e-a134-851ebfa5ceb2\",\n      \"schedule\": {\n        \"schedule_items\": [\n          {\n            \"timestamp\": \"2020-02-15T00:00:00.000Z\",\n            \"unit_price\": 1000000,\n            \"quantity\": 1\n          }\n        ]\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.metronome.com/v2/contracts/edit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer_id\": \"13117714-3f05-48e5-a6e9-a66093f13b4d\",\n  \"contract_id\": \"d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc\",\n  \"add_overrides\": [\n    {\n      \"type\": \"MULTIPLIER\",\n      \"starting_at\": \"2024-11-02T00:00:00Z\",\n      \"product_id\": \"d4fc086c-d8e5-4091-a235-fbba5da4ec14\",\n      \"multiplier\": 2,\n      \"priority\": 100\n    }\n  ],\n  \"add_scheduled_charges\": [\n    {\n      \"product_id\": \"2e30f074-d04c-412e-a134-851ebfa5ceb2\",\n      \"schedule\": {\n        \"schedule_items\": [\n          {\n            \"timestamp\": \"2020-02-15T00:00:00.000Z\",\n            \"unit_price\": 1000000,\n            \"quantity\": 1\n          }\n        ]\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
  }
}

{
  "message": "<string>"
}

Contracts

Edit a contract

The ability to edit a contract helps you react quickly to the needs of your customers and your business.

Use this endpoint to:

Encode mid-term commitment and discount changes
Fix configuration mistakes and easily roll back packaging changes

Key response fields:

The id of the edit
Complete edit details. For example, if you edited the contract to add new overrides and credits, you will receive the IDs of those overrides and credits in the response.

Usage guidelines:

When you edit a contract, any draft invoices update immediately to reflect that edit. Finalized invoices remain unchanged - you must void and regenerate them in the UI or API to reflect the edit.
Contract editing must be enabled to use this endpoint. Reach out to your Metronome representative to learn more.

POST

contracts

edit

Edit a contract

curl --request POST \
  --url https://api.metronome.com/v2/contracts/edit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
  "contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
  "add_overrides": [
    {
      "type": "MULTIPLIER",
      "starting_at": "2024-11-02T00:00:00Z",
      "product_id": "d4fc086c-d8e5-4091-a235-fbba5da4ec14",
      "multiplier": 2,
      "priority": 100
    }
  ],
  "add_scheduled_charges": [
    {
      "product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
      "schedule": {
        "schedule_items": [
          {
            "timestamp": "2020-02-15T00:00:00.000Z",
            "unit_price": 1000000,
            "quantity": 1
          }
        ]
      }
    }
  ]
}
'

import requests

url = "https://api.metronome.com/v2/contracts/edit"

payload = {
    "customer_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
    "contract_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
    "add_overrides": [
        {
            "type": "MULTIPLIER",
            "starting_at": "2024-11-02T00:00:00Z",
            "product_id": "d4fc086c-d8e5-4091-a235-fbba5da4ec14",
            "multiplier": 2,
            "priority": 100
        }
    ],
    "add_scheduled_charges": [
        {
            "product_id": "2e30f074-d04c-412e-a134-851ebfa5ceb2",
            "schedule": { "schedule_items": [
                    {
                        "timestamp": "2020-02-15T00:00:00.000Z",
                        "unit_price": 1000000,
                        "quantity": 1
                    }
                ] }
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer_id: '13117714-3f05-48e5-a6e9-a66093f13b4d',
    contract_id: 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
    add_overrides: [
      {
        type: 'MULTIPLIER',
        starting_at: '2024-11-02T00:00:00Z',
        product_id: 'd4fc086c-d8e5-4091-a235-fbba5da4ec14',
        multiplier: 2,
        priority: 100
      }
    ],
    add_scheduled_charges: [
      {
        product_id: '2e30f074-d04c-412e-a134-851ebfa5ceb2',
        schedule: {
          schedule_items: [{timestamp: '2020-02-15T00:00:00.000Z', unit_price: 1000000, quantity: 1}]
        }
      }
    ]
  })
};

fetch('https://api.metronome.com/v2/contracts/edit', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.metronome.com/v2/contracts/edit",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer_id' => '13117714-3f05-48e5-a6e9-a66093f13b4d',
    'contract_id' => 'd7abd0cd-4ae9-4db7-8676-e986a4ebd8dc',
    'add_overrides' => [
        [
                'type' => 'MULTIPLIER',
                'starting_at' => '2024-11-02T00:00:00Z',
                'product_id' => 'd4fc086c-d8e5-4091-a235-fbba5da4ec14',
                'multiplier' => 2,
                'priority' => 100
        ]
    ],
    'add_scheduled_charges' => [
        [
                'product_id' => '2e30f074-d04c-412e-a134-851ebfa5ceb2',
                'schedule' => [
                                'schedule_items' => [
                                                                [
                                                                                                                                'timestamp' => '2020-02-15T00:00:00.000Z',
                                                                                                                                'unit_price' => 1000000,
                                                                                                                                'quantity' => 1
                                                                ]
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.metronome.com/v2/contracts/edit"

	payload := strings.NewReader("{\n  \"customer_id\": \"13117714-3f05-48e5-a6e9-a66093f13b4d\",\n  \"contract_id\": \"d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc\",\n  \"add_overrides\": [\n    {\n      \"type\": \"MULTIPLIER\",\n      \"starting_at\": \"2024-11-02T00:00:00Z\",\n      \"product_id\": \"d4fc086c-d8e5-4091-a235-fbba5da4ec14\",\n      \"multiplier\": 2,\n      \"priority\": 100\n    }\n  ],\n  \"add_scheduled_charges\": [\n    {\n      \"product_id\": \"2e30f074-d04c-412e-a134-851ebfa5ceb2\",\n      \"schedule\": {\n        \"schedule_items\": [\n          {\n            \"timestamp\": \"2020-02-15T00:00:00.000Z\",\n            \"unit_price\": 1000000,\n            \"quantity\": 1\n          }\n        ]\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.metronome.com/v2/contracts/edit")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer_id\": \"13117714-3f05-48e5-a6e9-a66093f13b4d\",\n  \"contract_id\": \"d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc\",\n  \"add_overrides\": [\n    {\n      \"type\": \"MULTIPLIER\",\n      \"starting_at\": \"2024-11-02T00:00:00Z\",\n      \"product_id\": \"d4fc086c-d8e5-4091-a235-fbba5da4ec14\",\n      \"multiplier\": 2,\n      \"priority\": 100\n    }\n  ],\n  \"add_scheduled_charges\": [\n    {\n      \"product_id\": \"2e30f074-d04c-412e-a134-851ebfa5ceb2\",\n      \"schedule\": {\n        \"schedule_items\": [\n          {\n            \"timestamp\": \"2020-02-15T00:00:00.000Z\",\n            \"unit_price\": 1000000,\n            \"quantity\": 1\n          }\n        ]\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.metronome.com/v2/contracts/edit")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer_id\": \"13117714-3f05-48e5-a6e9-a66093f13b4d\",\n  \"contract_id\": \"d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc\",\n  \"add_overrides\": [\n    {\n      \"type\": \"MULTIPLIER\",\n      \"starting_at\": \"2024-11-02T00:00:00Z\",\n      \"product_id\": \"d4fc086c-d8e5-4091-a235-fbba5da4ec14\",\n      \"multiplier\": 2,\n      \"priority\": 100\n    }\n  ],\n  \"add_scheduled_charges\": [\n    {\n      \"product_id\": \"2e30f074-d04c-412e-a134-851ebfa5ceb2\",\n      \"schedule\": {\n        \"schedule_items\": [\n          {\n            \"timestamp\": \"2020-02-15T00:00:00.000Z\",\n            \"unit_price\": 1000000,\n            \"quantity\": 1\n          }\n        ]\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc"
  }
}

{
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Contract and customer IDs and fields to update

customer_id

string<uuid>

required

ID of the customer whose contract is being edited

contract_id

string<uuid>

required

ID of the contract being edited

uniqueness_key

string

Optional uniqueness key to prevent duplicate contract edits.

Required string length: 1 - 128

add_commits

object[]

Show child attributes

add_credits

object[]

Show child attributes

add_recurring_commits

object[]

Show child attributes

add_recurring_credits

object[]

Show child attributes

add_overrides

object[]

Show child attributes

add_scheduled_charges

object[]

Show child attributes

add_subscriptions

object[]

Optional list of subscriptions to add to the contract.

Show child attributes

add_spend_threshold_configuration

object

Show child attributes

add_prepaid_balance_threshold_configuration

object

Show child attributes

add_billing_provider_configuration_update

object

Update the billing provider configuration on the contract. Currently only supports adding a billing provider configuration to a contract that does not already have one.

Show child attributes

update_contract_name

string | null

Value to update the contract name to. If not provided, the contract name will remain unchanged.

update_scheduled_charges

object[]

Show child attributes

update_commits

object[]

Show child attributes

update_credits

object[]

Show child attributes

update_recurring_commits

object[]

Edits to these recurring commits will only affect commits whose access schedules has not started. Expired commits, and commits with an active access schedule will remain unchanged.

Show child attributes

update_recurring_credits

object[]

Edits to these recurring credits will only affect credits whose access schedules has not started. Expired credits, and credits with an active access schedule will remain unchanged.

Show child attributes

update_subscriptions

object[]

Optional list of subscriptions to update.

Show child attributes

update_spend_threshold_configuration

object

Show child attributes

update_prepaid_balance_threshold_configuration

object

Show child attributes

update_contract_end_date

string<date-time> | null

RFC 3339 timestamp indicating when the contract will end (exclusive).

update_net_payment_terms_days

number | null

Number of days after issuance of invoice after which the invoice is due (e.g. Net 30).

allow_contract_ending_before_finalized_invoice

boolean

If true, allows setting the contract end date earlier than the end_timestamp of existing finalized invoices. Finalized invoices will be unchanged; if you want to incorporate the new end date, you can void and regenerate finalized usage invoices. Defaults to true.

archive_commits

object[]

IDs of commits to archive

Show child attributes

archive_credits

object[]

IDs of credits to archive

Show child attributes

archive_scheduled_charges

object[]

IDs of scheduled charges to archive

Show child attributes

remove_overrides

object[]

IDs of overrides to remove

Show child attributes

Response

Success

data

object

required

Show child attributes

⌘I

GET STARTED

ESSENTIALS

ENDPOINTS

Edit a contract

Use this endpoint to:

Key response fields:

Usage guidelines:

Authorizations

Body

Response