Standalone credits

A standalone credit is a type of order that reduces your tax liability without referencing a previous order. Unlike a standard return, 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. If you have the original order ID, use a standard return 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".

$
POST /tax/connections/{connectionId}/orders

$
curl -X POST "https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders" \
>
  -H "Authorization: Bearer <token>" \
>
  -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.

1
{
2
  "$schema": "https://api.v3.taxcloud.com/tax/schemas/OrderResponse.json",
3
  "connectionId": "e3e119ae-76f0-4300-ab03-02cd47af3678",
4
  "kind": "credit",
5
  "customerId": "customer-1",
6
  "orderId": "credit-order-1",
7
  "deliveredBySeller": false,
8
  "destination": {
9
    "line1": "401 Chicago Ave",
10
    "city": "Minneapolis",
11
    "state": "MN",
12
    "zip": "55415-1515",
13
    "countryCode": "US"
14
  },
15
  "origin": {
16
    "line1": "401 Chicago Ave",
17
    "city": "Minneapolis",
18
    "state": "MN",
19
    "zip": "55415-1515",
20
    "countryCode": "US"
21
  },
22
  "currency": {
23
    "currencyCode": "USD"
24
  },
25
  "lineItems": [
26
    {
27
      "index": 0,
28
      "itemId": "1234",
29
      "tic": 0,
30
      "price": 10.5,
31
      "quantity": 1,
32
      "tax": {
33
        "rate": 0.01,
34
        "amount": 0.05
35
      }
36
    }
37
  ],
38
  "transactionDate": "2025-01-15T00:00:00Z",
39
  "completedDate": "2025-01-15T00:00:00Z",
40
  "exemption": {
41
    "isExempt": false,
42
    "exemptionId": null
43
  },
44
  "channel": null,
45
  "excludeFromFiling": false
46
}

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 conversion endpoint.

$
POST /tax/connections/{connectionId}/carts/orders

$
curl -X POST "https://api.v3.taxcloud.com/tax/connections/{connectionId}/carts/orders" \
>
  -H "Authorization: Bearer <token>" \
>
  -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. 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

For the complete list of error responses, see the Create Order API reference.

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.