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 |