# Pix Pull Subscription

An Invoice Pull Subscription is a recurring payment agreement between a payer and a receiver, authorized through the Pix Automatic infrastructure. Once active, it allows the receiver to periodically trigger automatic debits by issuing invoices that match the agreed conditions such as amount, frequency, and billing cycle without requiring new consent for each transaction.

You can use asynchronous webhooks to monitor status changes.

### The Invoice Pull Subscription object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the subscription. |
| `amount` | INTEGER | Fixed amount to be charged every cycle in cents. |
| `amountMinLimit` | INTEGER | Minimum amount limit in cents. |
| `bacenId` | STRING | Central Bank identifier. |
| `brcode` | STRING | BR Code for the subscription. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `data` | OBJECT | Additional information associated with the subscription. On creation, its content depends on the subscription type: the payer's bank account details for "push", no data for "qrcode", and immediate payment parameters for "qrcodeAndPayment" and "paymentAndOrQrcode". When an active subscription is retrieved or listed, data can contain the payer's accountNumber, bankCode, branchCode and taxId regardless of the authorization journey. |
| `displayDescription` | STRING | Description presented to the payer. |
| `due` | STRING | Due date for payer approval or denial. |
| `end` | STRING | Final date of the subscription. |
| `externalId` | STRING | Unique external ID to prevent duplicate subscriptions. |
| `interval` | STRING | Cycle definition. Options: "week", "month", "quarter", "semester", "year". |
| `name` | STRING | Debtor full name. |
| `pullMode` | STRING | Defines if pull requests are automatic or manual. |
| `pullRetryLimit` | INTEGER | Number of retries allowed. Options: 0, 3. |
| `referenceCode` | STRING | Unique reference code for the contract. |
| `start` | STRING | Expected date to settle first pull request. |
| `status` | STRING | Current subscription status. |
| `tags` | LIST OF STRINGS | Tags associated with the subscription. |
| `taxId` | STRING | Debtor CPF or CNPJ. |
| `type` | STRING | Subscription journey type. Options: "push", "qrcode", "qrcodeAndPayment", "paymentAndOrQrcode". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Invoice Pull Subscriptions

`POST /v2/invoice-pull-subscription`

Use this route to create new invoice pull subscriptions.

**Data by authorization journey**

The type of the subscription defines the authorization journey and, with it, the content of the data object. You always inform it in the data property of the subscription, following the naming conventions of each SDK.

| Journey | type | data |
| --- | --- | --- |
| 1st: push notification | push | Required. Bank account details of the payer. |
| 2nd: QR Code with direct authorization | qrcode | Not required. It can be omitted. |
| 3rd: QR Code with authorization upon payment | qrcodeAndPayment | Required. Parameters of the immediate payment. |
| 4th: billing QR Code with authorization offer | paymentAndOrQrcode | Required. Parameters of the immediate payment. |

For **push**, data carries the bank account of the payer. Every field is a string and all of them are required:

| Field | Type | Tag | Description |
| --- | --- | --- | --- |
| accountNumber | STRING | REQUIRED | Account number of the payer. Example: "5647143184367616". |
| branchCode | STRING | REQUIRED | Branch code of the payer. Example: "0001". |
| bankCode | STRING | REQUIRED | ISPB of the institution of the payer. Example: "20018183". |
| taxId | STRING | REQUIRED | CPF or CNPJ of the payer. Example: "012.345.678-90". |

```
{
    "subscriptions": [
        {
            "type": "push",
            "amount": 1000000,
            "interval": "month",
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "start": "2025-09-14",
            "data": {
                "accountNumber": "5647143184367616",
                "branchCode": "0001",
                "bankCode": "20018183",
                "taxId": "012.345.678-90"
            }
        }
    ]
}
```

For **qrcodeAndPayment** and **paymentAndOrQrcode**, data carries the parameters of the immediate payment. The fields below follow the same rules as the ones of an Invoice:

