List

API Reference

Credit Grants

List credit grants

client.v1.creditGrants.list(?, ?): CursorPage<>

post/v1/credits/listGrants

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

Parameters

params

Hide ParametersShow Parameters

limitnumber

optional

Query param: Max number of results that should be returned

minimum1

maximum100

next_pagestring

optional

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

credit_grant_idsarray

optional

Array<string>

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

credit_type_idsarray

optional

Array<string>

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

customer_idsarray

optional

Array<string>

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

effective_beforestring

optional

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

formatdate-time

not_expiring_beforestring

optional

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

formatdate-time

Returns

CreditGrantListResponse

Hide ParametersShow Parameters

idstring

the Metronome ID of the credit grant

formatuuid

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.

Hide ParametersShow Parameters

effective_atstring

The end_date of the customer's current billing period.

formatdate-time

excluding_pendingnumber

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

including_pendingnumber

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_fieldsRecord<string, string>

customer_idstring

the Metronome ID of the customer

formatuuid

deductionsarray

Array<>

Hide ParametersShow Parameters

amountnumber

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

created_bystring

credit_grant_idstring

the credit grant this entry is related to

formatuuid

effective_atstring

formatdate-time

reasonstring

running_balancenumber

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

invoice_idunion

optional

string | null

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_atstring

formatdate-time

expires_atstring

formatdate-time

grant_amount

the amount of credits initially granted

Hide ParametersShow Parameters

amountnumber

credit_type

the credit type for the amount granted

namestring

paid_amount

the amount paid for this credit grant

Hide ParametersShow Parameters

amountnumber

credit_type

the credit type for the amount paid

pending_deductionsarray

Array<>

Hide ParametersShow Parameters

amountnumber

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

created_bystring

credit_grant_idstring

the credit grant this entry is related to

formatuuid

effective_atstring

formatdate-time

reasonstring

running_balancenumber

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

invoice_idunion

optional

string | null

formatuuid

prioritynumber

credit_grant_typeunion

optional

string | null

invoice_idunion

optional

string | null

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

formatuuid

productsarray

optional

Array<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

idstring

namestring

reasonunion

optional

string | null

uniqueness_keyunion

optional

string | null

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

import Metronome from '@metronome/sdk';

const client = new Metronome({
  bearerToken: 'My Bearer Token',
});

// Automatically fetches more pages as needed.
for await (const creditGrantListResponse of client.v1.creditGrants.list({
  credit_type_ids: ['2714e483-4ff1-48e4-9e25-ac732e8f24f2'],
  customer_ids: ['d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc', '0e5b8609-d901-4992-b394-c3c2e3f37b1c'],
  effective_before: '2022-02-01T00:00:00Z',
  not_expiring_before: '2022-02-01T00:00:00Z',
})) {
  console.log(creditGrantListResponse.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"
}