API

Orders operations

Escrowed orders, payments, delivery, acceptance and disputes.

Escrowed orders, payments, delivery, acceptance and disputes. Paths are relative to https://reuseforge.com/api/v1.

Operations in this area
Operation	Method	Path
List your orders	`GET`	`/orders`
Create an order	`POST`	`/orders`
Get an order	`GET`	`/orders/{order_id}`
Fund an order	`POST`	`/orders/{order_id}/pay`
Cancel an unpaid order	`POST`	`/orders/{order_id}/cancel`
Deliver sold items (seller)	`POST`	`/orders/{order_id}/deliver`
Accept delivery and release escrow	`POST`	`/orders/{order_id}/accept`
Dispute delivered items	`POST`	`/orders/{order_id}/dispute`
Refund an item (seller)	`POST`	`/orders/{order_id}/items/{item_id}/refund`
Resolve a dispute (arbiter)	`POST`	`/orders/{order_id}/items/{item_id}/resolve`
List payouts	`GET`	`/payouts`
Seller earnings summary	`GET`	`/earnings`

List your orders

GET /orders Enabled on reuseforge.com

Orders you bought (role=buyer, default) or sold (role=seller, only the order items you sell are shown). Newest first.

List your orders: facts
Property	Value
Operation ID	`list_orders`
Authentication	Bearer token holding `orders:read`
Rate tier	`read`: 60/min per IP anonymous, 600/min per token with a token
Python SDK	`client.list_orders(...)`
JavaScript SDK	`client.listOrders(...)`
CLI	`rf orders list`
MCP tool	`list_orders`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

List your orders: parameters
Name	In	Type	Required	Description
`role`	query	`string: buyer, seller`	no	Default `"buyer"`.
`state`	query	`OrderState`	no
`cursor`	query	`string`	no	Opaque cursor from the previous page's `next_cursor`.
`limit`	query	`integer`	no	Page size. Default `30`.

Responses

List your orders: responses
Status	Meaning	Body
200 OK	A page of orders.	`application/json`: `OrderPage`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl 'https://reuseforge.com/api/v1/orders' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN"

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

for entry in client.list_orders():  # iterating fetches further pages on demand
    print(entry["id"])

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

for await (const entry of client.listOrders()) {  // iterating fetches further pages on demand
  console.log(entry.id);
}

CLI

bash

rf orders list

# rf orders list [options]
# all options: rf orders list --help

Response 200 OK:

json

