---
title: "codespar payables"
description: "Payables: submit one (structured or manual), read its state and trail"
---

Payables: submit one (structured or manual), read its state and trail

13 commands in `@codespar/cli 0.22.5`.

Each one prints what its operation answered. [What a command prints](/docs/cli/reference#what-a-command-prints) has the rule, and [Configuration](/docs/cli/config#what-a-script-gets-when-a-command-fails) has the exit codes and the shape of a failure.

### `codespar payables list`

List payables

```bash
codespar payables list
```

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |

`GET /v1/payables` · [parameters, responses and refusals](/docs/api/reference/payables#get-v1payables)

### `codespar payables create`

Create a payable from a partner's record or a person's form

```bash
codespar payables create --input-file body.json
```

```json title="body.json"
{
  "schema_version": "payable.v1",
  "doc_type": "invoice",
  "attribution": {
    "channel": "upload",
    "credential_id": "credential_0000000000000000",
    "connection_id": "conn_0000000000000000",
    "actor": "string"
  },
  "document_hash": "string",
  "supplier": {
    "document": {
      "value": "string",
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    },
    "name": {
      "value": "string",
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    }
  },
  "recipient": {
    "document": {
      "value": "string",
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    },
    "name": {
      "value": "string",
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    }
  },
  "invoice_number": {
    "value": "string",
    "from": "parser_local",
    "evidence": {
      "page": 0,
      "excerpt": "string",
      "verification": "verified"
    },
    "confidence": 0
  },
  "serie": {
    "value": "string",
    "from": "parser_local",
    "evidence": {
      "page": 0,
      "excerpt": "string",
      "verification": "verified"
    },
    "confidence": 0
  },
  "issue_date": {
    "value": "2026-01-15",
    "from": "parser_local",
    "evidence": {
      "page": 0,
      "excerpt": "string",
      "verification": "verified"
    },
    "confidence": 0
  },
  "due_date": {
    "value": "2026-01-15",
    "from": "parser_local",
    "evidence": {
      "page": 0,
      "excerpt": "string",
      "verification": "verified"
    },
    "confidence": 0
  },
  "items": [
    {
      "description": {
        "value": "string",
        "from": "parser_local",
        "evidence": {
          "page": 0,
          "excerpt": "string",
          "verification": "verified"
        },
        "confidence": 0
      },
      "quantity": {
        "value": 1000,
        "from": "parser_local",
        "evidence": {
          "page": 0,
          "excerpt": "string",
          "verification": "verified"
        },
        "confidence": 0
      },
      "unit_amount_minor": {
        "value": 1000,
        "from": "parser_local",
        "evidence": {
          "page": 0,
          "excerpt": "string",
          "verification": "verified"
        },
        "confidence": 0
      },
      "total_amount_minor": {
        "value": 1000,
        "from": "parser_local",
        "evidence": {
          "page": 0,
          "excerpt": "string",
          "verification": "verified"
        },
        "confidence": 0
      }
    }
  ],
  "totals": {
    "subtotal_minor": {
      "value": 1000,
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    },
    "discount_minor": {
      "value": 1000,
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    },
    "tax_relief_deducted_minor": {
      "value": 1000,
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    },
    "freight_minor": {
      "value": 1000,
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    },
    "insurance_minor": {
      "value": 1000,
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    },
    "other_charges_minor": {
      "value": 1000,
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    },
    "taxes_added_minor": {
      "value": 1000,
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    },
    "taxes_included_minor": {
      "value": 1000,
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    },
    "grand_total_minor": {
      "value": 1000,
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    },
    "currency": {
      "value": "string",
      "from": "parser_local",
      "evidence": {
        "page": 0,
        "excerpt": "string",
        "verification": "verified"
      },
      "confidence": 0
    }
  },
  "carriers": {
    "boleto": "string",
    "br_code": "string",
    "nfe": "string"
  },
  "extraction": {
    "model": "string",
    "model_version": "string",
    "input_tokens": 0,
    "output_tokens": 0,
    "reasoning_tokens": 0
  }
}
```

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |
| `-i, --input <json>` | Request body as a JSON string |
| `-f, --input-file <path>` | Request body from a JSON file |

`POST /v1/payables` · [parameters, responses and refusals](/docs/api/reference/payables#post-v1payables)

### `codespar payables documents`

Create a payable from an uploaded document (PDF or image)

```bash
codespar payables documents
```

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |
| `-i, --input <json>` | Request body as a JSON string |
| `-f, --input-file <path>` | Request body from a JSON file |

`POST /v1/payables/documents` · [parameters, responses and refusals](/docs/api/reference/payables#post-v1payablesdocuments)

### `codespar payables counts`

Count the payables waiting for a person

```bash
codespar payables counts
```

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |

`GET /v1/payables/counts` · [parameters, responses and refusals](/docs/api/reference/payables#get-v1payablescounts)

### `codespar payables get`

Read a payable

```bash
codespar payables get payable_0000000000000000
```

| argument | what it is |
|---|---|
| `<payableId>` | `pbl_` followed by 16 characters. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |

`GET /v1/payables/{payableId}` · [parameters, responses and refusals](/docs/api/reference/payables#get-v1payablespayableid)

### `codespar payables review`

Complete the review of a payable

```bash
codespar payables review payable_0000000000000000 --input '{"resolutions":[]}'
```

| argument | what it is |
|---|---|
| `<payableId>` | `pbl_` followed by 16 characters. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |
| `-i, --input <json>` | Request body as a JSON string |
| `-f, --input-file <path>` | Request body from a JSON file |

`POST /v1/payables/{payableId}/review` · [parameters, responses and refusals](/docs/api/reference/payables#post-v1payablespayableidreview)

### `codespar payables pay`

Pay a payable under a consumer mandate

```bash
codespar payables pay payable_0000000000000000 --input '{"mandate_id":"mandate_0000000000000000"}'
```

| argument | what it is |
|---|---|
| `<payableId>` | `pbl_` followed by 16 characters. |

| option | what it does |
|---|---|
| `-q, --query <key=value>` | Query parameter (repeatable) (default: []) |
| `--timeout <ms>` | Per-request timeout in milliseconds |
| `-i, --input <json>` | Request body as a JSON string |
| `-f, --input-file <path>` | Request body from a JSON file |

`POST /v1/payables/{payableId}/pay` · [parameters, responses and refusals](/docs/api/reference/payables#post-v1payablespayableidpay)

### `codespar payables files upload`

Upload one file (10 MB, 10 PDF pages, 500 CSV/XLSX rows); prints its file_id and what was found

```bash
codespar payables files upload [options] <path>
```

### `codespar payables batches create`

Create a batch from files (uploaded first) and stated items

```bash
codespar payables batches create [options]
```

| option | what it does |
|---|---|
| `--file <path>` | A file to upload and read (repeatable, up to 20) (default: []) |
| `--file-id <id>` | A file already uploaded (repeatable) (default: []) |
| `--item <spec>` | A stated item, `pix_key=…,amount_minor=5000` or JSON (repeatable); one of pix_key, boleto_line, br_code (default: []) |
| `--idempotency-key <key>` | Your key, so a retry returns the same batch |

### `codespar payables batches get`

Read a batch: items as the rail resolved them, version, list_hash, per-item results

```bash
codespar payables batches get [options] <batchId>
```

### `codespar payables batches update-item`

Complement, correct, exclude or include one item, or choose its way (--rail); bumps the batch version

```bash
codespar payables batches update-item [options] <batchId> <itemId>
```

| option | what it does |
|---|---|
| `--expected-version <n>` | The version you reviewed |
| `--amount <minor>` | Amount in minor units (cents) |
| `--pix-key <key>` | Pix key |
| `--boleto-line <line>` | Boleto digitable line |
| `--br-code <payload>` | Pix copia-e-cola (BR Code) |
| `--description <text>` | Description |
| `--rail <pix\|boleto>` | The way to pay an item printed with a Pix code and a boleto (one bill, paid once) |
| `--exclude` | Leave this item out of the payment |
| `--include` | Put an excluded item back |

### `codespar payables batches pay`

Confirm the exact list (batch version + list_hash) and pay it; repeating resumes and never pays twice

```bash
codespar payables batches pay [options] <batchId>
```

| option | what it does |
|---|---|
| `--batch-version <n>` | The batch version you confirm |
| `--list-hash <hash>` | The list_hash you confirm |
| `--mandate <id>` | Mandate that authorizes the payment (required with an API key) |
| `--idempotency-key <key>` | Defaults to one derived from the batch, version and hash |

### `codespar payables batches discard`

Discard what was never sent; paid, uncertain and in-flight items stay. Sends nothing without --confirm

```bash
codespar payables batches discard [options] <batchId>
```

| option | what it does |
|---|---|
| `--confirm` | You confirmed: the items never sent leave the batch, and a batch with nothing sent is canceled |