# 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.
    Example: txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0

  - `allocations.transactions.amount` (number)
    Amount of credit that is allocated from the credit memo to the transaction.
If the `amount` 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.
    Example: USD

  - `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 `unpaid`, `partially-paid`, and `past-due` invoices can be deleted.
- To modify invoice allocations, send a modified invoice allocation array in the request.
Only `unpaid`, `partially-paid`, and `past-due` 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 `amount` 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.

  - `items.tax.amount` (number, required)
    Amount of the tax.

  - `items.tax.description` (string, required)
    Description of the tax.

  - `items.tax.rate` (number | null)
    Overall sales tax rate which includes state, county, city and district tax.

  - `items.tax.stateAmount` (number | null)
    Amount of sales tax to collect for the state.
    Example: 0.94

  - `items.tax.countyAmount` (number | null)
    Amount of sales tax to collect for the county.
    Example: 0.04

  - `items.tax.cityAmount` (number | null)
    Amount of sales tax to collect for the city.
    Example: 0

  - `items.tax.specialDistrictAmount` (number | null)
    Amount of sales tax to collect for the special district.
    Example: 0.38

  - `items.tax.stateRate` (number | null)
    State sales tax rate for given location.

  - `items.tax.countyRate` (number | null)
    County sales tax rate for given location.

  - `items.tax.cityRate` (number | null)
    City sales tax rate for given location.

  - `items.tax.specialDistrictRate` (number | null)
    Special district sales tax rate for given location.

  - `items.tax.jurisdictions` (object | null)
    Jurisdiction names for the invoice.

  - `items.tax.jurisdictions.country` (string | null)
    Two-letter ISO country code for the provided location.
    Example: US

  - `items.tax.jurisdictions.state` (string | null)
    Postal abbreviated state name for the provided location.
    Example: CA

  - `items.tax.jurisdictions.county` (string | null)
    County name for the provided location.
    Example: LOS ANGELES

  - `items.tax.jurisdictions.city` (string | null)
    City name for the provided location.
    Example: LOS ANGELES

  - `reason` (string)
    Reason for the credit memo.
    Enum: "return", "product-unsatisfactory", "order-change", "order-cancellation", "chargeback", "write-off", "waiver", "customer-credit", "prepayment", "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.
    Example: cus_0YV7DDSDD1C8DA64KHH2W33CPF

  - `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.
    Example: txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0

  - `allocations.transactions.amount` (number)
    Amount of credit that is allocated from the credit memo to the transaction.
If the `amount` 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.
    Example: USD

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

  - `allocations.transactions.updatedTime` (string)
    Date and time when the resource is updated.
This value is set 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 `unpaid`, `partially-paid`, and `past-due` invoices can be deleted.
- To modify invoice allocations, send a modified invoice allocation array in the request.
Only `unpaid`, `partially-paid`, and `past-due` 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 `amount` 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)
    Read-only timestamp in ISO 8601 date-time format.

  - `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.

  - `items.tax.amount` (number, required)
    Amount of the tax.

  - `items.tax.description` (string, required)
    Description of the tax.

  - `items.tax.rate` (number | null)
    Overall sales tax rate which includes state, county, city and district tax.

  - `items.tax.stateAmount` (number | null)
    Amount of sales tax to collect for the state.
    Example: 0.94

  - `items.tax.countyAmount` (number | null)
    Amount of sales tax to collect for the county.
    Example: 0.04

  - `items.tax.cityAmount` (number | null)
    Amount of sales tax to collect for the city.
    Example: 0

  - `items.tax.specialDistrictAmount` (number | null)
    Amount of sales tax to collect for the special district.
    Example: 0.38

  - `items.tax.stateRate` (number | null)
    State sales tax rate for given location.

  - `items.tax.countyRate` (number | null)
    County sales tax rate for given location.

  - `items.tax.cityRate` (number | null)
    City sales tax rate for given location.

  - `items.tax.specialDistrictRate` (number | null)
    Special district sales tax rate for given location.

  - `items.tax.jurisdictions` (object | null)
    Jurisdiction names for the invoice.

  - `items.tax.jurisdictions.country` (string | null)
    Two-letter ISO country code for the provided location.
    Example: US

  - `items.tax.jurisdictions.state` (string | null)
    Postal abbreviated state name for the provided location.
    Example: CA

  - `items.tax.jurisdictions.county` (string | null)
    County name for the provided location.
    Example: LOS ANGELES

  - `items.tax.jurisdictions.city` (string | null)
    City name for the provided location.
    Example: LOS ANGELES

  - `status` (string)
    Status of the credit memo.
    Enum: "draft", "quotation", "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", "prepayment", "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.
    Example: cus_0YV7DDSDD1C8DA64KHH2W33CPF

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

  - `quoteId` (string | null)
    ID of the related quote.
    Example: qt_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 `expand` 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.
    Example: txn_0YVDTQJ8YWDGQACV2N2N5SPWQ0

  - `allocations.transactions.amount` (number)
    Amount of credit that is allocated from the credit memo to the transaction.
If the `amount` 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.
    Example: USD

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

  - `allocations.transactions.updatedTime` (string)
    Date and time when the resource is updated.
This value is set 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 `unpaid`, `partially-paid`, and `past-due` invoices can be deleted.
- To modify invoice allocations, send a modified invoice allocation array in the request.
Only `unpaid`, `partially-paid`, and `past-due` 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 `amount` 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)
    Read-only timestamp in ISO 8601 date-time format.

  - `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.

  - `items.tax.amount` (number, required)
    Amount of the tax.

  - `items.tax.description` (string, required)
    Description of the tax.

  - `items.tax.rate` (number | null)
    Overall sales tax rate which includes state, county, city and district tax.

  - `items.tax.stateAmount` (number | null)
    Amount of sales tax to collect for the state.
    Example: 0.94

  - `items.tax.countyAmount` (number | null)
    Amount of sales tax to collect for the county.
    Example: 0.04

  - `items.tax.cityAmount` (number | null)
    Amount of sales tax to collect for the city.
    Example: 0

  - `items.tax.specialDistrictAmount` (number | null)
    Amount of sales tax to collect for the special district.
    Example: 0.38

  - `items.tax.stateRate` (number | null)
    State sales tax rate for given location.

  - `items.tax.countyRate` (number | null)
    County sales tax rate for given location.

  - `items.tax.cityRate` (number | null)
    City sales tax rate for given location.

  - `items.tax.specialDistrictRate` (number | null)
    Special district sales tax rate for given location.

  - `items.tax.jurisdictions` (object | null)
    Jurisdiction names for the invoice.

  - `items.tax.jurisdictions.country` (string | null)
    Two-letter ISO country code for the provided location.
    Example: US

  - `items.tax.jurisdictions.state` (string | null)
    Postal abbreviated state name for the provided location.
    Example: CA

  - `items.tax.jurisdictions.county` (string | null)
    County name for the provided location.
    Example: LOS ANGELES

  - `items.tax.jurisdictions.city` (string | null)
    City name for the provided location.
    Example: LOS ANGELES

  - `status` (string)
    Status of the credit memo.
    Enum: "draft", "quotation", "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", "prepayment", "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.
    Example: cus_0YV7DDSDD1C8DA64KHH2W33CPF

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

  - `quoteId` (string | null)
    ID of the related quote.
    Example: qt_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 `expand` 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.