Sale POST

The latest version of the Cin7 Core API (V2) is available, with more advanced functionality and support for recent system changes. See the full API documentation to get started.

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” }]

Was this article helpful?

Have more questions? Submit a request