Grant customer credits by external ID

POST

https://api.agentpaid.io/api/v2/customers/external/:externalId/credits/grants

POST

/api/v2/customers/external/:externalId/credits/grants

import { PaidClient } from "@paid-ai/paid-node";
async function main() {
    const client = new PaidClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.customers.grantCustomerCreditsByExternalId({
        externalId: "customer_123",
        body: {
            creditCurrencyKey: "api_credits",
            amount: 10000,
            startsAt: new Date("2026-06-05T12:00:00.000Z"),
            expiresAt: new Date("2026-12-31T23:59:59.000Z"),
            idempotencyKey: "grant_acme_2026-06-05",
        },
    });
}
main();

{
  "created": true,
  "customer": {
    "id": "cus_abc123",
    "externalId": "customer-123"
  },
  "creditCurrency": {
    "key": "api_credits",
    "name": "API Credits"
  },
  "grant": {
    "amount": 10000,
    "amountDecimal": "10000",
    "startsAt": "2026-06-05T12:00:00.000Z",
    "expiresAt": "2026-12-31T23:59:59.000Z",
    "status": "active"
  },
  "createdAt": "2026-06-05T12:34:56.000Z"
}

Immediately grant credits to a customer looked up by external ID using an active credit currency key.

Authentication

AuthorizationBearer

API Key authentication using Bearer token

Path parameters

externalIdstringRequired

Customer ID from the integrator’s system, stored on Paid as externalId.

Request

Body

creditCurrencyKeystringRequiredformat: "^[a-z0-9_-]+$">=1 character

Stable machine-readable key for the active credit currency to grant.

amountdoubleRequired

Number of credits to grant, exact to at most 6 decimal places. This is not a monetary amount.

startsAtdatetimeOptional

When these credits become spendable, as an RFC3339 datetime with timezone. Must be at or before the current server time. Defaults to the current server time when omitted.

expiresAtdatetime or nullOptional

When these credits expire, as an RFC3339 datetime with timezone. Omit or set null for credits that do not expire.

idempotencyKeystringOptional1-255 characters

Unique key for this grant within your organization. A retry with the same key and request body returns the original grant with created: false instead of granting again. Reusing a key for a different customer or request body returns 409.

Response

201

createdboolean

True when this request created a new grant. False when an earlier request with the same idempotencyKey already created it.

customerobject

creditCurrencyobject

grantobject

createdAtdatetime

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error

500

Internal Server Error