Tham chiếu API

Categories are the top level of the catalogue. They carry no prices and no stock of their own — they exist to group listings, and displayPriority is the order an operator wants them shown in.

curl -X GET 'https://rollroyce.store/api/v1/client/catalog/categories' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": [
    {
      "id": 3,
      "name": "Example category",
      "slug": "example-category",
      "description": null,
      "image": null,
      "displayPriority": 0,
      "createdAt": "2026-01-04T09:12:00.000Z"
    }
  ],
  "message": null,
  "meta": {
    "pagination": {
      "total": 42,
      "perPage": 20,
      "currentPage": 1,
      "lastPage": 3
    }
  }
}

A group is one thing you can buy. type decides how it is delivered:

• account — stock is delivered automatically. availableStock says how many units are sellable right now, and credentials become readable once the order completes.
• product — a collaborator fulfils it by hand. The group holds individual products, and sellingPrice on the group itself is 0 because it does not apply.

availableStock is omitted, not null, on listings where it could not be computed. Treat a missing key as unknown rather than as zero.

The listing hides an account group that has no sellable stock and does not allow preorder, and a product group with no active product. Such a group still answers GET /client/catalog/groups/:id — absent from the list is not the same as gone.

Where a group asks the buyer questions at checkout, the payload carries a requireInput array — one { key, label, type, required, … } per question. Those keys are what inputs on an order answers.

A price filter narrows the result set in a way that is easy to miss. Send priceMin, priceMax or sort=price and the listing is restricted to type="account" groups. That is not a bug: a product group's sellingPrice is 0 meaning "not applicable", so including them would sort every one of them to the front and make the filter meaningless. If you want product groups, do not filter or sort by price.

Send no sort to get the operator's own ordering (displayPriority), which is what the storefront shows.

curl -X GET 'https://rollroyce.store/api/v1/client/catalog/groups' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": [
    {
      "id": 12,
      "categoryId": 3,
      "type": "account",
      "name": "Example listing",
      "description": "What the buyer receives.",
      "image": null,
      "sellingPrice": "12.5000",
      "attributes": {
        "region": "EU"
      },
      "allowPreorder": false,
      "hasWarranty": true,
      "warrantyMinutes": 1440,
      "minPurchaseQuantity": 1,
      "maxPurchaseQuantity": 10,
      "displayPriority": 0,
      "soldCount": 318,
      "createdAt": "2026-01-04T09:12:00.000Z",
      "availableStock": 74
    }
  ],
  "message": null,
  "meta": {
    "pagination": {
      "total": 42,
      "perPage": 20,
      "currentPage": 1,
      "lastPage": 3
    }
  }
}

The same shape as one row of the listing, read fresh. Use it immediately before placing an order: availableStock, minPurchaseQuantity and maxPurchaseQuantity are the three values a checkout has to respect, and all three can change between a listing being cached and an order being placed.

A group an operator has hidden or locked answers 404, the same as one that never existed — visibility is not something the API narrates.

curl -X GET 'https://rollroyce.store/api/v1/client/catalog/groups/12' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": {
    "id": 12,
    "categoryId": 3,
    "type": "account",
    "name": "Example listing",
    "description": "What the buyer receives.",
    "image": null,
    "sellingPrice": "12.5000",
    "attributes": {
      "region": "EU"
    },
    "allowPreorder": false,
    "hasWarranty": true,
    "warrantyMinutes": 1440,
    "minPurchaseQuantity": 1,
    "maxPurchaseQuantity": 10,
    "displayPriority": 0,
    "soldCount": 318,
    "createdAt": "2026-01-04T09:12:00.000Z",
    "availableStock": 74
  },
  "message": null
}

Only type="product" groups have rows here. Passing an account group's id returns an empty page, not an error — the request was well-formed and the answer is "none", which is a different thing from "wrong".

Each product's sellingPrice is per unit. An order for a product group names products and quantities in items; the group's own price is not used.

curl -X GET 'https://rollroyce.store/api/v1/client/catalog/groups/12/products' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": [
    {
      "id": 77,
      "groupId": 12,
      "name": "Top-up 500",
      "image": null,
      "description": null,
      "sellingPrice": "4.9000",
      "displayPriority": 0,
      "createdAt": "2026-01-04T09:12:00.000Z"
    }
  ],
  "message": null,
  "meta": {
    "pagination": {
      "total": 42,
      "perPage": 20,
      "currentPage": 1,
      "lastPage": 3
    }
  }
}

