## List

`v1.credit_grants.list(CreditGrantListParams**kwargs)  -> SyncCursorPage[CreditGrantListResponse]`

**post** `/v1/credits/listGrants`

List credit grants. This list does not included voided grants.

### Parameters

- **limit:** `int`

  Max number of results that should be returned

- **next\_page:** `str`

  Cursor that indicates where the next page of results should start.

- **credit\_grant\_ids:** `List[str]`

  An array of credit grant IDs. If this is specified, neither credit_type_ids nor customer_ids may be specified.

- **credit\_type\_ids:** `List[str]`

  An array of credit type IDs. This must not be specified if credit_grant_ids is specified.

- **customer\_ids:** `List[str]`

  An array of Metronome customer IDs. This must not be specified if credit_grant_ids is specified.

- **effective\_before:** `Union[str, datetime]`

  Only return credit grants that are effective before this timestamp (exclusive).

- **not\_expiring\_before:** `Union[str, datetime]`

  Only return credit grants that expire at or after this timestamp.

### Returns

- `class CreditGrantListResponse`

  - **id:** `str`

    the Metronome ID of the credit grant

  - **balance:** `Balance`

    The effective balance of the grant as of the end of the customer's current billing period. Expiration deductions will be included only if the grant expires before the end of the current billing period.

    - **effective\_at:** `datetime`

      The end_date of the customer's current billing period.

    - **excluding\_pending:** `float`

      The grant's current balance including all posted deductions. If the grant has expired, this amount will be 0.

    - **including\_pending:** `float`

      The grant's current balance including all posted and pending deductions. If the grant expires before the end of the customer's current billing period, this amount will be 0.

  - **custom\_fields:** `Dict[str, str]`

  - **customer\_id:** `str`

    the Metronome ID of the customer

  - **deductions:** `List[CreditLedgerEntry]`

    - **amount:** `float`

      an amount representing the change to the customer's credit balance

    - **created\_by:** `str`

    - **credit\_grant\_id:** `str`

      the credit grant this entry is related to

    - **effective\_at:** `datetime`

    - **reason:** `str`

    - **running\_balance:** `float`

      the running balance for this credit type at the time of the ledger entry, including all preceding charges

    - **invoice\_id:** `Optional[str]`

      if this entry is a deduction, the Metronome ID of the invoice where the credit deduction was consumed; if this entry is a grant, the Metronome ID of the invoice where the grant's paid_amount was charged

  - **effective\_at:** `datetime`

  - **expires\_at:** `datetime`

  - **grant\_amount:** `GrantAmount`

    the amount of credits initially granted

    - **amount:** `float`

    - **credit\_type:** `CreditTypeData`

      the credit type for the amount granted

  - **name:** `str`

  - **paid\_amount:** `PaidAmount`

    the amount paid for this credit grant

    - **amount:** `float`

    - **credit\_type:** `CreditTypeData`

      the credit type for the amount paid

  - **pending\_deductions:** `List[CreditLedgerEntry]`

    - **amount:** `float`

      an amount representing the change to the customer's credit balance

    - **created\_by:** `str`

    - **credit\_grant\_id:** `str`

      the credit grant this entry is related to

    - **effective\_at:** `datetime`

    - **reason:** `str`

    - **running\_balance:** `float`

      the running balance for this credit type at the time of the ledger entry, including all preceding charges

    - **invoice\_id:** `Optional[str]`

      if this entry is a deduction, the Metronome ID of the invoice where the credit deduction was consumed; if this entry is a grant, the Metronome ID of the invoice where the grant's paid_amount was charged

  - **priority:** `float`

  - **credit\_grant\_type:** `Optional[str]`

  - **invoice\_id:** `Optional[str]`

    the Metronome ID of the invoice with the purchase charge for this credit grant, if applicable

  - **products:** `Optional[List[Product]]`

    The products which these credits will be applied to. (If unspecified, the credits will be applied to charges for all products.)

    - **id:** `str`

    - **name:** `str`

  - **reason:** `Optional[str]`

  - **uniqueness\_key:** `Optional[str]`

    Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error.

### Example

```python
from datetime import datetime
from metronome import Metronome

client = Metronome(
    bearer_token="My Bearer Token",
)
page = client.v1.credit_grants.list(
    credit_type_ids=["2714e483-4ff1-48e4-9e25-ac732e8f24f2"],
    customer_ids=["d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "0e5b8609-d901-4992-b394-c3c2e3f37b1c"],
    effective_before=datetime.fromisoformat("2022-02-01T00:00:00"),
    not_expiring_before=datetime.fromisoformat("2022-02-01T00:00:00"),
)
page = page.data[0]
print(page.id)
```