Sales

A sale represents a single line item (row) in a transaction with a customer.

A transaction is created within Custobar by combining all the information in the sale rows having the same sale_external_id. Each sale row holds information about the bought product, quantity and sale price.

The transaction-level information (e.g. the customer made the purchase) is supplied with one or multiple sale rows in addition to its product information.

Transaction-level fields

Transaction-level fields apply to the entire purchase regardless of which sale row the information was supplied, the transaction-level fields are prefixed with sale_.

Mandatory fields

Field	Type	Description
sale_external_id	string	Your unique identifier for the entire transaction which includes all the sale rows. Must be included in all sale rows.
sale_date	datetime	Date of the sale, e.g. 2017-08-28 or 2017-08-28T14:10:00Z. If the timezone is not given, the timezone will be defaulted to the timezone configured in the Custobar’s settings.

The customer making the transaction is identified by supplying at least one of the customer identifying fields external_id, phone_number or email. These fields should be prefixed too, thus email becoming sale_email, etc.

Customer field	Sale field
external_id	sale_customer_id
phone_number	sale_phone_number
email	sale_email

Optional fields

Field	Type	Description
sale_currency	string	The currency, in which the sale was made. Must be defined together with sale_exchange_rage.
sale_discount	money	Discount that applies to the purchase as a whole, e.g. a discount of 5.00 € should be passed as 500.
sale_exchange_rate	number	Exchange rate from the sale_currency to default currency in Custobar. Must be defined together with sale_currency.
sale_payment_method	string	Your identifier of the payment method used.
sale_shipping	money	The added shipping cost in cents.
sale_shipping_method	string	The added shipping method.
sale_shipping_in_currency	money	The added shipping cost in cents. sale_shipping_in_currency can be defined instead of sale_shipping when sale_currency and sale_exchange_rate have been defined.
sale_shop_id	string	external_id of a shop where the purchase was made.
sale_state	string	A sale state, one of “NEW”, “PENDING_PAYMENT”, “PROCESSING”, “COMPLETE”, “CANCELLED”, “CLOSED” or “HOLDED”. Sales in special states “CANCELLED” or “CLOSED” are not included in the statistics. If omitted, the sale is treated as “COMPLETE”.
sale_total	money	The total price of the transaction in cents, e.g. 950.00 € should be passed as 95000. If sale_total field is missing, sale total is calculated as sum(sale row total fields) - sale_discount.
tags	[set][] of string	Tags assigned for this Sale.

Sale-row-level fields

Mandatory fields

Field	Type	Description
external_id	string	Your unique identifier of sale row.
product_id	string	external_id of a product sold.
quantity	number	Quantity of the product sold. Supplying double value is supported, but it is rounded to precision of two decimal places using the normal rounding rules, e.g. a value of 0.003 will become 0.00.
unit_price	money	The price of a one unit in cents. Unit price of 1795.00 € should be passed as 179500. The unit price is a price of a single item, before discount has been applied.

Optional fields

Field	Type	Description
discount	money	A discount of 0.50 € should be passed as 50. Both the positive and negative value is calculated towards a discount.
total	money	The total price of sale row in cents.
unit_price_in_currency	money	If the sale_currency is defined, the price may be given in that currency, instead of unit_price.
tags	[set][] of string	Tags assigned for this Sale-row.

If total field is not supplied, the value of a sale row is calculated as (unit_price * quantity) - discount.

Company-specific fields

You may add additional fields, that are company specific by prefixing them with a company short name and a double underscore __, e.g. COMPANY__pos_id. The company specific fields apply to the entire transaction and are not sale row specific.

Company specific fields are searchable in the Custobar user interface.

Providing sales in currency other than the default currency

You may send sales in some other currency than the default currency defined in Custobar settings. To do so, you’ll need to send

sale_currency - The currency in which the sale occurred.
sale_exchange_rate - The exchange rate to the default currency. The formula is unit_price_in_currency / sale_exchange_rate = the price in the default Custobar currency.
unit_price_in_currency - The price of the sale row in sale_currency.

Canceled / Returned sales

While different ERP and eCommerce systems manage returns / canceled sales differently, our best practice is to mark the returned / canceled sales with the sale_state value CANCELED.
With this state, Custobar will not calculate the returned sale as a conversion and the revenue is removed from the aggregated total revenue.
Please note: This is the best practice for the case where the entire sale is canceled.
If only one sale row of the sale is canceled / returned, then you can update the price of that sale row to 0 and mark the sale row with the tags value CANCELED.

Example

To upload new sale, you may pass them to Custobar using a HTTP POST command, e.g.

curl -X POST -u USER -H "Content-Type: application/json" \
    --data-binary @sales.json https://COMPANY.custobar.com/api/sales/upload/

The product objects must be provided as a list, wrapped into a JSON object, with a key sales, as shown in the example below.

The example represents a single transaction with two sale order rows.

{
  "sales": [
    {
      "sale_external_id": "1000",
      "sale_customer_id": "A501",
      "sale_date": "2017-12-01T13:11:23Z",
      "sale_shop_id": "1",
      "sale_discount": 0,
      "sale_total": 5160,
      "sale_payment_method": "Credit Card",

      "external_id": "1000-1",
      "product_id": "SKU0435",
      "unit_price": 1200,
      "quantity": 1,
      "total": 1200,

       "COMPANY__sales_person": "3"
    },
    {
       "sale_external_id": "1000",

       "external_id": "1000-2",
       "product_id": "SKU3429",
       "unit_price": 2080,
       "quantity": 2,
       "discount": 200,
       "total": 3960
    },
    {
       "sale_external_id": "5000",
       "sale_exchange_rate": 1.112,
       "sale_currency": "USD",

       "external_id": "5000-2",
       "product_id": "SKU3429",
       "unit_price_in_currency": 2080,
       "quantity": 2
    }
  ]
}

