> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.taxcloud.com/api-v-3/guides/workflows/processing-returns/standalone-credits/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.taxcloud.com/_mcp/server. # Standalone credits A standalone credit is a type of order that reduces your tax liability without referencing a previous order. Unlike a [standard return](https://docs.taxcloud.com/guides/workflows/processing-returns/standard-returns), which reverses part or all of a specific transaction, a standalone credit exists as its own independent record in TaxCloud. This is useful when a credit adjustment originates outside the standard order-and-return flow, for example, a credit memo from an accounting platform where the original invoice wasn't processed through TaxCloud. For tax timing implications and compliance considerations, see the [Returns & Credits Overview](https://docs.taxcloud.com/guides/workflows/processing-returns/overview). If you have the original order ID, use a [standard return](https://docs.taxcloud.com/guides/workflows/processing-returns/standard-returns) instead, it provides a stronger audit trail. ## When to Use Standalone Credits Standalone credits are designed for scenarios where a standard return against an existing order isn't possible or practical: * **Accounting platform credit memos** — Systems like QuickBooks Online allow users to create credit memos that aren't linked to a specific invoice. When syncing these to TaxCloud, a standalone credit is the appropriate path. * **Migrations from other tax providers** — If the original transaction was processed through another provider (e.g., Avalara) and you need to record a credit in TaxCloud, there's no TaxCloud order to return against. * **ERP-initiated adjustments** — Enterprise systems may generate credit adjustments through workflows that don't carry the original order reference. * **Multi-system environments** — When the transaction originated in a channel or system that doesn't integrate with TaxCloud, but the credit needs to be reflected in your TaxCloud filings. ## How It Works A standalone credit uses the same workflow as a regular order. You submit it through the same endpoint, and it goes through the same validation steps: address validation, TIC enrichment, and exemption handling all apply. You must provide the same required fields: origin, destination, line items, customer ID, and dates. The difference is in how TaxCloud records it. A standalone credit is stored with negative line item amounts, which means it naturally reduces your tax obligation for the relevant jurisdictions when your returns are filed. It flows through the same reporting and filing pipelines as any other order; there's nothing special you need to do after submitting it. ## Creating a Standalone Credit ### Request Submit a `POST` request to the Create Order endpoint with `kind` set to `"credit"`. ```shell POST /tax/connections/{connectionId}/orders ``` ```shell curl -X POST "https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders" \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ -d '{ "kind": "credit", "completedDate": "2025-01-15T00:00:00Z", "currency": { "currencyCode": "USD" }, "customerId": "customer-1", "deliveredBySeller": false, "destination": { "city": "Minneapolis", "countryCode": "US", "line1": "401 Chicago Ave", "state": "MN", "zip": "55415-1515" }, "excludeFromFiling": false, "exemption": { "exemptionId": null, "isExempt": false }, "lineItems": [ { "index": 0, "itemId": "1234", "price": 10.50, "quantity": 1, "tax": { "amount": 0.05, "rate": 0.01 }, "tic": 0 } ], "orderId": "credit-order-1", "origin": { "city": "Minneapolis", "countryCode": "US", "line1": "401 Chicago Ave", "state": "MN", "zip": "55415-1515" }, "transactionDate": "2025-01-15T00:00:00Z" }' ``` ### Response The response mirrors a standard order response, with `kind` set to `"credit"` confirming the order was created as a credit. ```json { "$schema": "https://api.v3.taxcloud.com/tax/schemas/OrderResponse.json", "connectionId": "e3e119ae-76f0-4300-ab03-02cd47af3678", "kind": "credit", "customerId": "customer-1", "orderId": "credit-order-1", "deliveredBySeller": false, "destination": { "line1": "401 Chicago Ave", "city": "Minneapolis", "state": "MN", "zip": "55415-1515", "countryCode": "US" }, "origin": { "line1": "401 Chicago Ave", "city": "Minneapolis", "state": "MN", "zip": "55415-1515", "countryCode": "US" }, "currency": { "currencyCode": "USD" }, "lineItems": [ { "index": 0, "itemId": "1234", "tic": 0, "price": 10.5, "quantity": 1, "tax": { "rate": 0.01, "amount": 0.05 } } ], "transactionDate": "2025-01-15T00:00:00Z", "completedDate": "2025-01-15T00:00:00Z", "exemption": { "isExempt": false, "exemptionId": null }, "channel": null, "excludeFromFiling": false } ``` ## Key Requirements ### `kind` must be `"credit"` The `kind` field accepts two values: `"order"` (the default) and `"credit"`. If you omit "kind” or set it to `"order"`, TaxCloud creates a standard order that adds to your tax liability. Only `"credit"` creates a negative adjustment. ### `completedDate` is required Unlike regular orders where `completedDate` can be set later (e.g., when the order ships), credit orders must include a `completedDate` at creation time. This is because a credit represents a finalized adjustment, there's no pending fulfillment step. ### Provide full address and line item details Credit orders require the same fields as regular orders: origin address, destination address, customer ID, line items with prices, quantities, and TICs. TaxCloud uses the destination address to determine which jurisdictions receive the tax credit, so accuracy matters here. ### Line item prices should be positive Enter your line item prices as positive values. TaxCloud handles the negation internally when storing and filing credit orders. You do not need to submit negative prices yourself. ## Creating a Credit from a Cart If your integration uses TaxCloud's cart flow for pre-submission tax lookups, you can convert a cart into a credit order by passing `kind: "credit"` on the [cart-to-order](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/cart/create-orders) conversion endpoint. ```shell POST /tax/connections/{connectionId}/carts/orders ``` ```shell curl -X POST "https://api.v3.taxcloud.com/tax/connections/{connectionId}/carts/orders" \ -H "X-API-KEY: " \ -H "Content-Type: application/json" \ -d '{ "cartId": "cart-123", "orderId": "credit-from-cart-1", "kind": "credit", "completed": true }' ``` This is particularly useful for integrations where the user experience includes a pre-checkout tax preview before the credit is finalized, common in ERP and accounting platform integrations where a user reviews the tax impact of a credit memo before committing it. Note that the cart itself is created normally with positive line item values. The `kind` designation happens at conversion time, not at cart creation. Carts do not support a `kind` field. ## How Credits Appear in Reporting Credit orders show up in your TaxCloud transactions and filings with negative amounts. The tax credit is applied to the jurisdictions specified by the credit order's destination address. In your filing reports, these negative amounts reduce your tax obligation for the corresponding filing period. If the credit causes a filing period to go negative (more credits than debits for a given jurisdiction), this is handled normally by TaxCloud's filing process. However, some states may reach out requesting documentation about what the credits relate to. ## Compliance and Audit Traceability Tax authorities, particularly in states participating in the Streamlined Sales Tax (SST) program, generally prefer credits to be traceable back to an original sale. If audited, you may be asked to show what each credit relates to. Standalone credits, by definition, don't carry this linkage within TaxCloud. To strengthen your audit position: * **Maintain your own mapping** between standalone credits and the original invoices or transactions they relate to, in your own system of record. Even a simple reference (e.g., storing the original invoice number alongside the TaxCloud credit order ID) can satisfy most audit inquiries. * **Use standard returns when possible.** If the original transaction exists in TaxCloud, always prefer the [Refund API](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/refunds/refund-order). Reserve standalone credits for cases where the standard path genuinely isn't available. * **Keep documentation accessible.** If a state questions a negative filing period, you'll need to demonstrate that the credits correspond to legitimate returns or adjustments. Having clear records in your accounting or ERP system is the best preparation. ## Error Handling | Error | Cause | Resolution | | ----- | ----- | ----- | | `400` Bad Request | Missing required fields or invalid `kind` value | Ensure `kind` is exactly `"credit"` or `"order"`. Verify all required fields are present. | | `422` Unprocessable Entity | Invalid address, missing `completedDate`, or other validation failure | Credit orders require `completedDate` at creation. Verify addresses are valid U.S. addresses. | For the complete list of error responses, see the [Create Order API reference](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/orders/create-order#response.error). ## Best Practices * **Default to standard returns.** Only use standalone credits when you don't have an original order in TaxCloud to return against. * **Always include `completedDate`.** Omitting it will cause the request to fail. Use the date the credit was finalized in your system. * **Use accurate destination addresses.** TaxCloud allocates the tax credit across jurisdictions based on the destination. An incorrect address means the credit goes to the wrong jurisdictions, which can cause compliance issues. * **Keep your own audit trail.** Store a reference linking each standalone credit to its business justification (original invoice, credit memo number, etc.) in your own system. * **Use consistent `orderID` values.** Give credit orders meaningful, unique IDs in your system (e.g., `credit-memo-1234`) so they're easy to identify when reviewing transactions in TaxCloud.