Grant customer credits by external ID | Paid

import { PaidClient } from "@paid-ai/paid-node";
async function main() {
    const client = new PaidClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.customers.grantCustomerCreditsByExternalId("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"),
        },
    });
}
main();

{
  "created": true,
  "customer": {
    "id": "cus_abc123",
    "externalId": "customer-123"
  },
  "creditCurrency": {
    "key": "api_credits",
    "name": "API Credits"
  },
  "grant": {
    "amount": 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.

amountintegerRequired

Number of credits to grant. 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.

Response

201

createdboolean

True when this request created a new grant.

customerobject

creditCurrencyobject

grantobject

createdAtdatetime

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error