Sale POST

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 authorized
AUTHORISED	Indicating that order or invoice was authorized

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 authorized
AUTOPICKPACK	Order sill be created with Pick and Pack phases authorized
AUTOPICKPACKSHIP	Order sill be created with Pick and Pack and Ship phases authorized

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 Cin7 Core will set it to default value (if field has it). If there is no default value specified Cin7 Core 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. Cin7 Core 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 authorize, 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": "Authorized",
"OrderStatus": "Authorized",
"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”
}]

Sale POST

Was this article helpful?