A quote creates nothing. No order, no reservation, no charge — it prices the basket you describe and tells you what the account would pay. Stock is not held, so a quote is a good faith estimate and not a promise.

The body is the same shape as POST /client/orders. Build one object, quote it, then post it. A quote checks less than an order does: the group must exist, be active and match orderType, a product basket must name at least one line, and every product must belong to the group — but quantity bounds, stock, product availability, preorder and inputs are only enforced when the order is placed. A quote that succeeds is not an order that will.

Read paidAmount. It already has the account's standing discount applied, and discountSource says where that discount came from:

Discount codes do not work through the API. Sending code is a 422 E_DISCOUNT_CODE_NOT_ALLOWED_VIA_API, and the order is not created. The refusal is deliberate and loud: silently ignoring the code would let a buyer pay full price believing they had a discount. Account-level discounts above still apply — you get those without asking. A quote that carries a code also spends a separate budget of 10 per minute per account before it is refused, so do not probe.

curl -X POST 'https://rollroyce.store/api/v1/client/orders/quote' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Origin: https://rollroyce.store' \
  -H 'Content-Type: application/json' \
  -d '{"orderType":"account","groupId":12,"quantity":2}'

{
  "data": {
    "originalAmount": "25.0000",
    "discountAmount": "2.5000",
    "discountPercent": "10.00",
    "paidAmount": "22.5000",
    "discountSource": "user_tier"
  },
  "message": null
}

This is the one endpoint that spends money. It debits the account's wallet and creates a real order. There is no sandbox and no dry run — quote it first.

Two shapes, one discriminator

orderType is explicit rather than inferred from which fields you sent, so a malformed request gets one clear error instead of a guess:

• orderType: "account" — set quantity. Optionally preorder: true on a group that allows buying ahead of stock.
• orderType: "product" — set items, up to 100 lines of { productId, quantity }.

inputs answers a product group's own questions (its requireInput list). Keys the group did not ask for are dropped silently; a required one that is missing is a 422 whose field is the question's key. An account order carries no inputs.

A group that is missing, hidden, locked, or of the other type is 409 E_GROUP_UNAVAILABLE — the same code for all four, so a 409 here does not mean "try again later".

201 does not mean delivered

Every order comes back 201, already paid for. Read deliveryState before reading credentials: done means the credentials are written; pending means a large order or a preorder is still being written in the background — poll GET /client/orders/:code until it is done; none is a product order, which is fulfilled by a collaborator and never has credentials; failed means delivery could not complete and an operator will refund or retry.

There is no idempotency key. If this request times out, do not resend it — read GET /client/orders and check whether the order landed. Resending blindly charges the wallet twice.

curl -X POST 'https://rollroyce.store/api/v1/client/orders' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Origin: https://rollroyce.store' \
  -H 'Content-Type: application/json' \
  -d '{"orderType":"account","groupId":12,"quantity":1}'

{
  "data": {
    "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
    "orderType": "account",
    "groupName": "Example listing",
    "items": null,
    "quantity": 2,
    "originalAmount": "25.0000",
    "discountAmount": "2.5000",
    "discountPercent": "10.00",
    "paidAmount": "22.5000",
    "discountSource": "user_tier",
    "status": "completed",
    "isRefunded": false,
    "refundAmount": "0.0000",
    "isPreorder": false,
    "deliveryState": "done",
    "deliveredCount": 2,
    "reservedCount": 0,
    "paidAt": "2026-02-11T14:03:22.000Z",
    "createdAt": "2026-02-11T14:03:20.000Z"
  },
  "message": "Purchase completed successfully"
}

Every order the account has placed, newest first — including orders placed through the website, not only through this API. A key reads its owner's history, not its own.

status is the order's lifecycle (pending, processing, completed, cancelled); deliveryState is whether the goods have been written yet (none, pending, done, failed). They move independently, and for anything that reads credentials the one that matters is deliveryState.

Because website orders are included, discountSource can also be code on an order that was paid with a discount code there — a value an order placed through the API can never carry.

