# Upsert a credit memo

Creates or updates (upserts) a credit memo with a specified ID.

Endpoint: PUT /credit-memos/{id}
Version: latest
Security: SecretApiKey, JWT

## Path parameters:

  - `id` (string, required)
    ID of the resource.

## Request fields (application/json):

  - `allocations` (object)
    Allocations reduce the unused amount of a credit memo.

  - `allocations.transactions` (array)
    List of transactions (typically refunds, credits, and chargebacks) that are allocated to reduce the unused amount of a credit memo.

  - To delete transaction allocations, send an empty transaction allocation array in the request.
  - To modify transaction allocations, send a modified transaction allocation array in the request.
  - If you do not want to modify or delete transaction allocations, do not send a transaction allocation array in the request.

  - `allocations.transactions.transactionId` (string)
    ID of the transaction to which the credit memo is allocated.

  - `allocations.transactions.amount` (number)
    Amount of credit that is allocated from the credit memo to the transaction.
If the  value is not supplied or exceeds the unused amount of the credit memo or the transaction amount, the lesser of the following two values is used:
- The unused amount of the credit memo.
- The transaction amount.

  - `allocations.invoices` (array)
    List of invoices that the credit memo is allocated to.

- To delete invoice allocations, send an empty invoice allocation array in the request.
  Only , , and  invoices can be deleted.
- To modify invoice allocations, send a modified invoice allocation array in the request.
  Only , , and  invoices can be modified.
- If you do not want to modify or delete invoice allocations, do not send an invoice allocation array in the request.

  - `allocations.invoices.invoiceId` (string)
    ID of invoice to which the credit memo is allocated.
    Example: "in_0YVF9605RKC62BP14NE2R7V2XT"

  - `allocations.invoices.amount` (number)
    Amount of credit that is allocated from the credit memo to the invoice.
If the  value is not supplied or exceeds the unused amount of the credit memo or the invoice due amount, the lesser of the following two values is used:
- The unused amount of the credit memo.
- The invoice due amount.

  - `items` (array)
    Items of the credit memo.

  - `items.invoiceItemId` (string,null)
    ID of the invoice item to which the credit item is referenced.
    Example: "ii_0YVFDEQS2KCFTBN9HXWJFY55GV"

  - `items.description` (string)
    Description of the credit memo item.

  - `items.unitPrice` (number, required)
    Price of the credit memo item.

  - `items.quantity` (integer, required)
    Quantity of the credit memo item.

  - `items.productId` (string,null)
    ID of the related product.
    Example: "prod_0YV7DES3WPC5J8JD8QTVNZBZNZ"

  - `items.planId` (string,null)
    ID of the related plan.
    Example: "plan_0YV7DENSVGDBW9S71XZNNYYQ0X"

  - `items.tax` (any)
    Credit memo item tax.

  - `reason` (string)
    Reason for the credit memo.
    Enum: "return", "product-unsatisfactory", "order-change", "order-cancellation", "chargeback", "write-off", "waiver", "customer-credit", "other"

  - `description` (string)
    Public description, that is visible to customers, which describes the purpose of the credit memo.

  - `shippingAmount` (number)
    Shipping amount of an invoice to credit.

  - `customerId` (string, required)
    ID of the customer resource.

  - `currency` (string, required)
    Currency code in ISO 4217 format.

  - `invoiceId` (string,null)
    ID of the invoice to which the credit memo is issued.
    Example: "in_0YVF9605RKC62BP14NE2R7V2XT"

## Response 200 fields (application/json):

  - `id` (string)
    ID of the credit memo.
    Example: "crmm_0YVCNN22TWC3G8H82QNPNVZCHG"

  - `number` (integer)
    Auto-incrementing number based on the sequence of credit memos for any particular customer.

  - `allocations` (object)
    Allocations reduce the unused amount of a credit memo.

  - `allocations.transactions` (array)
    List of transactions (typically refunds, credits, and chargebacks) that are allocated to reduce the unused amount of a credit memo.

  - To delete transaction allocations, send an empty transaction allocation array in the request.
  - To modify transaction allocations, send a modified transaction allocation array in the request.
  - If you do not want to modify or delete transaction allocations, do not send a transaction allocation array in the request.

  - `allocations.transactions.transactionId` (string)
    ID of the transaction to which the credit memo is allocated.

  - `allocations.transactions.amount` (number)
    Amount of credit that is allocated from the credit memo to the transaction.
