> For the complete documentation index, see [llms.txt](https://6dot50.gitbook.io/6dot50-apis/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://6dot50.gitbook.io/6dot50-apis/pay-api/batches/post-batches.md).

# POST /batches

This operation creates a new payment Batch in DRAFT status.

When creating a new Batch:

1. A unique ID will be returned which can be used for subsequent calls to query and/or modify the Batch.
2. A Batch is created with no Payments. Payments for the batch are added by calling [`POST /batches/{id}/payments`](/6dot50-apis/pay-api/batches/post-batches-id-payments.md).
3. A new batch will be created in a draft status (i.e. statusCode: DRAFT). Batches in draft status are not processed until [`POST /batch/{id}/submit`](/6dot50-apis/pay-api/batches/post-batches-id-submit.md) is called.
4. `externalId` (in the request body) can be supplied to map payment identifiers in an external system. If `externalId` is supplied, then it must be unique.

{% hint style="info" %}
When a batch is in DRAFT status, it can be updated (e.g. name and payment details can be updated) as well as cancelled.
{% endhint %}

### Request

Creating a new Batch requires the following payload:

```
{
  "name": "string",
  "externalId": "string"
}
```

<table><thead><tr><th width="186">Header</th><th width="118.33333333333331">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Yes</td><td>Bearer token from <a href="/6dot50-apis/pay-api/authentication.md"><code>/authentication/getToken</code></a></td></tr></tbody></table>

<table><thead><tr><th width="187">Body Field</th><th width="119.33333333333331">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>Yes</td><td>Friendly name to give to the Batch.</td></tr><tr><td><code>externalId</code></td><td>No</td><td>Optional batch identifier that can be supplied by external system for tracing purposes. If supplied, the <strong><code>externalID</code> across all batches must be unique</strong>.</td></tr></tbody></table>

{% code title="Sample Request" %}

```
{
  "name": "Test Batch 1",
  "externalId": "testbatch1"
}
```

{% endcode %}

### Response

If successful, the operation will return a Batch response:

```
{
  "id": "string($guid)",
  "name": "string",
  "externalId": "string",
  "statusCode": "string",
  "createdAt": "string($date-time)"
}
```

<table><thead><tr><th width="178.33333333333331">Field</th><th width="202">Response Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td>string($guid)</td><td>Unique ID for the Batch. Used for subsequent calls to other Batch operations.</td></tr><tr><td><code>name</code></td><td>string</td><td>Name of the batch as supplied in the request.</td></tr><tr><td><code>externalId</code></td><td>string</td><td>External ID of the batch as supplied in the request.</td></tr><tr><td><code>statusCode</code></td><td>string</td><td>Status of the Batch. A new Batch will always have a DRAFT status code.</td></tr><tr><td><code>createdAt</code></td><td>string($date-time)</td><td>Date and time when the Batch was created.</td></tr></tbody></table>

{% code title="Sample Response" %}

```
{
  "id": "b7ccbefd-51e1-4720-81fb-da5700e34e81",
  "name": "Test Batch 1",
  "externalId": "testbatch1",
  "statusCode": "DRAFT",
  "createdAt": "2022-12-13T12:29:39.6332995Z"
}
```

{% endcode %}