curl -X GET 'https://rollroyce.store/api/v1/client/orders' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": [
    {
      "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
      "orderType": "account",
      "groupName": "Example listing",
      "items": null,
      "quantity": 2,
      "originalAmount": "25.0000",
      "discountAmount": "2.5000",
      "discountPercent": "10.00",
      "paidAmount": "22.5000",
      "discountSource": "user_tier",
      "status": "completed",
      "isRefunded": false,
      "refundAmount": "0.0000",
      "isPreorder": false,
      "deliveryState": "done",
      "deliveredCount": 2,
      "reservedCount": 0,
      "paidAt": "2026-02-11T14:03:22.000Z",
      "createdAt": "2026-02-11T14:03:20.000Z"
    }
  ],
  "message": null,
  "meta": {
    "pagination": {
      "total": 42,
      "perPage": 20,
      "currentPage": 1,
      "lastPage": 3
    }
  }
}

Orders are addressed by their public ord_… code, never by a numeric id. A value that does not match that shape is refused by the router as a 404 E_NOT_FOUND before any handler runs. An order that belongs to another account is a 404 E_ORDER_NOT_FOUND — a key never learns that a foreign code exists.

The detail does not embed the delivered accounts. An order can hold tens of thousands of them, so they live behind their own paginated endpoint.

items is the product-line snapshot for a product order, and null for an account one. Cost prices are never included — you see what you were charged.

curl -X GET 'https://rollroyce.store/api/v1/client/orders/ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": {
    "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
    "orderType": "account",
    "groupName": "Example listing",
    "items": null,
    "quantity": 2,
    "originalAmount": "25.0000",
    "discountAmount": "2.5000",
    "discountPercent": "10.00",
    "paidAmount": "22.5000",
    "discountSource": "user_tier",
    "status": "completed",
    "isRefunded": false,
    "refundAmount": "0.0000",
    "isPreorder": false,
    "deliveryState": "done",
    "deliveredCount": 2,
    "reservedCount": 0,
    "paidAt": "2026-02-11T14:03:22.000Z",
    "createdAt": "2026-02-11T14:03:20.000Z"
  },
  "message": null
}

The only endpoint in this API that decrypts anything. It returns the account credentials delivered by a completed account order, and it is the reason credential:read is a separate ability from order:read.

It is paginated because an order can carry tens of thousands of rows, and it carries two limits rather than one: 10 requests per minute, and 120,000 credential rows per hour. Both are counted per account rather than per key, and the first is shared with the website's own credential views. The second is what stops a compromised key from draining an entire order history in one pass.

warrantyExpiresAt is null on a group with no warranty. Where it is set, it is the deadline for raising a complaint about that specific account.

Fetch these once and store them where you keep secrets. Re-reading the same page repeatedly spends a budget that exists to make bulk extraction slow, and the data does not change. Reading a page also marks those rows as viewed on the website.

An order still being written — or a product order, which never has credentials — answers 404 E_ORDER_NOT_FOUND, the same as an order that does not exist. Poll the order's deliveryState first.

curl -X GET 'https://rollroyce.store/api/v1/client/orders/ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11/credentials' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": [
    {
      "id": 90211,
      "username": "delivered-account",
      "password": "delivered-secret",
      "extra": null,
      "warrantyExpiresAt": "2026-02-12T14:03:22.000Z"
    }
  ],
  "message": "Account credentials revealed",
  "meta": {
    "pagination": {
      "total": 42,
      "perPage": 20,
      "currentPage": 1,
      "lastPage": 3
    }
  }
}

The same credentials as the paginated read, delivered as one file in one request: text/plain, sent as an attachment named <code>-accounts.txt, one account per line as username<delimiter>password<delimiter>extra. There are always three fields on a line — an account with no extra ends in an empty field — lines are separated by CRLF, and the file ends on its last line.

It exists because the paginated read is throttled by request: at 100 rows a page and 10 requests a minute, an order over 1,000 accounts cannot be read in one go that way. A download is one request whatever the order size, and the server streams it a batch at a time rather than building the file in memory.

delimiter picks the separator (:, /, | or ,, default :). Fields are written exactly as delivered, never quoted or escaped, so choose one your data cannot contain.

format=ndjson streams the same rows as one JSON object per line instead — { id, username, password, extra, warrantyExpiresAt }, the row the paginated read returns — for a program that wants the whole order in one request without parsing a delimited file. It is sent inline rather than as an attachment.

The whole order counts against the 120,000-rows-per-hour budget the moment the download starts, and every row in the file is marked as viewed on the website — a buyer who has the file has every credential in it. Download once and store the file where you keep secrets.

