---
title: "Grant credit"
method: POST
path: "/credits"
tags: ["Credits"]
---

# Grant credit

`POST /credits`

## Request

- Base URL: `https://api.togai.com`
- URL: `https://api.togai.com/credits`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/togaihq/apis/togai-apis/docs/credits/post.ts> (a function with typed inputs; its response is checked against the schema)

Grant credit

## Request body

- CreateCreditRequest: payload to create credits
  - `creditRequests` CreditRequest[], required
    - `accountId` string, required
    - `purpose` string, required
    - `applicableEntityIds` string[]: List of entity ids for which the credit is applicable. If null or empty, the credit is applicable to all ids. This list can accept special values like: - ALL_USAGE_METER_RATE_CARDS: To apply the credit to all usage meter rate cards - ALL_FIXED_FEE_RATE_CARDS: To apply the credit to all fixed fee rate cards
    - `effectiveFrom` string, date, required
    - `effectiveUntil` string, date
    - `creditAmount` number
    - `priority` integer, required
    - `grantorId` string: The entity through which the credit has been granted
    - `idempotencyKey` string: The idempotency key for uniqueness of the credit record

## Response `200`

Response for List credits request

- CreateCreditResponse
  - `credits` Credit[], required
    - `accountId` string, required
    - `purpose` string, required
    - `applicableEntityIds` string[]: List of entity ids for which the credit is applicable. If null or empty, the credit is applicable to all ids. This list can accept special values like: - ALL_USAGE_METER_RATE_CARDS: To apply the credit to all usage meter rate cards - ALL_FIXED_FEE_RATE_CARDS: To apply the credit to all fixed fee rate cards
    - `effectiveFrom` string, date, required
    - `effectiveUntil` string, date
    - `creditAmount` number
    - `priority` integer, required
    - `grantorId` string: The entity through which the credit has been granted
    - `idempotencyKey` string: The idempotency key for uniqueness of the credit record
    - `id` string, required: Identifier of credits
    - `customerId` string, required
    - `status` 'ACTIVE' | 'CONSUMED' | 'EXPIRED' | 'VOIDED', required
    - `creditUnit` string
    - `holdAmount` number
    - `consumedAmount` number
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time

## Other responses

- `400`: Error response
- `401`: Error response
- `403`: Error response
- `404`: Error response
- `429`: Error response
- `default`: Error response

## Changes

- **2023-11-30** `b3351be4b462`: 1 breaking, 1 info
  - the response property `credits/items/allOf[#/components/schemas/CreditRequest]/creditAmount` became optional for the status `200`
  - the request property `creditRequests/items/creditAmount` became optional
- **2023-09-25** `ae3b70608528`: 2 info
  - added the new optional request property `creditRequests/items/idempotencyKey`
  - added the optional property `credits/items/allOf[#/components/schemas/CreditRequest]/idempotencyKey` to the response with the `200` status
- **2023-09-07** `cfabb13f9886`: 2 breaking, 8 warning, 2 info
  - added the new required request property `creditRequests`
  - the response's body type changed from no type to `object` for status `200`
  - removed the request property `accountId`
  - removed the request property `applicableEntityIds`
  - …8 more
- **2023-09-02** `6b13f6f47735`: 7 breaking, 1 warning, 4 info
  - added the new required request property `accountId`
  - added the new required request property `creditAmount`
  - added the new required request property `effectiveFrom`
  - added the new required request property `priority`
  - …8 more

[Operation history](https://skmtc.dev/togaihq/apis/togai-apis/changes/credits/post.md)

---

[API](https://skmtc.dev/togaihq/apis/togai-apis.md) - [All operations](https://skmtc.dev/togaihq/apis/togai-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/togaihq/apis/togai-apis/revisions/442f5d8f4aa0?raw)