List Balances

API Reference

Contracts

List balances

client.V1.Contracts.ListBalances(ctx, body) (*, error)

post/v1/contracts/customerBalances/list

List balances (commits and credits).

Parameters

body

Hide ParametersShow Parameters

CustomerIDfield

param.Field[string]

formatuuid

IDfield

optional

param.Field[string]

formatuuid

CoveringDatefield

optional

param.Field[Time]

Return only balances that have access schedules that "cover" the provided date

formatdate-time

EffectiveBeforefield

optional

param.Field[Time]

Include only balances that have any access before the provided date (exclusive)

formatdate-time

IncludeArchivedfield

optional

param.Field[bool]

Include archived credits and credits from archived contracts.

IncludeBalancefield

optional

param.Field[bool]

Include the balance of credits and commits in the response. Setting this flag may cause the query to be slower.

IncludeContractBalancesfield

optional

param.Field[bool]

Include balances on the contract level.

IncludeLedgersfield

optional

param.Field[bool]

Include ledgers in the response. Setting this flag may cause the query to be slower.

Limitfield

optional

param.Field[int64]

The maximum number of commits to return. Defaults to 25.

minimum1

maximum25

NextPagefield

optional

param.Field[string]

The next page token from a previous response.

StartingAtfield

optional

param.Field[Time]

Include only balances that have any access on or after the provided date

formatdate-time

Returns

V1ContractListBalancesResponsestruct

Hide ParametersShow Parameters

Dataarray

[]V1ContractListBalancesResponseData

Hide ParametersShow Parameters

Commitstruct

Hide ParametersShow Parameters

IDstring

formatuuid

Product

Hide ParametersShow Parameters

IDstring

formatuuid

Namestring

Type

Hide ParametersShow Parameters

CommitTypePrepaidconst

"PREPAID"

CommitTypePostpaidconst

"POSTPAID"

AccessSchedule

optional

The schedule that the customer will gain access to the credits purposed with this commit.

Amountfloat64

optional

(DEPRECATED) Use access_schedule + invoice_schedule instead.

ApplicableContractIDsarray

optional

[]string

ApplicableProductIDsarray

optional

[]string

ApplicableProductTagsarray

optional

[]string

ArchivedAtTime

optional

RFC 3339 timestamp indicating when the commit was archived. If not provided, the commit is not archived.

formatdate-time

Balancefloat64

optional

The current balance of the credit or commit. This balance reflects the amount of credit or commit that the customer has access to use at this moment - thus, expired and upcoming credit or commit segments contribute 0 to the balance. The balance will match the sum of all ledger entries with the exception of the case where the sum of negative manual ledger entries exceeds the positive amount remaining on the credit or commit - in that case, the balance will be 0. All manual ledger entries associated with active credit or commit segments are included in the balance, including future-dated manual ledger entries.

Contract

optional

Hide ParametersShow Parameters

IDstring

formatuuid

CustomFieldsmap

optional

map[string, string]

Descriptionstring

optional

HierarchyConfiguration

optional

Optional configuration for commit hierarchy access control

Hide ParametersShow Parameters

ChildAccess

Hide ParametersShow Parameters

CommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessAllstruct

Hide ParametersShow Parameters

Type

Hide ParametersShow Parameters

CommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessAllTypeAllconst

"ALL"

CommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessNonestruct

Hide ParametersShow Parameters

Type

Hide ParametersShow Parameters

CommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessNoneTypeNoneconst

"NONE"

CommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessContractIDsstruct

Hide ParametersShow Parameters

ContractIDsarray

[]string

Type

Hide ParametersShow Parameters

CommitHierarchyConfigurationChildAccessCommitHierarchyChildAccessContractIDsTypeContractIDsconst

"CONTRACT_IDS"

InvoiceContract

optional

The contract that this commit will be billed on.

Hide ParametersShow Parameters

IDstring

formatuuid

InvoiceSchedule

optional

The schedule that the customer will be invoiced for this commit.

Ledgerarray

optional

[]CommitLedger