An order still being written — or a product order, which never has credentials — answers 404 E_ORDER_NOT_FOUND, the same as an order that does not exist. Poll the order's deliveryState first. Every refusal, including a 429, is decided before the first byte, so it arrives as the usual JSON error envelope and never as a truncated file.

curl -X GET 'https://rollroyce.store/api/v1/client/orders/ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11/export' \
  -H 'X-Api-Key: YOUR_API_KEY'

There is no top-up endpoint on this surface. Funding a wallet happens on the website, and deliberately so: it moves real money and belongs behind a session.

Check this before a batch of orders rather than discovering 409 E_INSUFFICIENT_BALANCE partway through one. discountPercent here is the same rate a quote would apply, computed without a basket.

curl -X GET 'https://rollroyce.store/api/v1/client/me/balance' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": {
    "balance": "184.2500",
    "discountPercent": "10.00",
    "discountSource": "user_tier"
  },
  "message": null
}

Product orders waiting for someone to take them. This is the work board.

What you see here is deliberately thinner than what you see once you hold an order: no payoutAmount, and no prices on the items. An unclaimed order shows what the work is, not what it pays — so the queue cannot be mined for the platform's margins by anyone who never intends to claim anything.

Poll it. The collaborator budget is 240 requests a minute for exactly this reason, so a check every few seconds is well within it.

curl -X GET 'https://rollroyce.store/api/v1/collab/product-orders/queue' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": [
    {
      "id": 5512,
      "orderId": 8821,
      "state": "unclaimed",
      "handlerUserId": null,
      "claimedAt": null,
      "completedAt": null,
      "resultNote": null,
      "payoutReleaseAt": null,
      "payoutPaid": false,
      "payoutPaidAt": null,
      "createdAt": "2026-02-11T14:03:22.000Z",
      "order": {
        "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
        "items": [
          {
            "product_id": 77,
            "item": "Top-up 500",
            "quantity": 1
          }
        ]
      }
    }
  ],
  "message": null,
  "meta": {
    "pagination": {
      "total": 42,
      "perPage": 20,
      "currentPage": 1,
      "lastPage": 3
    }
  }
}

Orders you currently hold or have completed. payoutAmount is present here, because you hold them.

state filters the list. The four values are the whole lifecycle, but only two of them can appear here:

Money still in escrow is a completed row with payoutPaidAt null; this is where to look for it, not the payout history.

There is no ceiling on how many orders you may hold at once. The claim rate limit is about how fast you take them, not how many you have.

curl -X GET 'https://rollroyce.store/api/v1/collab/product-orders' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": [
    {
      "id": 5512,
      "orderId": 8821,
      "state": "claimed",
      "handlerUserId": 41,
      "claimedAt": "2026-02-11T14:20:00.000Z",
      "completedAt": null,
      "resultNote": null,
      "payoutAmount": "3.7500",
      "payoutReleaseAt": null,
      "payoutPaid": false,
      "payoutPaidAt": null,
      "createdAt": "2026-02-11T14:03:22.000Z",
      "order": {
        "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
        "items": [
          {
            "product_id": 77,
            "item": "Top-up 500",
            "quantity": 1
          }
        ]
      }
    }
  ],
  "message": null,
  "meta": {
    "pagination": {
      "total": 42,
      "perPage": 20,
      "currentPage": 1,
      "lastPage": 3
    }
  }
}

One order in full — but only for the order you hold. Any other order, including one still in the queue, is a 403 E_PRODUCT_ORDER_INPUT_FORBIDDEN; an id that does not exist is a 404.

That means the buyer's brief is not readable before claiming. The queue shows what the work is (the items); input — schema for what was asked, values for what the buyer replied — is only here, after the claim. Claim what the item list tells you that you can do, then read the brief.

As the holder you get payoutAmount and each item's selling_price and cost_price. The response is the same shape when the buyer's own account reads it, with payoutAmount and handlerUserId null and the prices stripped — write your client to tolerate null there.

curl -X GET 'https://rollroyce.store/api/v1/collab/product-orders/5512' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": {
    "id": 5512,
    "orderId": 8821,
    "state": "claimed",
    "handlerUserId": 41,
    "claimedAt": "2026-02-11T14:20:00.000Z",
    "completedAt": null,
    "resultNote": null,
    "payoutAmount": "3.7500",
    "payoutReleaseAt": null,
    "payoutPaid": false,
    "payoutPaidAt": null,
    "createdAt": "2026-02-11T14:03:22.000Z",
    "order": {
      "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
      "items": [
        {
          "product_id": 77,
          "item": "Top-up 500",
          "quantity": 1
        }
      ]
    },
    "input": {
      "schema": [
        {
          "key": "server",
          "label": "Server"
        }
      ],
      "values": {
        "server": "eu-west"
      }
    }
  },
  "message": null
}

