Skip to content
RemindCash

Request and response examples

A complete flow from creating a receivable to recording a payment, plus common error responses.

Public API status

The v1 API described here is implemented and tested, but api.remindcash.com is not yet open to the public. It opens after final acceptance testing; until then requests return 503. Examples use placeholders — never paste a real key into shared code.

These examples use placeholder keys and fictional data. Run them against your own company only.

1. Create a draft receivable

BASH
curl https://api.remindcash.com/v1/receivables \
  --request POST \
  --header "Authorization: Bearer $REMINDCASH_API_KEY" \
  --header "Idempotency-Key: create-inv-1042-0001" \
  --header "Content-Type: application/json" \
  --data '{
    "customer": { "display_name": "Studio North", "email": "billing@studionorth.example" },
    "amount": "1250.00",
    "currency": "USD",
    "due_date": "2026-10-15",
    "external_reference": "INV-1042",
    "description": "Website redesign"
  }'
JSON
{
    "data": {
        "id": 1,
        "customer_id": 1,
        "amount_minor": 125000,
        "paid_minor": 0,
        "currency": "USD",
        "due_date": "2026-10-15",
        "status": "draft",
        "external_reference": "INV-1042",
        "description": "Website redesign",
        "version": "4e6fea39ae2fab8ccb843657f081d276513739a71787c060a007b65e3acbbbc1"
    }
}

Sending the identical request again with the same Idempotency-Key returns this same response.

2. Move the due date

BASH
curl https://api.remindcash.com/v1/receivables/1 \
  --request PATCH \
  --header "Authorization: Bearer $REMINDCASH_API_KEY" \
  --header "Idempotency-Key: update-inv-1042-0001" \
  --header "Content-Type: application/json" \
  --data '{
    "expected_version": "4e6fea39ae2fab8ccb843657f081d276513739a71787c060a007b65e3acbbbc1",
    "due_date": "2026-10-20"
  }'
JSON
{
    "data": {
        "id": 1,
        "customer_id": 1,
        "amount_minor": 125000,
        "paid_minor": 0,
        "currency": "USD",
        "due_date": "2026-10-20",
        "status": "draft",
        "external_reference": "INV-1042",
        "description": "Website redesign",
        "version": "aed5e5d947a49b4805d8389b618896872615e9e46f13536a11fbaad167d04b93"
    }
}

3. Record a partial payment

BASH
curl https://api.remindcash.com/v1/receivables/1/payments \
  --request POST \
  --header "Authorization: Bearer $REMINDCASH_API_KEY" \
  --header "Idempotency-Key: payment-inv-1042-0001" \
  --header "Content-Type: application/json" \
  --data '{ "amount": "250.00" }'
JSON
{
    "data": {
        "id": 1,
        "receivable_id": 1,
        "amount_minor": 25000,
        "remaining_after_minor": 100000,
        "status_after": "draft",
        "recorded_at": "2026-10-11T12:58:05.000000Z"
    }
}

4. Cancel the receivable

BASH
curl https://api.remindcash.com/v1/receivables/1/cancel \
  --request POST \
  --header "Authorization: Bearer $REMINDCASH_API_KEY" \
  --header "Idempotency-Key: cancel-inv-1042-00001" \
  --header "Content-Type: application/json" \
  --data '{ "reason": "Customer cancelled the project." }'
JSON
{
    "data": {
        "id": 1,
        "status": "cancelled",
        "paid_minor": 25000,
        "version": "049a6c669d9211215001be5a324c3f5c9e057797ef4d89e21c8aa632578a87ae"
    }
}

Common errors

Reusing an idempotency key with a different body:

JSON
{
    "error": {
        "code": "conflict",
        "message": "Request conflicts with current state."
    },
    "request_id": "13676e74-1d59-47c7-b7d0-b6e763cb8766"
}

Updating with a stale expected_version also returns 409 conflict. A missing key returns:

JSON
{
    "error": {
        "code": "validation_failed",
        "message": "Validation failed.",
        "fields": {
            "Idempotency-Key": [
                "Provide a 16–128 character Idempotency-Key using letters, digits, dots, underscores, colons or hyphens."
            ]
        }
    },
    "request_id": "249b739e-00f7-41ee-875a-266cfd4870bc"
}

A status change that is not allowed — for example pausing a draft:

JSON
{
    "error": {
        "code": "validation_failed",
        "message": "Validation failed.",
        "fields": {
            "action": [
                "This status change is not available for the receivable."
            ]
        }
    },
    "request_id": "f9e414bd-5508-4c43-82bb-ce56ced55f77"
}