List

API Reference

V1

Credit Grants

List credit grants

v1.credit_grants.list(CreditGrantListParams**kwargs) -> SyncCursorPage[idstrbalanceBalancecustom_fieldsDict[str, str]customer_idstrdeductionslisteffective_atdatetimeexpires_atdatetimegrant_amountGrantAmountnamestrpaid_amountPaidAmountpending_deductionslistpriorityfloatcredit_grant_typestrinvoice_idstrproductslistreasonstruniqueness_keystrCreditGrantListResponse]

post/v1/credits/listGrants

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

Parameters

limitint

optional

Max number of results that should be returned

minimum1

maximum100

next_pagestr

optional

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

credit_grant_idslist

optional

List[str]

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

credit_type_idslist

optional

List[str]

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

customer_idslist

optional

List[str]

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

effective_beforeunion

optional

Union[str, datetime]

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

formatdate-time

not_expiring_beforeunion

optional

Union[str, datetime]

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

formatdate-time

Returns

CreditGrantListResponseclass

Hide ParametersShow Parameters

idstr

the Metronome ID of the credit grant

formatuuid

balanceeffective_atdatetimeexcluding_pendingfloatincluding_pendingfloatBalance

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.

Hide ParametersShow Parameters

effective_atdatetime

The end_date of the customer's current billing period.

formatdate-time

excluding_pendingfloat

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

including_pendingfloat

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_fieldsDict[str, str]

Dict[str, str]

customer_idstr

the Metronome ID of the customer

formatuuid

deductionslist

List[amountfloatcreated_bystrcredit_grant_idstreffective_atdatetimereasonstrrunning_balancefloatinvoice_idstrCreditLedgerEntry]

Hide ParametersShow Parameters

amountfloat

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

created_bystr

credit_grant_idstr

the credit grant this entry is related to

formatuuid

effective_atdatetime

formatdate-time

reasonstr

running_balancefloat

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

invoice_idstr

optional

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

formatuuid

effective_atdatetime

formatdate-time

expires_atdatetime

formatdate-time

grant_amountamountfloatcredit_typeCreditTypeDataGrantAmount

the amount of credits initially granted

Hide ParametersShow Parameters

amountfloat

credit_typeidstrnamestrCreditTypeData

the credit type for the amount granted

namestr

paid_amountamountfloatcredit_typeCreditTypeDataPaidAmount

the amount paid for this credit grant

Hide ParametersShow Parameters

amountfloat

credit_typeidstrnamestrCreditTypeData

the credit type for the amount paid

pending_deductionslist

List[amountfloatcreated_bystrcredit_grant_idstreffective_atdatetimereasonstrrunning_balancefloatinvoice_idstrCreditLedgerEntry]

Hide ParametersShow Parameters

amountfloat

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

created_bystr

credit_grant_idstr

the credit grant this entry is related to

formatuuid

effective_atdatetime

formatdate-time

reasonstr

running_balancefloat

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

invoice_idstr

optional

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

formatuuid

priorityfloat

credit_grant_typestr

optional

invoice_idstr

optional

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

formatuuid

productslist

optional

Optional[List[Product]]

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

Hide ParametersShow Parameters

idstr

namestr

reasonstr

optional

uniqueness_keystr

optional

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.

minLength1

maxLength128

HTTPTypeScriptPythonGoRubyTerraform

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)

200 Example

{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "balance": {
        "effective_at": "2019-12-27T18:11:19.117Z",
        "excluding_pending": 0,
        "including_pending": 0
      },
      "custom_fields": {
        "foo": "string"
      },
      "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "deductions": [
        {
          "amount": 0,
          "created_by": "created_by",
          "credit_grant_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "effective_at": "2019-12-27T18:11:19.117Z",
          "reason": "Automated invoice deduction",
          "running_balance": 0,
          "invoice_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
        }
      ],
      "effective_at": "2019-12-27T18:11:19.117Z",
      "expires_at": "2019-12-27T18:11:19.117Z",
      "grant_amount": {
        "amount": 0,
        "credit_type": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "name": "name"
        }
      },
      "name": "name",
      "paid_amount": {
        "amount": 0,
        "credit_type": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "name": "name"
        }
      },
      "pending_deductions": [
        {
          "amount": 0,
          "created_by": "created_by",
          "credit_grant_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "effective_at": "2019-12-27T18:11:19.117Z",
          "reason": "Automated invoice deduction",
          "running_balance": 0,
          "invoice_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
        }
      ],
      "priority": 0,
      "credit_grant_type": "credit_grant_type",
      "invoice_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "products": [
        {
          "id": "id",
          "name": "name"
        }
      ],
      "reason": "reason",
      "uniqueness_key": "x"
    }
  ],
  "next_page": "next_page"
}