---
title: "POST /api/v1/billing.service-credits.grants.insert"
method: POST
path: "/api/v1/billing.service-credits.grants.insert"
tags: ["Billing"]
---

# POST /api/v1/billing.service-credits.grants.insert

`POST /api/v1/billing.service-credits.grants.insert`

## Request

- Base URL: `https://api.partly.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.partly.com/api/v1/billing.service-credits.grants.insert`
- Auth: none declared. Required headers: `authorization`

Issue an immutable service-credit grant idempotently with an audit record. A subscription_period grant takes its amount and bounds from the period's pricing-policy allowance. Restricted to billing staff.

## Headers

- `authorization` string, required: UTF-8 encoded string

## Request body

- union
  - object: A grant of `top_up`, `credit_line` or `promotional` credits, with the amount and bounds the caller chooses.
    - `account_id` string, uuid, required: UUID value type
    - `effective_at` string, date-time, nullable: DateTime at a given timezone (RFC3339 format)
    - `expires_at` string, date-time, required: DateTime at a given timezone (RFC3339 format)
    - `idempotency_key` string, required: UTF-8 encoded string
    - `kind` 'top_up', required
    - `quanta` integer, required: 64-bit unsigned integer
    - `reason` string, required: UTF-8 encoded string
  - object: A grant of `top_up`, `credit_line` or `promotional` credits, with the amount and bounds the caller chooses.
    - `account_id` string, uuid, required: UUID value type
    - `effective_at` string, date-time, nullable: DateTime at a given timezone (RFC3339 format)
    - `expires_at` string, date-time, required: DateTime at a given timezone (RFC3339 format)
    - `idempotency_key` string, required: UTF-8 encoded string
    - `kind` 'credit_line', required
    - `quanta` integer, required: 64-bit unsigned integer
    - `reason` string, required: UTF-8 encoded string
  - object: A grant of `top_up`, `credit_line` or `promotional` credits, with the amount and bounds the caller chooses.
    - `account_id` string, uuid, required: UUID value type
    - `effective_at` string, date-time, nullable: DateTime at a given timezone (RFC3339 format)
    - `expires_at` string, date-time, required: DateTime at a given timezone (RFC3339 format)
    - `idempotency_key` string, required: UTF-8 encoded string
    - `kind` 'promotional', required
    - `quanta` integer, required: 64-bit unsigned integer
    - `reason` string, required: UTF-8 encoded string
  - object: The allowance of a subscription period. The amount is the allowance of the pricing-policy revision pinned at the period's start, and the grant takes effect and expires with the period. The period is the grant's identity: the grant is stored as `period:{period id}`, the key the per-period issuer uses, so repeating the request, or the issuer reaching the period, returns the same grant.
    - `account_id` string, uuid, required: UUID value type
    - `kind` 'subscription_period', required
    - `reason` string, required: UTF-8 encoded string
    - `subscription_period_id` string, uuid, required: UUID value type

## Response `200`

200 OK

- BillingServiceCreditGrantIssueResponse
  - `created` boolean, required: Boolean value
  - `grant` BillingServiceCreditGrantDetail, required
    - `account_id` string, uuid, required: UUID value type
    - `actor` string, required: UTF-8 encoded string
    - `created_at` string, date-time, required: DateTime at a given timezone (RFC3339 format)
    - `effective_at` string, date-time, required: DateTime at a given timezone (RFC3339 format)
    - `expires_at` string, date-time, required: DateTime at a given timezone (RFC3339 format)
    - `id` string, uuid, required: UUID value type
    - `issuance_key` string, required: UTF-8 encoded string
    - `kind` union, required
      - 'subscription_period'
      - 'top_up'
      - 'credit_line'
      - 'promotional'
    - `quanta` integer, required: 64-bit unsigned integer
    - `reason` string, required: UTF-8 encoded string
    - `subscription_period_id` string, uuid, required: UUID value type

## Other responses

- `default`: Error cases

## Changes

- **2026-10-16** `1d9ff7d63238`: 1 breaking, 1 info
  - removed `subschema #1: billing.ServiceCreditBoundedGrantRequest, subschema #2: billing.ServiceCreditBoundedGrantRequest, subschema #3: billing.ServiceCreditBoundedGrantRequest, subschema #4: billing.ServiceCreditPeriodGrantRequest` from the request body `oneOf` list
  - added `subschema #1: top_up, subschema #2: credit_line, subschema #3: promotional, subschema #4: subscription_period` to the request body `oneOf` list
- **2026-10-14** `dcced4ac6ce2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/partly/apis/core-server/changes/api/v1/billing.service-credits.grants.insert/post.md)

---

[API](https://skmtc.dev/partly/apis/core-server.md) · [All operations](https://skmtc.dev/partly/apis/core-server/llms.txt) · [OpenAPI document](https://skmtc.dev/partly/apis/core-server/revisions/0060854f7c86?raw)