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

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.

Optional fields

Sale-row-level fields

Mandatory fields

The products listed in the sales are linked to the products in Custobar's database by matching the product_id in the sale to the external_id of the imported products.

If there is no product in the database matching the product_id of the incoming sale, a product with that ID will be created along with the sale, and the details listed in the sale (title, price, etc.) will be copied to that new product.

In case a product_id is not included in the sale, Custobar tries to find a matching product using the sku and ean fields instead, and link the sale to that product.

If the sale does not include product_id, but includes a sku or ean, but a matching product is not found, Custobar will create the product, but it will give it a synthetic external_id, composed of the ean/sku in the sale. Note however, that if the product matching that sku/ean is later imported to Custobar, it won't be matched to this product with the synthetic id. So, if the system that is importing sales to Custobar does not have access to the proper product_ids, it can use ean/sku instead to identify the sale. But, in this case, it's important to import the products first, so that the matching products will be found at the sales import time.

You can also skip the sending of values in the field unit_price and instead send in the sale_total for the whole sale transaction as well.

Optional fields

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

This example is sent in without a unique ID for the sale rows (external_id) which then connects all rows to one sale using the sale_external_id field.

{
  "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",
      "product_id": "SKU0435",
      "unit_price": 1200,
      "quantity": 1,
      "total": 1200
    },
    {
       "sale_external_id": "1000",
       "product_id": "SKU3429",
       "unit_price": 2080,
       "quantity": 2,
       "discount": 200,
       "total": 3960
    }
  ]
}