Proposal Object-Level Mapping
Overview
Use this object structure to create and send a proposal via the 2Checkout API 6.0.
Object-Level Mapping
Proposal Object
|
Parameter name |
Type |
Required |
Description |
|---|---|---|---|
|
proposalId |
String |
Required |
The unique system-generated merchant proposal ID. |
|
name |
String | Required |
The name of the proposal |
|
version |
Integer |
|
Internal version of the proposal (incremented on each modification) |
|
createDate |
String |
|
The creation date of the proposal; date-time ISO 8601 format |
|
updateDate |
String |
|
The update date of the proposal; date-time ISO 8601 format; populated by the userId |
|
createdBy |
String |
|
The unique external system user identifier of the user that created the proposal; populated by the userId |
|
updatedBy |
String |
|
The unique external system user identifier of the user that last updated the proposal |
|
locked |
Boolean |
|
Signals if the proposal is locked or not for updates in order to restrict modifications |
|
source |
String, Enum |
|
Source of the proposal, used for reporting purposes; Can be: [ MERCHANT_CPANEL, MERCHANT_API, QUOTE_INTERFACE, SALESFORCE_CPQ ] |
|
content |
Object (Proposal Content) |
Required |
The content of the proposal |
|
billTo/billingDetails |
Object (billTo/billingDetails) |
Required |
The billing details associated with the proposal |
|
tac |
Object (tac) |
|
Terms and conditions applied to the proposal |
|
type |
String, enum |
Required |
The type of proposal that defines the way it will be processed onwards; Can be [ renewal, upgrade, acquisition ] |
|
sentBy |
Object (sentBy) |
|
Represents the account manager from the vendor |
|
links |
Object (links) |
|
The proposal links details |
|
status |
String, Enum |
|
The status of the proposal; can be [ opened, sent, in_review, reviewed, closed_won, closed_lost, declined, expired, accepted ] |
|
statusComment |
String |
|
Free text comment that can accompaniate a status |
|
expirationDate |
String |
|
The date at which the proposal expires; date-time ISO 8601 format |
|
sellTo |
Object (sellTo) |
Required |
Represents the entity using the service. Used for tax calculation. |
BillTo Object
|
Parameter name |
Type |
Required |
Description |
|---|---|---|---|
|
company |
String |
Required |
End-user company name. |
|
|
String | Required |
Contact email address. |
|
vatCode |
String | Required |
For companies, it needs to be the VAT ID. |
|
phone |
String | Required |
Contact phone number. |
|
country |
String | Required |
The country for the address. Represents the country code as specified by ISO 3166-1 alpha-2. |
|
state |
String | Required |
The country state for the address. |
|
city |
String | Required |
The city for the address. |
|
zip |
String | Required |
The address zip code. |
|
address |
String | Required |
The street address. |
SellTo Object
|
Parameter name |
Type |
Required |
Description |
|---|---|---|---|
|
company |
String |
Required |
End-user company name. |
|
|
String | Required |
Contact email address. |
|
vatCode |
String | Required |
For companies, it needs to be the VAT ID. |
|
phone |
String | Required |
Contact phone number. |
|
country |
String | Required |
The country for the address. Represents the country code as specified by ISO 3166-1 alpha-2. |
|
state |
String | Required |
The country state for the address. |
|
city |
String | Required |
The city for the address. |
|
zip |
String | Required |
The address zip code. |
|
address |
String | Required |
The street address. |
Terms and conditions Object
|
Parameter name |
Type |
Required |
Description |
|---|---|---|---|
|
content |
String |
Optional |
The terms and conditions of the proposal |
|
acceptedDate |
String |
Optional |
The UTC date when the proposal terms and conditions were accepted in ISO 8601 format |
SentBy Object
|
Parameter name |
Type |
Required |
Description |
|---|---|---|---|
|
firstName |
String |
Optional |
The first name for the email sender |
|
lastName |
String | Optional |
The last name for the email sender |
|
|
String | Optional |
The email address of the email sender |
Content Object
|
Parameter name |
Type |
Required |
Description |
|---|---|---|---|
|
language |
String |
Required |
The ISO 639-1 language code used to display the content of the proposal. |
|
currency |
String |
Required |
The ISO 4217 currency code used to display the product and order values. |
|
lineItems |
Array of Objects (lineItem) |
Required |
The list of products & associated custom values for the proposal. |
LineItem Object
|
Parameter name |
Type |
Required |
Description |
|---|---|---|---|
|
productName |
String |
Required |
Name of the product |
|
productCode |
String | Required |
2Checkout product code |
|
quantity |
Float |
Required |
The quantity of the product |
|
price |
Float | Required |
The list price of the product |
|
discountPrice |
Float | Required |
The discounted price of the product |
|
priceType |
String, enum |
Required |
The price type, can be gross or net |
|
subscriptionReference |
String |
Optional |
The subscription reference for upgrade of renewal |
|
contractPeriod |
Integer |
Optional |
The number of billing cycles. A zero value means a lifetime contract period and billingCycle is not needed in this case. |
|
immediateAction |
String |
Optional |
Defines if the contract starts now or at the end of current billing cycle or contract period [ now, end_of_billing_cycle, end_of_contract ] |
|
billingCycle |
Object (billingCycle) |
Optional |
The billing cycle configuration |
|
priceOptions |
Array of priceOption Objects |
Optional |
Array of selected price options. |
|
additionalFields |
Array of additionalFields Object |
Optional |
Array of Product additional fields |
PriceOption Object
|
Parameter name |
Type |
Required |
Description |
|---|---|---|---|
|
groupCode |
String |
Optional |
The price options group code. |
|
groupOptions |
Array of Strings |
Optional |
Selected group option code. |
BillingCycle Object
|
Parameter name |
Type |
Required |
Description |
|---|---|---|---|
|
unit |
String, Enum |
Optional |
The unit for the billing cycle, can be [day, month]. |
|
value |
Integer |
Optional |
The number of days or months. Minimum for a day unit is 7. |
Link Object
|
Parameter name |
Type |
Required |
Description |
|---|---|---|---|
|
linkId |
String |
Optional |
The unique link id. |
|
url |
String | Optional |
The link URL for viewing. |
|
status |
String, Enum |
Optional |
The status of the proposal. |
|
|
String | Optional |
The link URL for downloading the PDF. |
AdditionalFields Object
|
Parameter name |
Type |
Required |
Description |
|---|---|---|---|
|
code |
String |
Optional |
The alpha-numeric characters, underscores and dashes that are set as the field identifier. |
|
value |
String |
Optional |
Selected field value. |
Errors
|
Parameter name |
Type |
Description |
|---|---|---|
|
code |
Integer |
Internal error code. |
|
detail |
String |
The details of the error associated with the code. |
|
status |
Integer |
HTTP error code. |
Proposal Object Sample
{
"updatedDate": "20120-03-20 20:12:11Z",
"locked": true,
"status": "sent",
"expirationDate": "20120-10-20 20:12:11Z",
"billTo": {
"company": "Randcomp",
"email": "y2hzhca4pc@groupbuff.com",
"vatCode": "85421564",
"phone": "12172196850",
"country": "US",
"state": "Illinois",
"city": "Carthage",
"zip": "62321",
"address": "1849 Cardinal Lane"
},
"content": {
"language": "ro",
"currency": "ron",
"terms": 30,
"lineItems": [
{
"productName": "Antivirus",
"productCode": "FP10",
"quantity": 2,
"subscriptionReference": "FDG223",
"contractPeriod": 12,
"immediateAction": false,
"billingCycle": {
"unit": "month",{
"proposal": {
"updatedDate": "2020-05-11 10:14:24",
"locked": false,
"status": "sent",
"billTo": {
"company": "vgvhW98CiP",
"firstName": "NbNlhZaw0m",
"lastName": "GSPTiT8hUz",
"email": "JwhQwQseHu@2checkout.com",
"vatCode": "sxHuDDdwLu",
"phone": "0744444445",
"country": "ro",
"state": "Yd0d97R44a",
"city": "YyHln6KZdf",
"zip": "02179000",
"address": "E2LyqFKFXX"
},
"content": {
"language": "ro",
"currency": "usd",
"lineItems": [
{
"productName": "G2e8AESWBF",
"productCode": "KL1171S",
"quantity": 10,
"price": 80.29,
"discountedPrice": 20,
"priceType": "net",
"contractPeriod": 12,
"shortDescription": "<p>scurta descriere in romana</p>\r\n",
"priceOptions": [
{
"option": "License Duration ro",
"selections": [
"1 an ",
"2 ani"
]
},
{
"option": "Numar calculatoare",
"selections": [
"2 calculatoare"
]
}
],
"subscriptionReference": "8B48958B24",
"subscriptionExpirationDate": "2020-02-03T05:13:16-04:00",
"immediateAction": "now",
"unitVat": 0,
"vatPercent": 0,
"vat": 0,
"grossPrice": 1902.27,
"grossDiscountedPrice": 1902.27,
"netPrice": 1902.27,
"netDiscountedPrice": 0,
"billingCycle": {
"unit": "day",
"value": "12"
}
},
{
"productName": "qc9zgm10eh",
"productCode": "KL1091S",
"quantity": 4,
"price": 80.85,
"discountedPrice": 76,
"priceType": "net",
"contractPeriod": 12,
"shortDescription": "",
"priceOptions": [],
"immediateAction": "now",
"unitVat": 0,
"vatPercent": 0,
"vat": 0,
"grossPrice": 71.57,
"grossDiscountedPrice": 71.57,
"netPrice": 71.57,
"netDiscountedPrice": 0,
"billingCycle": {
"unit": "day",
"value": "8"
}
}
]
},
"tac": {
"content": "7hxl1gZoMH"
},
"link": {
"url": "https://proposal.2checkout.com/AlexB/7fe96d63-f287-4e2d-9302-71bd89ad4955",
"status": "accepted"
},
"type": "upgrade",
"sentBy": {
"firstName": "7cnCFntR46",
"lastName": "ZMUxWvHtd1",
"email": "GijBj_test@2checkout.com"
},
"sellTo": {
"company": "WanT1TjuiK",
"firstName": "Ec4WUxhvGb",
"lastName": "wF36GumR0e",
"email": "CoFq5_test@2checkout.com",
"vatCode": "w2SWzM4xqw",
"phone": "0744444480",
"country": "ro",
"state": "KFNK1PgNr1",
"city": "31CeVIrfB2",
"zip": "02179000",
"address": "gjIyFInjot"
},
"taxes": {
"netPrice": 1973.84,
"grossPrice": 1973.84,
"netDiscountedPrice": 1973.84,
"grossDiscountedPrice": 1973.84,
"discount": 0,
"vat": 0,
"dueNow": 1973.84,
"totalContractValue": 23686.079999999998
},
"pdfFileName": "1ed46260-4cb0-43d0-b2a0-afc1aad9f6be.pdf",
"expirationDate": "2020-06-11 10:14:24"
},
"merchant": {
"merchantCode": "AlexB",
"companyName": "AlexB CompanyName",
"commercialName": "AlexB CommercialName",
"logoSrc": "AlexB"
}
}
Error Handling
| Error text | Error message | Error code |
|---|---|---|
|
Unauthorized |
ERR_UNAUTHORIZED |
401 |
|
Route not found |
ERR_NOT_FOUND |
404 |
|
Internal Error |
ERR_INTERNAL_ERROR |
500 |
|
Bad Request |
ERR_BAD_REQUEST |
400 |
|
Proposal has terms |
ERR_PROPOSAL_HAS_TERMS |
400 |
|
error accepting proposal |
PROPOSAL_SERVICE_ERROR |
400 |
|
Invalid proposal |
ERR_INVALID_PROPOSAL |
400 |
|
Missing request parameters |
ERR_MISSING_PARAMETER |
404 |
|
Proposal not found |
ERR_PROPOSALID_INVALID |
404 |
|
Proposal not found |
ERR_PROPOSAL_NOT_FOUND |
404 |
|
Error accepting proposal |
ERR_PROPOSAL_ACCEPT |
400 |
|
Error declining proposal |
ERR_PROPOSAL_DECLINE |
400 |
|
Invalid payment method |
ERR_INVALID_PAYMENT_METHOD |
400 |
|
Retry payment |
ERR_ORDER_RETRY_PAYMENT |
417 |
|
Retry payment invalid payment data |
ERR_ORDER_RETRY_PAYMENT_INVALID |
402 |
|
Error creating order |
ERR_ORDER_CREATE |
400 |
|
Unauthorized |
ERR_UNAUTHORIZED |
401 |
