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.
Actions
| 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. | ||
| PATCH | /api/contracts/:id |
update | Update contract | ||
| 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. | ||
Elements
| 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.
Timezones
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, 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