| Field | Type | Tag | Description |
| --- | --- | --- | --- |
| amount | INTEGER | REQUIRED | Amount of the immediate payment in cents. Example: 20000 (R$200.00). |
| due | STRING | OPTIONAL | Due datetime of the immediate payment in ISO 8601. Example: "2027-05-31T02:59:59.999999+00:00". Default value: 2 days after creation. |
| expiration | INTEGER | OPTIONAL | Time in seconds counted from the due datetime until the invoice expires. Default value: 5097600 (59 days). Inform 0 so that the invoice expires automatically after its due date. |
| fine | FLOAT | OPTIONAL | Fixed percentage over the amount of the invoice, charged when the payment occurs after the due datetime. Example: 2.5 means 2.5%. Default value: 2.00 (2%). |
| interest | FLOAT | OPTIONAL | Monthly interest percentage charged when it is paid after the due datetime. Example: 5 means 5% per month. Default value: 1.00 (1%). |

```
{
    "subscriptions": [
        {
            "type": "qrcodeAndPayment",
            "amount": 1000000,
            "interval": "month",
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "start": "2025-09-14",
            "data": {
                "amount": 20000,
                "due": "2027-05-31T02:59:59.999999+00:00",
                "expiration": 0,
                "fine": 2.5,
                "interest": 5
            }
        }
    ]
}
```

```
{
    "subscriptions": [
        {
            "type": "paymentAndOrQrcode",
            "amount": 1000000,
            "interval": "month",
            "pullMode": "manual",
            "pullRetryLimit": 3,
            "start": "2025-09-14",
            "data": {
                "amount": 20000,
                "due": "2027-05-31T02:59:59.999999+00:00",
                "expiration": 0,
                "fine": 2.5,
                "interest": 5
            }
        }
    ]
}
```

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `displayDescription` | OPTIONAL | Description to be presented to the payer. |
| `externalId` | OPTIONAL | Safe string that must be unique among all your Invoice PullSubscriptions to prevent duplicates. |
| `interval` | REQUIRED | Cycle definition of the Invoice Pull Requests. Options are "week", "month", "quarter", "semester" and "year". |
| `name` | OPTIONAL | Name of the debtor. |
| `pullMode` | REQUIRED | Defines if the invoice pull requests will be made automatically by Stark Bank or manually by the company. |
| `pullRetryLimit` | REQUIRED | Defines how many times the receiver is able to create Invoice Pull Requests for retries. Options are "0" and "3". |
| `referenceCode` | OPTIONAL | Safe string that must be unique among all your Pix Subscriptions and represent a contract. |
| `start` | REQUIRED | Expected date to settle the first Invoice Pull Request. |
| `taxId` | OPTIONAL | Tax id of the debtor. |
| `type` | REQUIRED | Subscription journey type. Options: "push", "qrcode", "qrcodeAndPayment" or "paymentAndOrQrcode". |
| `amount` | CONDITIONALLY REQUIRED | Fixed amount to be charged every cycle. Required if the subscription has a fixed amount, and never sent together with amountMinLimit. Minimum is 1 (R$0.01). |
| `amountMinLimit` | CONDITIONALLY REQUIRED | Minimum amount limit that the payer can set to be charged every cycle. Required if the subscription has a variable amount, and never sent together with amount. Minimum is 1 (R$0.01). |
| `data` | CONDITIONALLY REQUIRED | Additional data required by some types of invoice pull subscription. On creation, it is required for the **push**, **qrcodeAndPayment** and **paymentAndOrQrcode** types, and not required for the **qrcode** type. For the **push** type, it sets the bank account details of the payer, with accountNumber, branchCode, bankCode and taxId as required strings. For the **qrcodeAndPayment** or **paymentAndOrQrcode** types, it sets the immediate payment parameters: amount in cents is required, while due in ISO 8601 (default: 2 days after creation), expiration in seconds (default 5097600, 59 days), fine as a fixed percentage (default 2.00) and interest as a monthly percentage (default 1.00) are optional. This parameter only defines what you send on creation. When an active subscription is later retrieved or listed, the data returned in the response can contain the payer's accountNumber, bankCode, branchCode and taxId regardless of the authorization journey. |
| `due` | OPTIONAL | Due date for answering with an approval or denial. If not provided, defaults to 2 days after creation. |
| `end` | OPTIONAL | Determines the final date of the subscription. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

