The Sale resource allows creating new Sale, by sending POST request:

 

Operation

HTTP Action

Create new Sale

POST /Sale

 

Creating new Sale

To create new Sale you need to send POST request to Sales endpoint with Sale structure (see below) as payload.

Available Fields for Sale:

Property

Type

Length

Required

Notes

CustomerID

Guid

 

Yes*

Customer identifier

Customer

String

256

Yes*

Customer name. Required if CustomerID not provided

Contact

String

256

Customer Contact name

Phone

String

50

Customer Contact phone

Email

String

256

 

Customer Contact email

OrderDate

Date

 

 

Date when task was created. If field is not specified, using CURRENT DATE instead

SaleAccount

String

50

Account code used by default for invoice lines when no revenue account is defined on Product. By default it is equal to Customer Sale account

BillingAddress

Structured

Sale Billing address, see above

ShippingAddress

Structured

Sale Shipping address, see above. Required only if integration with ShipStation is turned on.

TaxRule

String

50

Default Tax Rule name selected for Sale. If not specified Customers’ Tax Rule will be used instead

TaxInclusive

Boolean

Flag indicating price is Tax inclusive for Sale lines. Default value if not specified is false.

Terms

String

256

Payment terms name. If not specified, Customer’s Payment Term will be used instead

ShipBy

Date

 

 

Date when shipment is due

PriceTier

String

50

Price Tier name selected for Sale. If not specified, Customer’s Sale Price Tier will be used instead

Location

String

256

Location name to pick stock from. Do not provide it for Service Only Sale.

Note

String

1024

Custom Sale note

CustomerReference

String

256

Reference number used by customer to identify this sale. Could be a purchase order number generated by customer.

InvoiceStatus

String

16

 

String enumeration. See valid values and its description below. If not specified used Default value (NOTAUTHORISED)

OrderStatus

String

16

 

String enumeration. See valid values and its description below. If not specified used Default value (NOTAUTHORISED). Ignored for Service Only Sale

AutoPickPackShipMode

String

16

 

String enumeration. See valid values and its description below. If not specified used Default value (NOPICK)

SalesRepresentative

String

256

Sales representative name

InvoiceDate

Date

 

 

Date when invoice created. Default value is current date, used if not specified

InvoiceDueDate

Date

 

 

Date until invoice is valid. If not specified, used default value from Terms

CurrencyRate

Decimal with up to 4 decimal places

 

 

Currency Conversion rate expressed as number of Sale currency units for one Customer currency unit. Default value is 1 used in case if not specified.

OrderMemo

String

1024

 

Comment for Order or Quote. Used as Quote memo only if OrderStatus is false.

InvoiceMemo

String

1024

 

Memo for invoice. If OrderStatus is false it will be ignored.

Lines 

Array of Line

Yes

Sale Lines, see below

Payments 

Array of Payment

 

 

Sale Payments, see below. If OrderStatus isn’t AUTHORISED, it will be used as prepayments

AdditionalAttributes

Structured

 

 

Sale Additional Attributes, see below

 

Available Fields for BillingAddress and ShippingAddress:

Property

Type

Length

Required

Notes

Line1

String

256

Yes

Line2

String

256

City

String

256

State

String

256

Postcode

String

20

Country

String

32

 

Available Fields for InvoiceStatus and OrderStatus statuses:

Value

Description

NOTAUTHORISED

Default value. Indicating that order or invoice wasn’t authorised

AUTHORISED

Indicating that order or invoice was authorised

 

Available Fields for AutoPickPackShipMode:

Note: Enabled only for products which are not a service with OrderStatus=AUTHORISED option value. Also with auto pick/pack/ship mode all products will be picked/packed/shipped fully matching lines, you are not available to split it. If Sale Task is Service Only this parameter will be ignored.

Value

Description

NOPICK

Order will be created without picking

AUTOPICK

Order sill be created with Pick phase authorised

AUTOPICKPACK

Order sill be created with Pick and Pack phases authorised

AUTOPICKPACKSHIP

Order sill be created with Pick and Pack and Ship phases authorised

 

Available Fields for Sale Line:

Property

Type

Length

Required

Notes

SKU

String

50

Yes

Product SKU referenced by this Line

Quantity

Decimal with up to 4 decimal places

Yes

Product or service quantity. Minimal value is 1.

Price

Decimal with up to 4 decimal places

Yes

Price per unit in Customer currency

Tax

Decimal with up to 4 decimal places

 

Yes

 

Total

Decimal with up to 4 decimal places

 

Yes

For validation

LineOrder

Integer

 

 

Line order of item in Order and Invoice: 1,2,3,…

Discount

Decimal with up to 2 decimal places

Discount. Value between 0 and 100. For free items discount is 100. Default value is 0

SaleAccount

String

50

 

Account code of revenue account. If not specified SaleAccount defined in Sale will be used by default.

TaxRule

String

50

Yes

Line Tax Rule name.

Comment

String

256

 

Short comment for line

DropShip

Boolean

 

 