A list of ordered events that impact the balance of a commit. For example, an invoice deduction or a rollover.

Hide ParametersShow Parameters

CommitLedgerPrepaidCommitSegmentStartLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPrepaidCommitSegmentStartLedgerEntryTypePrepaidCommitSegmentStartconst

"PREPAID_COMMIT_SEGMENT_START"

CommitLedgerPrepaidCommitAutomatedInvoiceDeductionLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

InvoiceIDstring

formatuuid

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPrepaidCommitAutomatedInvoiceDeductionLedgerEntryTypePrepaidCommitAutomatedInvoiceDeductionconst

"PREPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION"

ContractIDstring

optional

formatuuid

CommitLedgerPrepaidCommitRolloverLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

NewContractIDstring

formatuuid

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPrepaidCommitRolloverLedgerEntryTypePrepaidCommitRolloverconst

"PREPAID_COMMIT_ROLLOVER"

CommitLedgerPrepaidCommitExpirationLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPrepaidCommitExpirationLedgerEntryTypePrepaidCommitExpirationconst

"PREPAID_COMMIT_EXPIRATION"

CommitLedgerPrepaidCommitCanceledLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

InvoiceIDstring

formatuuid

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPrepaidCommitCanceledLedgerEntryTypePrepaidCommitCanceledconst

"PREPAID_COMMIT_CANCELED"

ContractIDstring

optional

formatuuid

CommitLedgerPrepaidCommitCreditedLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

InvoiceIDstring

formatuuid

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPrepaidCommitCreditedLedgerEntryTypePrepaidCommitCreditedconst

"PREPAID_COMMIT_CREDITED"

ContractIDstring

optional

formatuuid

CommitLedgerPrepaidCommitSeatBasedAdjustmentLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPrepaidCommitSeatBasedAdjustmentLedgerEntryTypePrepaidCommitSeatBasedAdjustmentconst

"PREPAID_COMMIT_SEAT_BASED_ADJUSTMENT"

CommitLedgerPostpaidCommitInitialBalanceLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPostpaidCommitInitialBalanceLedgerEntryTypePostpaidCommitInitialBalanceconst

"POSTPAID_COMMIT_INITIAL_BALANCE"

CommitLedgerPostpaidCommitAutomatedInvoiceDeductionLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

InvoiceIDstring

formatuuid

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPostpaidCommitAutomatedInvoiceDeductionLedgerEntryTypePostpaidCommitAutomatedInvoiceDeductionconst

"POSTPAID_COMMIT_AUTOMATED_INVOICE_DEDUCTION"

ContractIDstring

optional

formatuuid

CommitLedgerPostpaidCommitRolloverLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

NewContractIDstring

formatuuid

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPostpaidCommitRolloverLedgerEntryTypePostpaidCommitRolloverconst

"POSTPAID_COMMIT_ROLLOVER"

CommitLedgerPostpaidCommitTrueupLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

InvoiceIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPostpaidCommitTrueupLedgerEntryTypePostpaidCommitTrueupconst

"POSTPAID_COMMIT_TRUEUP"

ContractIDstring

optional

formatuuid

CommitLedgerPrepaidCommitManualLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

Reasonstring

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPrepaidCommitManualLedgerEntryTypePrepaidCommitManualconst

"PREPAID_COMMIT_MANUAL"

CommitLedgerPostpaidCommitManualLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

Reasonstring

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPostpaidCommitManualLedgerEntryTypePostpaidCommitManualconst

"POSTPAID_COMMIT_MANUAL"

CommitLedgerPostpaidCommitExpirationLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CommitLedgerPostpaidCommitExpirationLedgerEntryTypePostpaidCommitExpirationconst

"POSTPAID_COMMIT_EXPIRATION"

Namestring

optional

NetsuiteSalesOrderIDstring

optional

This field's availability is dependent on your client's configuration.

Priorityfloat64

optional

If multiple credits or commits are applicable, the one with the lower priority will apply first.

RateType

optional

Hide ParametersShow Parameters

CommitRateTypeCommitRateconst

