order_edits

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 $X gift item plus a -$ 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.

POST

api

v202604

orders

{order_id}

edits

Atomically apply one or more edits to an existing order

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

Authorizations

Authorization

string

header

required

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

Idempotency-Key

string

Optional client-generated key (UUID recommended) that the server uses to deduplicate retries. The first request with a given key executes normally; subsequent requests with the same key return the cached response with X-Idempotent-Replayed: true for 24 hours. A concurrent retry while the first is still in flight returns HTTP 409. The cache is scoped to the authenticated company.

Maximum string length: 255

Path Parameters

order_id

integer

required

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

application/json

operations

object[]

required

One or more edit operations to apply atomically. The whole transaction commits or rolls back together.

Minimum array length: 1

Show child attributes

expected_updated_at

string<date-time>

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.

order

object

required

The edited order, including the eight recalculated current_* totals and its adjustments.

Show child attributes

status

integer

required

HTTP status code, repeated in the body (200 on success).

meta

object

required

Response metadata (request_id and timestamp).

Show child attributes

Validate an Apple Pay merchant session

Dry-run an edit and return the would-be order shape

Atomically apply one or more edits to an existing order

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

Overview

Task guides

Endpoints

Auth endpoints

Checkout endpoints

Public SDK endpoints

Payment gateway endpoints

Cart payment endpoints

Commerce endpoints

Webhooks endpoints

Atomically apply one or more edits to an existing order

Authorizations

Headers

Path Parameters

Body

Response