If the  value is not supplied or exceeds the unused amount of the credit memo or the transaction amount, the lesser of the following two values is used:
- The unused amount of the credit memo.
- The transaction amount.

  - `allocations.transactions.currency` (string)
    Currency code in ISO 4217 format.

  - `allocations.transactions.createdTime` (string)
    Date and time which is set automatically when the resource is created.

  - `allocations.transactions.updatedTime` (string)
    Date and time which updates automatically when the resource is updated.

  - `allocations.invoices` (array)
    List of invoices that the credit memo is allocated to.

- To delete invoice allocations, send an empty invoice allocation array in the request.
  Only , , and  invoices can be deleted.
- To modify invoice allocations, send a modified invoice allocation array in the request.
  Only , , and  invoices can be modified.
- If you do not want to modify or delete invoice allocations, do not send an invoice allocation array in the request.

  - `allocations.invoices.invoiceId` (string)
    ID of invoice to which the credit memo is allocated.
    Example: "in_0YVF9605RKC62BP14NE2R7V2XT"

  - `allocations.invoices.amount` (number)
    Amount of credit that is allocated from the credit memo to the invoice.
If the  value is not supplied or exceeds the unused amount of the credit memo or the invoice due amount, the lesser of the following two values is used:
- The unused amount of the credit memo.
- The invoice due amount.

  - `allocations.invoices.createdTime` (string)
    Date and time at which a credit memo is allocated.

  - `items` (array)
    Items of the credit memo.

  - `items.id` (string)
    ID of the credit memo item.
    Example: "crmm_itm_01HXC7PK2C6F367VYCFXDRYMAQ"

  - `items.invoiceItemId` (string,null)
    ID of the invoice item to which the credit item is referenced.
    Example: "ii_0YVFDEQS2KCFTBN9HXWJFY55GV"

  - `items.description` (string)
    Description of the credit memo item.

  - `items.unitPrice` (number, required)
    Price of the credit memo item.

  - `items.quantity` (integer, required)
    Quantity of the credit memo item.

  - `items.price` (number)
    Total price of the credit memo item.

  - `items.productId` (string,null)
    ID of the related product.
    Example: "prod_0YV7DES3WPC5J8JD8QTVNZBZNZ"

  - `items.planId` (string,null)
    ID of the related plan.
    Example: "plan_0YV7DENSVGDBW9S71XZNNYYQ0X"

  - `items.tax` (any)
    Credit memo item tax.

  - `status` (string)
    Status of the credit memo.
    Enum: "issued", "applied", "partially-applied", "voided"

  - `reason` (string)
    Reason for the credit memo.
    Enum: "return", "product-unsatisfactory", "order-change", "order-cancellation", "chargeback", "write-off", "waiver", "customer-credit", "other"

  - `description` (string)
    Public description, that is visible to customers, which describes the purpose of the credit memo.

  - `shippingAmount` (number)
    Shipping amount of an invoice to credit.

  - `taxAmount` (number)
    Sum of items tax amount of an invoice to credit.

  - `totalAmount` (number)
    Total amount of all credits in the credit memo, including items, shipping, and tax.

  - `unusedAmount` (number)
    Unused credit memo amount that has not been allocated.

  - `revision` (integer)
    Number of times the credit memo has been modified.

  - `customerId` (string, required)
    ID of the customer resource.

  - `invoiceId` (string,null)
    ID of the invoice to which the credit memo is issued.
    Example: "in_0YVF9605RKC62BP14NE2R7V2XT"

  - `_links` (array)
    Related links.

  - `_links.href` (string)
    Link URL.

  - `_links.rel` (string)
    Type of link.
    Enum: "self", "customer", "invoice"

  - `_embedded` (object)
    Embedded objects that are requested by the  query parameter.

  - `_embedded.customer` (object)

## Response 201 fields (application/json):

  - `id` (string)
    ID of the credit memo.
    Example: "crmm_0YVCNN22TWC3G8H82QNPNVZCHG"

  - `number` (integer)
    Auto-incrementing number based on the sequence of credit memos for any particular customer.

  - `allocations` (object)
    Allocations reduce the unused amount of a credit memo.

  - `allocations.transactions` (array)
    List of transactions (typically refunds, credits, and chargebacks) that are allocated to reduce the unused amount of a credit memo.

  - To delete transaction allocations, send an empty transaction allocation array in the request.
  - To modify transaction allocations, send a modified transaction allocation array in the request.
  - If you do not want to modify or delete transaction allocations, do not send a transaction allocation array in the request.

  - `allocations.transactions.transactionId` (string)
    ID of the transaction to which the credit memo is allocated.

  - `allocations.transactions.amount` (number)
    Amount of credit that is allocated from the credit memo to the transaction.