"COMMIT_RATE"

CommitRateTypeListRateconst

"LIST_RATE"

RolledOverFrom

optional

Hide ParametersShow Parameters

CommitIDstring

formatuuid

ContractIDstring

formatuuid

RolloverFractionfloat64

optional

SalesforceOpportunityIDstring

optional

This field's availability is dependent on your client's configuration.

Specifiersarray

optional

[]CommitSpecifier

List of filters that determine what kind of customer usage draws down a commit or credit. A customer's usage needs to meet the condition of at least one of the specifiers to contribute to a commit's or credit's drawdown.

Hide ParametersShow Parameters

PresentationGroupValuesmap

optional

map[string, string]

PricingGroupValuesmap

optional

map[string, string]

ProductIDstring

optional

If provided, the specifier will only apply to the product with the specified ID.

formatuuid

ProductTagsarray

optional

[]string

If provided, the specifier will only apply to products with all the specified tags.

UniquenessKeystring

optional

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

minLength1

maxLength128

Creditstruct

Hide ParametersShow Parameters

IDstring

formatuuid

Product

Hide ParametersShow Parameters

IDstring

formatuuid

Namestring

Type

Hide ParametersShow Parameters

CreditTypeCreditconst

"CREDIT"

AccessSchedule

optional

The schedule that the customer will gain access to the credits.

ApplicableContractIDsarray

optional

[]string

ApplicableProductIDsarray

optional

[]string

ApplicableProductTagsarray

optional

[]string

Balancefloat64

optional

Contract

optional

Hide ParametersShow Parameters

IDstring

formatuuid

CustomFieldsmap

optional

map[string, string]

Descriptionstring

optional

HierarchyConfiguration

optional

Optional configuration for credit hierarchy access control

Hide ParametersShow Parameters

ChildAccess

Hide ParametersShow Parameters

CreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessAllstruct

Hide ParametersShow Parameters

Type

Hide ParametersShow Parameters

CreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessAllTypeAllconst

"ALL"

CreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessNonestruct

Hide ParametersShow Parameters

Type

Hide ParametersShow Parameters

CreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessNoneTypeNoneconst

"NONE"

CreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessContractIDsstruct

Hide ParametersShow Parameters

ContractIDsarray

[]string

Type

Hide ParametersShow Parameters

CreditHierarchyConfigurationChildAccessCommitHierarchyChildAccessContractIDsTypeContractIDsconst

"CONTRACT_IDS"

Ledgerarray

optional

[]CreditLedger

A list of ordered events that impact the balance of a credit. For example, an invoice deduction or an expiration.

Hide ParametersShow Parameters

CreditLedgerCreditSegmentStartLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CreditLedgerCreditSegmentStartLedgerEntryTypeCreditSegmentStartconst

"CREDIT_SEGMENT_START"

CreditLedgerCreditAutomatedInvoiceDeductionLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

InvoiceIDstring

formatuuid

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CreditLedgerCreditAutomatedInvoiceDeductionLedgerEntryTypeCreditAutomatedInvoiceDeductionconst

"CREDIT_AUTOMATED_INVOICE_DEDUCTION"

ContractIDstring

optional

formatuuid

CreditLedgerCreditExpirationLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CreditLedgerCreditExpirationLedgerEntryTypeCreditExpirationconst

"CREDIT_EXPIRATION"

CreditLedgerCreditCanceledLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

InvoiceIDstring

formatuuid

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CreditLedgerCreditCanceledLedgerEntryTypeCreditCanceledconst

"CREDIT_CANCELED"

ContractIDstring

optional

formatuuid

CreditLedgerCreditCreditedLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

InvoiceIDstring

formatuuid

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CreditLedgerCreditCreditedLedgerEntryTypeCreditCreditedconst

"CREDIT_CREDITED"

ContractIDstring

optional

formatuuid

CreditLedgerCreditManualLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

Reasonstring

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CreditLedgerCreditManualLedgerEntryTypeCreditManualconst

"CREDIT_MANUAL"