subscriptions = starkbank.invoicepullsubscription.create([
    starkbank.InvoicePullSubscription(
        amount=0,
        amount_min_limit=5000,
        data={
            "account_number": "9123900000",
            "bank_code": "05097757",
            "branch_code": "1126",
            "tax_id": "20.018.183/0001-80"
        },
        display_description="Dragon Travel Fare",
        external_id="b7e6a2c2-8e2b-4c1a-9e2a-123456789abc",
        interval="month",
        name="John Snow",
        pull_mode="manual",
        pull_retry_limit=3,
        start="2025-09-14T00:00:00Z",
        end="2025-10-14T00:00:00Z",
        reference_code="contract-12345",
        tags=[],
        tax_id="012.345.678-90",
        type="push"
    ),
])

for subscription in subscriptions:
    print(subscription)
```

**Response**

```python
InvoicePullSubscription(
    amount=0,
    amount_min_limit=5000,
    bacen_id=RR2001818320250904xDUK7RgCRT4,
    created=2025-09-04 20:57:33.833777,
    data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
    display_description=Dragon Travel Fare,
    due=2025-09-14 00:00:00,
    end=2025-10-14 00:00:00,
    external_id=b7e6a2c2-8e2b-4c1a-9e2a-123456789abc,
    id=5656565656565656,
    interval=month,
    name=John Snow,
    pull_mode=manual,
    pull_retry_limit=3,
    reference_code=contract-12345,
    start=2025-09-14 00:00:00,
    status=active,
    tags=[],
    tax_id=012.345.678-90,
    type=push,
    updated=2025-09-14 00:00:00
)
```

### List Invoice Pull Subscriptions

`GET /v2/invoice-pull-subscription`

Here you can list and filter all invoice pull subscriptions 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. |
| `expand` | OPTIONAL | List of strings to expand the invoice pull subscription information. Options: "data". |
| `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. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter invoice pull subscriptions by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

subscriptions = starkbank.invoicepullsubscription.query(
    after="2025-09-01",
    before="2025-09-30",
)

for subscription in subscriptions:
    print(subscription)
```

**Response**

```python
InvoicePullSubscription(
    amount=0,
    amount_min_limit=5000,
    bacen_id=RR2001818320250909WDW2JAoiyB2,
    created=2025-09-09 21:42:36.419070,
    data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
    display_description=Dragon Travel Fare,
    due=2025-09-11 21:42:35.878330,
    end=2025-10-14 03:00:00,
    external_id=e0ef6c02-f58e-44cd-b04d-e914d4df9405,
    id=4656724615102464,
    interval=month,
    name=John Snow,
    pull_mode=manual,
    pull_retry_limit=3,
    reference_code=contract-12345,
    start=2025-09-14 03:00:00,
    status=active,
    tags=[],
    tax_id=012.345.678-90,
    type=push,
    updated=2025-09-09 21:42:43.694648
)
```

### Get an Invoice Pull Subscription

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

Get a single invoice pull subscription by its id.

**Parameters**

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

**Request**

```python
import starkbank

subscriptions = starkbank.invoicepullsubscription.get("4656724615102464")

for subscription in subscriptions:
    print(subscription)
```

**Response**

```python
InvoicePullSubscription(
    amount=0,
    amount_min_limit=5000,
    bacen_id=RR2001818320250909WDW2JAoiyB2,
    created=2025-09-09 21:42:36.419070,
    data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
    display_description=Dragon Travel Fare,
    due=2025-09-11 21:42:35.878330,
    end=2025-10-14 03:00:00,
    external_id=e0ef6c02-f58e-44cd-b04d-e914d4df9405,
    id=4656724615102464,
    interval=month,
    name=John Snow,
    pull_mode=manual,
    pull_retry_limit=3,
    reference_code=contract-12345,
    start=2025-09-14 03:00:00,
    status=active,
    tags=[],
    tax_id=012.345.678-90,
    type=push,
    updated=2025-09-09 21:42:43.694648
)
```

### Cancel an Invoice Pull Subscription

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

Cancel an existing invoice pull subscription. The subscription must be with "active" status to be canceled.

**Parameters**

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

**Request**

```python
import starkbank

