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, brand_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 and brand_id are the only
updatable fields: its notes live in QuickBooks Online and are re-imported from there on every
sync. Sending any other field with its current value is accepted.
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). owner_id must be an active user of your company. 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.
owner_id and brand_id stay in Distru: an update that changes only those fields neither pulls
from nor pushes to QuickBooks Online.
Required permission: credits_permissions_create to create, credits_permissions_edit to
update. Creating requires a customer (company_id) the authenticated user can see under their
team restrictions; a hidden one returns 403. Updating also requires access to the credit under
those restrictions (a hidden credit returns 403), and an owner_id they can assign under the
same restrictions.
BearerAuthorizationBearer <token>API token generated in Distru (Settings → Distru API). Send it on every request as Authorization: Bearer YOUR_API_TOKEN.
Credit data
application/json- body
Parameters for creating or updating a credit
amount?numberThe 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.
brand_id?stringID of the brand (a company) this credit is for. Informational only: it never limits which invoices the credit can be applied to. Optional; can be set or changed on any credit, including automatically-created ones. Must be a company of yours that is not deleted. Omit to leave unchanged on update; send null to clear.
company_id?stringID 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?stringA note on this credit, visible to the customer. Omit to leave unchanged on update; send null to clear.
id?stringID of the credit to update. Omit to create a new credit; include it to update an existing one. Automatically-created credits accept only some fields; see the endpoint description.
internal_note?stringAn internal note on this credit, not shown to the customer. Omit to leave unchanged on update; send null to clear.
owner_id?stringID 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?stringOptional 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.
The updated credit
*/*- response
A single credit wrapped in a data envelope
data?Store credit held by a customer that can be applied toward what they owe. Credits can be issued manually or generated automatically (for example from a return or an invoice overpayment).
curl -X POST 'https://app.distru.com/public/v1/credits' \ -H 'Content-Type: application/json' \ -d '{ "amount": 80, "brand_id": "00000000-0000-0000-0000-0000000000ca", "id": "6efeb7da-451e-41dd-a6f2-a6800d689664", "internal_note": "updated"}'{ "data": { "amount": "80", "brand": { "id": "00000000-0000-0000-0000-000000000308", "name": "Company 1919", "updated_datetime": "2026-10-13T15:03:32.240414Z" }, "canceled_datetime": null, "company": { "id": "00000000-0000-0000-0000-0000000002f8", "name": "Company 1891", "updated_datetime": "2026-10-13T15:03:32.139592Z" }, "creator": { "banned": false, "deleted_at": null, "email": "[email protected]", "full_name": "FirstName5756 LastName5757", "id": "00000000-0000-0000-0000-000000000b24", "inserted_datetime": "2026-10-13T15:03:32.124537Z", "role": { "id": "00000000-0000-0000-0000-000000000b91", "name": "Admin 2960" }, "updated_datetime": "2026-10-13T15:03:32.124537Z" }, "credit_number": "CRT-0000001", "credit_uses": [ { "amount": "40", "credit": { "amount": "80", "credit_number": "CRT-0000001", "id": "dc6a0e0d-a0dc-4acd-8aac-19c94702c7e2", "source": "USER" }, "id": "8329f79e-d6c4-4b4f-a72f-b258383d3fcb", "inserted_datetime": "2026-10-13T15:03:32.223866Z", "payment": { "amount": "10", "company": { "id": "00000000-0000-0000-0000-000000000300", "name": "Company 1906", "updated_datetime": "2026-10-13T15:03:32.196573Z" }, "credit_uses": [ { "amount": "40", "credit": { "amount": "80", "credit_number": "CRT-0000001", "id": "dc6a0e0d-a0dc-4acd-8aac-19c94702c7e2", "source": "USER" }, "id": "8329f79e-d6c4-4b4f-a72f-b258383d3fcb" } ], "description": null, "fully_paid_with_credits": false, "id": "00000000-0000-0000-0000-000000000032", "inserted_datetime": "2026-10-13T15:03:32.217532Z", "invoice": { "id": "00000000-0000-0000-0000-000000000038", "invoice_number": "Invoice #55", "status": "NOT_PAID", "total": "32.00" }, "overpayment_credits": [], "payment_date": "2026-10-13T15:03:32.217019Z", "payment_datetime": "2026-10-13T15:03:32.217019Z", "payment_method": { "active": true, "deleted_at": null, "id": "00000000-0000-0000-0000-000000000044", "inserted_datetime": "2026-10-13T15:03:32.216019Z", "name": "Payment Method 67", "qb_payment_method_id": null, "type": "CREDIT_CARD", "updated_datetime": "2026-10-13T15:03:32.216019Z" }, "payment_number": "Payment #49", "payment_type": "INVOICE", "purchase": null, "quickbooks_deposit_account_id": null, "status": "POSTED", "updated_datetime": "2026-10-13T15:03:32.217532Z" } } ], "deleted_in_qbo": false, "external_note": "ext", "id": "dc6a0e0d-a0dc-4acd-8aac-19c94702c7e2", "inserted_datetime": "2026-10-13T15:03:32.157477Z", "internal_note": "updated", "original_amount": "150", "owner": { "banned": false, "deleted_at": null, "email": "[email protected]", "full_name": "FirstName5756 LastName5757", "id": "00000000-0000-0000-0000-000000000b24", "inserted_datetime": "2026-10-13T15:03:32.124537Z", "role": { "id": "00000000-0000-0000-0000-000000000b91", "name": "Admin 2960" }, "updated_datetime": "2026-10-13T15:03:32.124537Z" }, "payment": null, "qb_credit_memo_id": null, "qb_payment_id": null, "qb_sync_status": null, "remaining_balance": "40", "return": null, "source": "USER", "status": "ACTIVE", "updated_datetime": "2026-10-13T15:03:32.268115Z" }}