Takes an order out of the queue and assigns it to you. Once claimed it is yours: there is no way to hand it back. The only exits are complete and cancel, and cancelling refunds the buyer.

The claim is a single atomic write, so exactly one collaborator wins a contested order and everyone else gets 409 E_PRODUCT_ORDER_ALREADY_CLAIMED. That is normal traffic, not an error to alert on.

A lost race still spends one of your 20 claims per minute. The budget is charged before the handler runs. Claim orders you have read and intend to work on; a bot that claims the whole queue on sight burns its budget losing races.

curl -X POST 'https://rollroyce.store/api/v1/collab/product-orders/5512/claim' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Origin: https://rollroyce.store'

{
  "data": {
    "id": 5512,
    "orderId": 8821,
    "state": "claimed",
    "handlerUserId": 41,
    "claimedAt": "2026-02-11T14:20:00.000Z",
    "completedAt": null,
    "resultNote": null,
    "payoutAmount": "3.7500",
    "payoutReleaseAt": null,
    "payoutPaid": false,
    "payoutPaidAt": null,
    "createdAt": "2026-02-11T14:03:22.000Z",
    "order": {
      "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
      "items": [
        {
          "product_id": 77,
          "item": "Top-up 500",
          "quantity": 1
        }
      ]
    }
  },
  "message": null
}

Reports the work done. This starts the payout clock: payoutReleaseAt comes back set — the completion time plus the operator's hold, 24 hours by default — and the money leaves escrow at that time rather than immediately.

resultNote reaches the buyer. It is how you tell them what you delivered and where to find it, so it is worth writing properly — for many orders it is the entire delivery.

Only the holder may complete. Completing twice is 409 E_PRODUCT_ORDER_STATE_INVALID, not a second payout.

curl -X POST 'https://rollroyce.store/api/v1/collab/product-orders/5512/complete' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Origin: https://rollroyce.store' \
  -H 'Content-Type: application/json' \
  -d '{"resultNote":"Delivered, code sent in-app."}'

{
  "data": {
    "id": 5512,
    "orderId": 8821,
    "state": "completed",
    "handlerUserId": 41,
    "claimedAt": "2026-02-11T14:20:00.000Z",
    "completedAt": "2026-02-11T15:02:00.000Z",
    "resultNote": "Delivered, code sent in-app.",
    "payoutAmount": "3.7500",
    "payoutReleaseAt": "2026-02-12T15:02:00.000Z",
    "payoutPaid": false,
    "payoutPaidAt": null,
    "createdAt": "2026-02-11T14:03:22.000Z",
    "order": {
      "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
      "items": [
        {
          "product_id": 77,
          "item": "Top-up 500",
          "quantity": 1
        }
      ]
    }
  },
  "message": null
}

Gives up an order you are holding. The buyer is refunded in full, and the payout for it will never be released. The order is released too — it leaves your list, and this response is the last time you can read it.

This is the most dangerous call in the API. It destroys a real order and moves real money, and it is why product_order:cancel is the one ability left out of the default grant — a key must ask for it explicitly. Mint that key narrowly, and keep it out of anything that runs unattended.

It carries a tighter budget than every other route on this surface: 10 a minute. That is not a throughput limit, it is a blast radius.

reason is recorded on the order. Fill it in — it is what an operator reads when a buyer asks what happened.

curl -X POST 'https://rollroyce.store/api/v1/collab/product-orders/5512/cancel' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Origin: https://rollroyce.store' \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Cannot source this variant."}'

{
  "data": {
    "id": 5512,
    "orderId": 8821,
    "state": "cancelled",
    "handlerUserId": null,
    "claimedAt": null,
    "completedAt": null,
    "resultNote": null,
    "payoutAmount": "3.7500",
    "payoutReleaseAt": null,
    "payoutPaid": false,
    "payoutPaidAt": null,
    "createdAt": "2026-02-11T14:03:22.000Z",
    "order": {
      "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
      "items": [
        {
          "product_id": 77,
          "item": "Top-up 500",
          "quantity": 1
        }
      ]
    }
  },
  "message": null
}