subscriptions = starkbank.invoicepullsubscription.cancel("4656724615102464")

print(subscription)
```

**Response**

```python
InvoicePullSubscription(
        amount=0,
        amount_min_limit=5000,
        bacen_id=RR2001818320250909WDW2JAoiyB2,
        created=2025-09-09 21:42:36.419070,
        data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
        display_description=Dragon Travel Fare,
        due=2025-09-11 21:42:35.878330,
        end=2025-10-14 03:00:00,
        external_id=e0ef6c02-f58e-44cd-b04d-e914d4df9405,
        id=4656724615102464,
        interval=month,
        name=John Snow,
        pull_mode=manual,
        pull_retry_limit=3,
        reference_code=contract-12345,
        start=2025-09-14 03:00:00,
        status=active,
        tags=[],
        tax_id=012.345.678-90,
        type=push,
        updated=2025-09-09 21:42:43.694648
)
```

### List Invoice Pull Subscription Logs

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

Get a paged list of invoice pull subscription 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. |
| `subscriptionIds` | OPTIONAL | List of strings to get specific entities by ids. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `types` | OPTIONAL | Filter logs by log types. |

**Request**

```python
import starkbank

logs = starkbank.invoicepullsubscription.log.query(
    after="2025-09-01",
    before="2025-09-30",
)

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

**Response**

```python
Log(
    created=2025-09-09 21:58:09.963082,
    errors=[],
    id=5631191491280896,
    subscription=InvoicePullSubscription(
            amount=1000000,
            amount_min_limit=5000,
            bacen_id=RR2001818320250909fxSoQw3VO04,
            created=2025-09-09 21:58:03.557191,
            data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
            display_description=Dragon Travel Fare,
            due=2025-09-11 21:58:02.951121,
            end=2025-10-14 03:00:00,
            external_id=f4a4c70b-bf5a-400d-8eae-685128691645z,
            id=4582433332658176,
            interval=month,
            name=John Snow,
            pull_mode=manual,
            pull_retry_limit=3,
            reference_code=contract-12345,
            start=2025-09-14 03:00:00,
            status=active,
            tags=[],
            tax_id=012.345.678-90,
            type=push,
            updated=2025-09-09 21:58:11.552600
    ),
    type=confirmed
)
```

### Get an Invoice Pull Subscription Log

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

Get a single invoice pull subscription log by its id.

**Parameters**

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

**Request**

```python
import starkbank

logs = starkbank.invoicepullsubscription.log.get("5631191491280896")

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

**Response**

```python
Log(
    created=2025-09-09 21:58:09.963082,
    errors=[],
    id=5631191491280896,
    subscription=InvoicePullSubscription(
            amount=1000000,
            amount_min_limit=5000,
            bacen_id=RR2001818320250909fxSoQw3VO04,
            created=2025-09-09 21:58:03.557191,
            data={'accountNumber': '9123900000', 'bankCode': '05097757', 'branchCode': '1126', 'taxId': '20.018.183/0001-80'},
            display_description=Dragon Travel Fare,
            due=2025-09-11 21:58:02.951121,
            end=2025-10-14 03:00:00,
            external_id=f4a4c70b-bf5a-400d-8eae-685128691645z,
            id=4582433332658176,
            interval=month,
            name=John Snow,
            pull_mode=manual,
            pull_retry_limit=3,
            reference_code=contract-12345,
            start=2025-09-14 03:00:00,
            status=active,
            tags=[],
            tax_id=012.345.678-90,
            type=push,
            updated=2025-09-09 21:58:11.552600
    ),
    type=confirmed
)
```

## 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-subscription-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/invoice-pull-subscription-node.md)
- [PHP](https://docs.starkbank.com/api/v2/invoice-pull-subscription-php.md)
- [Java](https://docs.starkbank.com/api/v2/invoice-pull-subscription-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/invoice-pull-subscription-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/invoice-pull-subscription-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/invoice-pull-subscription-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/invoice-pull-subscription-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/invoice-pull-subscription-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/invoice-pull-subscription-curl.md)