Skip to main content



Coupa Success Portal

Contracts API (/contracts)

Use the contracts API to create, update, or query a contract, including the business groups involved, key dates, the status of the contract, and the financial terms.

The URL to access contracts is: https://{your_instance_name}/api/contracts

See Integration Best Practices for more info.


Verb Path Action Description
PUT /api/contracts/:id/add_approver add_approver Manually add an approver for a contract
PUT /api/contracts/:id/ccc_signature_created ccc_signature_created Notifies that a signature has been added in CCC.
PUT /api/contracts/:id/complete complete Moves the contract to the completed state.
POST /api/contracts create Create contract
POST /api/contracts/:id/create_published create_published /api/contracts/:id/create_published
DELETE /api/contracts/:id destroy Delete contract
GET /api/contracts index Query contracts
POST /api/contracts/:id/legal_agreement legal_agreement Add or update legal legal_agreement file
PUT /api/contracts/:id/legal_agreement legal_agreement Add or update legal legal_agreement file
PUT /api/contracts/:id/remove_approval remove_approval Remove an approver who was manually added
GET /api/contracts/:id/retrieve_legal_agreement retrieve_legal_agreement Get legal legal_agreement file
GET /api/contracts/:id show Show contract
PUT /api/contracts/:id/submit_for_approval submit_for_approval Submits the contract for approval.
PUT /api/contracts/:id update Update contract
PUT /api/contracts/:id/update_published update_published Updates a contract when it's published.
PUT /api/contracts/:id/withdraw_signatures withdraw_signatures Moves contract to corresponding status after CCC withdraw_signatures.


Element Description Req'd Unique Allowable Value In Out Data Type
amended-contract-type Amended Contract Type       yes yes string(255)
consent Notice to Consent     notice, consent, not_required, not_assignable yes yes string(255)
content-groups Business Groups       yes yes Business Group
contract-owner Contract owner       yes yes User
contract-terms contract_terms       yes yes Contract Term
contract-type Custom-defined label for categorization yes no any yes yes Contract Type
contract-type-custom-field-1 Contract type custom field 1 no no any yes yes string(255)
contract-type-custom-field-2 Contract type custom field 2 no no any yes yes string(255)
contract-type-custom-field-3 Contract type custom field 3 no no any yes yes string(255)
contract-type-custom-field-4 Contract type custom field 4 no no any yes yes string(255)
contract-type-custom-field-5 Contract type custom field 5 no no any yes yes string(255)
contract-type-custom-field-6 Contract type custom field 6 no no any yes yes string(255)
contract-type-custom-field-7 Contract type custom field 7 no no any yes yes string(255)
contract-type-custom-field-8 Contract type custom field 8 no no any yes yes string(255)
contract-type-custom-field-9 Contract type custom field 9 no no any yes yes string(255)
contract-type-custom-field-10 Contract type custom field 10 no no any yes yes string(255)
created-at Automatically created by Coupa in the format YYYY-MM-DDTHH:MM:SS+HH:MMZ         yes datetime
created-by User who created         yes User
currency Contract Currency Code       yes yes Currency
current-approval Current approval         yes Approval
default-account default_account       yes yes Account
department Owner Department no no any yes yes Department 
description Descriptive notes about the contract false false any yes yes string(1024)
end-date Expire Date yes     yes yes datetime
execution-date Date when the contract is completed and legally binding no no any yes yes datetime
id Coupa unique identifier         yes integer
is-default Default Account for Supplier Invoice       yes yes boolean
legal-agreement-url Optional url for the legal agreement       yes yes string(255)
length-of-notice-unit Unit of Length of Notice(Days/Months/Years)     days, months, years yes yes string(255)
length-of-notice-value Value of Length of Notice       yes yes string(255)
master-contract Master Contract number or name       yes yes Contract
max-commit Maximum Commit Amount       yes yes decimal(32,4)
maximum-value Maximum Commit Amount       yes yes decimal(32,4)
min-commit Minimum Commit Amount       yes yes decimal(32,4)
minimum-value Minimum Commit Amount       yes yes decimal(32,4)
name Contract Name yes yes   yes yes string(100)
no-of-renewals No of Renewals       yes yes string(255)
number Contract Number yes yes   yes yes string(50)
order-window-tz order_window_tz     A valid timezone yes yes string(255)
parent Parent       yes yes Contract
payment-term Payment term code on contract       yes yes Payment Term 
po-message Order Windows PO Message       yes yes string(255)
preferred Indicate preferred contract for supplier       yes yes boolean
published-date Date when the contract was published no no any yes yes datetime
quote-response-id Id of Quote Response         yes integer
reason-insight-events Reason insight events yes     yes yes Reason Insight Event
renewal-length-unit Unit of Renewal Length(Days/Months/Years)     days, months, years yes yes string(255)
renewal-length-value Value of Renewal Length       yes yes string(255)
requisition-message Order Windows Requisition Message       yes yes string(255)
savings-pct Savings Achieved through Contracts Pricing       yes yes decimal(20,2)
schedule schedule       yes yes Order Window 
shipping-term Shipping term code on contract       yes yes Shipping Term 
source-id The source id of contract creation       yes yes sting(255)
source-type The source type of contract creation       yes yes string(255)
start-date Start Date yes     yes yes datetime
status Status of the Contract yes     yes yes draft
strict-invoicing-rules Strict Invoicing Rules       yes yes boolean
submitter User who submitted the contract for approval         yes User
supplier Supplier Name yes     yes yes Supplier 
supplier-account Supplier Account Number       yes yes string(255)
supplier-invoiceable Supplier Can Invoice Directly       yes yes boolean
taggings Taggings no no   yes yes Tagging API
tags Tags no no   yes yes Tag API
term-type Term type     fixed, auto_renew, perpetual yes yes string(255)
terminated Terminated       yes yes boolean
termination-notice Termination Notice     yes, no yes yes string(255)
termination-notice-length-unit Unit of Termination Notice Length(Days/Months/Years)     days, months, years yes yes string(255)
termination-notice-length-value Value of Termination Notice Length       yes yes integer
terms terms       yes yes text
type Contract type     MasterContract, AmendmentContract   yes string(255)
updated-at Automatically created by Coupa in the format YYYY-MM-DDTHH:MM:SS+HH:MMZ         yes datetime
updated-by User who updated         yes User
use-order-windows Use Order Windows       yes yes boolean
used-for-buying Used for Buying       yes yes boolean
version version       yes yes integer
  • When dealing with large data sets of contracts, always limit your GET with some criteria.
  • The content groups and categories must already exist in the system.


