List

API Reference

V1

Credit Grants

List credit grants

v1.credit_grants.list(**kwargs) -> CursorPage<idStringbalanceobjectcustom_fieldshashcustomer_idStringdeductionsarrayeffective_atTimeexpires_atTimegrant_amountobjectnameStringpaid_amountobjectpending_deductionsarraypriorityFloatcredit_grant_typeStringinvoice_idStringproductsarrayreasonStringuniqueness_keyStringCreditGrantListResponse>

post/v1/credits/listGrants

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

Parameters

limitInteger

optional

Max number of results that should be returned

minimum1

maximum100

next_pageString

optional

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

credit_grant_idsarray

optional

Array[String]

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]

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

customer_idsarray

optional

Array[String]

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

effective_beforeTime

optional

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

formatdate-time

not_expiring_beforeTime

optional

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

formatdate-time

Returns

CreditGrantListResponseclass

Hide ParametersShow Parameters

idString

the Metronome ID of the credit grant

formatuuid

balanceobject

{ effective_at, excluding_pending, including_pending}

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_atTime

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_fieldshash

Hash[Symbol, String]

customer_idString

the Metronome ID of the customer

formatuuid

deductionsarray

Array[amountFloatcreated_byStringcredit_grant_idStringeffective_atTimereasonStringrunning_balanceFloatinvoice_idStringCreditLedgerEntry]

Hide ParametersShow Parameters

amountFloat

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_atTime

formatdate-time

reasonString

running_balanceFloat

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

invoice_idString

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_atTime

formatdate-time

expires_atTime

formatdate-time

grant_amountobject

{ amount, credit_type}

the amount of credits initially granted

Hide ParametersShow Parameters

amountFloat

credit_typeidStringnameStringCreditTypeData

the credit type for the amount granted

nameString

paid_amountobject

{ amount, credit_type}

the amount paid for this credit grant

Hide ParametersShow Parameters

amountFloat

credit_typeidStringnameStringCreditTypeData

the credit type for the amount paid

pending_deductionsarray

Array[amountFloatcreated_byStringcredit_grant_idStringeffective_atTimereasonStringrunning_balanceFloatinvoice_idStringCreditLedgerEntry]

Hide ParametersShow Parameters

amountFloat

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_atTime

formatdate-time

reasonString

running_balanceFloat

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

invoice_idString

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_typeString

optional

invoice_idString

optional

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

formatuuid

productsarray

optional

Array[{ id, name}]

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

reasonString

optional

uniqueness_keyString

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

require "metronome_sdk"

metronome = MetronomeSDK::Client.new(bearer_token: "My Bearer Token")

page = metronome.v1.credit_grants.list

puts(page)

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"
}