# Credit Grants ## Create `client.v1.creditGrants.create(CreditGrantCreateParamsbody, RequestOptionsoptions?): CreditGrantCreateResponse` **post** `/v1/credits/createGrant` Create a new credit grant ### Parameters - **body:** `CreditGrantCreateParams` - **customer\_id:** `string` the Metronome ID of the customer - **expires\_at:** `string` The credit grant will only apply to usage or charges dated before this timestamp - **grant\_amount:** `GrantAmount` the amount of credits granted - **amount:** `number` - **credit\_type\_id:** `string` the ID of the pricing unit to be used. Defaults to USD (cents) if not passed. - **name:** `string` the name of the credit grant as it will appear on invoices - **paid\_amount:** `PaidAmount` the amount paid for this credit grant - **amount:** `number` - **credit\_type\_id:** `string` the ID of the pricing unit to be used. Defaults to USD (cents) if not passed. - **priority:** `number` - **credit\_grant\_type:** `string` - **custom\_fields:** `Record` Custom fields to attach to the credit grant. - **effective\_at:** `string` The credit grant will only apply to usage or charges dated on or after this timestamp - **invoice\_date:** `string` The date to issue an invoice for the paid_amount. - **product\_ids:** `Array` The product(s) which these credits will be applied to. (If unspecified, the credits will be applied to charges for all products.). The array ordering specified here will be used to determine the order in which credits will be applied to invoice line items - **reason:** `string` - **rollover\_settings:** `RolloverSettings` Configure a rollover for this credit grant so if it expires it rolls over a configured amount to a new credit grant. This feature is currently opt-in only. Contact Metronome to be added to the beta. - **expires\_at:** `string` The date to expire the rollover credits. - **priority:** `number` The priority to give the rollover credit grant that gets created when a rollover happens. - **rollover\_amount:** `RolloverAmountMaxPercentage | RolloverAmountMaxAmount` Specify how much to rollover to the rollover credit grant - `RolloverAmountMaxPercentage` - `RolloverAmountMaxAmount` - **uniqueness\_key:** `string` 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. ### Returns - `CreditGrantCreateResponse` - **data:** `ID` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const creditGrant = await client.v1.creditGrants.create({ customer_id: '9b85c1c1-5238-4f2a-a409-61412905e1e1', expires_at: '2022-04-01T00:00:00Z', grant_amount: { amount: 1000, credit_type_id: '5ae401dc-a648-4b49-9ac3-391bb5bc4d7b' }, name: 'Acme Corp Promotional Credit Grant', paid_amount: { amount: 5000, credit_type_id: '2714e483-4ff1-48e4-9e25-ac732e8f24f2' }, priority: 0.5, credit_grant_type: 'trial', effective_at: '2022-02-01T00:00:00Z', reason: 'Incentivize new customer', }); console.log(creditGrant.data); ``` ## List `client.v1.creditGrants.list(CreditGrantListParamsparams?, RequestOptionsoptions?): CursorPage` **post** `/v1/credits/listGrants` List credit grants. This list does not included voided grants. ### Parameters - **params:** `CreditGrantListParams` - **limit:** `number` Query param: Max number of results that should be returned - **next\_page:** `string` Query param: Cursor that indicates where the next page of results should start. - **credit\_grant\_ids:** `Array` Body param: An array of credit grant IDs. If this is specified, neither credit_type_ids nor customer_ids may be specified. - **credit\_type\_ids:** `Array` Body param: An array of credit type IDs. This must not be specified if credit_grant_ids is specified. - **customer\_ids:** `Array` Body param: An array of Metronome customer IDs. This must not be specified if credit_grant_ids is specified. - **effective\_before:** `string` Body param: Only return credit grants that are effective before this timestamp (exclusive). - **not\_expiring\_before:** `string` Body param: Only return credit grants that expire at or after this timestamp. ### Returns - `CreditGrantListResponse` - **id:** `string` the Metronome ID of the credit grant - **balance:** `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. - **effective\_at:** `string` The end_date of the customer's current billing period. - **excluding\_pending:** `number` The grant's current balance including all posted deductions. If the grant has expired, this amount will be 0. - **including\_pending:** `number` 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\_fields:** `Record` - **customer\_id:** `string` the Metronome ID of the customer - **deductions:** `Array` - **amount:** `number` an amount representing the change to the customer's credit balance - **created\_by:** `string` - **credit\_grant\_id:** `string` the credit grant this entry is related to - **effective\_at:** `string` - **reason:** `string` - **running\_balance:** `number` the running balance for this credit type at the time of the ledger entry, including all preceding charges - **invoice\_id:** `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 - **effective\_at:** `string` - **expires\_at:** `string` - **grant\_amount:** `GrantAmount` the amount of credits initially granted - **amount:** `number` - **credit\_type:** `CreditTypeData` the credit type for the amount granted - **name:** `string` - **paid\_amount:** `PaidAmount` the amount paid for this credit grant - **amount:** `number` - **credit\_type:** `CreditTypeData` the credit type for the amount paid - **pending\_deductions:** `Array` - **amount:** `number` an amount representing the change to the customer's credit balance - **created\_by:** `string` - **credit\_grant\_id:** `string` the credit grant this entry is related to - **effective\_at:** `string` - **reason:** `string` - **running\_balance:** `number` the running balance for this credit type at the time of the ledger entry, including all preceding charges - **invoice\_id:** `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 - **priority:** `number` - **credit\_grant\_type:** `string | null` - **invoice\_id:** `string | null` the Metronome ID of the invoice with the purchase charge for this credit grant, if applicable - **products:** `Array` The products which these credits will be applied to. (If unspecified, the credits will be applied to charges for all products.) - **id:** `string` - **name:** `string` - **reason:** `string | null` - **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. ### Example ```node 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); } ``` ## Edit `client.v1.creditGrants.edit(CreditGrantEditParamsbody, RequestOptionsoptions?): CreditGrantEditResponse` **post** `/v1/credits/editGrant` Edit an existing credit grant ### Parameters - **body:** `CreditGrantEditParams` - **id:** `string` the ID of the credit grant - **credit\_grant\_type:** `string` the updated credit grant type - **expires\_at:** `string` the updated expiration date for the credit grant - **name:** `string` the updated name for the credit grant ### Returns - `CreditGrantEditResponse` - **data:** `ID` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const response = await client.v1.creditGrants.edit({ id: '9b85c1c1-5238-4f2a-a409-61412905e1e1', expires_at: '2022-04-01T00:00:00Z', name: 'Acme Corp Promotional Credit Grant', }); console.log(response.data); ``` ## List Entries `client.v1.creditGrants.listEntries(CreditGrantListEntriesParamsparams?, RequestOptionsoptions?): CreditGrantListEntriesResponse` **post** `/v1/credits/listEntries` Fetches a list of credit ledger entries. Returns lists of ledgers per customer. Ledger entries are returned in chronological order. Ledger entries associated with voided credit grants are not included. ### Parameters - **params:** `CreditGrantListEntriesParams` - **next\_page:** `string` Query param: Cursor that indicates where the next page of results should start. - **sort:** `"asc" | "desc"` Query param: Ledgers sort order by date, asc or desc. Defaults to asc. - `"asc"` - `"desc"` - **credit\_type\_ids:** `Array` Body param: A list of Metronome credit type IDs to fetch ledger entries for. If absent, ledger entries for all credit types will be returned. - **customer\_ids:** `Array` Body param: A list of Metronome customer IDs to fetch ledger entries for. If absent, ledger entries for all customers will be returned. - **ending\_before:** `string` Body param: If supplied, ledger entries will only be returned with an effective_at before this time. This timestamp must not be in the future. If no timestamp is supplied, all entries up to the start of the customer's next billing period will be returned. - **starting\_on:** `string` Body param: If supplied, only ledger entries effective at or after this time will be returned. ### Returns - `CreditGrantListEntriesResponse` - **data:** `Array` - **customer\_id:** `string` - **ledgers:** `Array` - **credit\_type:** `CreditTypeData` - **ending\_balance:** `EndingBalance` the effective balances at the end of the specified time window - **effective\_at:** `string` the ending_before request parameter (if supplied) or the current billing period's end date - **excluding\_pending:** `number` the ending balance, including the balance of all grants that have not expired before the effective_at date and deductions that happened before the effective_at date - **including\_pending:** `number` the excluding_pending balance plus any pending invoice deductions and expirations that will happen by the effective_at date - **entries:** `Array` - **amount:** `number` an amount representing the change to the customer's credit balance - **created\_by:** `string` - **credit\_grant\_id:** `string` the credit grant this entry is related to - **effective\_at:** `string` - **reason:** `string` - **running\_balance:** `number` the running balance for this credit type at the time of the ledger entry, including all preceding charges - **invoice\_id:** `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 - **pending\_entries:** `Array` - **amount:** `number` an amount representing the change to the customer's credit balance - **created\_by:** `string` - **credit\_grant\_id:** `string` the credit grant this entry is related to - **effective\_at:** `string` - **reason:** `string` - **running\_balance:** `number` the running balance for this credit type at the time of the ledger entry, including all preceding charges - **invoice\_id:** `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 - **starting\_balance:** `StartingBalance` - **effective\_at:** `string` the starting_on request parameter (if supplied) or the first credit grant's effective_at date - **excluding\_pending:** `number` the starting balance, including all posted grants, deductions, and expirations that happened at or before the effective_at timestamp - **including\_pending:** `number` the excluding_pending balance plus any pending activity that has not been posted at the time of the query - **next\_page:** `string | null` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const response = await client.v1.creditGrants.listEntries({ credit_type_ids: ['2714e483-4ff1-48e4-9e25-ac732e8f24f2'], customer_ids: ['6a37bb88-8538-48c5-b37b-a41c836328bd'], ending_before: '2021-02-01T00:00:00Z', starting_on: '2021-01-01T00:00:00Z', }); console.log(response.data); ``` ## Void `client.v1.creditGrants.void(CreditGrantVoidParamsbody, RequestOptionsoptions?): CreditGrantVoidResponse` **post** `/v1/credits/voidGrant` Void a credit grant ### Parameters - **body:** `CreditGrantVoidParams` - **id:** `string` - **release\_uniqueness\_key:** `boolean` If true, resets the uniqueness key on this grant so it can be re-used - **void\_credit\_purchase\_invoice:** `boolean` If true, void the purchase invoice associated with the grant ### Returns - `CreditGrantVoidResponse` - **data:** `ID` ### Example ```node import Metronome from '@metronome/sdk'; const client = new Metronome({ bearerToken: 'My Bearer Token', }); const response = await client.v1.creditGrants.void({ id: '9b85c1c1-5238-4f2a-a409-61412905e1e1' }); console.log(response.data); ``` ## Domain Types ### Credit Ledger Entry - `CreditLedgerEntry` - **amount:** `number` an amount representing the change to the customer's credit balance - **created\_by:** `string` - **credit\_grant\_id:** `string` the credit grant this entry is related to - **effective\_at:** `string` - **reason:** `string` - **running\_balance:** `number` the running balance for this credit type at the time of the ledger entry, including all preceding charges - **invoice\_id:** `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 ### Rollover Amount Max Amount - `RolloverAmountMaxAmount` - **type:** `"MAX_AMOUNT"` Rollover up to a fixed amount of the original credit grant amount. - `"MAX_AMOUNT"` - **value:** `number` The maximum amount to rollover. ### Rollover Amount Max Percentage - `RolloverAmountMaxPercentage` - **type:** `"MAX_PERCENTAGE"` Rollover up to a percentage of the original credit grant amount. - `"MAX_PERCENTAGE"` - **value:** `number` The maximum percentage (0-1) of the original credit grant to rollover.