Africa/Abidjan, Africa/Accra, Africa/Addis_Ababa, Africa/Algiers, Africa/Asmara, Africa/Asmera, Africa/Bamako, Africa/Bangui, Africa/Banjul, Africa/Bissau, Africa/Blantyre, Africa/Brazzaville, Africa/Bujumbura, Africa/Cairo, Africa/Casablanca, Africa/Ceuta, Africa/Conakry, Africa/Dakar, Africa/Dar_es_Salaam, Africa/Djibouti, Africa/Douala, Africa/El_Aaiun, Africa/Freetown, Africa/Gaborone, Africa/Harare, Africa/Johannesburg, Africa/Juba, Africa/Kampala, Africa/Khartoum, Africa/Kigali, Africa/Kinshasa, Africa/Lagos, Africa/Libreville, Africa/Lome, Africa/Luanda, Africa/Lubumbashi, Africa/Lusaka, Africa/Malabo, Africa/Maputo, Africa/Maseru, Africa/Mbabane, Africa/Mogadishu, Africa/Monrovia, Africa/Nairobi, Africa/Ndjamena, Africa/Niamey, Africa/Nouakchott, Africa/Ouagadougou, Africa/Porto-Novo, Africa/Sao_Tome, Africa/Timbuktu, Africa/Tripoli, Africa/Tunis, Africa/Windhoek, America/Adak, America/Anchorage, America/Anguilla, America/Antigua, America/Araguaina, America/Argentina/Buenos_Aires, America/Argentina/Catamarca, America/Argentina/ComodRivadavia, America/Argentina/Cordoba, America/Argentina/Jujuy, America/Argentina/La_Rioja, America/Argentina/Mendoza, America/Argentina/Rio_Gallegos, America/Argentina/Salta, America/Argentina/San_Juan, America/Argentina/San_Luis, America/Argentina/Tucuman, America/Argentina/Ushuaia, America/Aruba, America/Asuncion, America/Atikokan, America/Atka, America/Bahia, America/Bahia_Banderas, America/Barbados, America/Belem, America/Belize, America/Blanc-Sablon, America/Boa_Vista, America/Bogota, America/Boise, America/Buenos_Aires, America/Cambridge_Bay, America/Campo_Grande, America/Cancun, America/Caracas, America/Catamarca, America/Cayenne, America/Cayman, America/Chicago, America/Chihuahua, America/Coral_Harbour, America/Cordoba, America/Costa_Rica, America/Creston, America/Cuiaba, America/Curacao, America/Danmarkshavn, America/Dawson, America/Dawson_Creek, America/Denver, America/Detroit, America/Dominica, America/Edmonton, America/Eirunepe, America/El_Salvador, America/Ensenada, America/Fort_Nelson, America/Fort_Wayne, America/Fortaleza, America/Glace_Bay, America/Godthab, America/Goose_Bay, America/Grand_Turk, America/Grenada, America/Guadeloupe, America/Guatemala, America/Guayaquil, America/Guyana, America/Halifax, America/Havana, America/Hermosillo, America/Indiana/Indianapolis, America/Indiana/Knox, America/Indiana/Marengo, America/Indiana/Petersburg, America/Indiana/Tell_City, America/Indiana/Vevay, America/Indiana/Vincennes, America/Indiana/Winamac, America/Indianapolis, America/Inuvik, America/Iqaluit, America/Jamaica, America/Jujuy, America/Juneau, America/Kentucky/Louisville, America/Kentucky/Monticello, America/Knox_IN, America/Kralendijk, America/La_Paz, America/Lima, America/Los_Angeles, America/Louisville, America/Lower_Princes, America/Maceio, America/Managua, America/Manaus, America/Marigot, America/Martinique, America/Matamoros, America/Mazatlan, America/Mendoza, America/Menominee, America/Merida, America/Metlakatla, America/Mexico_City, America/Miquelon, America/Moncton, America/Monterrey, America/Montevideo, America/Montreal, America/Montserrat, America/Nassau, America/New_York, America/Nipigon, America/Nome, America/Noronha, America/North_Dakota/Beulah, America/North_Dakota/Center, America/North_Dakota/New_Salem, America/Ojinaga, America/Panama, America/Pangnirtung, America/Paramaribo, America/Phoenix, America/Port-au-Prince, America/Port_of_Spain, America/Porto_Acre, America/Porto_Velho, America/Puerto_Rico, America/Rainy_River, America/Rankin_Inlet, America/Recife, America/Regina, America/Resolute, America/Rio_Branco, America/Rosario, America/Santa_Isabel, America/Santarem, America/Santiago, America/Santo_Domingo, America/Sao_Paulo, America/Scoresbysund, America/Shiprock, America/Sitka, America/St_Barthelemy, America/St_Johns, America/St_Kitts, America/St_Lucia, America/St_Thomas, America/St_Vincent, America/Swift_Current, America/Tegucigalpa, America/Thule, America/Thunder_Bay, America/Tijuana, America/Toronto, America/Tortola, America/Vancouver, America/Virgin, America/Whitehorse, America/Winnipeg, America/Yakutat, America/Yellowknife, Antarctica/Casey, Antarctica/Davis, Antarctica/DumontDUrville, Antarctica/Macquarie, Antarctica/Mawson, Antarctica/McMurdo, Antarctica/Palmer, Antarctica/Rothera, Antarctica/South_Pole, Antarctica/Syowa, Antarctica/Troll, Antarctica/Vostok, Arctic/Longyearbyen, Asia/Aden, Asia/Almaty, Asia/Amman, Asia/Anadyr, Asia/Aqtau, Asia/Aqtobe, Asia/Ashgabat, Asia/Ashkhabad, Asia/Baghdad, Asia/Bahrain, Asia/Baku, Asia/Bangkok, Asia/Barnaul, Asia/Beirut, Asia/Bishkek, Asia/Brunei, Asia/Calcutta, Asia/Chita, Asia/Choibalsan, Asia/Chongqing, Asia/Chungking, Asia/Colombo, Asia/Dacca, Asia/Damascus, Asia/Dhaka, Asia/Dili, Asia/Dubai, Asia/Dushanbe, Asia/Gaza, Asia/Harbin, Asia/Hebron, Asia/Ho_Chi_Minh, Asia/Hong_Kong, Asia/Hovd, Asia/Irkutsk, Asia/Istanbul, Asia/Jakarta, Asia/Jayapura, Asia/Jerusalem, Asia/Kabul, Asia/Kamchatka, Asia/Karachi, Asia/Kashgar, Asia/Kathmandu, Asia/Katmandu, Asia/Khandyga, Asia/Kolkata, Asia/Krasnoyarsk, Asia/Kuala_Lumpur, Asia/Kuching, Asia/Kuwait, Asia/Macao, Asia/Macau, Asia/Magadan, Asia/Makassar, Asia/Manila, Asia/Muscat, Asia/Nicosia, Asia/Novokuznetsk, Asia/Novosibirsk, Asia/Omsk, Asia/Oral, Asia/Phnom_Penh, Asia/Pontianak, Asia/Pyongyang, Asia/Qatar, Asia/Qostanay, Asia/Qyzylorda, Asia/Rangoon, Asia/Riyadh, Asia/Saigon, Asia/Sakhalin, Asia/Samarkand, Asia/Seoul, Asia/Shanghai, Asia/Singapore, Asia/Srednekolymsk, Asia/Taipei, Asia/Tashkent, Asia/Tbilisi, Asia/Tehran, Asia/Tel_Aviv, Asia/Thimbu, Asia/Thimphu, Asia/Tokyo, Asia/Tomsk, Asia/Ujung_Pandang, Asia/Ulaanbaatar, Asia/Ulan_Bator, Asia/Urumqi, Asia/Ust-Nera, Asia/Vientiane, Asia/Vladivostok, Asia/Yakutsk, Asia/Yekaterinburg, Asia/Yerevan, Atlantic/Azores, Atlantic/Bermuda, Atlantic/Canary, Atlantic/Cape_Verde, Atlantic/Faeroe, Atlantic/Faroe, Atlantic/Jan_Mayen, Atlantic/Madeira, Atlantic/Reykjavik, Atlantic/South_Georgia, Atlantic/St_Helena, Atlantic/Stanley, Australia/ACT, Australia/Adelaide, Australia/Brisbane, Australia/Broken_Hill, Australia/Canberra, Australia/Currie, Australia/Darwin, Australia/Eucla, Australia/Hobart, Australia/LHI, Australia/Lindeman, Australia/Lord_Howe, Australia/Melbourne, Australia/NSW, Australia/North, Australia/Perth, Australia/Queensland, Australia/South, Australia/Sydney, Australia/Tasmania, Australia/Victoria, Australia/West, Australia/Yancowinna, Brazil/Acre, Brazil/DeNoronha, Brazil/East, Brazil/West, CET, CST6CDT, Canada/Atlantic, Canada/Central, Canada/East-Saskatchewan, Canada/Eastern, Canada/Mountain, Canada/Newfoundland, Canada/Pacific, Canada/Saskatchewan, Canada/Yukon, Chile/Continental, Chile/EasterIsland, Cuba, EET, EST, EST5EDT, Egypt, Eire, Etc/GMT, Etc/GMT+0, Etc/GMT+1, Etc/GMT+10, Etc/GMT+11, Etc/GMT+12, Etc/GMT+2, Etc/GMT+3, Etc/GMT+4, Etc/GMT+5, Etc/GMT+6, Etc/GMT+7, Etc/GMT+8, Etc/GMT+9, Etc/GMT-0, Etc/GMT-1, Etc/GMT-10, Etc/GMT-11, Etc/GMT-12, Etc/GMT-13, Etc/GMT-14, Etc/GMT-2, Etc/GMT-3, Etc/GMT-4, Etc/GMT-5, Etc/GMT-6, Etc/GMT-7, Etc/GMT-8, Etc/GMT-9, Etc/GMT0, Etc/Greenwich, Etc/UCT, Etc/UTC, Etc/Universal, Etc/Zulu, Europe/Amsterdam, Europe/Andorra, Europe/Astrakhan, Europe/Athens, Europe/Belfast, Europe/Belgrade, Europe/Berlin, Europe/Bratislava, Europe/Brussels, Europe/Bucharest, Europe/Budapest, Europe/Busingen, Europe/Chisinau, Europe/Copenhagen, Europe/Dublin, Europe/Gibraltar, Europe/Guernsey, Europe/Helsinki, Europe/Isle_of_Man, Europe/Istanbul, Europe/Jersey, Europe/Kaliningrad, Europe/Kiev, Europe/Kirov, Europe/Lisbon, Europe/Ljubljana, Europe/London, Europe/Luxembourg, Europe/Madrid, Europe/Malta, Europe/Mariehamn, Europe/Minsk, Europe/Monaco, Europe/Moscow, Europe/Nicosia, Europe/Oslo, Europe/Paris, Europe/Podgorica, Europe/Prague, Europe/Riga, Europe/Rome, Europe/Samara, Europe/San_Marino, Europe/Sarajevo, Europe/Simferopol, Europe/Skopje, Europe/Sofia, Europe/Stockholm, Europe/Tallinn, Europe/Tirane, Europe/Tiraspol, Europe/Ulyanovsk, Europe/Uzhgorod, Europe/Vaduz, Europe/Vatican, Europe/Vienna, Europe/Vilnius, Europe/Volgograd, Europe/Warsaw, Europe/Zagreb, Europe/Zaporozhye, Europe/Zurich, Zurich, GB, GB-Eire, GMT, GMT+0, GMT-0, GMT0, Greenwich, HST, Hongkong, Iceland, Indian/Antananarivo, Indian/Chagos, Indian/Christmas, Indian/Cocos, Indian/Comoro, Indian/Kerguelen, Indian/Mahe, Indian/Maldives, Indian/Mauritius, Indian/Mayotte, Indian/Reunion, Iran, Israel, Jamaica, Japan, Kwajalein, Libya, MET, MST, MST7MDT, Mexico/BajaNorte, Mexico/BajaSur, Mexico/General, NZ, NZ-CHAT, Navajo, PRC, PST8PDT, Pacific/Apia, Pacific/Auckland, Pacific/Bougainville, Pacific/Chatham, Pacific/Chuuk, Pacific/Easter, Pacific/Efate, Pacific/Enderbury, Pacific/Fakaofo, Pacific/Fiji, Pacific/Funafuti, Pacific/Galapagos, Pacific/Gambier, Pacific/Guadalcanal, Pacific/Guam, Pacific/Honolulu, Pacific/Johnston, Pacific/Kiritimati, Pacific/Kosrae, Pacific/Kwajalein, Pacific/Majuro, Pacific/Marquesas, Pacific/Midway, Pacific/Nauru, Pacific/Niue, Pacific/Norfolk, Pacific/Noumea, Pacific/Pago_Pago, Pacific/Palau, Pacific/Pitcairn, Pacific/Pohnpei, Pacific/Ponape, Pacific/Port_Moresby, Pacific/Rarotonga, Pacific/Saipan, Pacific/Samoa, Pacific/Tahiti, Pacific/Tarawa, Pacific/Tongatapu, Pacific/Truk, Pacific/Wake, Pacific/Wallis, Pacific/Yap, Poland, Portugal, ROC, ROK, Singapore, Turkey, UCT, US/Alaska, US/Aleutian, US/Arizona, US/Central, US/East-Indiana, US/Eastern, US/Hawaii, US/Indiana-Starke, US/Michigan, US/Mountain, US/Pacific, US/Pacific-New, US/Samoa, UTC, Universal, W-SU, WET, Zulu, UTC, International Date Line West, Midway Island, American Samoa, Hawaii, Alaska, Pacific Time (US & Canada), Tijuana, Mountain Time (US & Canada), Arizona, Chihuahua, Mazatlan, Central Time (US & Canada), Saskatchewan, Guadalajara, Mexico City, Monterrey, Central America, Eastern Time (US & Canada), Indiana (East), Bogota, Lima, Quito, Atlantic Time (Canada), Caracas, La Paz, Santiago, Newfoundland, Brasilia, Buenos Aires, Montevideo, Georgetown, Greenland, Mid-Atlantic, Azores, Cape Verde Is., Dublin, Edinburgh, Lisbon, London, Casablanca, Monrovia, Belgrade, Bratislava, Budapest, Ljubljana, Prague, Sarajevo, Skopje, Warsaw, Zagreb, Brussels, Copenhagen, Madrid, Paris, Amsterdam, Berlin, Bern, Rome, Stockholm, Vienna, West Central Africa, Bucharest, Cairo, Helsinki, Kyiv, Riga, Sofia, Tallinn, Vilnius, Athens, Istanbul, Minsk, Jerusalem, Harare, Pretoria, Kaliningrad, Moscow, St. Petersburg, Volgograd, Samara, Kuwait, Riyadh, Nairobi, Baghdad, Tehran, Abu Dhabi, Muscat, Baku, Tbilisi, Yerevan, Kabul, Ekaterinburg, Islamabad, Karachi, Tashkent, Chennai, Kolkata, Mumbai, New Delhi, Kathmandu, Astana, Dhaka, Sri Jayawardenepura, Almaty, Novosibirsk, Rangoon, Bangkok, Hanoi, Jakarta, Krasnoyarsk, Beijing, Chongqing, Hong Kong, Urumqi, Kuala Lumpur, Singapore, Taipei, Perth, Irkutsk, Ulaanbaatar, Seoul, Osaka, Sapporo, Tokyo, Yakutsk, Darwin, Adelaide, Canberra, Melbourne, Sydney, Brisbane, Hobart, Vladivostok, Guam, Port Moresby, Magadan, Srednekolymsk, Solomon Is., New Caledonia, Fiji, Kamchatka, Marshall Is., Auckland, Wellington, Nuku'alofa, Tokelau Is., Chatham Is., Samoa

  • Was this article helpful?