Required if product is not a service with “Optional Drop Ship” mode. Otherwise it ignored.

 

Available Fields for Sale Payment:

Property

Type

Length

Required

Notes

Reference

String

50

Payment reference number

Amount

Money

Yes

Payment amount in customer currency

DatePaid

Date

Yes

Date when payment has been made

Account

String

50

Yes

Account Code of the ACTIVE account from chart of accounts applicable for payments.

CurrencyRate

Decimal with up to 5 decimal places

Yes

Currency Conversion rate expressed as number of Base currency units for one Customer currency unit. By Default Equals 1 when customer currency is the same as base currency, otherwise you must specify it.

 

Available Fields for AdditionalAttributes:

Property

Type

Length

Required

Notes

AdditionalAttribute1

String

256

Additional Attribute 1 value

AdditionalAttribute2

String

256

Additional Attribute 2 value

AdditionalAttribute3

String

256

Additional Attribute 3 value

AdditionalAttribute4

String

256

Additional Attribute 4 value

AdditionalAttribute5

String

256

Additional Attribute 5 value

AdditionalAttribute6

String

256

Additional Attribute 6 value

AdditionalAttribute7

String

256

Additional Attribute 7 value

AdditionalAttribute8

String

256

Additional Attribute 8 value

AdditionalAttribute9

String

256

Additional Attribute 9 value

AdditionalAttribute10

String

256

Additional Attribute 10 value

 

 

Sale creation details

The properties marked “Required” are required for POST request. The request won’t be fulfilled unless these properties are valid.

If any optional field was not provided in payload DEAR will set it to default value (if field has it). If there is no default value specified DEAR will leave it empty.

API Sale creation features and limitations

There are some restrictions on Sale creation via API. Please keep it in your mind if you want to use restricted features – please use non API creation interface.

1. If you add to Sale product with quantity more than you have. DEAR silently create backorder record for this product.

2. It is impossible to use product with one SKU more once in Lines. If you try to do it, you will receive exception.

3. AUTO PICK PACK SHIP. If you request Pick status authorise, If you have not enough quantity to do picking. Pick status will be draft, pack, ship = not available. You won’t get exception in this case.

4. You can create Quote only if you will set OrderStatus status to (false). In this case Lines will be used as Quote Lines. Otherwise it will be used only as Order and Invoice lines.

Sample of request payload

{

 "Customer": "new customer",

 "Contact": "John Smith",

 "Phone": "+61 222 7895555",

 "OrderDate": "2015/01/01",

 "SaleAccount": "711",

 "BillingAddress": {

 "Line1": "street",

 "Line2": "building flat",

 "City": "NewTown",

 "State": "NewState",

 "Postcode": "123123",

 "Country": "US"

 },

 "ShippingAddress": {

 "Line1": "street",

 "Line2": "building flat",

 "City": "NewTown",

 "State": "NewState",

 "Postcode": "123123",

 "Country": "US"

 },

 "TaxRule": "Tax on Sales",

 "TaxInclusive": false,

 "Terms": "30 days term",

 "PriceTier": "Retail price",

 "Location": "Main Warehouse",

 "Note": "Some notes",

 "CustomerReference": "some customer reference",

 "InvoiceStatus": "Authorised",

 "OrderStatus": "Authorised",

 "AutoPickPackShipMode": "AUTOPICKPACKSHIP",

 "SalesRepresentative": "John Smith",

  "InvoiceDate": "2015/01/01",

 "InvoiceDueDate": "2015/01/01",

 "CurrencyRate": 1.07,

 "OrderMemo": "sample order request",

 "InvoiceMemo": "sample invoice memo",

 "Payments": [

 {

 "Reference": "payment sample reference",

 "Amount": 1.11,

 "DatePaid": "2015/01/01",

 "Account": "713",

 "CurrencyRate": 1.07

 }

 ],

 "Lines": [

 {

 "SKU": "BOM-1",

 "Quantity": 0.5,

 "Price": 50,

 "Tax": 5.5,

 "Total": 25,

 "TaxRule": "Tax on Sales",

 "DropShip": false,

 "Discount": 0,

 "SaleAccount": "710",

 "Comment": "Some product"

 },

 {

 "SKU": "Shipment",

 "Quantity": 1,

 "Price": 4.78,

 "Tax": 0,

 "Total": 4.78,

 "TaxRule": "Free export"

 },

    {

 "SKU": "DS-PROD",

 "Quantity": 1,

 "Price": 11,

 "Tax": 0.78,

 "Total": 11,

 "TaxRule": "Tax on Sales",

 "DropShip": true

 }

 ],

 "AdditionalAttributes": {

 "AdditionalAttribute1": "some value",

 "AdditionalAttribute2": "some value"

 }

}

Return value

In case if no errors occurred you will receive response with newly created Sale structure (from GET method), otherwise you will receive response, containing one or several errors. Respond will have structure like this:

[{

ErrorCode”:400,

“Exception”:”Error explanation will be here”

},

{

ErrorCode”:404,

“Exception”:”Customer not found”

}]