What has already been paid to you, most recently paid first. Every row here has payoutPaidAt set; money still in escrow is not listed — it is a completed row on your product orders, where:

• payoutReleaseAt in the future, payoutPaidAt null — done and still in escrow.
• payoutReleaseAt in the past, payoutPaidAt null — due, waiting on the payout run.

Escrow is a hold, not a review: nobody has to approve anything for the clock to run out. It exists so a complaint raised shortly after delivery can still be settled against money that has not moved yet.

curl -X GET 'https://rollroyce.store/api/v1/collab/payouts' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": [
    {
      "id": 5512,
      "payoutAmount": "3.7500",
      "completedAt": "2026-02-11T15:02:00.000Z",
      "payoutReleaseAt": "2026-02-12T15:02:00.000Z",
      "payoutPaidAt": "2026-02-12T16:00:00.000Z"
    }
  ],
  "message": null,
  "meta": {
    "pagination": {
      "total": 42,
      "perPage": 20,
      "currentPage": 1,
      "lastPage": 3
    }
  }
}

Every complaint item filed against one of your sales — an account you supplied or a product order you completed. One row per disputed item, not per complaint: a buyer who names ten accounts gives you ten rows, each answered on its own.

The two statuses that need you:

• open — the buyer just filed it. Answer before collabRespondBy, or the buyer is refunded automatically and, if the money had reached you, clawed back.
• fixed — you sent a fix and the buyer has until buyerConfirmBy to say it worked. Their silence closes the item in your favour.

escalated means the buyer said your fix did not work and an administrator decides. The three closed statuses (refunded, rejected, done) carry closedReason — which road led there.

amountAtStake is what a refund would cost you: the account's price, or the product order's remaining paid amount. alreadyPaidOut tells you whether that money is still in escrow (a refund just cancels the payout) or already in your pot (a refund is clawed back — pot, then collateral, then debt).

curl -X GET 'https://rollroyce.store/api/v1/collab/complaints' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": [
    {
      "id": 301,
      "complaintCode": "cmp_4c2a9f10-7b3e-4d88-9e61-2f5b8c7d1a90",
      "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
      "subjectType": "order_item",
      "orderItemId": 12044,
      "reason": "Password no longer works.",
      "attachments": [
        "/uploads/complaint/x8Fq2mZk0aLp.webp"
      ],
      "status": "open",
      "closedReason": null,
      "amountAtStake": "12.5000",
      "alreadyPaidOut": false,
      "collabRespondBy": "2026-02-13T14:20:00.000Z",
      "collabRespondedAt": null,
      "collabAction": null,
      "collabNote": null,
      "buyerConfirmBy": null,
      "buyerConfirmedAt": null,
      "buyerVerdict": null,
      "buyerNote": null,
      "refundAmount": "0.0000",
      "clawbackAmount": "0.0000",
      "resolution": null,
      "resolvedAt": null,
      "createdAt": "2026-02-11T14:20:00.000Z"
    }
  ],
  "message": null,
  "meta": {
    "pagination": {
      "total": 42,
      "perPage": 20,
      "currentPage": 1,
      "lastPage": 3
    }
  }
}

One item, by id. An item that is not yours is a 404, not a 403 — whether a complaint exists against somebody else's sale is not yours to learn.

curl -X GET 'https://rollroyce.store/api/v1/collab/complaints/301' \
  -H 'X-Api-Key: YOUR_API_KEY'

{
  "data": {
    "id": 301,
    "complaintCode": "cmp_4c2a9f10-7b3e-4d88-9e61-2f5b8c7d1a90",
    "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
    "subjectType": "order_item",
    "orderItemId": 12044,
    "reason": "Password no longer works.",
    "attachments": [
      "/uploads/complaint/x8Fq2mZk0aLp.webp"
    ],
    "status": "open",
    "closedReason": null,
    "amountAtStake": "12.5000",
    "alreadyPaidOut": false,
    "collabRespondBy": "2026-02-13T14:20:00.000Z",
    "collabRespondedAt": null,
    "collabAction": null,
    "collabNote": null,
    "buyerConfirmBy": null,
    "buyerConfirmedAt": null,
    "buyerVerdict": null,
    "buyerNote": null,
    "refundAmount": "0.0000",
    "clawbackAmount": "0.0000",
    "resolution": null,
    "resolvedAt": null,
    "createdAt": "2026-02-11T14:20:00.000Z"
  },
  "message": null
}

