Skip to main content
POST
Create credit memo

Authorizations

​
Authorization
string
header
required

Use your app's API key as the username, and leave the password blank

Headers

​
Idempotency-Key
string

Makes a retry safe when you never got the answer to a call: a timeout, a dropped connection, a worker that crashed. Send a new key (a UUID, say) with each request you mean to make once, and the same key when you send that request again. A repeat with the key and the same method, path, query and body answers 201 with what the first call created, as it is now, marked Idempotent-Replayed: true, and queues nothing. The same key with a different request is a 422. A key belongs to your app (sandbox and production apps never share one), lasts as long as what it created, and is 1 to 255 printable ASCII characters.

Required string length: 1 - 255
Pattern: ^[\x20-\x7E]+$

Path Parameters

​
connection_id
string<uuid>
required

The connection (a customer's QuickBooks company file) this request is queued for.

Query Parameters

​
webhook_url
string<uri>

Where QuBe Sync POSTs the answered request (this same document with response_json filled in), signed with X-QUBE-Signature. Send one with every request: it is how answers are delivered. Optional only so a script can queue and look up links.self by hand. It must be an absolute http or https URL. It may not contain a username or password, and in production it may not point at localhost or a private, loopback or link-local address. A qube listen URL must be one of this app's.

Maximum string length: 2048

Body

application/json
​
customer_ref
object
required

customer_ref identifies a customer or customer job. If both full_name and list_id are provided, full_name is ignored. In SalesReceipt and ReceivePayment, it identifies who receives credit. In TimeTracking, it identifies who the time can be billed to and is required in TimeTrackingAdd when IsBillable is true.

​
discount_line_add
object
​
request_id
string

Your own label for the request, sent to QuickBooks as its qbXML requestID and echoed in the raw answer (response_xml); optional, since the answer's webhook already carries the request's id.

​
ship_address
object

This aggregate supports at most five address lines. You can provide a structured address (Addr1-Addr3 plus City/State/postal_code/etc.) or use block mode (Addr1-Addr5 only). Do not mix block mode with other address fields. In block mode, each Addr line prints as its own line and is returned in ship_address_block or bill_address_block.

​
fob
string

QuickBooks uses the term FOB, “freight on board,” to indicate the place from which the product is shipped. The FOB has no accounting implications.

​
bill_address
object

This aggregate supports at most five address lines. You can provide a structured address (Addr1-Addr3 plus City/State/postal_code/etc.) or use block mode (Addr1-Addr5 only). Do not mix block mode with other address fields. In block mode, each Addr line prints as its own line and is returned in ship_address_block or bill_address_block.

​
other
string

Other, Other1, and Other2 are built-in transaction custom fields. Other is transaction-level; Other1 and Other2 are line-level. These fields are always available through the SDK and do not require DataExtDef setup. Template labels in the UI can be renamed, but SDK names remain fixed as Other, Other1, and Other2.

​
is_tax_included
boolean

For future use with international versions of QuickBooks.

​
customer_sales_tax_code_ref
object

Refers to the sales-tax code for sales related to this customer. (That is, it refers to a member of the SalesTaxCode list.) The sales-tax code indicates whether an item is taxable or non-taxable, and why. In a request, if a customer_sales_tax_code_ref aggregate includes both full_name and list_id, full_name will be ignored.

​
is_to_be_printed
boolean

If is_to_be_printed is true, QuickBooks queues the form for later printing. It does not print immediately; printing is still a user action in QuickBooks.

​
def_macro
string

def_macro lets you assign a reusable name to a returned txn_id or txn_line_id so later requests can reference it with useMacro. This feature requires SDK 2.0+.

​
is_pending
boolean

If is_pending is set to true, the credit memo hasn’t been completed. Within QuickBooks, you can change the is_pending status for a credit memo by choosing “Mark Credit Memo As Pending” or “Mark Credit Memo As Final” from the Edit menu.

​
ref_number
string

ref_number is a user-managed transaction reference (for example, a check number). It can be edited and is not guaranteed to be globally unique. Some transaction types auto-populate ref_number when omitted, based on QuickBooks preferences and numbering state.

​
shipping_line_add
object
​
customer_msg_ref
object

A standard message such as “Thank you for your business,” or “Please sign and return this estimate to indicate your approval.” A customer message can be included at the bottom of a form. A customer_msg_ref aggregate refers to one of the messages on the CustomerMsg list. In a request, if a customer_msg_ref aggregate includes both full_name and list_id, full_name will be ignored.

​
credit_memo_line_group_add
object[]

Represents a previously defined group of lines in the credit memo. Compare with CreditMemoLine, which represents just one line in the credit memo.

At least one entry is required across credit_memo_line_add and credit_memo_line_group_add; they combine, any number of each. QuickBooks receives them in that order: every credit_memo_line_add, then every credit_memo_line_group_add.

​
terms_ref
object

Refers to the payment terms associated with this entity. (This will be an item on the DateDrivenTerms or StandardTerms list.) If a terms_ref aggregate includes both full_name and list_id, full_name will be ignored.

​
due_date
string<date>

The date on which payment is due.

​
sales_tax_line_add
object
​
credit_memo_line_add
object[]

Represents one line in the credit memo. Compare with CreditMemoGroupLine, which represents a previously defined group of lines in the credit memo.

At least one entry is required across credit_memo_line_add and credit_memo_line_group_add; they combine, any number of each. QuickBooks receives them in that order: every credit_memo_line_add, then every credit_memo_line_group_add.

​
sales_rep_ref
object

A sales representative must be on the Employee, Vendor, or Other Names list within QuickBooks. Sales representative’s names and initials appear on the Rep drop-down list on QuickBooks sales forms. A sales_rep_ref refers to a person on the SalesRep list. In a request, if a sales_rep_ref aggregate includes both full_name and list_id, full_name will be ignored.

​
class_ref
object

Use classes to categorize transactions (for example, by department, location, or work type). Class tracking is off by default in QuickBooks. A class_ref points to one class; if both full_name and list_id are provided, full_name is ignored. In InvoiceAdd, a header-level class_ref is applied to line items unless you override or clear it on individual lines.

​
external_guid
string

Allows for the attachment of a user defined GUID value.

​
ship_method_ref
object

A shipping method, for example, standard mail or overnight delivery. A ship_method_ref aggregate refers to an item on the ShipMethod list. In a request, if a ship_method_ref aggregate includes both full_name and list_id, full_name will be ignored.

​
po_number
string

Purchase order number.

​
memo
string

The memo doesn’t print on the credit memo, but does appear in the account register and the customer register.

​
txn_date
string<date>

The date of the transaction. In some cases, if you leave txn_date out of an -Add message, QuickBooks will prefill txn_date with the date of the last-saved transaction of the same type.

​
item_sales_tax_ref
object

An ItemSalesTax entry represents one tax rate paid to one tax agency. Use it when a transaction needs a single tax calculation. For multi-rate scenarios, use a sales-tax group instead. If both full_name and list_id are provided for item_sales_tax_ref, list_id is used.

​
is_to_be_emailed
boolean

When enabled, QuickBooks validates the customer email at runtime before sending. If no valid email is available, the request fails.

​
template_ref
object

QuickBooks templates specify how to print certain transactions. A template query returns the names of all templates that have been defined in QuickBooks. A template_ref element refers to one of these templates.

​
ar_account_ref
object

ar_account_ref points to an Accounts Receivable account. If both full_name and list_id are provided, full_name is ignored.

​
exchange_rate
number

exchange_rate is the rate from this currency to the company’s home currency at AsOfDate. You can supply a rate when adding transactions, but QuickBooks does not provide rates through the SDK. If your home currency is USD and internet access is available, rates can be downloaded in the QuickBooks UI via Lists > Currency > Activities > Download Latest Exchange Rates.

​
ship_date
string<date>

The date when the product was, or will be, shipped.

​
include_ret_element
enum<string>[]
Available options:
ARAccountRef,
BillAddress,
BillAddressBlock,
ClassRef,
CreditMemoLineGroupRet,
CreditMemoLineRet,
CreditRemaining,
CreditRemainingInHomeCurrency,
CurrencyRef,
CustomerMsgRef,
CustomerRef,
CustomerSalesTaxCodeRef,
DataExtRet,
DiscountLineRet,
DueDate,
EditSequence,
ExchangeRate,
ExternalGUID,
FOB,
IsPending,
IsTaxIncluded,
IsToBeEmailed,
IsToBePrinted,
ItemSalesTaxRef,
LinkedTxn,
ListID,
Memo,
Other,
OwnerID,
PONumber,
RefNumber,
SalesRepRef,
SalesTaxLineRet,
SalesTaxPercentage,
SalesTaxTotal,
ShipAddress,
ShipAddressBlock,
ShipDate,
ShipMethodRef,
ShippingLineRet,
Subtotal,
TemplateRef,
TermsRef,
TimeCreated,
TimeModified,
TotalAmount,
TxnDate,
TxnID,
TxnNumber

Callbacks

POST
{$request.query.webhook_url}answered

Body

application/json

POSTed to webhook_url as JSON, signed with X-QUBE-Signature (t=<timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>" with your app's webhook secret>).

​
app_id
string<uuid>
required

Your app's id.

​
app_name
string
required
​
error
object | null
required

Set when state is error, retryable, timed_out or discarded. error_type says where it failed: for a timed_out request it is timed_out, and for a discarded one discarded, unless the request was retryable when your app discarded it, which keeps the connection error that held it up. user_message is safe to show an end user; error_code is QuickBooks' own status code for a business error, hresult the Web Connector's for a connection/XML error; debug_message is for you.

​
id
string<uuid>
required

The request's id, as the 201 returned it. For an iterated query, every page carries the first page's id here.

​
page_request_id
string<uuid>
required

This page's own id. Equal to id except on later pages of an iterated query.

​
response_json
Success · object
required

QuBe Sync's summary of QuickBooks' answer. Only an Error severity from QuickBooks is status: "error" (and makes the request's state error), so a query that matched nothing is still success. A Warn severity is a success with warning beside it.

​
sandbox
boolean
required

Whether the app is a sandbox app.

​
state
enum<string>
required

response_received: QuickBooks accepted it; read response_json. error: it is over and QuBe Sync won't try again -- see error, and response_json.error for a QuickBooks business error; with error_type outcome_unknown a write may still have been applied, so look before sending it again. retryable: QuickBooks could not be reached and QuBe Sync keeps trying; show the customer error.user_message so they can fix it. timed_out: no answer came back -- the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, mid-request. QuickBooks may still have applied it, so look before sending it again. discarded: your app discarded it before the Web Connector picked it up, so QuickBooks never got it. Both carry an error.

Available options:
response_received,
error,
retryable,
timed_out,
discarded
​
timestamp
integer
required

Unix seconds; the same t the signature covers.

​
iteration_state
enum<string>

continue: more pages will follow, each its own webhook. done: this was the last page. max_sandbox_iterations_reached: a sandbox app's page limit stopped the iteration.

Available options:
not_applicable,
continue,
done,
max_sandbox_iterations_reached
​
links
object

Present only with response_xml_omitted.

​
page
integer | null

The page number, when iterated.

​
response_xml
string | null

QuickBooks' raw qbXML answer. response_json is the same, summarized. One answer can be at most 4 MB as the Web Connector sends it, about 3 MB of qbXML; QuickBooks' answer over that isn't kept: this is null and error.error_type is response_too_large. A webhook whose body would be over 1 MB is sent without it: null, with response_xml_omitted true; fetch it from links.self.

​
response_xml_omitted
boolean

Present, and true, only when response_xml was left out to keep the body under 1 MB. response_json is still here; GET links.self for response_xml.

Response

2XX

Received. Anything else is retried with backoff for about 8 hours.

Response

Queued for the connection's Web Connector. Pass webhook_url and QuBe Sync POSTs the answer to it once QuickBooks has answered (see the answered callback: its own payload, not this document). links.self returns this document on demand, with response_json filled in.

​
data
object
required