CreditLedgerCreditSeatBasedAdjustmentLedgerEntrystruct

Hide ParametersShow Parameters

Amountfloat64

SegmentIDstring

formatuuid

TimestampTime

formatdate-time

Type

Hide ParametersShow Parameters

CreditLedgerCreditSeatBasedAdjustmentLedgerEntryTypeCreditSeatBasedAdjustmentconst

"CREDIT_SEAT_BASED_ADJUSTMENT"

Namestring

optional

NetsuiteSalesOrderIDstring

optional

This field's availability is dependent on your client's configuration.

Priorityfloat64

optional

If multiple credits or commits are applicable, the one with the lower priority will apply first.

RateType

optional

Hide ParametersShow Parameters

CreditRateTypeCommitRateconst

"COMMIT_RATE"

CreditRateTypeListRateconst

"LIST_RATE"

SalesforceOpportunityIDstring

optional

This field's availability is dependent on your client's configuration.

Specifiersarray

optional

[]CreditSpecifier

Hide ParametersShow Parameters

PresentationGroupValuesmap

optional

map[string, string]

PricingGroupValuesmap

optional

map[string, string]

ProductIDstring

optional

If provided, the specifier will only apply to the product with the specified ID.

formatuuid

ProductTagsarray

optional

[]string

If provided, the specifier will only apply to products with all the specified tags.

UniquenessKeystring

optional

minLength1

maxLength128

NextPagestring

package main

import (
  "context"
  "fmt"

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

func main() {
  client := metronome.NewClient(
    option.WithBearerToken("My Bearer Token"),
  )
  response, err := client.V1.Contracts.ListBalances(context.TODO(), metronome.V1ContractListBalancesParams{
    CustomerID: metronome.F("13117714-3f05-48e5-a6e9-a66093f13b4d"),
    ID: metronome.F("6162d87b-e5db-4a33-b7f2-76ce6ead4e85"),
    IncludeLedgers: metronome.F(true),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Data)
}

200 Example

{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "product": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "name": "name"
      },
      "type": "PREPAID",
      "access_schedule": {
        "schedule_items": [
          {
            "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
            "amount": 0,
            "ending_before": "2019-12-27T18:11:19.117Z",
            "starting_at": "2019-12-27T18:11:19.117Z"
          }
        ],
        "credit_type": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "name": "name"
        }
      },
      "amount": 0,
      "applicable_contract_ids": [
        "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      ],
      "applicable_product_ids": [
        "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      ],
      "applicable_product_tags": [
        "string"
      ],
      "archived_at": "2019-12-27T18:11:19.117Z",
      "balance": 0,
      "contract": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      },
      "custom_fields": {
        "foo": "string"
      },
      "description": "description",
      "hierarchy_configuration": {
        "child_access": {
          "type": "ALL"
        }
      },
      "invoice_contract": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      },
      "invoice_schedule": {
        "credit_type": {
          "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "name": "name"
        },
        "do_not_invoice": true,
        "schedule_items": [
          {
            "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
            "amount": 0,
            "quantity": 0,
            "timestamp": "2019-12-27T18:11:19.117Z",
            "unit_price": 0,
            "invoice_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
          }
        ]
      },
      "ledger": [
        {
          "amount": 0,
          "segment_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "timestamp": "2019-12-27T18:11:19.117Z",
          "type": "PREPAID_COMMIT_SEGMENT_START"
        }
      ],
      "name": "name",
      "netsuite_sales_order_id": "netsuite_sales_order_id",
      "priority": 0,
      "rate_type": "COMMIT_RATE",
      "rolled_over_from": {
        "commit_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "contract_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      },
      "rollover_fraction": 0,
      "salesforce_opportunity_id": "salesforce_opportunity_id",
      "specifiers": [
        {
          "presentation_group_values": {
            "foo": "string"
          },
          "pricing_group_values": {
            "foo": "string"
          },
          "product_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
          "product_tags": [
            "string"
          ]
        }
      ],
      "uniqueness_key": "x"
    }
  ],
  "next_page": "next_page"
}