Close the item in the buyer's favour. This is final: the buyer's wallet is credited the full amountAtStake in the same transaction, and the item can never be reopened from this surface.

Where the money comes from depends on alreadyPaidOut:

• false — the payout was still in escrow. It is simply never released.
• true — you had been paid. The whole refund is recovered down the ladder: your commission pot first, your collateral deposit second, and the remainder as a negative pot balance (a recorded debt). Your spendable wallet is never touched.

Only an open item can be refunded from here; anything else is a 422 E_COMPLAINT_NOT_ACTIONABLE.

curl -X POST 'https://rollroyce.store/api/v1/collab/complaints/301/refund' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Origin: https://rollroyce.store' \
  -H 'Content-Type: application/json' \
  -d '{"note":"Sorry — refunded."}'

{
  "data": {
    "id": 301,
    "complaintCode": "cmp_4c2a9f10-7b3e-4d88-9e61-2f5b8c7d1a90",
    "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
    "subjectType": "order_item",
    "orderItemId": 12044,
    "reason": "Password no longer works.",
    "attachments": [
      "/uploads/complaint/x8Fq2mZk0aLp.webp"
    ],
    "status": "refunded",
    "closedReason": "collab_refund",
    "amountAtStake": "12.5000",
    "alreadyPaidOut": false,
    "collabRespondBy": "2026-02-13T14:20:00.000Z",
    "collabRespondedAt": "2026-02-11T16:00:00.000Z",
    "collabAction": "refund",
    "collabNote": "Sorry — refunded.",
    "buyerConfirmBy": null,
    "buyerConfirmedAt": null,
    "buyerVerdict": null,
    "buyerNote": null,
    "refundAmount": "12.5000",
    "clawbackAmount": "0.0000",
    "resolution": null,
    "resolvedAt": "2026-02-11T16:00:00.000Z",
    "createdAt": "2026-02-11T14:20:00.000Z"
  },
  "message": "The buyer has been refunded"
}

The other answer: fix it instead of paying. What "fix" means depends on the item's subjectType:

• order_item — send credentials. They overwrite the disputed account in place, encrypted the way the original was; the buyer's order page shows the replacement immediately. The old credential is not kept.
• product_order — send resultNote, the re-done result. The order stays completed.

Sending the wrong half is a field-level 422. On success the item becomes fixed and the buyer's clock starts (buyerConfirmBy): they either confirm (the hold is released and your payout resumes on the next run), report it is still broken (an administrator decides), or say nothing until the clock runs out — which also releases the hold. There is one round: a buyer who reports "still broken" goes straight to the administrator.

curl -X POST 'https://rollroyce.store/api/v1/collab/complaints/301/fix' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Origin: https://rollroyce.store' \
  -H 'Content-Type: application/json' \
  -d '{"note":"Replaced with a fresh account.","credentials":"{ \"username\": \"new.user\", \"password\": \"new-pass\" }","resultNote":"Re-delivered, see attached."}'

{
  "data": {
    "id": 301,
    "complaintCode": "cmp_4c2a9f10-7b3e-4d88-9e61-2f5b8c7d1a90",
    "orderCode": "ord_9f2c1b7e-5a40-4c6d-9b21-8e0a4d3f5c11",
    "subjectType": "order_item",
    "orderItemId": 12044,
    "reason": "Password no longer works.",
    "attachments": [
      "/uploads/complaint/x8Fq2mZk0aLp.webp"
    ],
    "status": "fixed",
    "closedReason": null,
    "amountAtStake": "12.5000",
    "alreadyPaidOut": false,
    "collabRespondBy": "2026-02-13T14:20:00.000Z",
    "collabRespondedAt": "2026-02-11T16:00:00.000Z",
    "collabAction": "fix",
    "collabNote": "Replaced with a fresh account.",
    "buyerConfirmBy": "2026-02-14T16:00:00.000Z",
    "buyerConfirmedAt": null,
    "buyerVerdict": null,
    "buyerNote": null,
    "refundAmount": "0.0000",
    "clawbackAmount": "0.0000",
    "resolution": null,
    "resolvedAt": null,
    "createdAt": "2026-02-11T14:20:00.000Z"
  },
  "message": "Your fix was sent; the buyer has been asked to confirm"
}