Start

Platform

App store purchases

Auth

Builds

Credits

Credit grants

Database

Flags

Generated Assets

Assets

Hosting

Jobs and cron

Localization

Monitoring

Network

Notifications

Organizations

Payments

Queues

Realtime

Runners

Sandboxes

Storage

Webhooks

Workflows

Getting Started

Installation

Authentication

AI Services

KV Store

Overview

Webhooks

Deploy & Infrastructure

Reference

On this page

Request
CreditGrant
ResourceMeta
Subject
Response
ResourceMeta
Subject
Errors
Examples

Reference

Create a credit grant

Gives a subject credit.

Checked 2026-09-28

Gives a subject credit. Append-only: a change is a new grant that supersedes the old. Refused with INVALID_STATE (tax_treatment_unsupported) for post_tax_settlement while the merchant has automatic tax on.

Path POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/credit_grants
Scope billing:credits.approve
Effect write — a successful call changes state.
Collection credit_grants

#Request

Field	Type	What it is
`parent`	`string`	The environment to create in. Required.
`credit_grant`	`CreditGrant`	The credit grant. Required.

#CreditGrant

Field	Type	What it is
`name`	`string`	`orgs/{org}/projects/{project}/envs/{env}/credit_grants/{credit_grant}`.
`meta`	`ResourceMeta`	Resource metadata.
`subject`	`Subject`	Who receives it. Required.
`kind`	`string`	`amount` (a total) or `monthly_cap` (up to the amount in each month). Required.
`amount_minor`	`string`	Minor units, a decimal string. Required.
`start_time`	`timestamp`	When it starts applying. Required.
`expire_time`	`timestamp`	When it stops applying; required. Not renewing is how charging starts. Required.
`approver`	`string`	Who approved it. Required.
`reason`	`string`	Why. Required.
`supersedes`	`string`	The grant this one replaces.
`tax_treatment`	`string`	`undecided`, `price_reduction`, or `post_tax_settlement`; no default. `post_tax_settlement` is refused while the merchant has automatic tax on. Required.
`collection_mode`	`string`	`standard` or `hold`; no default. Over the credit, a held invoice stays due but is not collected until an explicit audited release. Required.

#ResourceMeta

Field	Type	What it is
`labels`	`map<string, string>`	Caller-writable, indexed labels (AIP-122 label rules).
`annotations`	`map<string, string>`	Caller-writable, unindexed annotations.
`display_name`	`string`	Caller-writable human-readable name.

#Subject

Field	Type	What it is
`end_user`	`string`	An end user's id (Sylphx Auth, or the app's own OIDC issuer). One of the `kind` group.
`customer_organization`	`string`	A customer organization's id. One of the `kind` group.

#Response

Field	Type	What it is
`name`	`string`	`orgs/{org}/projects/{project}/envs/{env}/credit_grants/{credit_grant}`.
`uid`	`string`	`cgrt_<cell><ulid>`; never reused. Output only.
`meta`	`ResourceMeta`	Resource metadata.
`subject`	`Subject`	Who receives it. Required.
`kind`	`string`	`amount` (a total) or `monthly_cap` (up to the amount in each month). Required.
`amount_minor`	`string`	Minor units, a decimal string. Required.
`start_time`	`timestamp`	When it starts applying. Required.
`expire_time`	`timestamp`	When it stops applying; required. Not renewing is how charging starts. Required.
`approver`	`string`	Who approved it. Required.
`reason`	`string`	Why. Required.
`supersedes`	`string`	The grant this one replaces.
`tax_treatment`	`string`	`undecided`, `price_reduction`, or `post_tax_settlement`; no default. `post_tax_settlement` is refused while the merchant has automatic tax on. Required.
`collection_mode`	`string`	`standard` or `hold`; no default. Over the credit, a held invoice stays due but is not collected until an explicit audited release. Required.

#ResourceMeta

Field	Type	What it is
`generation`	`int64`	Increases by one on every change to `spec`. Output only.
`etag`	`string`	Strong ETag (AIP-154): changes on any change to spec, status, or metadata. Send it back as `If-Match` or `etag` to make Update and Delete conditional; a mismatch fails with ABORTED / 409 `ETAG_MISMATCH`. Output only.
`create_time`	`timestamp`	When the Resource was created. Output only.
`update_time`	`timestamp`	When the Resource last changed. Output only.
`delete_time`	`timestamp`	Set while the Resource is being deleted. Output only.
`labels`	`map<string, string>`	Caller-writable, indexed labels (AIP-122 label rules).
`annotations`	`map<string, string>`	Caller-writable, unindexed annotations.
`display_name`	`string`	Caller-writable human-readable name.
`creator`	`string`	The principal that created the Resource. Output only.

#Subject

Field	Type	What it is
`end_user`	`string`	An end user's id (Sylphx Auth, or the app's own OIDC issuer). One of the `kind` group.
`customer_organization`	`string`	A customer organization's id. One of the `kind` group.

#Errors

UNAUTHENTICATED — No valid key or token was presented.
PERMISSION_DENIED — The key lacks the method's permission.
INVALID_FIELD — A field failed validation.
UNKNOWN_FIELD — The request has a field the schema does not know.
INVALID_STATE — The Resource is in a state that forbids the call.
IDEMPOTENCY_KEY_REUSED — An Idempotency-Key was reused with another body.
IDEMPOTENCY_IN_PROGRESS — The first call with this Idempotency-Key is still running.

Every error arrives in the body Errors describes.

#Examples

curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/credit_grants" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_minor":"…","approver":"…","collection_mode":"…","expire_time":{},"kind":"…","reason":"…","start_time":{},"subject":{},"tax_treatment":"…"}'

Was this page helpful?

Tell us what is missing, wrong, or unclear — this opens a real inbox.

Send feedback

Platform links