Proposal microservice
- Last updated
- Save as PDF
Overview
Use the Proposal object via SOAP API 6.0 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 API 6.0.
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:
|
|
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 [amendment, 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. |
| terms | Int | Optional | Can be NULL. |
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. |
| prorationDate | String | Optional | ISO8601 format with UTC timezone. |
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. |
|
|
String | Required |
Contact email address. |
|
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. |
|
|
String | Required |
The email address of the email sender. |
Links Object
| 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. |
| String | Required | The link URL for downloading the PDF. |
SellTo Object
| Parameters | Type | Required/Optional | Description |
|---|---|---|---|
|
company |
String |
Required |
End-user company name. |
|
|
String | Required |
Contact email address. |
|
vatCode |
String | Optional |
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. |
| taxExemptionId | String | Optional | The tax exemption ID code. |
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. |
| prorationDate | String | Optional | ISO8601 format with UTC timezone. |
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. |
|
|
String | Required |
Contact email address. |
|
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. |
|
|
String | Required |
The email address of the email sender. |
Links Object
| 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. |
| String | Required | The link URL for downloading the PDF. |
SellTo Object
| Parameters | Type | Required/Optional | Description |
|---|---|---|---|
|
company |
String |
Required |
End-user company name. |
|
|
String | Required |
Contact email address. |
|
vatCode |
String | Optional |
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. |
| taxExemptionId | String | Optional | The tax exemption ID code. |
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. |