Data Reference

Sales

A sale represents a single line item (row) in a transaction with a customer.

The transaction-level information (e.g. the customer made the purchase) is supplied with one or multiple sale rows in addition to its product information.

Transaction-level fields

Transaction-level fields apply to the entire purchase regardless of which sale row the information was supplied, the transaction-level fields are prefixed with sale_.

Mandatory fields

Field	Type	Description
sale_external_id	string	Your unique identifier for the entire transaction which includes all the sale rows. Must be included in all sale rows.
sale_date	datetime	Date of the sale, e.g. 2017-08-28 or 2017-08-28T14:10:00Z. If the timezone is not given, the timezone will be defaulted to the timezone configured in the Custobar’s settings.

Customer field	Sale field
external_id	sale_customer_id
phone_number	sale_phone_number
email	sale_email

Optional fields

Field	Type	Description
sale_currency	string	The currency, in which the sale was made. Must be defined together with sale_exchange_rage.
sale_discount	money	Discount that applies to the purchase as a whole, e.g. a discount of 5.00 € should be passed as 500.
sale_exchange_rate	number	Exchange rate from the sale_currency to default currency in Custobar. Must be defined together with sale_currency.
sale_payment_method	string	Your identifier of the payment method used.
sale_shipping	money	The added shipping cost in cents.
sale_shipping_method	string	The added shipping method.
sale_shipping_in_currency	money	The added shipping cost in cents. sale_shipping_in_currency can be defined instead of sale_shipping when sale_currency and sale_exchange_rate have been defined.
sale_shop_id	string	external_id of a shop where the purchase was made.
sale_state	string	A sale state, one of “NEW”, “PENDING_PAYMENT”, “PROCESSING”, “COMPLETE”, “CANCELLED”, “CLOSED” or “HOLDED”. Sales in special states “CANCELLED” or “CLOSED” are not included in the statistics. If omitted, the sale is treated as “COMPLETE”.
sale_total	money	The total price of the transaction in cents, e.g. 950.00 € should be passed as 95000. If sale_total field is missing, sale total is calculated as sum(sale row total fields) - sale_discount.
tags	[set][] of string	Tags assigned for this Sale.

Sale-row-level fields

Mandatory fields

Field	Type	Description
external_id	string	Your unique identifier of sale row.
product_id	string	external_id of a product sold.
quantity	number	Quantity of the product sold. Supplying double value is supported, but it is rounded to precision of two decimal places using the normal rounding rules, e.g. a value of 0.003 will become 0.00.
unit_price	money	The price of a one unit in cents. Unit price of 1795.00 € should be passed as 179500. The unit price is a price of a single item, before discount has been applied.

Optional fields

Field	Type	Description
discount	money	A discount of 0.50 € should be passed as 50. Both the positive and negative value is calculated towards a discount.
total	money	The total price of sale row in cents.
unit_price_in_currency	money	If the sale_currency is defined, the price may be given in that currency, instead of unit_price.
tags	[set][] of string	Tags assigned for this Sale-row.

If total field is not supplied, the value of a sale row is calculated as (unit_price * quantity) - discount.

Company-specific fields

Company specific fields are searchable in the Custobar user interface.

Providing sales in currency other than the default currency

You may send sales in some other currency than the default currency defined in Custobar settings. To do so, you’ll need to send

sale_currency - The currency in which the sale occurred.
sale_exchange_rate - The exchange rate to the default currency. The formula is unit_price_in_currency / sale_exchange_rate = the price in the default Custobar currency.
unit_price_in_currency - The price of the sale row in sale_currency.

Canceled / Returned sales

Example

To upload new sale, you may pass them to Custobar using a HTTP POST command, e.g.

curl -X POST -u USER -H "Content-Type: application/json" \
    --data-binary @sales.json https://COMPANY.custobar.com/api/sales/upload/

The product objects must be provided as a list, wrapped into a JSON object, with a key sales, as shown in the example below.

The example represents a single transaction with two sale order rows.

{
  "sales": [
    {
      "sale_external_id": "1000",
      "sale_customer_id": "A501",
      "sale_date": "2017-12-01T13:11:23Z",
      "sale_shop_id": "1",
      "sale_discount": 0,
      "sale_total": 5160,
      "sale_payment_method": "Credit Card",

      "external_id": "1000-1",
      "product_id": "SKU0435",
      "unit_price": 1200,
      "quantity": 1,
      "total": 1200,

       "COMPANY__sales_person": "3"
    },
    {
       "sale_external_id": "1000",

       "external_id": "1000-2",
       "product_id": "SKU3429",
       "unit_price": 2080,
       "quantity": 2,
       "discount": 200,
       "total": 3960
    },
    {
       "sale_external_id": "5000",
       "sale_exchange_rate": 1.112,
       "sale_currency": "USD",

       "external_id": "5000-2",
       "product_id": "SKU3429",
       "unit_price_in_currency": 2080,
       "quantity": 2
    }
  ]
}