If the  value is not supplied or exceeds the unused amount of the credit memo or the transaction amount, the lesser of the following two values is used:
- The unused amount of the credit memo.
- The transaction amount.

  - `allocations.transactions.currency` (string)
    Currency code in ISO 4217 format.

  - `allocations.transactions.createdTime` (string)
    Date and time which is set automatically when the resource is created.

  - `allocations.transactions.updatedTime` (string)
    Date and time which updates automatically when the resource is updated.

  - `allocations.invoices` (array)
    List of invoices that the credit memo is allocated to.

- To delete invoice allocations, send an empty invoice allocation array in the request.
  Only , , and  invoices can be deleted.
- To modify invoice allocations, send a modified invoice allocation array in the request.
  Only , , and  invoices can be modified.
- If you do not want to modify or delete invoice allocations, do not send an invoice allocation array in the request.

  - `allocations.invoices.invoiceId` (string)
    ID of invoice to which the credit memo is allocated.
    Example: "in_0YVF9605RKC62BP14NE2R7V2XT"

  - `allocations.invoices.amount` (number)
    Amount of credit that is allocated from the credit memo to the invoice.
If the  value is not supplied or exceeds the unused amount of the credit memo or the invoice due amount, the lesser of the following two values is used:
- The unused amount of the credit memo.
- The invoice due amount.

  - `allocations.invoices.createdTime` (string)
    Date and time at which a credit memo is allocated.

  - `items` (array)
    Items of the credit memo.

  - `items.id` (string)
    ID of the credit memo item.
    Example: "crmm_itm_01HXC7PK2C6F367VYCFXDRYMAQ"

  - `items.invoiceItemId` (string,null)
    ID of the invoice item to which the credit item is referenced.
    Example: "ii_0YVFDEQS2KCFTBN9HXWJFY55GV"

  - `items.description` (string)
    Description of the credit memo item.

  - `items.unitPrice` (number, required)
    Price of the credit memo item.

  - `items.quantity` (integer, required)
    Quantity of the credit memo item.

  - `items.price` (number)
    Total price of the credit memo item.

  - `items.productId` (string,null)
    ID of the related product.
    Example: "prod_0YV7DES3WPC5J8JD8QTVNZBZNZ"

  - `items.planId` (string,null)
    ID of the related plan.
    Example: "plan_0YV7DENSVGDBW9S71XZNNYYQ0X"

  - `items.tax` (any)
    Credit memo item tax.

  - `status` (string)
    Status of the credit memo.
    Enum: "issued", "applied", "partially-applied", "voided"

  - `reason` (string)
    Reason for the credit memo.
    Enum: "return", "product-unsatisfactory", "order-change", "order-cancellation", "chargeback", "write-off", "waiver", "customer-credit", "other"

  - `description` (string)
    Public description, that is visible to customers, which describes the purpose of the credit memo.

  - `shippingAmount` (number)
    Shipping amount of an invoice to credit.

  - `taxAmount` (number)
    Sum of items tax amount of an invoice to credit.

  - `totalAmount` (number)
    Total amount of all credits in the credit memo, including items, shipping, and tax.

  - `unusedAmount` (number)
    Unused credit memo amount that has not been allocated.

  - `revision` (integer)
    Number of times the credit memo has been modified.

  - `customerId` (string, required)
    ID of the customer resource.

  - `invoiceId` (string,null)
    ID of the invoice to which the credit memo is issued.
    Example: "in_0YVF9605RKC62BP14NE2R7V2XT"

  - `_links` (array)
    Related links.

  - `_links.href` (string)
    Link URL.

  - `_links.rel` (string)
    Type of link.
    Enum: "self", "customer", "invoice"

  - `_embedded` (object)
    Embedded objects that are requested by the  query parameter.

  - `_embedded.customer` (object)

## Response 401 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 403 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 404 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 422 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

  - `invalidFields` (array)
    Invalid field details.
    Example: [{"field":"field1","message":"field1 is invalid"},{"field":"subObject.field2","message":"field2 is invalid"},{"field":"subObject.field2","message":"another error in the field2"}]

  - `invalidFields.field` (string)
    Name of the field.
Dot notation is used for nested object field names.

  - `invalidFields.message` (string)
    Message field.

## Response 429 fields (application/json):

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".
    Example: "about:blank"

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.
    Example: "Rate Limit Exceeded"

  - `status` (integer)
    HTTP status code.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.
    Example: "A request cannot be executed because the user has sent too many requests within a certain period of time"

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.