Guides
Start typing to search…

Order Update API

Ideally, seQura and the merchants should have all the order information synchronized to provide an excellent service to shoppers and merchants themselves. For instance: when the order is fullfilled, the merchant must inform seQura about the state of the unshipped and shipped carts. When there is a partial return, the merchant must update the shipped cart state. When there is a cancellation, the merchant has to inform that both unshipped and shipped carts are empty.

In order to do this, seQura provides an online interface where merchants can update order information using a web browser. A merchant who wishes to avoid performing the same changes in their own back-office system and in SeQura's web interface may opt to integrate their system with SeQura's Order Updates API. This document describes said API.

Sending updates

The endpoint for the order updates is https://sandbox.sequrapi.com/merchants/ merchant-ref/orders/order-ref where merchant-ref is your merchant reference or ID and order-ref is the reference that was sent as merchant_reference.order_ref_1 during checkout.

E.g., with merchant-ref being camisasonline and order-ref being A14/12345, the URL will be https://sandbox.sequrapi.com/merchants/camisasonline/orders/A14%2F12345 .
(Note that the slash (/) has to be escaped in the URL.)

Shipping scenarios

When the purchase is fully shipped

The most common case is when the shop ships the purchase. To manage this, the payload must contain an empty unshipped_cart and the shipped_cart containing all the purchased items.

{
  "order": {
    "unshipped_cart": {
      "currency": "EUR",
      "order_total_with_tax": 0,
      "items": []
    },
    "shipped_cart": {
      "currency": "EUR",
      "order_total_with_tax": 8350,
      "items":
        [
          {
            "reference": "shirt1234",
            "name": "shirt",
            "price_with_tax": 1250,
            "quantity": 1,
            "total_with_tax": 1250,
            "downloadable": false
          },
          {
            "reference": "jacket9876",
            "name": "jacket",
            "price_with_tax": 7100,
            "quantity": 1,
            "total_with_tax": 7100,
            "downloadable": false
          }
        ]
    },
    ...
  }
}

When the purchase is partialy shipped

In case of multiples shipments, please, keep the unshipped items in the unshipped_cart until they are shipped, and only the shipped items in the shipped_cart.

{
  "order": {
    "unshipped_cart": {
      "currency": "EUR",
      "order_total_with_tax": 1250,
      "items":
        [
          {
            "reference": "shirt1234",
            "name": "shirt",
            "price_with_tax": 1250,
            "quantity": 1,
            "total_with_tax": 1250,
            "downloadable": false
          },
        ]
    },
    "shipped_cart": {
      "currency": "EUR",
      "order_total_with_tax": 7100,
      "items":
        [
          {
            "reference": "jacket9876",
            "name": "jacket",
            "price_with_tax": 7100,
            "quantity": 1,
            "total_with_tax": 7100,
            "downloadable": false
          }
        ]
    },
    ...
  }
}

When there is a partial return

Again, you send the current state of the unshipped cart, if there isn't anything pending to be shipped, the unshipped_cart will be empty, and the non returned items will be in the shipped cart.

{
  "order": {
    "unshipped_cart": {
      "currency": "EUR",
      "order_total_with_tax": 0,
      "items": []
    },
    "shipped_cart": {
      "currency": "EUR",
      "order_total_with_tax": 7100,
      "items":
        [
          {
            "reference": "jacket9876",
            "name": "jacket",
            "price_with_tax": 7100,
            "quantity": 1,
            "total_with_tax": 7100,
            "downloadable": false
          }
        ]
    },
    ...
  }
}

When there is a full return or order cancellation

Both carts are empty. In the case it is an order cancellation, i.e. it never was shipped, please, also use the cancellation_reason field.

{
  "order": {
    "unshipped_cart": {
      "currency": "EUR",
      "order_total_with_tax": 0,
      "items": []
    },
    "shipped_cart": {
      "currency": "EUR",
      "order_total_with_tax": 0,
      "items": []
    },
    "cancellation_reason": "out_of_stock",
    ...
  }
}

When there is a cart update

If the shopper wants to change any item, it must also inform the new cart content.

{
  "order": {
    "unshipped_cart": {
      "currency": "EUR",
      "order_total_with_tax": 0,
      "items": []
    },
    "shipped_cart": {
      "currency": "EUR",
      "order_total_with_tax": 8350,
      "items":
        [
          {
            "reference": "shirt_XL",
            "name": "shirt XL",
            "price_with_tax": 1250,
            "quantity": 1,
            "total_with_tax": 1250,
            "downloadable": false
          },
          {
            "reference": "jacket9876",
            "name": "jacket",
            "price_with_tax": 7100,
            "quantity": 1,
            "total_with_tax": 7100,
            "downloadable": false
          }
        ]
    },
    ...
  }
}

Order upsellings

SeQura doesn't accept order upsellings with an initial price increase greater than 15%.

Shipping items in checkout

If your store is a physical store where the shopper can carry the purchase at the moment, or shops that do not ship items explicitly, for instance, online courses, ebooks or downloadable content, you can inform of this during the checkout. Read more

Order Update API Payload and Examples

A detailed description of the structure of the payload that is used in all the calls in the checkout, a JSON example and a PHP example. Read more

Calling the Order Update API

A sample of how you can call the Order Update API. Read more

When am I done?

Once you are done, your requests will get an HTTP response code and a json code in the body.

  • If the response code is a 200, 202 or 204 your update request has been processed. Log in to our back office and confirm that the changes in the order are the expected ones.
  • If the HTTP response code is a 409 indicating a conflict or any other error make sure you deal with it properly.

Updated 5 days ago