Skip to content
Metronome Docs
  • Auto
  • Light
  • Dark
Talk to an expert

List

API Reference
V1
Credit Grants
List credit grants
client.V1.CreditGrants.List(ctx, params) (*CursorPage[IDstringBalanceV1CreditGrantListResponseBalanceCustomFieldsmapCustomerIDstringDeductionsarrayEffectiveAtTimeExpiresAtTimeGrantAmountV1CreditGrantListResponseGrantAmountNamestringPaidAmountV1CreditGrantListResponsePaidAmountPendingDeductionsarrayPriorityfloat64CreditGrantTypestringInvoiceIDstringProductsarrayReasonstringUniquenessKeystringV1CreditGrantListResponse], error)
post/v1/credits/listGrants

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

Parameters
paramsLimitfieldNextPagefieldCreditGrantIDsfieldCreditTypeIDsfieldCustomerIDsfieldEffectiveBeforefieldNotExpiringBeforefieldV1CreditGrantListParams
Hide ParametersShow Parameters
Limitfield
optional
param.Field[int64]

Query param: Max number of results that should be returned

minimum1
maximum100
NextPagefield
optional
param.Field[string]

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

CreditGrantIDsfield
optional
param.Field[[]string]

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

CreditTypeIDsfield
optional
param.Field[[]string]

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

CustomerIDsfield
optional
param.Field[[]string]

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

EffectiveBeforefield
optional
param.Field[Time]

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

formatdate-time
NotExpiringBeforefield
optional
param.Field[Time]

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

formatdate-time
Returns
V1CreditGrantListResponsestruct
Hide ParametersShow Parameters
IDstring

the Metronome ID of the credit grant

formatuuid
BalanceEffectiveAtTimeExcludingPendingfloat64IncludingPendingfloat64V1CreditGrantListResponseBalance

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
EffectiveAtTime

The end_date of the customer's current billing period.

formatdate-time
ExcludingPendingfloat64

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

IncludingPendingfloat64

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.

CustomFieldsmap
map[string, string]
CustomerIDstring

the Metronome ID of the customer

formatuuid
Deductionsarray
[]Amountfloat64CreatedBystringCreditGrantIDstringEffectiveAtTimeReasonstringRunningBalancefloat64InvoiceIDstringCreditLedgerEntry
Hide ParametersShow Parameters
Amountfloat64

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

CreatedBystring
CreditGrantIDstring

the credit grant this entry is related to

formatuuid
EffectiveAtTime
formatdate-time
Reasonstring
RunningBalancefloat64

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

InvoiceIDstring
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
EffectiveAtTime
formatdate-time
ExpiresAtTime
formatdate-time
GrantAmountAmountfloat64CreditTypeCreditTypeDataV1CreditGrantListResponseGrantAmount

the amount of credits initially granted

Hide ParametersShow Parameters
Amountfloat64
CreditTypeIDstringNamestringCreditTypeData

the credit type for the amount granted

Namestring
PendingDeductionsarray
[]Amountfloat64CreatedBystringCreditGrantIDstringEffectiveAtTimeReasonstringRunningBalancefloat64InvoiceIDstringCreditLedgerEntry
Hide ParametersShow Parameters
Amountfloat64

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

CreatedBystring
CreditGrantIDstring

the credit grant this entry is related to

formatuuid
EffectiveAtTime
formatdate-time
Reasonstring
RunningBalancefloat64

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

InvoiceIDstring
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
Priorityfloat64
CreditGrantTypestring
optional
InvoiceIDstring
optional

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

formatuuid
Productsarray
optional
[]V1CreditGrantListResponseProduct

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
UniquenessKeystring
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
package main

import (
  "context"
  "fmt"
  "time"

  "github.com/Metronome-Industries/metronome-go"
  "github.com/Metronome-Industries/metronome-go/option"
)

func main() {
  client := metronome.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  page, err := client.V1.CreditGrants.List(context.TODO(), metronome.V1CreditGrantListParams{
    CreditTypeIDs: metronome.F([]string{"2714e483-4ff1-48e4-9e25-ac732e8f24f2"}),
    CustomerIDs: metronome.F([]string{"d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc", "0e5b8609-d901-4992-b394-c3c2e3f37b1c"}),
    EffectiveBefore: metronome.F(time.Now()),
    NotExpiringBefore: metronome.F(time.Now()),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", 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"
}