Order API

Use the REST API to interact with EverShop orders.

An order can carry many shipments. Each shipment covers specific order items at specific quantities, and order.shipment_status is a rollup computed from all of them — it is not a status you set directly.

Endpoints

Create An Order

Use this endpoint to create an order from a shopping cart.

Request Schema (application/json)

Field Name	Field Type	Required
cart_id	string	Yes

POST/api/orders

cURL

curl
  -H "Accept: application/json"
  -H "Authorization: Bearer <admin JWT token>"
  --data-raw '<JSON DATA>'
  https://<your domain>/api/orders

JavaScript

fetch('https://<your domain>/api/orders', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  },
  body: <JSON DATA>
})
  .then(response => response.json())
  .then(data => {
    if(data.error) {
      // Handle the error
    } else {
      // Handle the data
    }
  })
  .catch(error => {
    // Handle the error
  });

Sample Of Response

{
"data": {
  "order_id": 274,
  "uuid": "fd0b4f0fd6704ed0b53fa0c64ae7df3c",
  "integration_order_id": null,
  "order_number": "10274",
  "cart_id": 990,
  "currency": "USD",
  "customer_id": 20,
  "customer_email": "customer@example.com",
  "customer_full_name": "The Nguyen",
  "user_ip": null,
  "sid": "09d34c21-4af3-4db8-a38b-335ebf6d45fa",
  "user_agent": null,
  "coupon": null,
  "shipping_fee_excl_tax": 0,
  "shipping_fee_incl_tax": 0,
  "discount_amount": 0,
  "sub_total": 12345,
  "total_qty": 15,
  "total_weight": 81,
  "tax_amount": 0,
  "shipping_note": null,
  "grand_total": 12345,
  "shipping_method_data": {
    "provider_code": "core",
    "method_code": "0f1c8b7a-9d3e-4f2a-a1b6-77d4c2e9b510",
    "snapshot": {
      "code": "0f1c8b7a-9d3e-4f2a-a1b6-77d4c2e9b510",
      "name": "Free Shipping",
      "cost": 0
    }
  },
  "shipping_address_id": 551,
  "payment_method": "paypal",
  "payment_method_name": "Paypal",
  "billing_address_id": 552,
  "shipment_status": "pending",
  "payment_status": "pending",
  "created_at": "2023-02-07 14:18:04",
  "updated_at": "2023-02-07 14:18:04",
  "items": [
    {
      "order_item_id": 306,
      "uuid": "dc651b93008d475e9de6d85983586a2e",
      "order_item_order_id": 274,
      "product_id": 3,
      "referer": null,
      "product_sku": "NJC90842-Black-X",
      "product_name": "Lite racer adapt 3.0 shoes",
      "thumbnail": "/assets/catalog/8953/8037/plv3663-Black-thumb.png",
      "product_weight": 5.4,
      "product_price": 823,
      "product_price_incl_tax": 823,
      "qty": 15,
      "final_price": 823,
      "final_price_incl_tax": 823,
      "tax_percent": 0,
      "tax_amount": 0,
      "discount_amount": 0,
      "total": 12345,
      "variant_group_id": 62,
      "variant_options": "[{"attribute_code":"size","attribute_name":"Size","attribute_id":2,"option_id":4,"option_text":"X"},{"attribute_code":"color","attribute_name":"Color","attribute_id":3,"option_id":14,"option_text":"Black"}]",
      "product_custom_options": null,
      "requested_data": null
    }
  ],
  "shipping_address": {
    "order_address_id": 551,
    "uuid": "e0fbebaca66c11edb46b60d819134f39",
    "full_name": "The Nguyen",
    "postcode": "5000",
    "telephone": "123456",
    "country": "VN",
    "province": "Ho Chi Minh",
    "city": "Ho Chi Minh",
    "address_1": "Thu Duc ho chi minh",
    "address_2": null
  },
  "billing_address": {
    "order_address_id": 552,
    "uuid": "e0fd1671a66c11edb46b60d819134f39",
    "full_name": "The Nguyen",
    "postcode": "5000",
    "telephone": "123456",
    "country": "VN",
    "province": "Ho Chi Minh",
    "city": "Ho Chi Minh",
    "address_1": "Thu Duc ho chi minh",
    "address_2": null
  },
  "links": [
    {
      "rel": "edit",
      "href": "/admin/order/edit/fd0b4f0fd6704ed0b53fa0c64ae7df3c",
      "action": "GET",
      "types": [
        "text/xml"
      ]
    }
  ]
}
}

Shipping columns changed

order.shipping_method and order.shipping_method_name were dropped. The selection now lives in the shipping_method_data JSONB column, which holds provider_code, method_code and a snapshot of the method as quoted at checkout time.

billing_address can be null

The billing address is optional on zero-total orders (nothing is charged, taxed or invoiced). billing_address_id is null and billing_address resolves to null. Every other order still requires one.

---

Shipments

An order can have many shipments in EverShop 2.2 and later. Each carries its own items, status and tracking, and order.shipment_status is a derived rollup over them — see Shipment Status below.

The shipment endpoints have their own reference:

What you want to do	Where
Create a shipment, list an order's shipments, update, cancel, mark delivered, void a label	Shipment API
Understand the rollup, phases and status transitions	Multi-shipment And Fulfillment
Register a carrier so labels and tracking work	Carrier Development

---

Order-level Actions

Cancel An Order

Use this endpoint to cancel an order.

Request Schema (application/json)

Field Name	Field Type	Required
reason	string	Yes

POST/api/orders/:id/cancel

cURL

curl
  -H "Accept: application/json"
  -H "Authorization: Bearer <admin JWT token>"
  --data-raw '<JSON DATA>'
  https://<your domain>/api/orders/:id/cancel

JavaScript

fetch('https://<your domain>/api/orders/:id/cancel', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  },
  body: <JSON DATA>
})
  .then(response => response.json())
  .then(data => {
    if(data.error) {
      // Handle the error
    } else {
      // Handle the data
    }
  })
  .catch(error => {
    // Handle the error
  });

Sample Of Response

{
"data": {}
}

---

Mark Every Shipment Delivered

Legacy back-compat wrapper. It sweeps every shipment on the order that is not already delivered or canceled and advances it, then returns how many it actually moved. Prefer the per-shipment endpoint above for new integrations.

Request Schema (application/json)

Field Name	Field Type	Required
order_id	string	No

POST/api/deliveries

cURL

curl
  -H "Accept: application/json"
  -H "Authorization: Bearer <admin JWT token>"
  --data-raw '<JSON DATA>'
  https://<your domain>/api/deliveries

JavaScript

fetch('https://<your domain>/api/deliveries', {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer <admin JWT token>'
  },
  body: <JSON DATA>
})
  .then(response => response.json())
  .then(data => {
    if(data.error) {
      // Handle the error
    } else {
      // Handle the data
    }
  })
  .catch(error => {
    // Handle the error
  });

Sample Of Response

{
"data": {
  "order_id": 274,
  "updated_count": 2
}
}

Errors: 400 Invalid order id, 400 No shipments to mark delivered.

---

Shipment Status

order.shipment_status is an order-level rollup derived from the per-item shipment math. You never write it directly; it is recomputed after every shipment status change and after order cancellation.

Value	Meaning
pending	No items shipped yet. This is the value a brand-new order gets
partially_shipped	Some, but not all, shippable items have shipped
shipped	Every shippable item has shipped
partially_delivered	Some items delivered, others still in transit
delivered	Every shippable item delivered. An all-digital order short-circuits to this at creation
partially_canceled	Some items are in canceled shipments and nothing else has shipped
canceled	The whole order is canceled, or every shippable item sits in a canceled shipment

unfullfilled is dead

The legacy "unfullfilled" value no longer exists anywhere in the system. Integrations that switch on it will never match. The initial value is pending.

The three partially_* values are rollup-only — a single shipment can never carry them. Per-shipment status values are the registered shipment statuses (shipped, delivered, canceled, plus anything an extension registers).