Skip to main content
POST
/
credit-notes
Create a new credit note
curl --request POST \
  --url https://api-m.paypal.com/v1/commerce/billing/credit-notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
  "items": [
    {
      "fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "amount": {
        "value": 0.1
      }
    },
    {
      "fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a91",
      "amount": {
        "value": 0.05
      }
    }
  ]
}'
{
  "billing_entity_code": "acme_inc",
  "sequential_id": 2,
  "number": "PP-1234-US",
  "invoice_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
  "invoice_number": "PP-1234",
  "issuing_date": "2022-12-06",
  "credit_status": "AVAILABLE",
  "refund_status": "PENDING",
  "reason": "OTHER",
  "description": "Free text",
  "total_amount": {
    "value": 1.2,
    "currency_code": "USD"
  },
  "taxes_amount": {
    "value": 0.2,
    "currency_code": "USD"
  },
  "taxes_rate": 0.2,
  "sub_total_excluding_taxes_amount": {
    "value": 1,
    "currency_code": "USD"
  },
  "balance_amount": {
    "value": 1,
    "currency_code": "USD"
  },
  "credit_amount": {
    "value": 1,
    "currency_code": "USD"
  },
  "refund_amount": {
    "value": 0,
    "currency_code": "USD"
  },
  "created_at": "2022-09-14T16:35:31Z",
  "updated_at": "2022-09-14T16:35:31Z",
  "items": [
    {
      "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "amount": {
        "value": 1,
        "currency_code": "USD"
      },
      "fee": {
        "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "total_amount": {
          "value": 1.2,
          "currency_code": "USD"
        },
        "name": "Basic Plan"
      }
    }
  ],
  "applied_taxes": [
    {
      "id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "tax_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "tax_name": "TVA",
      "tax_code": "french_standard_vat",
      "tax_rate": 20,
      "tax_description": "French standard VAT",
      "amount": {
        "value": 20,
        "currency_code": "USD"
      },
      "created_at": "2022-09-14T16:35:31Z",
      "credit_note_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "base_amount": {
        "value": 1,
        "currency_code": "USD"
      }
    }
  ],
  "id": "<string>"
}

Authorizations

Authorization
string
header
required

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

Body

application/json
invoice_id
string<uuid>
required

The invoice unique identifier.

Example:

"1a901a90-1a90-1a90-1a90-1a901a901a90"

items
object[]
required

The list of credit note's items.

Minimum length: 1
Example:
[
{
"fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"amount": { "value": 0.1 }
},
{
"fee_id": "1a901a90-1a90-1a90-1a90-1a901a901a91",
"amount": { "value": 0.05 }
}
]
reason
enum<string>

The reason for credit note creation

Available options:
DUPLICATED_CHARGE,
PRODUCT_UNSATISFACTORY,
ORDER_CHANGE,
ORDER_CANCELLATION,
FRAUDULENT_CHARGE,
OTHER
Example:

"OTHER"

description
string

The description of the credit note.

Example:

"description"

credit_amount
object

The total amount to be credited on the customer balance.

refund_amount
object

The total amount to be refunded to the customer.

Response

Credit note created successfully.

billing_entity_code
string
required

Unique code used to identify the billing entity. Must contain only alphanumeric characters, underscores, and hyphens.

Example:

"acme_inc"

sequential_id
integer
required

The sequential identifier of the credit note, specifically scoped on the associated invoice. It provides a unique numerical identifier for the credit note within the context of the invoice.

Example:

2

number
string
required

The credit note unique number.

Example:

"PP-1234-US"

invoice_id
string<uuid>
required

Unique identifier assigned to the invoice that the credit note belongs to

Example:

"1a901a90-1a90-1a90-1a90-1a901a901a90"

invoice_number
string
required

The invoice unique number, related to the credit note.

Example:

"PP-1234"

issuing_date
string<date>
required

The date of creation of the credit note. It follows the ISO 8601 date format and provides the specific date when the credit note was created.

Example:

"2023-10-01"

reason
enum<string>
required

The reason for credit note creation

Available options:
DUPLICATED_CHARGE,
PRODUCT_UNSATISFACTORY,
ORDER_CHANGE,
ORDER_CANCELLATION,
FRAUDULENT_CHARGE,
OTHER
Example:

"OTHER"

total_amount
object
required

The total amount of the credit note.

taxes_amount
object
required

The tax amount of the credit note.

taxes_rate
number
required

The tax rate associated with this specific credit note.

Example:

0.2

sub_total_excluding_taxes_amount
object
required

The subtotal of the credit note excluding any applicable taxes.

balance_amount
object
required

The remaining credit note amount.

credit_amount
object
required

The credited amount of the credit note.

refund_amount
object
required

The refunded amount of the credit note.

created_at
string<date-time>
required

The date when the credit note was created. It is expressed in Coordinated Universal Time (UTC).

Example:

"2023-10-01T12:00:00Z"

updated_at
string<date-time>
required

The date when the credit note was last updated. It is expressed in Coordinated Universal Time (UTC).

Example:

"2023-10-01T12:00:00Z"

credit_status
enum<string>

The status of the credit portion of the credit note

Available options:
AVAILABLE,
CONSUMED,
VOIDED
Example:

"AVAILABLE"

refund_status
enum<string>

The status of the refund portion of the credit note

Available options:
PENDING,
SUCCEEDED,
FAILED
Example:

"PENDING"

description
string | null

The description of the credit note.

Example:

"Free text"

items
object[]

Array of credit note's items.

applied_taxes
object[]
id
string
I