How to Use Credit Memos

Creating a Credit Memo in Our Platform

In our API, the transactionType parameter within the PUT /v1/transactions/source/{source}/externalId/{externalId} endpoint allows for the creation of credit memos through two specific types: REFUND and TAXABLE_REFUND.

Credit Memo in Our API - Transaction Types (REFUND / TAXABLE_REFUND):

REFUND: A credit memo from a linked invoice. We would want to create a REFUND credit memo if we have a linked invoice in order to avoid discrepancies in our transactions.

TAXABLE_REFUND: A credit memo not linked to a specific invoice, used when issuing a partial refund to a customer. This type of credit memo is appropriate when the refund does not correspond to a specific invoice but is necessary to return funds to the customer. The applicable sales tax for the refunded amount will be calculated based on the shippingAddress provided in the request.

1. REFUND:

Description: When transactionType is set to REFUND, the system generates a credit memo from the createdFrom transactionId if isRefundLinked is set to true; otherwise, it issues a stand-alone credit memo with the total amount.

Parameters:

• isRefundLinked (boolean): Indicates whether this refund is linked to an existing invoice (true) or is a standalone credit memo (false).

• createdFrom (string): Specifies the original transactionId from which this credit memo is derived. If provided, the system retrieves the original transaction and uses its amount and tax details for the new credit memo.

• refundLinkedPercentage (number, 0-1): Determines the percentage of the original sales tax amount to credit. For example, if the original sales tax is $30 and refundLinkedPercentage is 0.5, the credit memo will reflect a sales tax of $15.

2. TAXABLE_REFUND:

Description: When transactionType is set to TAXABLE_REFUND, the system creates a credit memo based on the totalAmount provided. The sales tax is calculated according to the shippingAddress specified in the request.

Example Usage:

To create a credit memo linked to an existing invoice:

{
  "externalId": "INV172037616",
  "source": "9",
  "items": [
    {
      "unitPrice": 100,
      "quantity": 1,
      "totalPrice": 100,
      "description": "Product Return",
      "name": "Product XYZ",
      "taxCode": "C1S1",
      "manualSalesTax": false,
      "manualSalesTaxRate": 0
    }
  ],
  "shippingAddress": {
    "city": "Example City",
    "country": "US",
    "state": "EX",
    "street": "123 Example St",
    "zip": "12345"
  },
  "customerId": "vG9s_bmFkw7Km3OuIwgL7Q",
  "transactionStatus": "ACTIVE",
  "transactionType": "REFUND",
  "createdFrom": "INV172037615",
  "isRefundLinked": true,
  "currency": "USD"
}

In this example, a credit memo is created for a returned product, linked to the original transaction (createdFrom), with 50% of the original sales tax credited back to the customer.

For more detailed information on the PUT transaction endpoint and the transactionType parameter, please refer to our API documentation.