Guides
Start typing to search…

Shipment References API Using shipment references

By default, disbursements are calculated and reported per order. For merchants that need information on a sub-order level, seQura can generate the reports per shipment reference. While the most common need is to reconcile payments per shipment or delivery, the merchant is free to use this functionality in a way that produces the disbursement reports that make most sense from a business or process perspective.

This option must be activated by seQura and allows the merchant to reconcile order payments on the level that makes most sense from a business perspective.

Example scenario

For the 3 configuration examples below, we are going to use this common scenario:

  1. Shopper orders products A, B and C, costing 3, 5 and 10 €, with order ref N12.
  2. Merchant sends A and B from warehouse 1 and C from warehouse 2 and informs seQura about this.
  3. Shopper receives both packages, looks at the products and returns product B.
  4. seQura disburses the order.
  5. Shopper returns product C.
  6. seQura disburses the order.

The disbursement reports for this example will look different depending on whether the merchant uses shipment refs or not, and how.

Order-centric settlements (default)

The default configuration focuses on value per order. In the example, the merchant would send Order Update requests with the following carts for the three delivery/return operations above:

// Shipment
{
  "shipped_cart": {"items": [
      {"reference":"A", "total_with_tax":300},
      {"reference":"B", "total_with_tax":500},
      {"reference":"C", "total_with_tax":1000}
    ]}
}
// First return (resulting cart)
{
  "shipped_cart": {"items": [
      {"reference":"A", "total_with_tax":300},
      {"reference":"C", "total_with_tax":1000}
    ]}
}
// Second return (resulting cart)
{
  "shipped_cart": {"items": [
      {"reference":"A", "total_with_tax":300}
    ]}
}

SeQura uses this information to generate invoices (etc) for the shopper and disbursement reports for the merchant. The first disbursement will contain one line for order N12. (For brevity, we omit some fields.):

{
  "order_ref_1": "N12",
  "amount_with_tax": 1300,
  "maximum_amount_with_tax": 1800
},

The second disbursement also contains one line for N12:

{
  "order_ref_1": "N12",
  "amount_with_tax": -1000,
  "maximum_amount_with_tax": 1800
},

The merchant can use this information to deduce the amount transferred in each disbursement, and to see that a total of 3 € has been paid for the order.

Shipment-centric settlements

The "shipment_ref" configuration focuses on value per shipment. A merchant with this focus would send the following carts:

// Shipment
{
  "shipped_cart": {"items": [
      {"reference":"A", "total_with_tax":300, "shipment_ref": "w1-456456"},
      {"reference":"B", "total_with_tax":500, "shipment_ref": "w1-456456"},
      {"reference":"C", "total_with_tax":1000, "shipment_ref": "w2-876876"}
    ]}
}
// First return (resulting cart)
{
  "shipped_cart": {"items": [
      {"reference":"A", "total_with_tax":300, "shipment_ref": "w1-456456"},
      {"reference":"C", "total_with_tax":1000, "shipment_ref": "w2-876876"}
    ]}
}
// Second return (resulting cart)
{
  "shipped_cart": {"items": [
      {"reference":"A", "total_with_tax":300, "shipment_ref": "w1-456456"}
    ]}
}

Now, the first disbursement will contain two lines like these for order N12:

{
  "order_ref_1": "N12",
  "amount_with_tax": 300,
  "maximum_amount_with_tax": 1800,
  "shipment_ref": "w1-456456"
},
{
  "order_ref_1": "N12",
  "amount_with_tax": 1000,
  "maximum_amount_with_tax": 1800,
  "shipment_ref": "w2-876876"
},

The second disbursement contains one line for N12:

{
  "order_ref_1": "N12",
  "amount_with_tax": -1000,
  "maximum_amount_with_tax": 1800,
  "shipment_ref": "w2-876876"
},

After the first disbursement, the merchant sees that they have been paid 3 € for "w1-456456" and 10 € for "w2-876876". In the second disbursement, 10 € is being deducted for "w2-876876". And summarising the information in both disbursement reports, the merchant can now conclude that seQura has disbursed a total of 3€ for shipment_ref "w1-456456" and 0€ for "w2-876876".

Operation-centric settlements

For some merchants, focus is not on orders or shipments but on operations in their ERP or similar. These are typically merchants who do not sell physical products. In order to get the information they want from SeQura's disbursements, they will need to work a little harder to express their reality in terms that seQura can handle. For instance, the merchant might work with refunds (of money) rather than returns (of goods, with subsequent refunds) and might be more focused on the refund than on the item or items for which a refund was issued. In these cases, we recommend using discounts to play the role of refunds and transaction numbers to play the role of shipment refs. In the order above, this could be expressed as

// Shipment
{
  "shipped_cart": {"items": [
      {"reference":"A", "total_with_tax":300, "shipment_ref": "trans-1"},
      {"reference":"B", "total_with_tax":500, "shipment_ref": "trans-1"},
      {"reference":"C", "total_with_tax":1000, "shipment_ref": "trans-1"}
    ]}
}
// First return (resulting cart)
{
  "shipped_cart": {"items": [
      {"reference":"A", "total_with_tax":300, "shipment_ref": "trans-1"},
      {"reference":"B", "total_with_tax":500, "shipment_ref": "trans-1"},
      {"reference":"C", "total_with_tax":1000, "shipment_ref": "trans-1"},
      {"type": "discount", "reference":"BB", "total_with_tax":-500, "shipment_ref": "trans-2"}
    ]}
}
// Second return (resulting cart)
{
  "shipped_cart": {"items": [
      {"reference":"A", "total_with_tax":300, "shipment_ref": "trans-1"},
      {"reference":"B", "total_with_tax":500, "shipment_ref": "trans-1"},
      {"reference":"C", "total_with_tax":1000, "shipment_ref": "trans-1"},
      {"type": "discount", "reference":"BB", "total_with_tax":-500, "shipment_ref": "trans-2"},
      {"type": "discount", "reference":"CC", "total_with_tax":-1000, "shipment_ref": "trans-3"}
    ]}
}

This will lead to two lines in the first disbursement report:

{
  "order_ref_1": "N12",
  "amount_with_tax": 1800,
  "maximum_amount_with_tax": 1800,
  "shipment_ref": "trans-1"
},
{
  "order_ref_1": "N12",
  "amount_with_tax": -500,
  "maximum_amount_with_tax": 1800,
  "shipment_ref": "trans-2"
},

The second disbursement contains one line for the order:

{
  "order_ref_1": "N12",
  "amount_with_tax": -1000,
  "maximum_amount_with_tax": 1800,
  "shipment_ref": "trans-3"
},

Using this way of working, the merchant will get updates for orders but never for transactions.

Important note

Shipment refs are optional but have to be used consistently, per order. Specifically, if a merchant decides to use shipment refs, they need to provide them for all orders created from that point on, but are not allowed to use them on orders created previously. To avoid problems, we suggest that merchants choose a policy from the outset and stick to it.

Updated 5 days ago