Proposal Object-Level Mapping

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

Overview

Use this object structure to create and send a proposal via the 2Checkout API 6.0.

Object-Level Mapping

Proposal Object

Proposal Object-Level Mapping
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

BillTo Object Mapping
Parameter name	Type	Required	Description
company	String	Required	End-user company name.
email	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

SellTo Object Mapping
Parameter name	Type	Required	Description
company	String	Required	End-user company name.
email	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

Tac Object Mapping
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

SentBy Object Mapping
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
email	String	Optional	The email address of the email sender

Content Object

Content Object Mapping
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

LineItem Object Mapping
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

PriceOption Object Mapping
Parameter name	Type	Required	Description
groupCode	String	Optional	The price options group code.
groupOptions	Array of Strings	Optional	Selected group option code.

BillingCycle Object

BillingCycle Object Mapping
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

Link Object Mapping
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.
pdf	String	Optional	The link URL for downloading the PDF.

AdditionalFields Object

AdditionalFields Object Mapping
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

Proposal UI 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