---
title: "Create or update a credit"
method: POST
path: "/public/v1/credits"
tags: ["Credit"]
---

# Create or update a credit

`POST /public/v1/credits`

Create a new credit or update an existing one through a single endpoint.

Omit `id` to create a new credit; include the `id` of an existing credit to update it. Updates
are sparse: only the fields you send are changed, and any field you omit keeps its current
value. On create, the `credit_number` and `original_amount` are assigned automatically —
`original_amount` is frozen to the create-time `amount` and never changes afterward.

Credits created through the API are always manually-created (`USER` source) credits — the same
as a credit you would add by hand in the Distru UI. Credits generated automatically (from a
return, an invoice overpayment, or QuickBooks Online) cannot be created here, and only
`owner_id`, `external_note` and `internal_note` can be updated on them — their amount, customer
and QuickBooks Online item cannot be set through the API. On a credit memo created in QuickBooks
Online (`QB_CREDIT_MEMO` source) `owner_id` is the only updatable field: its notes live in
QuickBooks Online and are re-imported from there on every sync.

Constraints: on update the customer (`company_id`) cannot be changed. `amount` must be greater
than 0 and, on update, cannot be set below the amount already applied to invoices by this credit
(its used amount). Once a credit has an owner it can be reassigned but not removed.

Credits do not touch inventory or state compliance (Metrc / BioTrack). They do interact with
QuickBooks Online: if your account syncs credits with QuickBooks Online, updating an existing
credit first pulls the latest credit and payment state from QuickBooks Online (so a stale local
amount can be rejected), and any create or update is then pushed to QuickBooks Online in the
background. A 200/201 confirms the credit was saved in Distru, not that it has finished syncing
to QuickBooks Online — re-fetch the credit and read `qb_sync_status` to observe the sync result.

Required permission: `credits_permissions_create` to create, `credits_permissions_edit` to
update. Updating also requires access to the credit under the authenticated user's team
restrictions, and an `owner_id` they can assign under those same restrictions.

## Request body

- UpsertCredit — Parameters for creating or updating a credit
  - `amount` number — The credit's spendable face value. Must be greater than 0. Required when creating. On update, omitting it leaves the amount unchanged; when provided it cannot be set below the amount already applied to invoices by this credit (its used amount). Sets `original_amount` only at create time; `original_amount` never changes afterward.
  - `company_id` string — ID of the customer (company relationship) this credit applies to. Required when creating and the customer must exist and not be deleted. Immutable on update — sending a different value is rejected; omit it when updating.
  - `external_note` string — A note on this credit, visible to the customer. Omit to leave unchanged on update; send null to clear.
  - `id` string — ID of the credit to update. Omit to create a new credit; include it to update an existing one. Only manually-created (USER-source) credits can be updated.
  - `internal_note` string — An internal note on this credit, not shown to the customer. Omit to leave unchanged on update; send null to clear.
  - `owner_id` string — ID of the user who owns this credit. Defaults to the API key's user when creating if omitted. On update, omitting it leaves the owner unchanged; the owner can be reassigned on any credit but cannot be removed once set.
  - `quickbooks_sales_item_id` string — Optional ID of the QuickBooks Online sales item this credit maps to, used only when QuickBooks Online credit sync is enabled. Omit or send null to use the default "Distru Sales" item. When set it must reference an active QuickBooks Online sales item. Never required.

## Response `200`

The updated credit

## Other responses

- `201` — The created credit
- `400` — Invalid parameters
- `401` — Missing or invalid API token
- `403` — The API token lacks the required permission
- `404` — Not Found

---

[API](https://skmtc.dev/distru/apis/distru-api.md) · [All operations](https://skmtc.dev/distru/apis/distru-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/distru/distru-api/revisions/eb775b7b6ee0/schema)