Sign in
Credit

Create or update a credit

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.

post/public/v1/credits

Request body

amountnumber

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_idstring

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_notestring

A note on this credit, visible to the customer. Omit to leave unchanged on update; send null to clear.

idstring

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_notestring

An internal note on this credit, not shown to the customer. Omit to leave unchanged on update; send null to clear.

owner_idstring

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_idstring

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.

Example request

{
  "amount": 100,
  "company_id": "00000000-0000-0000-0000-00000000000a",
  "external_note": "External note",
  "internal_note": "Internal note"
}

Response

The updated credit

Changes

No recorded changes to this endpoint across all 1 revision of this API.