List credit grants

curl --request POST \
  --url https://api.metronome.com/v1/credits/listGrants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "credit_type_ids": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c",
  "customer_ids": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c",
  "credit_grant_ids": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c",
  "not_expiring_before": "2022-02-01T00:00:00Z",
  "effective_before": "2022-02-01T00:00:00Z"
}
'

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "effective_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "priority": 123,
      "grant_amount": {
        "amount": 123,
        "credit_type": {
          "name": "<string>",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      },
      "paid_amount": {
        "amount": 123,
        "credit_type": {
          "name": "<string>",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      },
      "balance": {
        "excluding_pending": 123,
        "including_pending": 123,
        "effective_at": "2023-11-07T05:31:56Z"
      },
      "deductions": [
        {
          "amount": 123,
          "reason": "Automated invoice deduction",
          "running_balance": 123,
          "effective_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>",
          "credit_grant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ],
      "pending_deductions": [
        {
          "amount": 123,
          "reason": "Automated invoice deduction",
          "running_balance": 123,
          "effective_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>",
          "credit_grant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ],
      "custom_fields": {},
      "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "uniqueness_key": "<string>",
      "reason": "<string>",
      "credit_grant_type": "<string>",
      "products": [
        {
          "id": "<string>",
          "name": "<string>"
        }
      ]
    }
  ],
  "next_page": "<string>"
}

POST

credits

listGrants

List credit grants

curl --request POST \
  --url https://api.metronome.com/v1/credits/listGrants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "credit_type_ids": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c",
  "customer_ids": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c",
  "credit_grant_ids": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c",
  "not_expiring_before": "2022-02-01T00:00:00Z",
  "effective_before": "2022-02-01T00:00:00Z"
}
'

{
  "data": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "effective_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z",
      "priority": 123,
      "grant_amount": {
        "amount": 123,
        "credit_type": {
          "name": "<string>",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      },
      "paid_amount": {
        "amount": 123,
        "credit_type": {
          "name": "<string>",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      },
      "balance": {
        "excluding_pending": 123,
        "including_pending": 123,
        "effective_at": "2023-11-07T05:31:56Z"
      },
      "deductions": [
        {
          "amount": 123,
          "reason": "Automated invoice deduction",
          "running_balance": 123,
          "effective_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>",
          "credit_grant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ],
      "pending_deductions": [
        {
          "amount": 123,
          "reason": "Automated invoice deduction",
          "running_balance": 123,
          "effective_at": "2023-11-07T05:31:56Z",
          "created_by": "<string>",
          "credit_grant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      ],
      "custom_fields": {},
      "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "uniqueness_key": "<string>",
      "reason": "<string>",
      "credit_grant_type": "<string>",
      "products": [
        {
          "id": "<string>",
          "name": "<string>"
        }
      ]
    }
  ],
  "next_page": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

limit

integer

Max number of results that should be returned

Required range: 1 <= x <= 100

next_page

string

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

Body

application/json

Filters specifying which credit grants should be included

credit_type_ids

string<uuid>[]

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

Example:

"d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c"

customer_ids

string<uuid>[]

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

Example:

"d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c"

credit_grant_ids

string<uuid>[]

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

Example:

"d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc, 0e5b8609-d901-4992-b394-c3c2e3f37b1c"

not_expiring_before

string<date-time>

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

Example:

"2022-02-01T00:00:00Z"

effective_before

string<date-time>

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

Example:

"2022-02-01T00:00:00Z"

Response

200 - application/json

Success

data

object[]

required

Show child attributes

data.id

string<uuid>

required

the Metronome ID of the credit grant

data.name

string

required

data.customer_id

string<uuid>

required

the Metronome ID of the customer

data.effective_at

string<date-time>

required

data.expires_at

string<date-time>

required

data.priority

number

required

data.grant_amount

object

required

the amount of credits initially granted

Show child attributes

data.grant_amount.amount

number

required

data.grant_amount.credit_type

object

required

the credit type for the amount granted

Show child attributes

data.grant_amount.credit_type.name

string

required

data.grant_amount.credit_type.id

string<uuid>

required

data.paid_amount

object

required

the amount paid for this credit grant

Show child attributes

data.paid_amount.amount

number

required

data.paid_amount.credit_type

object

required

the credit type for the amount paid

Show child attributes

data.paid_amount.credit_type.name

string

required

data.paid_amount.credit_type.id

string<uuid>

required

data.balance

object

required

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.

Show child attributes

data.balance.excluding_pending

number

required

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

data.balance.including_pending

number

required

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.

data.balance.effective_at

string<date-time>

required

The end_date of the customer's current billing period.

data.deductions

object[]

required

Show child attributes

data.deductions.amount

number

required

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

data.deductions.reason

string

required

Example:

"Automated invoice deduction"

data.deductions.running_balance

number

required

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

data.deductions.effective_at

string<date-time>

required

data.deductions.created_by

string

required

data.deductions.credit_grant_id

string<uuid>

required

the credit grant this entry is related to

data.deductions.invoice_id

string<uuid> | 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

data.pending_deductions

object[]

required

Show child attributes

data.pending_deductions.amount

number

required

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

data.pending_deductions.reason

string

required

Example:

"Automated invoice deduction"

data.pending_deductions.running_balance

number

required

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

data.pending_deductions.effective_at

string<date-time>

required

data.pending_deductions.created_by

string

required

data.pending_deductions.credit_grant_id

string<uuid>

required

the credit grant this entry is related to

data.pending_deductions.invoice_id

string<uuid> | null

data.custom_fields

object

required

Custom fields to be added eg. { "key1": "value1", "key2": "value2" }

Show child attributes

data.custom_fields.{key}

string

data.invoice_id

string<uuid> | null

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

data.uniqueness_key

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.

Required string length: 1 - 128

data.reason

string | null

data.credit_grant_type

string | null

data.products

object[]

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

Show child attributes

data.products.id

string

required

data.products.name

string

required

next_page

string | null

required

Create a credit grant

List credit ledger entries

⌘I

Plans-Specific Endpoints

Plans-Contracts Shared Endpoints

List credit grants

Authorizations

Query Parameters

Body

Response