Orders

GET /orders

Orders bought or sold

Scope: orders:read, or the broad read. Newest first, by id.

Parameters

Example request

curl "https://www.seoclerk.com/api/v1/orders" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

A page of these in data, with meta.limit and meta.next_cursor.

{
    "data": [
        {
            "id": 481220,
            "service_id": 9012,
            "buyer_id": 1501,
            "seller_id": 77,
            "title": "Logo design",
            "status": 1,
            "unit_price": {
                "amount": "25.00",
                "currency": "USD"
            },
            "quantity": 1,
            "delivery_days": 3,
            "created_at": "2026-10-09T18:22:05Z",
            "started_at": "2026-10-09T18:22:05Z",
            "completed_at": null,
            "site": "SEOClerks",
            "unread": true,
            "important": false,
            "note": null
        }
    ],
    "meta": {
        "limit": 25,
        "next_cursor": null,
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

POST /orders

Buy a listing with the balance

Scope: checkout:write. The broad write grant does not include it. Idempotency-Key is required.

One ordinary listing by another member, paid from the balance; there is no card path. The debit, the order and its payment commit together. When the balance is short and the key also holds deposits:write (and the site allows it), the member's own Auto Reload runs once and the purchase is tried again.

Parameters

Request body

Example request

curl -X POST "https://www.seoclerk.com/api/v1/orders" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: createorder-1" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":9012,"tier":2,"extras":["1"],"expected_total":"45.00"}'

Response 201

{
    "data": {
        "id": 481221,
        "service_id": 9012,
        "buyer_id": 1501,
        "seller_id": 77,
        "title": "Logo design",
        "status": 0,
        "unit_price": {
            "amount": "45.00",
            "currency": "USD"
        },
        "quantity": 1,
        "total": {
            "amount": "45.00",
            "currency": "USD"
        },
        "paid_from": "balance"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

POST /orders/quote

Price an order without placing it

Scope: checkout:write. The broad write grant does not include it.

The same body as POST orders, priced without writing anything. shortfall is what the balance lacks; deposit_amount is the whole-dollar link that would cover it; duplicate_of names a recent purchase of the same listing at the same total. It takes no Idempotency-Key and places no order.

Request body

Example request

curl -X POST "https://www.seoclerk.com/api/v1/orders/quote" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":1024,"expected_total":"12.50"}'

Response 200

{
    "data": {
        "listing_id": 1024,
        "title": "Logo design",
        "seller_id": 1024,
        "quantity": 1,
        "unit_price": {
            "amount": "12.50",
            "currency": "USD"
        },
        "total": {
            "amount": "12.50",
            "currency": "USD"
        },
        "paid_from": "balance",
        "balance_available": {
            "amount": "12.50",
            "currency": "USD"
        },
        "shortfall": {
            "amount": "12.50",
            "currency": "USD"
        },
        "order_page": "https://www.seoclerk.com/example",
        "duplicate_of": {
            "order_id": 1024,
            "created_at": "2026-10-10T14:03:22Z"
        },
        "duplicate_window_hours": 1,
        "spend_limit": {
            "limit": {
                "amount": "12.50",
                "currency": "USD"
            },
            "window_days": 1,
            "spent": {
                "amount": "12.50",
                "currency": "USD"
            },
            "remaining": {
                "amount": "12.50",
                "currency": "USD"
            }
        },
        "auto_reload": {
            "on": true,
            "setup_url": "https://www.seoclerk.com/example"
        },
        "deposit_amount": 1
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

GET /orders/{id}

An order

Scope: orders:read, or the broad read. The order's recorded buyer or seller; anyone else gets 404.

Parameters

Example request

curl "https://www.seoclerk.com/api/v1/orders/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

{
    "data": {
        "id": 1024,
        "service_id": 1024,
        "buyer_id": 1024,
        "seller_id": 1024,
        "title": "Logo design",
        "status": 1,
        "unit_price": {
            "amount": "12.50",
            "currency": "USD"
        },
        "quantity": 1,
        "delivery_days": 1,
        "created_at": "2026-10-10T14:03:22Z",
        "started_at": "2026-10-10T14:03:22Z",
        "completed_at": "2026-10-10T14:03:22Z",
        "site": "SEOClerks",
        "unread": true,
        "important": true,
        "note": "string"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

PATCH /orders/{id}

Set your flags on an order, and the seller's note

Scope: orders:write, or the broad write. Idempotency-Key is optional.

Unread and important are your own side's flags, as on the order page. Only the seller writes a note; the buyer gets 403 wrong_role. An order whose stored data cannot take a note answers 409 invalid_request.

Parameters

Request body

Example request

curl -X PATCH "https://www.seoclerk.com/api/v1/orders/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"unread":true}'

Response 200

{
    "data": {
        "id": 1024,
        "unread": true,
        "important": true,
        "note": "string"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

POST /orders/{id}/buyer-ratings

Rate the buyer

Scope: orders:write, or the broad write. The seller. Idempotency-Key is required.

Parameters

Request body

Example request

curl -X POST "https://www.seoclerk.com/api/v1/orders/1024/buyer-ratings" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: ratebuyer-1" \
  -H "Content-Type: application/json" \
  -d '{"rating":"positive","comment":"Great work."}'

Response 200

{
    "data": {
        "order_id": 1024,
        "rating_id": 1024
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

PATCH /orders/{id}/buyer-ratings/{rating_id}

Edit your rating of the buyer

Scope: orders:write, or the broad write. The seller. Idempotency-Key is optional.

Parameters

Request body

Example request

curl -X PATCH "https://www.seoclerk.com/api/v1/orders/1024/buyer-ratings/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rating":"positive","comment":"Great work."}'

Response 200

{
    "data": {
        "order_id": 1024,
        "rating_id": 1024
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

PATCH /orders/{id}/cancellation-requests/{message_id}

Answer or take back a cancellation request

Scope: orders:write, or the broad write. The order's recorded buyer or seller; anyone else gets 404. Idempotency-Key is optional.

Parameters

Request body

Example request

curl -X PATCH "https://www.seoclerk.com/api/v1/orders/1024/cancellation-requests/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"accepted"}'

Response 200

{
    "data": {
        "order_id": 1024,
        "message_id": 1024,
        "status": "string"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

POST /orders/{id}/completion

Complete an order and rate the seller

Scope: orders:write, or the broad write. The buyer. Idempotency-Key is required.

Parameters

Request body

Example request

curl -X POST "https://www.seoclerk.com/api/v1/orders/1024/completion" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: completeorder-1" \
  -H "Content-Type: application/json" \
  -d '{"rating":"positive","comment":"Great work."}'

Response 200

{
    "data": {
        "order_id": 1024,
        "rating_id": 1024,
        "status": 1
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

PATCH /orders/{id}/deliveries/{message_id}

Withdraw a delivery

Scope: orders:write, or the broad write. The seller who sent it. Idempotency-Key is optional.

Parameters

Request body

Example request

curl -X PATCH "https://www.seoclerk.com/api/v1/orders/1024/deliveries/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"withdrawn":true}'

Response 200

{
    "data": {
        "order_id": 1024,
        "message_id": 1024,
        "withdrawn": true
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

PATCH /orders/{id}/extension-requests/{message_id}

Answer or take back an extension request

Scope: orders:write, or the broad write. The order's recorded buyer or seller; anyone else gets 404. Idempotency-Key is optional.

Parameters

Request body

Example request

curl -X PATCH "https://www.seoclerk.com/api/v1/orders/1024/extension-requests/1024" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"accepted"}'

Response 200

{
    "data": {
        "order_id": 1024,
        "message_id": 1024,
        "status": "string"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

POST /orders/{id}/guarantee

Invoke the order's guarantee

Scope: orders:write, or the broad write. The buyer. Idempotency-Key is required.

Parameters

Request body

Example request

curl -X POST "https://www.seoclerk.com/api/v1/orders/1024/guarantee" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: invokeguarantee-1" \
  -H "Content-Type: application/json" \
  -d '{"reason":"string"}'

Response 200

{
    "data": {
        "order_id": 1024,
        "status": 1,
        "returned": {
            "amount": "12.50",
            "currency": "USD"
        }
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

POST /orders/{id}/invoice

Email the order's invoice to yourself

Scope: orders:write, or the broad write. The buyer; anyone else gets 404. Idempotency-Key is required.

The invoice the order page's button sends, to your account's email whatever your email preferences. Once per order in each half hour; sooner answers 429 rate_limited. The mail leaves after the request is stored.

Parameters

Example request

curl -X POST "https://www.seoclerk.com/api/v1/orders/1024/invoice" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: emailorderinvoice-1"

Response 202

{
    "data": {
        "order_id": 1024,
        "email": "[email protected]"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

GET /orders/{id}/messages

An order's messages

Scope: orders:read, or the broad read. The order's recorded buyer or seller; anyone else gets 404. Newest first, by id.

Parameters

Example request

curl "https://www.seoclerk.com/api/v1/orders/1024/messages" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY"

Response 200

A page of these in data, with meta.limit and meta.next_cursor.

{
    "data": [
        {
            "id": 1024,
            "sender_id": 1024,
            "recipient_id": 1024,
            "text": "Hello.",
            "created_at": "2026-10-10T14:03:22Z",
            "attachment_id": 1024,
            "action": "string"
        }
    ],
    "meta": {
        "limit": 1,
        "next_cursor": "string",
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

POST /orders/{id}/messages

Send an order message, delivery or request

Scope: orders:write, or the broad write. The order's recorded buyer or seller; anyone else gets 404. Idempotency-Key is required.

No attachment can be sent with an order message yet.

Parameters

Request body

Example request

curl -X POST "https://www.seoclerk.com/api/v1/orders/1024/messages" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Idempotency-Key: createordermessage-1" \
  -H "Content-Type: application/json" \
  -d '{"message":"Here is the finished logo.","action":"delivery"}'

Response 201

{
    "data": {
        "order_id": 481220,
        "message_id": 2204518,
        "action": "delivery"
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors

PATCH /orders/{id}/verification

Accept or reject an order awaiting verification

Scope: orders:write, or the broad write. The seller. Idempotency-Key is optional.

Parameters

Request body

Example request

curl -X PATCH "https://www.seoclerk.com/api/v1/orders/1024/verification" \
  -H "Authorization: Bearer $SEOCLERKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"accepted"}'

Response 200

{
    "data": {
        "order_id": 1024,
        "status": 1
    },
    "meta": {
        "request_id": "9f2c4e1ab07d3351"
    }
}

Errors