# Pix Pull Request

An Invoice Pull Request is a command sent to the payer's bank to trigger the automatic debit of a previously issued invoice linked to an active Invoice Pull Subscription. It confirms the receiver's intent to collect the agreed amount within the current billing cycle and initiates the settlement process through the Pix infrastructure.

You can use asynchronous webhooks to monitor status changes.

### The Invoice Pull Request object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the pull request. |
| `attemptType` | STRING | Type of attempt. Options: "default", "retry". |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `displayDescription` | STRING | Description presented to the payer. |
| `due` | STRING | Expected date of settlement. |
| `externalId` | STRING | Unique external ID for the pull request. |
| `installmentId` | STRING | ID of the installment linked to the pull request. |
| `invoiceId` | STRING | ID of the invoice to be pulled. |
| `status` | STRING | Current pull request status. |
| `subscriptionId` | STRING | ID of the invoice pull subscription. |
| `tags` | LIST OF STRINGS | Tags associated with the pull request. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Invoice Pull Requests

`POST /v2/invoice-pull-request`

Use this route to create new invoice pull requests.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `attemptType` | OPTIONAL | Define the type of attempt, if it is the first one of a billing cycle or if it is a retry. Options: "default", "retry". Default is "default". |
| `due` | REQUIRED | Expected date of settlement. |
| `invoiceId` | REQUIRED | Unique ID of the invoice to be pulled. |
| `subscriptionId` | REQUIRED | Unique ID of the invoice pull subscription. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

requests = starkbank.invoicepullrequest.create([
    starkbank.InvoicePullRequest(
        attempt_type="retry",
        due="2025-09-14",
        invoice_id="6649956664344576",
        subscription_id="4776669403414528",
        tags=[]
    )
])

for request in requests:
    print(request)
```

**Response**

```python
InvoicePullRequest(
    attempt_type=retry,
    created=2025-09-10 18:21:46.579211,
    display_description=,
    due=2025-09-14 03:00:00,
    external_id=c3cb7f72c8d94069adbc52a3b65515a4,
    id=5649587104645120,
    installment_id=5187902950604800,
    invoice_id=6649956664344576,
    status=created,
    subscription_id=4776669403414528,
    tags=[],
    updated=2025-09-10 18:21:46.579216
)
```

### List Invoice Pull Requests

`GET /v2/invoice-pull-request`

Here you can list and filter all invoice pull requests you have made. We return it paged.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `externalIds` | OPTIONAL | List of external IDs linked to the desired pull requests. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `invoiceIds` | OPTIONAL | List of invoice IDs linked to the desired pull requests. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter invoice pull request by the specified status. |
| `subscriptionIds` | OPTIONAL | List of subscription IDs linked to the desired pull requests. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

requests = starkbank.invoicepullrequest.query(
    after="2025-08-01",
    before="2025-08-30",
)

for request in requests:
    print(request)
```

**Response**

```python
InvoicePullRequest(
        attempt_type=default,
        created=2025-08-14 18:23:40.089592,
        display_description=,
        due=2025-08-16 23:59:59,
        external_id=c0a7f183f32e42b9a4cfc5ee997a3455,
        id=4875989783937024,
        installment_id=6381497086902272,
        invoice_id=5192316503457792,
        status=failed,
        subscription_id=4871746087813120,
        tags=[],
        updated=2025-08-17 00:00:07.816140
)
```

### Get an Invoice Pull Request

`GET /v2/invoice-pull-request/:id`

Get a single Invoice Pull Request by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | String used to get the specific invoice pull request by its ID. |

**Request**

```python
import starkbank

requests = starkbank.invoicepullrequest.get("4875989783937024")

for request in requests:
    print(request)
```

**Response**

```python
InvoicePullRequest(
        attempt_type=default,
        created=2025-08-14 18:23:40.089592,
        display_description=,
        due=2025-08-16 23:59:59,
        external_id=c0a7f183f32e42b9a4cfc5ee997a3455,
        id=4875989783937024,
        installment_id=6381497086902272,
        invoice_id=5192316503457792,
        status=failed,
        subscription_id=4871746087813120,
        tags=[],
        updated=2025-08-17 00:00:07.816140
)
```

### Cancel an Invoice Pull Request

`DELETE /v2/invoice-pull-request/:id`

Cancel a single Invoice Pull Request.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the invoice pull request entity. |

**Request**

```python
import starkbank

request = starkbank.invoicepullrequest.cancel("6281065945628672")

print(request)
```

**Response**

```python
InvoicePullRequest(
        attempt_type=default,
        created=2025-09-07 03:00:15.420295,
        display_description=Iron Bank S.A.,
        due=2025-09-09 03:00:00,
        external_id=35ce0f6775fc42f8942b6142aa9fd9b6,
        id=6281065945628672,
        installment_id=6401171258343424,
        invoice_id=4616495631958016,
        status=scheduled,
        subscription_id=5692449980678144,
        tags=[],
        updated=2025-09-07 03:00:57.777005
)
```

### List Invoice Pull Request Logs

`GET /v2/invoice-pull-request/log`

Get a paged list of invoice pull request logs. A log tracks a change in the entity according to its life cycle.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `requestIds` | OPTIONAL | List of strings to get specific entities by ids. |
| `types` | OPTIONAL | Filter payment requests by the specified types. Example: confirmed |

**Request**

```python
import starkbank

logs = starkbank.invoicepullrequest.log.get(
    after="2025-08-01",
    before="2025-08-30"
)

for log in logs:
    print(log)
```

**Response**

```python
Log(
        created=2025-08-17 00:00:05.640702,
        errors=[],
        id=5439643239579648,
        request=InvoicePullRequest(
                attempt_type=default,
                created=2025-08-14 18:23:40.089592,
                display_description=,
                due=2025-08-16 23:59:59,
                external_id=c0a7f183f32e42b9a4cfc5ee997a3455,
                id=4875989783937024,
                installment_id=6381497086902272,
                invoice_id=5192316503457792,
                status=failed,
                subscription_id=4871746087813120,
                tags=[],
                updated=2025-08-17 00:00:07.852905
        ),
        type=failed
)
```

### Get an Invoice Pull Request Log

`GET /v2/invoice-pull-request/log/:id`

Get a single invoice pull request log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | String used to get the specific invoice pull request log by its ID. |

**Request**

```python
import starkbank

logs = starkbank.invoicepullrequest.log.get("5439643239579648")

for log in logs:
    print(log)
```

**Response**

```python
Log(
        created=2025-08-17 00:00:05.640702,
        errors=[],
        id=5439643239579648,
        request=InvoicePullRequest(
                attempt_type=default,
                created=2025-08-14 18:23:40.089592,
                display_description=,
                due=2025-08-16 23:59:59,
                external_id=c0a7f183f32e42b9a4cfc5ee997a3455,
                id=4875989783937024,
                installment_id=6381497086902272,
                invoice_id=5192316503457792,
                status=failed,
                subscription_id=4871746087813120,
                tags=[],
                updated=2025-08-17 00:00:07.852905
        ),
        type=failed
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkbank.com/api/v2/invoice-pull-request-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/invoice-pull-request-node.md)
- [PHP](https://docs.starkbank.com/api/v2/invoice-pull-request-php.md)
- [Java](https://docs.starkbank.com/api/v2/invoice-pull-request-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/invoice-pull-request-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/invoice-pull-request-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/invoice-pull-request-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/invoice-pull-request-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/invoice-pull-request-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/invoice-pull-request-curl.md)