Shipment References API Using shipment references

By default, disbursements are calculated per order. For sub-order level information, seQura can generate reports per shipment reference. While most merchants use this to reconcile payments per shipment, you can use it however makes sense for your business.

Contact seQura to activate this option.

Example scenario

The following examples use this scenario:

Shopper orders products A, B, and C (3 €, 5 €, and 10 €), order ref N12.
You ship A and B from warehouse 1, C from warehouse 2, and inform seQura.
Shopper receives both packages and returns product B.
seQura disburses the order.
Shopper returns product C.
seQura disburses the order.

Disbursement reports look different depending on how you use shipment refs.

Order-centric settlements (default)

The default configuration focuses on value per order. Send Order Update requests with these carts:

// 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 to generate invoices for the shopper and disbursement reports for you. The first disbursement contains one line for order N12 (some fields omitted):

{
  "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
},

Use this information to determine the amount transferred in each disbursement. In this case, a total of 3 € has been paid for the order.

Shipment-centric settlements

The "shipment_ref" configuration focuses on value per shipment. Send these 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, you see you've been paid 3 € for "w1-456456" and 10 € for "w2-876876". In the second disbursement, 10 € is deducted for "w2-876876". Summarizing both reports: seQura has disbursed 3 € for "w1-456456" and 0 € for "w2-876876".

Operation-centric settlements

Some merchants focus on ERP operations rather than orders or shipments—typically those who don't sell physical products. To get the right information from seQura's disbursements, you'll need to express your operations in terms seQura can handle.

For example, if you work with refunds (money) rather than returns (goods), and care more about the refund than the item, use discounts to represent refunds and transaction numbers as shipment refs. The order above 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 approach, you get updates for orders but never for transactions.

Important note

Shipment refs are optional but must be used consistently per order. If you decide to use them, provide them for all orders going forward—you can't add them to orders created before you started using them. Choose a policy from the start and stick to it.