Feedback for “Orders”

[cjbarth]

With the field subtotal_ex_tax, is there also validation that this should be a positive number? The documentation doesn't say so, but we have types of orders that we're pushing from our ERP that are return orders (we don't actually return anything, we use a concept of a return order, so a negative sales amount). So, when we try to push that order to BC for a customer to have as a historical record, we're getting an error. However, there is nothing in the documentation that says a negative number wouldn't work because float, float_as_string, and integer data types all permit negative numbers.

[WillemHoman]

Hi @cjbarth
subtotal_ex_tax can't be negative.
Product quantity can be negative though, so this might work for you?

POST /v2/orders
{
    "customer_id": 0,
    "billing_address": {
        "first_name": "Joe",
        "last_name": "Schmoe",
        "street_1": "12 Main St",
        "country_iso2": "NZ",
        "state": "Sth Isl",
        "zip": "90210"
    },
    "products": [
        {
            "name": "Return",
            "quantity": -3,
            "price_inc_tax": 2,
            "price_ex_tax": 2
        }
    ]
}

Response

{
    "id": 541,
    <snip> 
    "subtotal_ex_tax": "-6.0000",
    "subtotal_inc_tax": "-6.0000",

[cjbarth]

Well, that means your documentation needs an update to say that limit on subtotal_ex_tax. What is more, your API may return the negative value, but as can be seen in the screenshot, the GUI doesn't show the negative value. Why the discrepancy?

[WillemHoman]

documentation needs an update

Yes, true

the GUI doesn't show the negative value

Which value do you mean?
The values in the UI reflect the values in the API response for the example above.

{
  "id": 541,
  "subtotal_ex_tax": "-6.0000",
  "subtotal_inc_tax": "-6.0000",
  "subtotal_tax": "0.0000",
  "base_shipping_cost": "0.0000",
  "shipping_cost_ex_tax": "0.0000",
  "shipping_cost_inc_tax": "0.0000",
  "shipping_cost_tax": "0.0000",
  "base_handling_cost": "0.0000",
  "handling_cost_ex_tax": "0.0000",
  "handling_cost_inc_tax": "0.0000",
  "handling_cost_tax": "0.0000",
  "handling_cost_tax_class_id": 0,
  "base_wrapping_cost": "0.0000",
  "wrapping_cost_ex_tax": "0.0000",
  "wrapping_cost_inc_tax": "0.0000",
  "wrapping_cost_tax": "0.0000",
  "total_ex_tax": "0.0000",
  "total_inc_tax": "0.0000",
  "total_tax": "0.0000"
}

The total_ex_tax and total_inc_tax don't reflect the negative value as it is an invariant across the entire platform that order totals can't be negative.

This is a discrepancy, but having negative quantities and negative subtotals is a legacy loophole more than an intentional feature.
We don't close this loophole as some merchants utilise it in creative ways and we wish to retain backwards compatibility.

Stepping back and looking at this a bit more broadly the

concept of a return order

is not one that BC supports.
Unfortunately due to the wide variety of external systems and processes our merchants utilise, we aren't able to support all of them.

BC supports the refunding of parts or all of an order with the Refunds API..

[cjbarth]

Which value do you mean?

I meant the Grand Total. It seems incongruous that the subtotal, plus the other items there, would not equal the Grand Total.

This is a discrepancy, but having negative quantities and negative subtotals is a legacy loophole more than an intentional feature.
We don't close this loophole as some merchants utilise it in creative ways and we wish to retain backwards compatibility.

This explains why you made the decision you did. It would be valuable to document this. I'm also super interested in what creative ways they might use this. It seems that "creative use" is a synonym for "wrong" or "abuse" and would be wise to see what other APIs they need to get their functionality and then work toward providing that so there is less dependency on API missuse.

Unfortunately due to the wide variety of external systems and processes our merchants utilise, we aren't able to support all of them.

I appreciate this and respect it. We knew you didn't support such a concept at a high level, but we didn't expect that we couldn't just have a negative order (especially since the documentation didn't say so). We were expecting we could meet our requirements with a negative order.

Thank you for your continued work on keeping the documentation up-to-date and for providing a little background here.

[WillemHoman]

what creative ways they might use this
what other APIs they need to get their functionality

It has historically been used to handle refunds via an API prior to the implementation of the refunds API.

we couldn't just have a negative order (especially since the documentation didn't say so)

Apologies for this surprise, I'll raise a PR to update the docs.

Thank you for your continued work on keeping the documentation up-to-date and for providing a little background here.

NP. Thanks for taking the time to raise this issue and help us improve our documentation.

[bc-traciporter]

Thank you @WillemHoman I created PR 527 for updating the subtotal_ex_tax description. Can you review it and suggest any changes?

[cjbarth]

It has historically been used to handle refunds via an API prior to the implementation of the refunds API.

I know it isn't my place, but I would encourage you to work with your customers to move them on to the correct API so that the platform can move forward with math that is accurate.

[bc-traciporter]

@WillemHoman I updated the other fields in PR 527.

[bc-traciporter]

Changes have been merged in PR 527. Closing ticket.