Skip to main content
knowledgecenter.2checkout.com

Proposal microservice

Overview

Use the Proposal object via SOAP APIv6 to store cart information at a point in time that allows you afterward to operate fast changes to the cart configuration so that you can offer custom deals to your shoppers. By using the Proposal object you can create, update, and search proposals via the 2Checkout API and control the following proposal attributes:

  • Proposal content
  • Price options
  • Proposal links
  • Billing details

Parameters 

Use the parameters below to add new custom deals for your shoppers via SOAP APIv6.

Proposal Object

Parameters Type  Required/Optional Description

proposalId

String

Required

The unique merchant proposal id generated by the 2Checkout system.

name

String

Required (create)

The name of the proposal.

version

Integer

Required

The version of the proposal. Every modification increments the version by 1.

createDate

String

Required

The UTC creation date for the proposal in ISO 8601 format. Example: 2020-01-05T17:21:42+00:00.

updateDate

String

 Required

The update date of the proposal; date-time ISO 8601 format; populated by the UserId.

createdBy

String

 Required

The unique external system user identifier of the user that created the proposal. Example: john.doe@customer.com.

updatedBy

String

 Required

The unique external system user identifier of the user that last updated the proposal. Example: john.doe@customer.com.

locked

Boolean

 Required

Signals if the proposal is locked or not for updates in order to restrict modifications.

Possible values:

  • True
  • False

source

String, enum

 Required

The source from where the proposal was created. Can be: [ MERCHANT_CPANEL, MERCHANT_API, QUOTE_INTERFACE, SALESFORCE_CPQ ].

content

Object (ProposalContent)

Required (create)

The content of the proposal.

billTo

Object (BillTo)

Required (create)

The billing details associated with the proposal.

tac

Object (tac)

Required

Terms and conditions applied to the proposal.

type

String, enum

Required (create)

The type of proposal that defines the way it will be processed onwards; Can be [ renewal, upgrade, acquisition ].

sentBy

Object (sentBy)

 Optional

Represents the account manager of the merchant.

links

Object (links)

 Required

The proposal links details.

status

String, enum

 Required

The status of the proposal; can be [ opened, sent, in_review, reviewed, closed_won, closed_lost, declined, expired, accepted ].

statusComment

String

 Required

Free text comments that can accompany a status.

expirationDate

String

 Optional

The date at which the proposal expires; date-time ISO 8601 format.

sellTo

Object (sellTo)

Required (create)

Represents the entity using the service. Used for tax calculation.

ProposalContent Object

Parameters Type Required Description

language

String

Required (create)

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

Parameters Type Required/Optional 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

Required

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 the 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 additionalField object

 Optional

Array of Product additional fields.

BillingCycle Object
Parameters Type Required/Optional Description

unit

String, enum

Required

The unit for the billing cycle can be [day, month].

value

Integer

Required

The number of days or months. The minimum for a day unit is 7.
 

PriceOptions - Array of priceOption objects
Parameters Type Required/Optional Description

groupCode

String

 Required

The price options group code.

groupOptions

Array of strings

 Required

Selected group option code.

AdditionalFields - Array of additionalField Object
Parameters Type Required/Optional Description

code

String

  Required

The alpha-numeric characters, underscores, and dashes that are set as the field identifier.

value

String

  Required

Selected field value.

BillTo Object

Parameters Type Required/Optional 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. Example: 1849 Cardinal Lane.

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.

tac Object

Parameters Type Required/Optional Description

content

String

Required

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. Example: 2020-01-05T17:21:42+00:00.

SentBy Object

Parameters Type Required/Optional Description

firstName

String Required

The first name of the email sender.

lastName

String Required

The last name of the email sender.

email

String Required

The email address of the email sender.

Parameters Type Required/Optional Description

linkId 

String Required

The unique link id.

url

String Required

The link URL for viewing.

status

String, enum

Required

The status of the proposal. Default: opened.

pdf String Required The link URL for downloading the PDF.

SellTo Object

Parameters Type Required/Optional 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.

ProposalContent Object

Parameters Type Required Description

language

String

Required (create)

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

Parameters Type Required/Optional 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

Required

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 the 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 additionalField object

 Optional

Array of Product additional fields.

BillingCycle Object
Parameters Type Required/Optional Description

unit

String, enum

Required

The unit for the billing cycle can be [day, month].

value

Integer

Required

The number of days or months. The minimum for a day unit is 7.
 

PriceOptions - Array of priceOption objects
Parameters Type Required/Optional Description

groupCode

String

 Required

The price options group code.

groupOptions

Array of strings

 Required

Selected group option code.

AdditionalFields - Array of additionalField Object
Parameters Type Required/Optional Description

code

String

  Required

The alpha-numeric characters, underscores, and dashes that are set as the field identifier.

value

String

  Required

Selected field value.

BillingCycle Object
Parameters Type Required/Optional Description

unit

String, enum

Required

The unit for the billing cycle can be [day, month].

value

Integer

Required

The number of days or months. The minimum for a day unit is 7.
 

PriceOptions - Array of priceOption objects
Parameters Type Required/Optional Description

groupCode

String

 Required

The price options group code.

groupOptions

Array of strings

 Required

Selected group option code.

AdditionalFields - Array of additionalField Object
Parameters Type Required/Optional Description

code

String

  Required

The alpha-numeric characters, underscores, and dashes that are set as the field identifier.

value

String

  Required

Selected field value.

BillTo Object

Parameters Type Required/Optional 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. Example: 1849 Cardinal Lane.

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.

tac Object

Parameters Type Required/Optional Description

content

String

Required

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. Example: 2020-01-05T17:21:42+00:00.

SentBy Object

Parameters Type Required/Optional Description

firstName

String Required

The first name of the email sender.

lastName

String Required

The last name of the email sender.

email

String Required

The email address of the email sender.

Parameters Type Required/Optional Description

linkId 

String Required

The unique link id.

url

String Required

The link URL for viewing.

status

String, enum

Required

The status of the proposal. Default: opened.

pdf String Required The link URL for downloading the PDF.

SellTo Object

Parameters Type Required/Optional 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.

Errors

Parameters Type Description

code

Integer

Internal error code.

detail

String

The details of the error associated with the code.

status

Integer

HTTP error code.