{
  "data": [
    {
      "id": "ord_tqjv5mw3k2na",
      "object": "order",
      "state": "settled",
      "buyer": {
        "id": "acc_samdevuser22",
        "type": "user",
        "handle": "samdev",
        "display_name": "Sam Okafor",
        "verified": false,
        "avatar_url": ""
      },
      "items": [
        {
          "item_id": "itm_ragharness22",
          "item": "janedoe/invoice-rag-harness",
          "title": "Invoice RAG harness",
          "version": "0.9.2",
          "seller": {
            "id": "acc_janedoeuser2",
            "type": "user",
            "handle": "janedoe",
            "display_name": "Jane Doe",
            "verified": false,
            "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
          },
          "state": "released",
          "price_cents": 1200,
          "fee_cents": 12,
          "seller_amount_cents": 1188,
          "project_id": null,
          "delivery": {
            "delivered_at": "2026-11-03T10:08:30Z",
            "access": {
              "type": "item_version",
              "version": "0.9.2"
            },
            "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c"
          },
          "deliver_by": "2026-11-10T10:08:00Z",
          "accept_by": "2026-11-10T10:08:30Z",
          "dispute": null,
          "resolution": null,
          "release_reason": "accepted"
        }
      ],
      "subtotal_cents": 1200,
      "fee_bps": 100,
      "fee_cents": 12,
      "total_cents": 1200,
      "currency": "USD",
      "payment": {
        "rail": "base-usdc",
        "network": "base-sepolia",
        "asset": "USDC",
        "status": "confirmed",
        "amount_cents": 1200,
        "amount_atomic": "12000000",
        "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
        "memo": null,
        "uri": null,
        "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b",
        "confirmations": 3,
        "required_confirmations": 3,
        "expires_at": null,
        "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
        "simulated": false
      },
      "plan_id": "pln_goalinvoice2",
      "accept_window_seconds": 604800,
      "deliver_window_seconds": 604800,
      "funded_at": "2026-11-03T10:07:12Z",
      "settled_at": "2026-11-03T11:20:45Z",
      "payouts": [
        {
          "id": "pyo_sellerpay222",
          "object": "payout",
          "order_id": "ord_tqjv5mw3k2na",
          "item_id": "itm_ragharness22",
          "kind": "seller",
          "recipient": {
            "id": "acc_janedoeuser2",
            "type": "user",
            "handle": "janedoe",
            "display_name": "Jane Doe",
            "verified": false,
            "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
          },
          "address": "0xA11cE0000000000000000000000000000000b0b2",
          "rail": "base-usdc",
          "amount_cents": 1188,
          "currency": "USD",
          "state": "sent",
          "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4",
          "sent_at": "2026-11-03T11:21:10Z",
          "project_id": null
        },
        {
          "id": "pyo_platformfee2",
          "object": "payout",
          "order_id": "ord_tqjv5mw3k2na",
          "item_id": "itm_ragharness22",
          "kind": "platform_fee",
          "recipient": null,
          "address": "0xFee0000000000000000000000000000000000001",
          "rail": "base-usdc",
          "amount_cents": 12,
          "currency": "USD",
          "state": "sent",
          "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4",
          "sent_at": "2026-11-03T11:21:10Z",
          "project_id": null
        }
      ],
      "next_actions": [],
      "created_at": "2026-11-03T10:05:00Z",
      "updated_at": "2026-11-03T11:21:10Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Create an order

POST /orders Enabled on reuseforge.com

Quotes an order for paid items, either from a plan (plan_id, optional option; the plan's paid_items are ordered) or from an explicit items list. Free items never need an order. The order starts awaiting_payment with a payment object telling the buyer where to send money; prices, the fee rate and the windows are snapshotted and never change afterwards. The quote expires at payment.expires_at.

The fee (fee_bps, default 100 = 1%) is deducted from the seller's proceeds at release; the buyer pays total_cents, which equals the sum of the item prices. Idempotency-Key is required.

Create an order: facts
Property	Value
Operation ID	`create_order`
Authentication	Bearer token holding `orders:create`
Rate tier	`payments`: not allowed anonymous, 30/min per token with a token
Idempotency	`Idempotency-Key` header, required. Money moves here, so it is not optional.
Python SDK	`client.create_order(...)`
JavaScript SDK	`client.createOrder(...)`
CLI	`rf orders create`
MCP tool	`create_order`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Create an order: parameters
Name	In	Type	Required	Description
`Idempotency-Key`	header	`string`	yes	Required here because the call moves or commits money. Same semantics as the optional header; omitting it returns 400 `idempotency_key_required`.

Request body

application/json, required, schema OrderCreate

Create an order: request fields
Field	Type	Required	Description
`plan_id`	`string`	no
`option`	`integer`	no	Pareto option to order. Defaults to the plan's recommended option.
`items`	array of `OrderItemInput`	no
`rail`	`PaymentRail`	no	Open set. Known: `simulated`, `base-usdc`, `base-usdt`, `btc`. Python nodes also use `usdc-base` and `usdt-ethereum`.
`wallet`	`string`	no	Buyer wallet address used for fund verification and as the default refund address.
`refund_address`	`string`	no
`accept_window_days`	`number`	no	Default `7`.
`deliver_window_days`	`number`	no	Default `7`.

Another body: Order specific items

json

{
  "items": [
    {
      "item": "janedoe/invoice-rag-harness",
      "version": "0.9.2"
    }
  ],
  "rail": "simulated",
  "accept_window_days": 7
}

Responses

Create an order: responses
Status	Meaning	Body
201 Created	The quoted order.	`application/json`: `Order`
400	The request is malformed (bad JSON, unknown or mistyped parameter, invalid cursor).	`Problem`. Codes: `invalid_request`, `invalid_json`, `invalid_parameter`, `invalid_cursor`, `idempotency_key_required`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
409	The request conflicts with current state (duplicate resource, wrong lifecycle state, idempotency conflict).	`Problem`. Codes: `conflict`, `already_exists`, `invalid_state`, `idempotency_in_progress`
410	The resource existed and is permanently unavailable (retracted item, expired plan).	`Problem`. Codes: `gone`, `plan_expired`
422	The body is well-formed JSON but invalid (`validation_failed` with per-field `errors`), or a business rule rejects it (`payment_invalid`, `webhook_url_forbidden`, `idempotency_key_reuse`).	`Problem`. Codes: `validation_failed`, `payment_invalid`, `rail_unsupported`, `idempotency_key_reuse`, `webhook_url_forbidden`, `invalid_signature`, `integrity_mismatch`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl -X POST 'https://reuseforge.com/api/v1/orders' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "plan_id": "pln_goalinvoice2",
  "rail": "base-usdc",
  "wallet": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7"
}'

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.create_order(
    plan_id="pln_goalinvoice2",
    rail="base-usdc",
    wallet="0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
)
print(result["id"])

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.createOrder({
  plan_id: "pln_goalinvoice2",
  rail: "base-usdc",
  wallet: "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
});
console.log(result.id);

CLI

bash

rf orders create --plan pln_goalinvoice2 --rail base-usdc --wallet 0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7

# rf orders create [options]
# all options: rf orders create --help

Response 201 Created:

json

{
  "id": "ord_tqjv5mw3k2na",
  "object": "order",
  "state": "awaiting_payment",
  "buyer": {
    "id": "acc_samdevuser22",
    "type": "user",
    "handle": "samdev",
    "display_name": "Sam Okafor",
    "verified": false,
    "avatar_url": ""
  },
  "items": [
    {
      "item_id": "itm_ragharness22",
      "item": "janedoe/invoice-rag-harness",
      "title": "Invoice RAG harness",
      "version": "0.9.2",
      "seller": {
        "id": "acc_janedoeuser2",
        "type": "user",
        "handle": "janedoe",
        "display_name": "Jane Doe",
        "verified": false,
        "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
      },
      "state": "pending",
      "price_cents": 1200,
      "fee_cents": 12,
      "seller_amount_cents": 1188,
      "project_id": null,
      "delivery": null,
      "deliver_by": null,
      "accept_by": null,
      "dispute": null,
      "resolution": null,
      "release_reason": null
    }
  ],
  "subtotal_cents": 1200,
  "fee_bps": 100,
  "fee_cents": 12,
  "total_cents": 1200,
  "currency": "USD",
  "payment": {
    "rail": "base-usdc",
    "network": "base-sepolia",
    "asset": "USDC",
    "status": "awaiting_payment",
    "amount_cents": 1200,
    "amount_atomic": "12000000",
    "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
    "memo": null,
    "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000",
    "tx_ref": null,
    "confirmations": 0,
    "required_confirmations": 3,
    "expires_at": "2026-11-03T11:05:00Z",
    "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
    "simulated": false
  },
  "plan_id": "pln_goalinvoice2",
  "accept_window_seconds": 604800,
  "deliver_window_seconds": 604800,
  "funded_at": null,
  "settled_at": null,
  "payouts": [],
  "next_actions": [
    {
      "type": "send_payment",
      "description": "Transfer 12.00 USDC on Base Sepolia to the escrow contract, then call pay_order with the transaction hash.",
      "chain_id": 84532,
      "to": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "data": null,
      "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000"
    }
  ],
  "created_at": "2026-11-03T10:05:00Z",
  "updated_at": "2026-11-03T10:05:00Z"
}

Get an order

GET /orders/{order_id} Enabled on reuseforge.com

Buyers see the whole order. A seller sees only the items they sell. Time-based transitions (delivery deadline, acceptance window) are applied when an order is read, so the state is always current.

Get an order: facts
Property	Value
Operation ID	`get_order`
Authentication	Bearer token holding `orders:read`
Rate tier	`read`: 60/min per IP anonymous, 600/min per token with a token
Python SDK	`client.get_order(...)`
JavaScript SDK	`client.getOrder(...)`
CLI	`rf orders get`
MCP tool	`get_order`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Get an order: parameters
Name	In	Type	Required	Description
`order_id`	path	`string`	yes

Responses

Get an order: responses
Status	Meaning	Body
200 OK	The order.	`application/json`: `Order`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl 'https://reuseforge.com/api/v1/orders/ord_tqjv5mw3k2na' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN"

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.get_order("ord_tqjv5mw3k2na")
print(result["id"])

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.getOrder("ord_tqjv5mw3k2na");
console.log(result.id);

CLI

bash

rf orders get ord_tqjv5mw3k2na

# rf orders get <order_id>
# all options: rf orders get --help

Response 200 OK:

json

{
  "id": "ord_tqjv5mw3k2na",
  "object": "order",
  "state": "funded",
  "buyer": {
    "id": "acc_samdevuser22",
    "type": "user",
    "handle": "samdev",
    "display_name": "Sam Okafor",
    "verified": false,
    "avatar_url": ""
  },
  "items": [
    {
      "item_id": "itm_ragharness22",
      "item": "janedoe/invoice-rag-harness",
      "title": "Invoice RAG harness",
      "version": "0.9.2",
      "seller": {
        "id": "acc_janedoeuser2",
        "type": "user",
        "handle": "janedoe",
        "display_name": "Jane Doe",
        "verified": false,
        "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
      },
      "state": "delivered",
      "price_cents": 1200,
      "fee_cents": 12,
      "seller_amount_cents": 1188,
      "project_id": null,
      "delivery": {
        "delivered_at": "2026-11-03T10:08:30Z",
        "access": {
          "type": "item_version",
          "version": "0.9.2"
        },
        "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c"
      },
      "deliver_by": "2026-11-10T10:08:00Z",
      "accept_by": "2026-11-10T10:08:30Z",
      "dispute": null,
      "resolution": null,
      "release_reason": null
    }
  ],
  "subtotal_cents": 1200,
  "fee_bps": 100,
  "fee_cents": 12,
  "total_cents": 1200,
  "currency": "USD",
  "payment": {
    "rail": "base-usdc",
    "network": "base-sepolia",
    "asset": "USDC",
    "status": "confirmed",
    "amount_cents": 1200,
    "amount_atomic": "12000000",
    "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
    "memo": null,
    "uri": null,
    "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b",
    "confirmations": 3,
    "required_confirmations": 3,
    "expires_at": null,
    "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
    "simulated": false
  },
  "plan_id": "pln_goalinvoice2",
  "accept_window_seconds": 604800,
  "deliver_window_seconds": 604800,
  "funded_at": "2026-11-03T10:07:12Z",
  "settled_at": null,
  "payouts": [],
  "next_actions": [
    {
      "type": "review_delivery",
      "description": "Test the delivered item, then call accept_order to release payment or dispute_order before 2026-11-10T10:08:30Z."
    }
  ],
  "created_at": "2026-11-03T10:05:00Z",
  "updated_at": "2026-11-03T10:08:30Z"
}

Fund an order

POST /orders/{order_id}/pay Enabled on reuseforge.com

Tells the platform the buyer has paid and asks it to verify. On a real rail send the transaction hash (tx_ref); the platform checks the chain (amount, token, escrow address, confirmations). On the simulated rail send an empty body and the platform books a test deposit; simulated funds are never real money.

Returns 200 with state: funded once the deposit has enough confirmations, or 202 with payment.status: pending_confirmations; poll get_order or wait for order.funded. The token spend limit (spend_limit_cents) is enforced here and the amount is counted only on success. Idempotency-Key is required, so a retry after a timeout can never double-count a payment.

Fund an order: facts
Property	Value
Operation ID	`pay_order`
Authentication	Bearer token holding `orders:pay`
Rate tier	`payments`: not allowed anonymous, 30/min per token with a token
Idempotency	`Idempotency-Key` header, required. Money moves here, so it is not optional.
Python SDK	`client.pay_order(...)`
JavaScript SDK	`client.payOrder(...)`
CLI	`rf orders pay`
MCP tool	`pay_order`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Fund an order: parameters
Name	In	Type	Required	Description
`order_id`	path	`string`	yes
`Idempotency-Key`	header	`string`	yes	Required here because the call moves or commits money. Same semantics as the optional header; omitting it returns 400 `idempotency_key_required`.

Request body

application/json, optional, schema PayOrder

Fund an order: request fields
Field	Type	Required	Description
`tx_ref`	`string`	no	Transaction hash. Required on real rails, ignored on `simulated`.

Another body: Simulated rail

json

{}

Responses

Fund an order: responses
Status	Meaning	Body
200 OK	Funded.	`application/json`: `Order`
202 Accepted	Payment seen but not final; confirmations pending.	`application/json`: `Order`
400	The request is malformed (bad JSON, unknown or mistyped parameter, invalid cursor).	`Problem`. Codes: `invalid_request`, `invalid_json`, `invalid_parameter`, `invalid_cursor`, `idempotency_key_required`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
409	The request conflicts with current state (duplicate resource, wrong lifecycle state, idempotency conflict).	`Problem`. Codes: `conflict`, `already_exists`, `invalid_state`, `idempotency_in_progress`
422	The body is well-formed JSON but invalid (`validation_failed` with per-field `errors`), or a business rule rejects it (`payment_invalid`, `webhook_url_forbidden`, `idempotency_key_reuse`).	`Problem`. Codes: `validation_failed`, `payment_invalid`, `rail_unsupported`, `idempotency_key_reuse`, `webhook_url_forbidden`, `invalid_signature`, `integrity_mismatch`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`
502	An upstream source (connector, chain RPC) failed or timed out. Retry with backoff.	`Problem`. Codes: `upstream_error`

Example

curl

bash

curl -X POST 'https://reuseforge.com/api/v1/orders/ord_tqjv5mw3k2na/pay' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b"
}'

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.pay_order(
    "ord_tqjv5mw3k2na",
    tx_ref="0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b",
)
print(result["id"])

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.payOrder("ord_tqjv5mw3k2na", { tx_ref: "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b" });
console.log(result.id);

CLI

bash

rf orders pay ord_tqjv5mw3k2na --tx 0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b

# rf orders pay <order_id> [options]
# all options: rf orders pay --help

Response 200 OK:

json

{
  "id": "ord_tqjv5mw3k2na",
  "object": "order",
  "state": "funded",
  "buyer": {
    "id": "acc_samdevuser22",
    "type": "user",
    "handle": "samdev",
    "display_name": "Sam Okafor",
    "verified": false,
    "avatar_url": ""
  },
  "items": [
    {
      "item_id": "itm_ragharness22",
      "item": "janedoe/invoice-rag-harness",
      "title": "Invoice RAG harness",
      "version": "0.9.2",
      "seller": {
        "id": "acc_janedoeuser2",
        "type": "user",
        "handle": "janedoe",
        "display_name": "Jane Doe",
        "verified": false,
        "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
      },
      "state": "pending",
      "price_cents": 1200,
      "fee_cents": 12,
      "seller_amount_cents": 1188,
      "project_id": null,
      "delivery": null,
      "deliver_by": null,
      "accept_by": null,
      "dispute": null,
      "resolution": null,
      "release_reason": null
    }
  ],
  "subtotal_cents": 1200,
  "fee_bps": 100,
  "fee_cents": 12,
  "total_cents": 1200,
  "currency": "USD",
  "payment": {
    "rail": "base-usdc",
    "network": "base-sepolia",
    "asset": "USDC",
    "status": "confirmed",
    "amount_cents": 1200,
    "amount_atomic": "12000000",
    "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
    "memo": null,
    "uri": null,
    "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b",
    "confirmations": 3,
    "required_confirmations": 3,
    "expires_at": null,
    "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
    "simulated": false
  },
  "plan_id": "pln_goalinvoice2",
  "accept_window_seconds": 604800,
  "deliver_window_seconds": 604800,
  "funded_at": "2026-11-03T10:07:12Z",
  "settled_at": null,
  "payouts": [],
  "next_actions": [],
  "created_at": "2026-11-03T10:05:00Z",
  "updated_at": "2026-11-03T10:07:12Z"
}

Cancel an unpaid order

POST /orders/{order_id}/cancel Enabled on reuseforge.com

Only orders still awaiting_payment can be cancelled. Idempotent.

Cancel an unpaid order: facts
Property	Value
Operation ID	`cancel_order`
Authentication	Bearer token holding `orders:create`
Rate tier	`write`: not allowed anonymous, 120/min per token with a token
Idempotency	`Idempotency-Key` header, optional. The SDKs and the CLI send one for you.
Python SDK	`client.cancel_order(...)`
JavaScript SDK	`client.cancelOrder(...)`
CLI	`rf orders cancel`
MCP tool	`cancel_order`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Cancel an unpaid order: parameters
Name	In	Type	Required	Description
`order_id`	path	`string`	yes
`Idempotency-Key`	header	`string`	no	Client-chosen unique key (1 to 255 printable ASCII characters, a UUID is ideal). A repeat of the same request with the same key within 24 hours returns the first response with `Idempotent-Replayed: true`. The same key with a different body returns 422 `idempotency_key_reuse`; a repeat while the first call is still running returns 409 `idempotency_in_progress`.

Responses

Cancel an unpaid order: responses
Status	Meaning	Body
200 OK	The cancelled order.	`application/json`: `Order`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
409	The request conflicts with current state (duplicate resource, wrong lifecycle state, idempotency conflict).	`Problem`. Codes: `conflict`, `already_exists`, `invalid_state`, `idempotency_in_progress`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl -X POST 'https://reuseforge.com/api/v1/orders/ord_tqjv5mw3k2na/cancel' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.cancel_order("ord_tqjv5mw3k2na")
print(result["id"])

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.cancelOrder("ord_tqjv5mw3k2na");
console.log(result.id);

CLI

bash

rf orders cancel ord_tqjv5mw3k2na

# rf orders cancel <order_id>
# all options: rf orders cancel --help

Response 200 OK:

json

{
  "id": "ord_tqjv5mw3k2na",
  "object": "order",
  "state": "cancelled",
  "buyer": {
    "id": "acc_samdevuser22",
    "type": "user",
    "handle": "samdev",
    "display_name": "Sam Okafor",
    "verified": false,
    "avatar_url": ""
  },
  "items": [
    {
      "item_id": "itm_ragharness22",
      "item": "janedoe/invoice-rag-harness",
      "title": "Invoice RAG harness",
      "version": "0.9.2",
      "seller": {
        "id": "acc_janedoeuser2",
        "type": "user",
        "handle": "janedoe",
        "display_name": "Jane Doe",
        "verified": false,
        "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
      },
      "state": "pending",
      "price_cents": 1200,
      "fee_cents": 12,
      "seller_amount_cents": 1188,
      "project_id": null,
      "delivery": null,
      "deliver_by": null,
      "accept_by": null,
      "dispute": null,
      "resolution": null,
      "release_reason": null
    }
  ],
  "subtotal_cents": 1200,
  "fee_bps": 100,
  "fee_cents": 12,
  "total_cents": 1200,
  "currency": "USD",
  "payment": {
    "rail": "base-usdc",
    "network": "base-sepolia",
    "asset": "USDC",
    "status": "awaiting_payment",
    "amount_cents": 1200,
    "amount_atomic": "12000000",
    "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
    "memo": null,
    "uri": "ethereum:0x036CbD53842c5426634e7929541eC2318f3dCF7e@84532/transfer?address=0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2&uint256=12000000",
    "tx_ref": null,
    "confirmations": 0,
    "required_confirmations": 3,
    "expires_at": "2026-11-03T11:05:00Z",
    "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
    "simulated": false
  },
  "plan_id": "pln_goalinvoice2",
  "accept_window_seconds": 604800,
  "deliver_window_seconds": 604800,
  "funded_at": null,
  "settled_at": null,
  "payouts": [],
  "next_actions": [],
  "created_at": "2026-11-03T10:05:00Z",
  "updated_at": "2026-11-03T10:09:00Z"
}

Deliver sold items (seller)

POST /orders/{order_id}/deliver Enabled on reuseforge.com

Seller side. Marks items of a funded order as delivered and starts the buyer's acceptance window. Items hosted on ReuseForge (access.type: item_version) are delivered automatically when the order is funded; call this for items whose content lives elsewhere (url, message). Fires order.delivered when every item is delivered. Deliveries are accepted until deliver_by; after that the buyer is refunded.

Deliver sold items (seller): facts
Property	Value
Operation ID	`deliver_order`
Authentication	Bearer token holding `orders:create`
Rate tier	`write`: not allowed anonymous, 120/min per token with a token
Idempotency	`Idempotency-Key` header, optional. The SDKs and the CLI send one for you.
Python SDK	`client.deliver_order(...)`
JavaScript SDK	`client.deliverOrder(...)`
CLI	`rf orders deliver`
MCP tool	`deliver_order`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Deliver sold items (seller): parameters
Name	In	Type	Required	Description
`order_id`	path	`string`	yes
`Idempotency-Key`	header	`string`	no	Client-chosen unique key (1 to 255 printable ASCII characters, a UUID is ideal). A repeat of the same request with the same key within 24 hours returns the first response with `Idempotent-Replayed: true`. The same key with a different body returns 422 `idempotency_key_reuse`; a repeat while the first call is still running returns 409 `idempotency_in_progress`.

Request body

application/json, required, schema DeliverOrder

Deliver sold items (seller): request fields
Field	Type	Required	Description
`items`	array of `object`	yes
`items[].item_id`	`string`	yes
`items[].access`	`DeliveryAccess`	yes
`items[].content_hash`	`ContentHash`	no	SHA-256 over the text made of one line `<sha256 of file bytes> <path>` per file (two spaces, `\n` after each line), files sorted by path in UTF-8 byte order. Identical to the output of `sha256sum` over the files, so it can be recomputed with standard tools.

Responses

Deliver sold items (seller): responses
Status	Meaning	Body
200 OK	The order with the delivered items.	`application/json`: `Order`
400	The request is malformed (bad JSON, unknown or mistyped parameter, invalid cursor).	`Problem`. Codes: `invalid_request`, `invalid_json`, `invalid_parameter`, `invalid_cursor`, `idempotency_key_required`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
409	The request conflicts with current state (duplicate resource, wrong lifecycle state, idempotency conflict).	`Problem`. Codes: `conflict`, `already_exists`, `invalid_state`, `idempotency_in_progress`
422	The body is well-formed JSON but invalid (`validation_failed` with per-field `errors`), or a business rule rejects it (`payment_invalid`, `webhook_url_forbidden`, `idempotency_key_reuse`).	`Problem`. Codes: `validation_failed`, `payment_invalid`, `rail_unsupported`, `idempotency_key_reuse`, `webhook_url_forbidden`, `invalid_signature`, `integrity_mismatch`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl -X POST 'https://reuseforge.com/api/v1/orders/ord_tqjv5mw3k2na/deliver' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "item_id": "itm_ragharness22",
      "access": {
        "type": "item_version",
        "version": "0.9.2"
      },
      "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c"
    }
  ]
}'

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.deliver_order(
    "ord_tqjv5mw3k2na",
    items=[
            {
                "item_id": "itm_ragharness22",
                "access": {"type": "item_version", "version": "0.9.2"},
                "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c",
            },
        ],
)
print(result["id"])

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.deliverOrder("ord_tqjv5mw3k2na", {
  items: [
    {
      item_id: "itm_ragharness22",
      access: { type: "item_version", version: "0.9.2" },
      content_hash: "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c",
    },
  ],
});
console.log(result.id);

CLI

bash

rf orders deliver ord_tqjv5mw3k2na

# rf orders deliver <order_id> [options]
# all options: rf orders deliver --help

Response 200 OK:

json

{
  "id": "ord_tqjv5mw3k2na",
  "object": "order",
  "state": "funded",
  "buyer": {
    "id": "acc_samdevuser22",
    "type": "user",
    "handle": "samdev",
    "display_name": "Sam Okafor",
    "verified": false,
    "avatar_url": ""
  },
  "items": [
    {
      "item_id": "itm_ragharness22",
      "item": "janedoe/invoice-rag-harness",
      "title": "Invoice RAG harness",
      "version": "0.9.2",
      "seller": {
        "id": "acc_janedoeuser2",
        "type": "user",
        "handle": "janedoe",
        "display_name": "Jane Doe",
        "verified": false,
        "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
      },
      "state": "delivered",
      "price_cents": 1200,
      "fee_cents": 12,
      "seller_amount_cents": 1188,
      "project_id": null,
      "delivery": {
        "delivered_at": "2026-11-03T10:08:30Z",
        "access": {
          "type": "item_version",
          "version": "0.9.2"
        },
        "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c"
      },
      "deliver_by": "2026-11-10T10:08:00Z",
      "accept_by": "2026-11-10T10:08:30Z",
      "dispute": null,
      "resolution": null,
      "release_reason": null
    }
  ],
  "subtotal_cents": 1200,
  "fee_bps": 100,
  "fee_cents": 12,
  "total_cents": 1200,
  "currency": "USD",
  "payment": {
    "rail": "base-usdc",
    "network": "base-sepolia",
    "asset": "USDC",
    "status": "confirmed",
    "amount_cents": 1200,
    "amount_atomic": "12000000",
    "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
    "memo": null,
    "uri": null,
    "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b",
    "confirmations": 3,
    "required_confirmations": 3,
    "expires_at": null,
    "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
    "simulated": false
  },
  "plan_id": "pln_goalinvoice2",
  "accept_window_seconds": 604800,
  "deliver_window_seconds": 604800,
  "funded_at": "2026-11-03T10:07:12Z",
  "settled_at": null,
  "payouts": [],
  "next_actions": [
    {
      "type": "review_delivery",
      "description": "Test the delivered item, then call accept_order to release payment or dispute_order before 2026-11-10T10:08:30Z."
    }
  ],
  "created_at": "2026-11-03T10:05:00Z",
  "updated_at": "2026-11-03T10:08:30Z"
}

Accept delivery and release escrow

POST /orders/{order_id}/accept Enabled on reuseforge.com

Buyer confirms satisfaction; escrow for the delivered items is released to the sellers (minus the platform fee). Irreversible. Requires the explicit orders:accept scope, which is never part of default tokens, so an autonomous agent cannot confirm satisfaction on its own unless a human granted it. The body must contain confirm: true. Without item_ids every delivered item is accepted. If the buyer stays silent, the acceptance window expiring releases the funds automatically (release_reason: window_expired). On self-custody rails the response may carry a sign_transaction entry in next_actions that the buyer's wallet must sign.

Accept delivery and release escrow: facts
Property	Value
Operation ID	`accept_order`
Authentication	Bearer token holding `orders:accept`
Rate tier	`payments`: not allowed anonymous, 30/min per token with a token
Idempotency	`Idempotency-Key` header, optional. The SDKs and the CLI send one for you.
Python SDK	`client.accept_order(...)`
JavaScript SDK	`client.acceptOrder(...)`
CLI	`rf orders accept`
MCP tool	`accept_order`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Accept delivery and release escrow: parameters
Name	In	Type	Required	Description
`order_id`	path	`string`	yes
`Idempotency-Key`	header	`string`	no	Client-chosen unique key (1 to 255 printable ASCII characters, a UUID is ideal). A repeat of the same request with the same key within 24 hours returns the first response with `Idempotent-Replayed: true`. The same key with a different body returns 422 `idempotency_key_reuse`; a repeat while the first call is still running returns 409 `idempotency_in_progress`.

Request body

application/json, required, schema AcceptOrder

Accept delivery and release escrow: request fields
Field	Type	Required	Description
`confirm`	`boolean: true`	yes	Must be true. A deliberate speed bump.
`item_ids`	array of `string`	no	Subset to accept. Default is every delivered item.
`note`	`string`	no

Responses

Accept delivery and release escrow: responses
Status	Meaning	Body
200 OK	Settled.	`application/json`: `Order`
400	The request is malformed (bad JSON, unknown or mistyped parameter, invalid cursor).	`Problem`. Codes: `invalid_request`, `invalid_json`, `invalid_parameter`, `invalid_cursor`, `idempotency_key_required`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
409	The request conflicts with current state (duplicate resource, wrong lifecycle state, idempotency conflict).	`Problem`. Codes: `conflict`, `already_exists`, `invalid_state`, `idempotency_in_progress`
422	The body is well-formed JSON but invalid (`validation_failed` with per-field `errors`), or a business rule rejects it (`payment_invalid`, `webhook_url_forbidden`, `idempotency_key_reuse`).	`Problem`. Codes: `validation_failed`, `payment_invalid`, `rail_unsupported`, `idempotency_key_reuse`, `webhook_url_forbidden`, `invalid_signature`, `integrity_mismatch`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl -X POST 'https://reuseforge.com/api/v1/orders/ord_tqjv5mw3k2na/accept' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "confirm": true,
  "note": "Tested against 400 invoices."
}'

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.accept_order(
    "ord_tqjv5mw3k2na",
    confirm=True,
    note="Tested against 400 invoices.",
)
print(result["id"])

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.acceptOrder("ord_tqjv5mw3k2na", { confirm: true, note: "Tested against 400 invoices." });
console.log(result.id);

CLI

bash

rf orders accept ord_tqjv5mw3k2na --note 'Tested against 400 invoices.'

# rf orders accept <order_id> [options]
# all options: rf orders accept --help

Response 200 OK:

json

{
  "id": "ord_tqjv5mw3k2na",
  "object": "order",
  "state": "settled",
  "buyer": {
    "id": "acc_samdevuser22",
    "type": "user",
    "handle": "samdev",
    "display_name": "Sam Okafor",
    "verified": false,
    "avatar_url": ""
  },
  "items": [
    {
      "item_id": "itm_ragharness22",
      "item": "janedoe/invoice-rag-harness",
      "title": "Invoice RAG harness",
      "version": "0.9.2",
      "seller": {
        "id": "acc_janedoeuser2",
        "type": "user",
        "handle": "janedoe",
        "display_name": "Jane Doe",
        "verified": false,
        "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
      },
      "state": "released",
      "price_cents": 1200,
      "fee_cents": 12,
      "seller_amount_cents": 1188,
      "project_id": null,
      "delivery": {
        "delivered_at": "2026-11-03T10:08:30Z",
        "access": {
          "type": "item_version",
          "version": "0.9.2"
        },
        "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c"
      },
      "deliver_by": "2026-11-10T10:08:00Z",
      "accept_by": "2026-11-10T10:08:30Z",
      "dispute": null,
      "resolution": null,
      "release_reason": "accepted"
    }
  ],
  "subtotal_cents": 1200,
  "fee_bps": 100,
  "fee_cents": 12,
  "total_cents": 1200,
  "currency": "USD",
  "payment": {
    "rail": "base-usdc",
    "network": "base-sepolia",
    "asset": "USDC",
    "status": "confirmed",
    "amount_cents": 1200,
    "amount_atomic": "12000000",
    "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
    "memo": null,
    "uri": null,
    "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b",
    "confirmations": 3,
    "required_confirmations": 3,
    "expires_at": null,
    "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
    "simulated": false
  },
  "plan_id": "pln_goalinvoice2",
  "accept_window_seconds": 604800,
  "deliver_window_seconds": 604800,
  "funded_at": "2026-11-03T10:07:12Z",
  "settled_at": "2026-11-03T11:20:45Z",
  "payouts": [
    {
      "id": "pyo_sellerpay222",
      "object": "payout",
      "order_id": "ord_tqjv5mw3k2na",
      "item_id": "itm_ragharness22",
      "kind": "seller",
      "recipient": {
        "id": "acc_janedoeuser2",
        "type": "user",
        "handle": "janedoe",
        "display_name": "Jane Doe",
        "verified": false,
        "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
      },
      "address": "0xA11cE0000000000000000000000000000000b0b2",
      "rail": "base-usdc",
      "amount_cents": 1188,
      "currency": "USD",
      "state": "sent",
      "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4",
      "sent_at": "2026-11-03T11:21:10Z",
      "project_id": null
    },
    {
      "id": "pyo_platformfee2",
      "object": "payout",
      "order_id": "ord_tqjv5mw3k2na",
      "item_id": "itm_ragharness22",
      "kind": "platform_fee",
      "recipient": null,
      "address": "0xFee0000000000000000000000000000000000001",
      "rail": "base-usdc",
      "amount_cents": 12,
      "currency": "USD",
      "state": "sent",
      "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4",
      "sent_at": "2026-11-03T11:21:10Z",
      "project_id": null
    }
  ],
  "next_actions": [],
  "created_at": "2026-11-03T10:05:00Z",
  "updated_at": "2026-11-03T11:21:10Z"
}

Dispute delivered items

POST /orders/{order_id}/dispute Enabled on reuseforge.com

Buyer freezes escrow for delivered (or overdue) items while an arbiter decides. Allowed inside the acceptance window. Needs only orders:create, so a restricted agent can always raise a problem even though it cannot release money.

Dispute delivered items: facts
Property	Value
Operation ID	`dispute_order`
Authentication	Bearer token holding `orders:create`
Rate tier	`write`: not allowed anonymous, 120/min per token with a token
Idempotency	`Idempotency-Key` header, optional. The SDKs and the CLI send one for you.
Python SDK	`client.dispute_order(...)`
JavaScript SDK	`client.disputeOrder(...)`
CLI	`rf orders dispute`
MCP tool	`dispute_order`
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Dispute delivered items: parameters
Name	In	Type	Required	Description
`order_id`	path	`string`	yes
`Idempotency-Key`	header	`string`	no	Client-chosen unique key (1 to 255 printable ASCII characters, a UUID is ideal). A repeat of the same request with the same key within 24 hours returns the first response with `Idempotent-Replayed: true`. The same key with a different body returns 422 `idempotency_key_reuse`; a repeat while the first call is still running returns 409 `idempotency_in_progress`.

Request body

application/json, required, schema DisputeOrder

Dispute delivered items: request fields
Field	Type	Required
`reason`	`string`	yes
`item_ids`	array of `string`	no
`evidence_urls`	array of `string (uri)`	no

Responses

Dispute delivered items: responses
Status	Meaning	Body
200 OK	The order with disputed items.	`application/json`: `Order`
400	The request is malformed (bad JSON, unknown or mistyped parameter, invalid cursor).	`Problem`. Codes: `invalid_request`, `invalid_json`, `invalid_parameter`, `invalid_cursor`, `idempotency_key_required`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
409	The request conflicts with current state (duplicate resource, wrong lifecycle state, idempotency conflict).	`Problem`. Codes: `conflict`, `already_exists`, `invalid_state`, `idempotency_in_progress`
422	The body is well-formed JSON but invalid (`validation_failed` with per-field `errors`), or a business rule rejects it (`payment_invalid`, `webhook_url_forbidden`, `idempotency_key_reuse`).	`Problem`. Codes: `validation_failed`, `payment_invalid`, `rail_unsupported`, `idempotency_key_reuse`, `webhook_url_forbidden`, `invalid_signature`, `integrity_mismatch`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl -X POST 'https://reuseforge.com/api/v1/orders/ord_tqjv5mw3k2na/dispute' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "The harness crashes on startup with the documented config (KeyError: embedder).",
  "evidence_urls": [
    "https://gist.github.com/samdev/0f1e2d3c4b5a69788776655443322110"
  ]
}'

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.dispute_order(
    "ord_tqjv5mw3k2na",
    reason="The harness crashes on startup with the documented config (KeyError: embedder).",
    evidence_urls=["https://gist.github.com/samdev/0f1e2d3c4b5a69788776655443322110"],
)
print(result["id"])

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.disputeOrder("ord_tqjv5mw3k2na", {
  reason: "The harness crashes on startup with the documented config (KeyError: embedder).",
  evidence_urls: ["https://gist.github.com/samdev/0f1e2d3c4b5a69788776655443322110"],
});
console.log(result.id);

CLI

bash

rf orders dispute ord_tqjv5mw3k2na --reason 'The harness crashes on startup with the documented config (KeyError: embedder).'

# rf orders dispute <order_id> [options]
# all options: rf orders dispute --help

Response 200 OK:

json

{
  "id": "ord_tqjv5mw3k2na",
  "object": "order",
  "state": "funded",
  "buyer": {
    "id": "acc_samdevuser22",
    "type": "user",
    "handle": "samdev",
    "display_name": "Sam Okafor",
    "verified": false,
    "avatar_url": ""
  },
  "items": [
    {
      "item_id": "itm_ragharness22",
      "item": "janedoe/invoice-rag-harness",
      "title": "Invoice RAG harness",
      "version": "0.9.2",
      "seller": {
        "id": "acc_janedoeuser2",
        "type": "user",
        "handle": "janedoe",
        "display_name": "Jane Doe",
        "verified": false,
        "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
      },
      "state": "disputed",
      "price_cents": 1200,
      "fee_cents": 12,
      "seller_amount_cents": 1188,
      "project_id": null,
      "delivery": {
        "delivered_at": "2026-11-03T10:08:30Z",
        "access": {
          "type": "item_version",
          "version": "0.9.2"
        },
        "content_hash": "sha256:5e9c1184f430924b3aa1ef77b4fb274c7cda4b1f458a9fe1ecbf203067971f1c"
      },
      "deliver_by": "2026-11-10T10:08:00Z",
      "accept_by": "2026-11-10T10:08:30Z",
      "dispute": {
        "reason": "The harness crashes on startup with the documented config (KeyError: embedder).",
        "opened_at": "2026-11-03T10:40:00Z"
      },
      "resolution": null,
      "release_reason": null
    }
  ],
  "subtotal_cents": 1200,
  "fee_bps": 100,
  "fee_cents": 12,
  "total_cents": 1200,
  "currency": "USD",
  "payment": {
    "rail": "base-usdc",
    "network": "base-sepolia",
    "asset": "USDC",
    "status": "confirmed",
    "amount_cents": 1200,
    "amount_atomic": "12000000",
    "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
    "memo": null,
    "uri": null,
    "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b",
    "confirmations": 3,
    "required_confirmations": 3,
    "expires_at": null,
    "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
    "simulated": false
  },
  "plan_id": "pln_goalinvoice2",
  "accept_window_seconds": 604800,
  "deliver_window_seconds": 604800,
  "funded_at": "2026-11-03T10:07:12Z",
  "settled_at": null,
  "payouts": [],
  "next_actions": [],
  "created_at": "2026-11-03T10:05:00Z",
  "updated_at": "2026-11-03T10:40:00Z"
}

Refund an item (seller)

POST /orders/{order_id}/items/{item_id}/refund Enabled on reuseforge.com

Seller voluntarily returns the whole price of one item to the buyer. Allowed while the item is pending, delivered or disputed. The platform fee is not charged on refunds.

Refund an item (seller): facts
Property	Value
Operation ID	`refund_order_item`
Authentication	Bearer token holding `orders:create`
Rate tier	`payments`: not allowed anonymous, 30/min per token with a token
Idempotency	`Idempotency-Key` header, optional. The SDKs and the CLI send one for you.
Python SDK	`client.refund_order_item(...)`
JavaScript SDK	`client.refundOrderItem(...)`
CLI	`rf orders refund`
MCP tool	`refund_order_item`
Deployments	reuseforge.com: enabled. Python node: not implemented (answers `501`).

Parameters

Refund an item (seller): parameters
Name	In	Type	Required	Description
`order_id`	path	`string`	yes
`item_id`	path	`string`	yes	The item id (`itm_...`) of a line in the order.
`Idempotency-Key`	header	`string`	no	Client-chosen unique key (1 to 255 printable ASCII characters, a UUID is ideal). A repeat of the same request with the same key within 24 hours returns the first response with `Idempotent-Replayed: true`. The same key with a different body returns 422 `idempotency_key_reuse`; a repeat while the first call is still running returns 409 `idempotency_in_progress`.

Request body

application/json, optional, schema RefundItem

Refund an item (seller): request fields
Field	Type	Required	Description
`note`	`string`	no

Responses

Refund an item (seller): responses
Status	Meaning	Body
200 OK	The order with the refunded item.	`application/json`: `Order`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
409	The request conflicts with current state (duplicate resource, wrong lifecycle state, idempotency conflict).	`Problem`. Codes: `conflict`, `already_exists`, `invalid_state`, `idempotency_in_progress`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl -X POST 'https://reuseforge.com/api/v1/orders/ord_tqjv5mw3k2na/items/itm_ragharness22/refund' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "note": "Refunded after a failed delivery."
}'

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.refund_order_item(
    "ord_tqjv5mw3k2na",
    "itm_ragharness22",
    note="Refunded after a failed delivery.",
)
print(result["id"])

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.refundOrderItem("ord_tqjv5mw3k2na", "itm_ragharness22", { note: "Refunded after a failed delivery." });
console.log(result.id);

CLI

bash

rf orders refund ord_tqjv5mw3k2na itm_ragharness22 --note 'Refunded after a failed delivery.'

# rf orders refund <order_id> <item_id> [options]
# all options: rf orders refund --help

Response 200 OK:

json

{
  "id": "ord_tqjv5mw3k2na",
  "object": "order",
  "state": "settled",
  "buyer": {
    "id": "acc_samdevuser22",
    "type": "user",
    "handle": "samdev",
    "display_name": "Sam Okafor",
    "verified": false,
    "avatar_url": ""
  },
  "items": [
    {
      "item_id": "itm_ragharness22",
      "item": "janedoe/invoice-rag-harness",
      "title": "Invoice RAG harness",
      "version": "0.9.2",
      "seller": {
        "id": "acc_janedoeuser2",
        "type": "user",
        "handle": "janedoe",
        "display_name": "Jane Doe",
        "verified": false,
        "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
      },
      "state": "refunded",
      "price_cents": 1200,
      "fee_cents": 0,
      "seller_amount_cents": 0,
      "project_id": null,
      "delivery": null,
      "deliver_by": "2026-11-10T10:08:00Z",
      "accept_by": null,
      "dispute": null,
      "resolution": {
        "seller_bps": 0,
        "refund_cents": 1200,
        "note": "Seller did not deliver before the deadline.",
        "resolved_at": "2026-11-10T10:09:00Z"
      },
      "release_reason": null
    }
  ],
  "subtotal_cents": 1200,
  "fee_bps": 100,
  "fee_cents": 0,
  "total_cents": 1200,
  "currency": "USD",
  "payment": {
    "rail": "base-usdc",
    "network": "base-sepolia",
    "asset": "USDC",
    "status": "confirmed",
    "amount_cents": 1200,
    "amount_atomic": "12000000",
    "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
    "memo": null,
    "uri": null,
    "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b",
    "confirmations": 3,
    "required_confirmations": 3,
    "expires_at": null,
    "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
    "simulated": false
  },
  "plan_id": "pln_goalinvoice2",
  "accept_window_seconds": 604800,
  "deliver_window_seconds": 604800,
  "funded_at": "2026-11-03T10:07:12Z",
  "settled_at": "2026-11-10T10:09:00Z",
  "payouts": [
    {
      "id": "pyo_buyerrefun22",
      "object": "payout",
      "order_id": "ord_tqjv5mw3k2na",
      "item_id": "itm_ragharness22",
      "kind": "refund",
      "recipient": {
        "id": "acc_samdevuser22",
        "type": "user",
        "handle": "samdev",
        "display_name": "Sam Okafor",
        "verified": false,
        "avatar_url": ""
      },
      "address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
      "rail": "base-usdc",
      "amount_cents": 1200,
      "currency": "USD",
      "state": "sent",
      "tx_ref": "0x4c1d9e7b2a6f08d35e9a1b7c4d2e6f80a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2",
      "sent_at": "2026-11-10T10:10:30Z",
      "project_id": null
    }
  ],
  "next_actions": [],
  "created_at": "2026-11-03T10:05:00Z",
  "updated_at": "2026-11-10T10:10:30Z"
}

Resolve a dispute (arbiter)

POST /orders/{order_id}/items/{item_id}/resolve Enabled on reuseforge.com

Platform arbiter splits a disputed item between seller and buyer. seller_bps is the seller's share of the item price in basis points (10000 = pay the seller everything, 0 = refund the buyer). Requires the admin scope on an admin account.

Resolve a dispute (arbiter): facts
Property	Value
Operation ID	`resolve_order_item`
Authentication	Bearer token holding `admin`
Rate tier	`payments`: not allowed anonymous, 30/min per token with a token
Idempotency	`Idempotency-Key` header, optional. The SDKs and the CLI send one for you.
Python SDK	`client.resolve_order_item(...)`
JavaScript SDK	`client.resolveOrderItem(...)`
CLI	`rf admin resolve`
MCP tool	not exposed as a tool
Deployments	reuseforge.com: enabled. Python node: implemented.

Parameters

Resolve a dispute (arbiter): parameters
Name	In	Type	Required	Description
`order_id`	path	`string`	yes
`item_id`	path	`string`	yes	The item id (`itm_...`) of a line in the order.
`Idempotency-Key`	header	`string`	no	Client-chosen unique key (1 to 255 printable ASCII characters, a UUID is ideal). A repeat of the same request with the same key within 24 hours returns the first response with `Idempotent-Replayed: true`. The same key with a different body returns 422 `idempotency_key_reuse`; a repeat while the first call is still running returns 409 `idempotency_in_progress`.

Request body

application/json, required, schema ResolveDispute

Resolve a dispute (arbiter): request fields
Field	Type	Required	Description
`seller_bps`	`integer`	yes
`note`	`string`	yes

Responses

Resolve a dispute (arbiter): responses
Status	Meaning	Body
200 OK	The order after resolution.	`application/json`: `Order`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
404	No such resource, or it is private and the caller may not know it exists.	`Problem`. Codes: `not_found`
409	The request conflicts with current state (duplicate resource, wrong lifecycle state, idempotency conflict).	`Problem`. Codes: `conflict`, `already_exists`, `invalid_state`, `idempotency_in_progress`
422	The body is well-formed JSON but invalid (`validation_failed` with per-field `errors`), or a business rule rejects it (`payment_invalid`, `webhook_url_forbidden`, `idempotency_key_reuse`).	`Problem`. Codes: `validation_failed`, `payment_invalid`, `rail_unsupported`, `idempotency_key_reuse`, `webhook_url_forbidden`, `invalid_signature`, `integrity_mismatch`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl -X POST 'https://reuseforge.com/api/v1/orders/ord_tqjv5mw3k2na/items/itm_ragharness22/resolve' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "seller_bps": 0,
  "note": "Seller did not deliver before the deadline."
}'

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.resolve_order_item(
    "ord_tqjv5mw3k2na",
    "itm_ragharness22",
    seller_bps=0,
    note="Seller did not deliver before the deadline.",
)
print(result["id"])

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.resolveOrderItem("ord_tqjv5mw3k2na", "itm_ragharness22", { seller_bps: 0, note: "Seller did not deliver before the deadline." });
console.log(result.id);

CLI

bash

rf admin resolve ord_tqjv5mw3k2na itm_ragharness22 --seller-bps 0 --note 'Seller did not deliver before the deadline.'

# rf admin resolve <order_id> <item_id> [options]
# all options: rf admin resolve --help

Response 200 OK:

json

{
  "id": "ord_tqjv5mw3k2na",
  "object": "order",
  "state": "settled",
  "buyer": {
    "id": "acc_samdevuser22",
    "type": "user",
    "handle": "samdev",
    "display_name": "Sam Okafor",
    "verified": false,
    "avatar_url": ""
  },
  "items": [
    {
      "item_id": "itm_ragharness22",
      "item": "janedoe/invoice-rag-harness",
      "title": "Invoice RAG harness",
      "version": "0.9.2",
      "seller": {
        "id": "acc_janedoeuser2",
        "type": "user",
        "handle": "janedoe",
        "display_name": "Jane Doe",
        "verified": false,
        "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
      },
      "state": "refunded",
      "price_cents": 1200,
      "fee_cents": 0,
      "seller_amount_cents": 0,
      "project_id": null,
      "delivery": null,
      "deliver_by": "2026-11-10T10:08:00Z",
      "accept_by": null,
      "dispute": null,
      "resolution": {
        "seller_bps": 0,
        "refund_cents": 1200,
        "note": "Seller did not deliver before the deadline.",
        "resolved_at": "2026-11-10T10:09:00Z"
      },
      "release_reason": null
    }
  ],
  "subtotal_cents": 1200,
  "fee_bps": 100,
  "fee_cents": 0,
  "total_cents": 1200,
  "currency": "USD",
  "payment": {
    "rail": "base-usdc",
    "network": "base-sepolia",
    "asset": "USDC",
    "status": "confirmed",
    "amount_cents": 1200,
    "amount_atomic": "12000000",
    "address": "0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2",
    "memo": null,
    "uri": null,
    "tx_ref": "0x709b55bd3da0f5a838125bd0ee20c5bfdd7caba173912d4281cae816b79a201b",
    "confirmations": 3,
    "required_confirmations": 3,
    "expires_at": null,
    "refund_address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
    "simulated": false
  },
  "plan_id": "pln_goalinvoice2",
  "accept_window_seconds": 604800,
  "deliver_window_seconds": 604800,
  "funded_at": "2026-11-03T10:07:12Z",
  "settled_at": "2026-11-10T10:09:00Z",
  "payouts": [
    {
      "id": "pyo_buyerrefun22",
      "object": "payout",
      "order_id": "ord_tqjv5mw3k2na",
      "item_id": "itm_ragharness22",
      "kind": "refund",
      "recipient": {
        "id": "acc_samdevuser22",
        "type": "user",
        "handle": "samdev",
        "display_name": "Sam Okafor",
        "verified": false,
        "avatar_url": ""
      },
      "address": "0x1D6c2b7A0E5a3C47bC8D90e5F0A2c1b3d4E5f6A7",
      "rail": "base-usdc",
      "amount_cents": 1200,
      "currency": "USD",
      "state": "sent",
      "tx_ref": "0x4c1d9e7b2a6f08d35e9a1b7c4d2e6f80a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2",
      "sent_at": "2026-11-10T10:10:30Z",
      "project_id": null
    }
  ],
  "next_actions": [],
  "created_at": "2026-11-03T10:05:00Z",
  "updated_at": "2026-11-10T10:10:30Z"
}

List payouts

GET /payouts Enabled on reuseforge.com

Money sent to you: seller proceeds, refunds and project revenue shares. Platform fee rows are visible to the seller whose sale produced them.

List payouts: facts
Property	Value
Operation ID	`list_payouts`
Authentication	Bearer token holding `orders:read`
Rate tier	`read`: 60/min per IP anonymous, 600/min per token with a token
Python SDK	`client.list_payouts(...)`
JavaScript SDK	`client.listPayouts(...)`
CLI	`rf payouts list`
MCP tool	`list_payouts`
Deployments	reuseforge.com: enabled. Python node: not implemented (answers `501`).

Parameters

List payouts: parameters
Name	In	Type	Required	Description
`kind`	query	`PayoutKind`	no
`state`	query	`string: pending, sent, failed`	no
`cursor`	query	`string`	no	Opaque cursor from the previous page's `next_cursor`.
`limit`	query	`integer`	no	Page size. Default `30`.

Responses

List payouts: responses
Status	Meaning	Body
200 OK	A page of payouts.	`application/json`: `PayoutPage`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl 'https://reuseforge.com/api/v1/payouts' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN"

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

for entry in client.list_payouts():  # iterating fetches further pages on demand
    print(entry["id"])

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

for await (const entry of client.listPayouts()) {  // iterating fetches further pages on demand
  console.log(entry.id);
}

CLI

bash

rf payouts list

# rf payouts list [options]
# all options: rf payouts list --help

Response 200 OK:

json

{
  "data": [
    {
      "id": "pyo_sellerpay222",
      "object": "payout",
      "order_id": "ord_tqjv5mw3k2na",
      "item_id": "itm_ragharness22",
      "kind": "seller",
      "recipient": {
        "id": "acc_janedoeuser2",
        "type": "user",
        "handle": "janedoe",
        "display_name": "Jane Doe",
        "verified": false,
        "avatar_url": "https://avatars.githubusercontent.com/u/1000001"
      },
      "address": "0xA11cE0000000000000000000000000000000b0b2",
      "rail": "base-usdc",
      "amount_cents": 1188,
      "currency": "USD",
      "state": "sent",
      "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4",
      "sent_at": "2026-11-03T11:21:10Z",
      "project_id": null
    },
    {
      "id": "pyo_platformfee2",
      "object": "payout",
      "order_id": "ord_tqjv5mw3k2na",
      "item_id": "itm_ragharness22",
      "kind": "platform_fee",
      "recipient": null,
      "address": "0xFee0000000000000000000000000000000000001",
      "rail": "base-usdc",
      "amount_cents": 12,
      "currency": "USD",
      "state": "sent",
      "tx_ref": "0xe2a1c0b6a4f8d37e5b19c8d70f6a3e24b5c91d08f7a6e5d4c3b2a19087f6e5d4",
      "sent_at": "2026-11-03T11:21:10Z",
      "project_id": null
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Seller earnings summary

GET /earnings Enabled on reuseforge.com

Where your sales money is right now. Changing payout addresses is deliberately not part of the API; it needs an interactive session.

Seller earnings summary: facts
Property	Value
Operation ID	`get_earnings`
Authentication	Bearer token holding `orders:read`
Rate tier	`read`: 60/min per IP anonymous, 600/min per token with a token
Python SDK	`client.get_earnings(...)`
JavaScript SDK	`client.getEarnings(...)`
CLI	`rf payouts earnings`
MCP tool	`get_earnings`
Deployments	reuseforge.com: enabled. Python node: not implemented (answers `501`).

Responses

Seller earnings summary: responses
Status	Meaning	Body
200 OK	The summary.	`application/json`: `Earnings`
401	Missing, malformed, expired or revoked credentials.	`Problem`. Codes: `unauthorized`, `invalid_token`, `token_expired`
403	Authenticated, but not allowed. Most often a missing scope (`insufficient_scope`, with `required_scopes`), an exceeded spend limit, or a role on the owning account that is too low. Also `version_quarantined` (the security scan or a moderator blocked the version you asked for) and `review_removed` (a moderator removed your review).	`Problem`. Codes: `insufficient_scope`, `forbidden`, `account_suspended`, `email_unverified`, `spend_limit_exceeded`, `purchase_required`, `quota_exceeded`, `version_quarantined`, `review_removed`
429	Rate limit for the operation's tier exceeded. Wait `Retry-After` seconds.	`Problem`. Codes: `rate_limited`

Example

curl

bash

curl 'https://reuseforge.com/api/v1/earnings' \
  -H "Authorization: Bearer $REUSEFORGE_TOKEN"

Python

python

import reuseforge

client = reuseforge.Client()  # token from REUSEFORGE_TOKEN, or the file `rf login` wrote

result = client.get_earnings()
print(result)

JavaScript

javascript

import { ReuseForge } from '@reuseforge/sdk';

const client = new ReuseForge({ token: process.env.REUSEFORGE_TOKEN });

const result = await client.getEarnings();
console.log(result);

CLI

bash

rf payouts earnings

# rf payouts earnings
# all options: rf payouts earnings --help

Response 200 OK:

json

{
  "currency": "USD",
  "in_escrow_cents": 3600,
  "releasable_soon_cents": 1200,
  "available_cents": 0,
  "paid_out_cents": 11880,
  "fees_paid_cents": 120,
  "by_rail": [
    {
      "rail": "base-usdc",
      "paid_out_cents": 11880
    }
  ]
}