Skip to main content

Proposal Object-Level Mapping

Proposal Object-Level Mapping

Last updated: 09-Sep-2020
Rate this article:

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

 

Rate this article:

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo