Atomically apply one or more edits to an existing order
Inserts items and / or adds general-purpose adjustments to an order
in a single DB transaction. After the operations run, the eight
current_* totals on the order are recalculated and an order-edit
audit record is written per operation.
On success, the order_edited lifecycle event fires so subscribed
webhooks receive the post-edit payload.
editor_type and editor_id are derived from the authenticated
credential — droplet installations land as ("droplet", handle),
admin user_company tokens as ("admin", user_company.id), other
tokens as ("system", auth_type). The payload itself never
carries these fields.
A typical use case is a droplet-driven free-gift flow: insert
a Xgiftitemplusa−X credit adjustment in one block; the
order’s current_amount is unchanged, but the audit log captures
both operations and webhook subscribers see the updated state.
curl --request POST \
--url https://api.fluid.app/api/v202604/orders/{order_id}/edits \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"operations": [
{
"type": "insert_item",
"variant_id": "abc123",
"quantity": 1,
"price": "29.99"
},
{
"type": "add_adjustment",
"amount": "-29.99",
"label": "Free gift credit",
"adjustment_type": "credit",
"source_type": "droplet",
"source_id": "free-gift-droplet"
}
]
}
'import requests
url = "https://api.fluid.app/api/v202604/orders/{order_id}/edits"
payload = { "operations": [
{
"type": "insert_item",
"variant_id": "abc123",
"quantity": 1,
"price": "29.99"
},
{
"type": "add_adjustment",
"amount": "-29.99",
"label": "Free gift credit",
"adjustment_type": "credit",
"source_type": "droplet",
"source_id": "free-gift-droplet"
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
operations: [
{type: 'insert_item', variant_id: 'abc123', quantity: 1, price: '29.99'},
{
type: 'add_adjustment',
amount: '-29.99',
label: 'Free gift credit',
adjustment_type: 'credit',
source_type: 'droplet',
source_id: 'free-gift-droplet'
}
]
})
};
fetch('https://api.fluid.app/api/v202604/orders/{order_id}/edits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fluid.app/api/v202604/orders/{order_id}/edits",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'operations' => [
[
'type' => 'insert_item',
'variant_id' => 'abc123',
'quantity' => 1,
'price' => '29.99'
],
[
'type' => 'add_adjustment',
'amount' => '-29.99',
'label' => 'Free gift credit',
'adjustment_type' => 'credit',
'source_type' => 'droplet',
'source_id' => 'free-gift-droplet'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fluid.app/api/v202604/orders/{order_id}/edits"
payload := strings.NewReader("{\n \"operations\": [\n {\n \"type\": \"insert_item\",\n \"variant_id\": \"abc123\",\n \"quantity\": 1,\n \"price\": \"29.99\"\n },\n {\n \"type\": \"add_adjustment\",\n \"amount\": \"-29.99\",\n \"label\": \"Free gift credit\",\n \"adjustment_type\": \"credit\",\n \"source_type\": \"droplet\",\n \"source_id\": \"free-gift-droplet\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fluid.app/api/v202604/orders/{order_id}/edits")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"operations\": [\n {\n \"type\": \"insert_item\",\n \"variant_id\": \"abc123\",\n \"quantity\": 1,\n \"price\": \"29.99\"\n },\n {\n \"type\": \"add_adjustment\",\n \"amount\": \"-29.99\",\n \"label\": \"Free gift credit\",\n \"adjustment_type\": \"credit\",\n \"source_type\": \"droplet\",\n \"source_id\": \"free-gift-droplet\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fluid.app/api/v202604/orders/{order_id}/edits")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"operations\": [\n {\n \"type\": \"insert_item\",\n \"variant_id\": \"abc123\",\n \"quantity\": 1,\n \"price\": \"29.99\"\n },\n {\n \"type\": \"add_adjustment\",\n \"amount\": \"-29.99\",\n \"label\": \"Free gift credit\",\n \"adjustment_type\": \"credit\",\n \"source_type\": \"droplet\",\n \"source_id\": \"free-gift-droplet\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"order": {
"id": 90210,
"order_number": "1001",
"status": "complete",
"currency_code": "USD",
"current_subtotal": "129.99",
"current_discount": "0.00",
"current_adjustment_total": "-29.99",
"current_amount": "100.00",
"adjustments": [
{
"id": 55,
"amount": "-29.99",
"label": "Free gift credit",
"adjustment_type": "credit",
"source_type": "droplet",
"source_id": "free-gift-droplet",
"created_at": "2026-04-01T12:00:00Z"
}
]
},
"status": 200,
"meta": {
"request_id": "018f2c1a-8b3a-7e6d-9f10-2a3b4c5d6e7f",
"timestamp": "2026-04-01T12:00:00Z"
}
}{
"error": {
"message": "<string>",
"details": {}
},
"status": 123,
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z"
}
}{
"message": "Invalid credentials."
}{
"message": "Not authorized."
}{
"error": {
"message": "<string>",
"details": {}
},
"status": 123,
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z"
}
}{
"error": {
"message": "<string>",
"details": {}
},
"status": 123,
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z"
}
}{
"error": {
"message": "<string>",
"details": {}
},
"status": 123,
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z"
}
}{
"status": "error",
"message": "The request was not processed. Retry it unchanged under the same Idempotency-Key."
}Authorizations
Bearer token authentication. Accepts company tokens, partner tokens,
public tokens, droplet installation tokens, and user_company tokens.
The authenticated credential determines editor_type and editor_id
on the resulting order-edit audit records — the payload never carries
either field.
Headers
Optional client-generated key (UUID recommended) that the server
uses to deduplicate retries: a stored response replays for up to 24
hours. An edit whose outcome is unknown holds its key until support
resolves it, and every retry under it answers 409 until then; once
support resolves it, the key stays held for 24 hours if the edit
took effect, or can be used again if it did not. The key is bound
to the exact request that first used it: the method, path and
query string, Content-Type and body bytes, and the editor the
edit is attributed to. A retry must resend that request unchanged,
byte for byte, and then replays the first response with
X-Idempotent-Replayed: true. Any other request under the key
answers 422 and does not run; use a new key only for a new
request. A client that cannot reproduce the original request
should read the order to confirm the outcome rather than retry
under a new key. A concurrent retry while the first is still in
flight returns 409. The cache is scoped to the authenticated
company. A key must not end with :lock, which is reserved; such
a key answers 422 and the edit does not run. A response already
cached under such a key, from before the suffix was reserved,
still replays on a retry of its request.
255Path Parameters
Primary-key id of the order to edit. Must belong to the authenticated company; an unknown id or an order owned by another company returns 404.
Body
One or more edit operations to apply atomically. The whole transaction commits or rolls back together.
1- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
Show child attributes
Show child attributes
Optional optimistic-concurrency guard. When provided, the
server compares against the order's current updated_at
before applying any operations and returns HTTP 409 with
the current value on mismatch. Pass the ISO-8601 string
received in a prior order response verbatim. Callers that
don't load the order first can omit this and bypass the
check.
Response
Edit applied successfully. Returns the updated order.
Order response wrapper. The order object includes the eight
recalculated current_* totals plus the adjustments array.
Edit history is not exposed through this API.
curl --request POST \
--url https://api.fluid.app/api/v202604/orders/{order_id}/edits \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"operations": [
{
"type": "insert_item",
"variant_id": "abc123",
"quantity": 1,
"price": "29.99"
},
{
"type": "add_adjustment",
"amount": "-29.99",
"label": "Free gift credit",
"adjustment_type": "credit",
"source_type": "droplet",
"source_id": "free-gift-droplet"
}
]
}
'import requests
url = "https://api.fluid.app/api/v202604/orders/{order_id}/edits"
payload = { "operations": [
{
"type": "insert_item",
"variant_id": "abc123",
"quantity": 1,
"price": "29.99"
},
{
"type": "add_adjustment",
"amount": "-29.99",
"label": "Free gift credit",
"adjustment_type": "credit",
"source_type": "droplet",
"source_id": "free-gift-droplet"
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
operations: [
{type: 'insert_item', variant_id: 'abc123', quantity: 1, price: '29.99'},
{
type: 'add_adjustment',
amount: '-29.99',
label: 'Free gift credit',
adjustment_type: 'credit',
source_type: 'droplet',
source_id: 'free-gift-droplet'
}
]
})
};
fetch('https://api.fluid.app/api/v202604/orders/{order_id}/edits', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.fluid.app/api/v202604/orders/{order_id}/edits",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'operations' => [
[
'type' => 'insert_item',
'variant_id' => 'abc123',
'quantity' => 1,
'price' => '29.99'
],
[
'type' => 'add_adjustment',
'amount' => '-29.99',
'label' => 'Free gift credit',
'adjustment_type' => 'credit',
'source_type' => 'droplet',
'source_id' => 'free-gift-droplet'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.fluid.app/api/v202604/orders/{order_id}/edits"
payload := strings.NewReader("{\n \"operations\": [\n {\n \"type\": \"insert_item\",\n \"variant_id\": \"abc123\",\n \"quantity\": 1,\n \"price\": \"29.99\"\n },\n {\n \"type\": \"add_adjustment\",\n \"amount\": \"-29.99\",\n \"label\": \"Free gift credit\",\n \"adjustment_type\": \"credit\",\n \"source_type\": \"droplet\",\n \"source_id\": \"free-gift-droplet\"\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.fluid.app/api/v202604/orders/{order_id}/edits")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"operations\": [\n {\n \"type\": \"insert_item\",\n \"variant_id\": \"abc123\",\n \"quantity\": 1,\n \"price\": \"29.99\"\n },\n {\n \"type\": \"add_adjustment\",\n \"amount\": \"-29.99\",\n \"label\": \"Free gift credit\",\n \"adjustment_type\": \"credit\",\n \"source_type\": \"droplet\",\n \"source_id\": \"free-gift-droplet\"\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.fluid.app/api/v202604/orders/{order_id}/edits")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"operations\": [\n {\n \"type\": \"insert_item\",\n \"variant_id\": \"abc123\",\n \"quantity\": 1,\n \"price\": \"29.99\"\n },\n {\n \"type\": \"add_adjustment\",\n \"amount\": \"-29.99\",\n \"label\": \"Free gift credit\",\n \"adjustment_type\": \"credit\",\n \"source_type\": \"droplet\",\n \"source_id\": \"free-gift-droplet\"\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"order": {
"id": 90210,
"order_number": "1001",
"status": "complete",
"currency_code": "USD",
"current_subtotal": "129.99",
"current_discount": "0.00",
"current_adjustment_total": "-29.99",
"current_amount": "100.00",
"adjustments": [
{
"id": 55,
"amount": "-29.99",
"label": "Free gift credit",
"adjustment_type": "credit",
"source_type": "droplet",
"source_id": "free-gift-droplet",
"created_at": "2026-04-01T12:00:00Z"
}
]
},
"status": 200,
"meta": {
"request_id": "018f2c1a-8b3a-7e6d-9f10-2a3b4c5d6e7f",
"timestamp": "2026-04-01T12:00:00Z"
}
}{
"error": {
"message": "<string>",
"details": {}
},
"status": 123,
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z"
}
}{
"message": "Invalid credentials."
}{
"message": "Not authorized."
}{
"error": {
"message": "<string>",
"details": {}
},
"status": 123,
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z"
}
}{
"error": {
"message": "<string>",
"details": {}
},
"status": 123,
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z"
}
}{
"error": {
"message": "<string>",
"details": {}
},
"status": 123,
"meta": {
"request_id": "<string>",
"timestamp": "2023-11-07T05:31:56Z"
}
}{
"status": "error",
"message": "The request was not processed. Retry it unchanged under the same Idempotency-Key."
}