Credit Notes

Credit notes adjust an invoice amount after it has been finalized. Used to issue credit or refunds.

Properties

Name
object
Type
string
Description
Type of object is always creditNote.
Allowed values: creditNote
Name
id
Type
string
Description
Unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"
Name
createdAt
Type
string
Description
Time when the credit note was created.
Example: "2024-06-14T19:38:34Z"
Name
creditTo
Type
string
Description
Specifies where the credit amount should be credited to. It can have one of the following values:

outOfBand: The amount should be handled outside the system by the customer.

userBalance: The amount should be added to the user balance at Gigs.
Allowed values: outOfBand userBalance
Name
fees
Type
array
Description
The credited fees.
Name
amount
Type
Price
Description
The amount of the fee.
Example: {"amount":100,"currency":"USD"}
Optional: This property may not always be included.
Name
name
Type
string
Description
The name of the fee.
Optional: This property may not always be included.
Example: "Recovery Fee"
Name
type
Type
string
Description
The type of the fee.
Optional: This property may not always be included.
Allowed values: recoveryFee
Name
fileUrl
Type
nullable string
Status
PREVIEW
Description
A signed URL to download the credit note PDF file. The URL is valid for 1 minute.

This field is null for projects without billing enabled, and for credit notes covering US-taxed plans.
Example: "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123"
Name
invoice
Type
string
Description
The unique identifier for the invoice that the credit note applies to.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
lineItems
Type
array
Description
The line items for the credit note.
Name
status
Type
string
Description
The status of the credit note. It can have one of the following values:

issued: The credit note was issued.

voided: The credit note was voided and no longer has any effect.
Allowed values: issued voided
Name
subtotal
Type
Price
Description
The total amount credited before any taxes or fees.
Example: {"amount":999,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
tax
Type
Price
Description
The sum of the amounts in taxes credited for each line item.
Example: {"amount":200,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
total
Type
Price
Description
The total amount credited after taxes and fees.
Example: {"amount":1199,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
voidedAt
Type
nullable string
Description
Time when the credit note was voided.
Example: "2024-06-14T19:38:34Z"

Example

{
  "object": "creditNote",
  "id": "crn_0SNlurA049MEWV49X25tqzNV2jji",
  "createdAt": "2024-06-14T19:38:34.0Z",
  "creditTo": "outOfBand",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123",
  "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "lineItems": [
    {
      "amount": {
        "amount": 999,
        "currency": "USD"
      },
      "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3"
        }
      ],
      "total": {
        "amount": 1199,
        "currency": "USD"
      }
    }
  ],
  "status": "issued",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voidedAt": "2024-06-14T19:38:34Z"
}

GET/projects/{project}/creditNotes

Create a credit note

Creates a new credit note for an invoice.

When only invoice is provided, the full amount of the invoice will be credited, including all taxes and fees. If the invoice has already been partially credited, the remaining amount will be credited.

When selected lineItems, taxes or fees are provided, only those will be credited.

Non-refundable taxes will still have to be filed with the tax authorities.

Body

Name
invoice
Type
string
required
Description
The unique identifier for the invoice that the credit note applies to.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
lineItems
Type
nullable array
Description
The line items for the credit note.
Name
invoiceLineItem
Type
string
Description
The unique identifier for the invoice line item that this line item applies to.
Example: "lin_0SNlurA049MEWV11QUKZGDMxJmKe"
Name
amount
Type
nullable integer
Description
The amount to be credited for the line item in the currency of the invoice. If not provided or null the line item will not be credited, but taxes will be credited if provided.
Example: 999
>= 0
Name
taxes
Type
array
Description
The taxes to be credited for this line item. If not provided, no taxes for this line item will be credited.
Name
fees
Type
nullable array
Description
The fees to be credited.
Name
type
Type
string
Description
The type of fee to be credited.
Name
amount
Type
integer
Description
The amount to be credited for the fee in the currency of the invoice.
Example: 999
>= 0

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Responses

Returns the created credit note.

Name
object
Type
string
Description
Type of object is always creditNote.
Allowed values: creditNote
Name
id
Type
string
Description
Unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"
Name
createdAt
Type
string
Description
Time when the credit note was created.
Example: "2024-06-14T19:38:34Z"
Name
creditTo
Type
string
Description
Specifies where the credit amount should be credited to. It can have one of the following values:

outOfBand: The amount should be handled outside the system by the customer.

userBalance: The amount should be added to the user balance at Gigs.
Allowed values: outOfBand userBalance
Name
fees
Type
array
Description
The credited fees.
Name
amount
Type
Price
Description
The amount of the fee.
Example: {"amount":100,"currency":"USD"}
Optional: This property may not always be included.
Name
name
Type
string
Description
The name of the fee.
Optional: This property may not always be included.
Example: "Recovery Fee"
Name
type
Type
string
Description
The type of the fee.
Optional: This property may not always be included.
Allowed values: recoveryFee
Name
fileUrl
Type
nullable string
Status
PREVIEW
Description
A signed URL to download the credit note PDF file. The URL is valid for 1 minute.

This field is null for projects without billing enabled, and for credit notes covering US-taxed plans.
Example: "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123"
Name
invoice
Type
string
Description
The unique identifier for the invoice that the credit note applies to.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
lineItems
Type
array
Description
The line items for the credit note.
Name
status
Type
string
Description
The status of the credit note. It can have one of the following values:

issued: The credit note was issued.

voided: The credit note was voided and no longer has any effect.
Allowed values: issued voided
Name
subtotal
Type
Price
Description
The total amount credited before any taxes or fees.
Example: {"amount":999,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
tax
Type
Price
Description
The sum of the amounts in taxes credited for each line item.
Example: {"amount":200,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
total
Type
Price
Description
The total amount credited after taxes and fees.
Example: {"amount":1199,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
voidedAt
Type
nullable string
Description
Time when the credit note was voided.
Example: "2024-06-14T19:38:34Z"

Request

POST

/projects/{project}/creditNotes

curl https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
  "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "lineItems": [
    {
      "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "amount": 999,
      "taxes": [
        {
          "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3",
          "amount": 200
        }
      ]
    }
  ],
  "fees": [
    {
      "amount": 999
    }
  ]
}'

Response

{
  "object": "creditNote",
  "id": "crn_0SNlurA049MEWV49X25tqzNV2jji",
  "createdAt": "2024-06-14T19:38:34Z",
  "creditTo": "outOfBand",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123",
  "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "lineItems": [
    {
      "amount": {
        "amount": 999,
        "currency": "USD"
      },
      "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3"
        }
      ],
      "total": {
        "amount": 1199,
        "currency": "USD"
      }
    }
  ],
  "status": "issued",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voidedAt": "2024-06-14T19:38:34Z"
}

GET/projects/{project}/creditNotes/{creditNote}

Retrieve a credit note

Retrieves the details of an existing credit note.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
creditNote
Type
string
required
Description
The unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"

Responses

Returns the credit note.

Name
object
Type
string
Description
Type of object is always creditNote.
Allowed values: creditNote
Name
id
Type
string
Description
Unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"
Name
createdAt
Type
string
Description
Time when the credit note was created.
Example: "2024-06-14T19:38:34Z"
Name
creditTo
Type
string
Description
Specifies where the credit amount should be credited to. It can have one of the following values:

outOfBand: The amount should be handled outside the system by the customer.

userBalance: The amount should be added to the user balance at Gigs.
Allowed values: outOfBand userBalance
Name
fees
Type
array
Description
The credited fees.
Name
amount
Type
Price
Description
The amount of the fee.
Example: {"amount":100,"currency":"USD"}
Optional: This property may not always be included.
Name
name
Type
string
Description
The name of the fee.
Optional: This property may not always be included.
Example: "Recovery Fee"
Name
type
Type
string
Description
The type of the fee.
Optional: This property may not always be included.
Allowed values: recoveryFee
Name
fileUrl
Type
nullable string
Status
PREVIEW
Description
A signed URL to download the credit note PDF file. The URL is valid for 1 minute.

This field is null for projects without billing enabled, and for credit notes covering US-taxed plans.
Example: "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123"
Name
invoice
Type
string
Description
The unique identifier for the invoice that the credit note applies to.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
lineItems
Type
array
Description
The line items for the credit note.
Name
status
Type
string
Description
The status of the credit note. It can have one of the following values:

issued: The credit note was issued.

voided: The credit note was voided and no longer has any effect.
Allowed values: issued voided
Name
subtotal
Type
Price
Description
The total amount credited before any taxes or fees.
Example: {"amount":999,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
tax
Type
Price
Description
The sum of the amounts in taxes credited for each line item.
Example: {"amount":200,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
total
Type
Price
Description
The total amount credited after taxes and fees.
Example: {"amount":1199,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
voidedAt
Type
nullable string
Description
Time when the credit note was voided.
Example: "2024-06-14T19:38:34Z"

Request

GET

/projects/{project}/creditNotes/{creditNote}

curl https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes/{creditNote} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Response

{
  "object": "creditNote",
  "id": "crn_0SNlurA049MEWV49X25tqzNV2jji",
  "createdAt": "2024-06-14T19:38:34Z",
  "creditTo": "outOfBand",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123",
  "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "lineItems": [
    {
      "amount": {
        "amount": 999,
        "currency": "USD"
      },
      "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3"
        }
      ],
      "total": {
        "amount": 1199,
        "currency": "USD"
      }
    }
  ],
  "status": "issued",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voidedAt": "2024-06-14T19:38:34Z"
}

POST/projects/{project}/creditNotes/{creditNote}/void

Void a credit note

Marks the credit note as void. This reverses the credited amount in the invoice and reported taxes.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
creditNote
Type
string
required
Description
The unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"

Responses

Returns the voided credit note.

Name
object
Type
string
Description
Type of object is always creditNote.
Allowed values: creditNote
Name
id
Type
string
Description
Unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"
Name
createdAt
Type
string
Description
Time when the credit note was created.
Example: "2024-06-14T19:38:34Z"
Name
creditTo
Type
string
Description
Specifies where the credit amount should be credited to. It can have one of the following values:

outOfBand: The amount should be handled outside the system by the customer.

userBalance: The amount should be added to the user balance at Gigs.
Allowed values: outOfBand userBalance
Name
fees
Type
array
Description
The credited fees.
Name
amount
Type
Price
Description
The amount of the fee.
Example: {"amount":100,"currency":"USD"}
Optional: This property may not always be included.
Name
name
Type
string
Description
The name of the fee.
Optional: This property may not always be included.
Example: "Recovery Fee"
Name
type
Type
string
Description
The type of the fee.
Optional: This property may not always be included.
Allowed values: recoveryFee
Name
fileUrl
Type
nullable string
Status
PREVIEW
Description
A signed URL to download the credit note PDF file. The URL is valid for 1 minute.

This field is null for projects without billing enabled, and for credit notes covering US-taxed plans.
Example: "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123"
Name
invoice
Type
string
Description
The unique identifier for the invoice that the credit note applies to.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
lineItems
Type
array
Description
The line items for the credit note.
Name
status
Type
string
Description
The status of the credit note. It can have one of the following values:

issued: The credit note was issued.

voided: The credit note was voided and no longer has any effect.
Allowed values: issued voided
Name
subtotal
Type
Price
Description
The total amount credited before any taxes or fees.
Example: {"amount":999,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
tax
Type
Price
Description
The sum of the amounts in taxes credited for each line item.
Example: {"amount":200,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
total
Type
Price
Description
The total amount credited after taxes and fees.
Example: {"amount":1199,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
voidedAt
Type
nullable string
Description
Time when the credit note was voided.
Example: "2024-06-14T19:38:34Z"

Request

POST

/projects/{project}/creditNotes/{creditNote}/void

curl https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes/{creditNote}/void \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Response

{
  "object": "creditNote",
  "id": "crn_0SNlurA049MEWV49X25tqzNV2jji",
  "createdAt": "2024-06-14T19:38:34Z",
  "creditTo": "outOfBand",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123",
  "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "lineItems": [
    {
      "amount": {
        "amount": 999,
        "currency": "USD"
      },
      "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3"
        }
      ],
      "total": {
        "amount": 1199,
        "currency": "USD"
      }
    }
  ],
  "status": "issued",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voidedAt": "2024-06-14T19:38:34Z"
}

Credit Notes

Credit notes adjust an invoice amount after it has been finalized. Used to issue credit or refunds.

Properties

Name
object
Type
string
Description
Type of object is always creditNote.
Allowed values: creditNote
Name
id
Type
string
Description
Unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"
Name
createdAt
Type
string
Description
Time when the credit note was created.
Example: "2024-06-14T19:38:34Z"
Name
creditTo
Type
string
Description
Specifies where the credit amount should be credited to. It can have one of the following values:

outOfBand: The amount should be handled outside the system by the customer.

userBalance: The amount should be added to the user balance at Gigs.
Allowed values: outOfBand userBalance
Name
fees
Type
array
Description
The credited fees.
Name
amount
Type
Price
Description
The amount of the fee.
Example: {"amount":100,"currency":"USD"}
Optional: This property may not always be included.
Name
name
Type
string
Description
The name of the fee.
Optional: This property may not always be included.
Example: "Recovery Fee"
Name
type
Type
string
Description
The type of the fee.
Optional: This property may not always be included.
Allowed values: recoveryFee
Name
fileUrl
Type
nullable string
Status
PREVIEW
Description
A signed URL to download the credit note PDF file. The URL is valid for 1 minute.

This field is null for projects without billing enabled, and for credit notes covering US-taxed plans.
Example: "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123"
Name
invoice
Type
string
Description
The unique identifier for the invoice that the credit note applies to.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
lineItems
Type
array
Description
The line items for the credit note.
Name
status
Type
string
Description
The status of the credit note. It can have one of the following values:

issued: The credit note was issued.

voided: The credit note was voided and no longer has any effect.
Allowed values: issued voided
Name
subtotal
Type
Price
Description
The total amount credited before any taxes or fees.
Example: {"amount":999,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
tax
Type
Price
Description
The sum of the amounts in taxes credited for each line item.
Example: {"amount":200,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
total
Type
Price
Description
The total amount credited after taxes and fees.
Example: {"amount":1199,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
voidedAt
Type
nullable string
Description
Time when the credit note was voided.
Example: "2024-06-14T19:38:34Z"

Example

{
  "object": "creditNote",
  "id": "crn_0SNlurA049MEWV49X25tqzNV2jji",
  "createdAt": "2024-06-14T19:38:34.0Z",
  "creditTo": "outOfBand",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123",
  "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "lineItems": [
    {
      "amount": {
        "amount": 999,
        "currency": "USD"
      },
      "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3"
        }
      ],
      "total": {
        "amount": 1199,
        "currency": "USD"
      }
    }
  ],
  "status": "issued",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voidedAt": "2024-06-14T19:38:34Z"
}

GET/projects/{project}/creditNotes

List all credit notes

Returns a list of credit notes.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Query Parameters

Name
after
Type
string
Description
A cursor for use in pagination. The after parameter takes an object ID that defines the position in the list, only items immediately following the item with that ID will be returned.
Name
before
Type
string
Description
A cursor for use in pagination. The before parameter takes an object ID that defines the position in the list, only items immediately preceding the item with that ID will be returned.
Name
limit
Type
integer
Description
The limit of items to be returned in the list, between 0 and 200.
Example: 20
Default: 10
>= 0
<= 200
Name
invoice
Type
string
Description
The unique identifier for the invoice to be filtered by.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
status
Type
array
Description
A comma-separated list of statuses to filter the credit notes by.

Responses

Returns a dictionary with an items property that contains an array of credit notes.

Name
object
Type
string
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
Description
List of objects of type creditNote.
Name
moreItemsAfter
Type
nullable string
Description
A unique identifier to be used as after pagination parameter if more items are available sorted after the current batch of items.
Name
moreItemsBefore
Type
nullable string
Description
A unique identifier to be used as before pagination parameter if more items are available sorted before the current batch of items.

Request

GET

/projects/{project}/creditNotes

curl https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Responses

{
  "object": "list",
  "items": [
    {
      "object": "creditNote",
      "id": "crn_0SNlurA049MEWV49X25tqzNV2jji",
      "createdAt": "2024-06-14T19:38:34Z",
      "creditTo": "outOfBand",
      "fees": [
        {
          "amount": {
            "amount": 100,
            "currency": "USD"
          },
          "name": "Recovery Fee",
          "type": "recoveryFee"
        }
      ],
      "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123",
      "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
      "lineItems": [
        {
          "amount": {
            "amount": 999,
            "currency": "USD"
          },
          "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
          "tax": {
            "amount": 200,
            "currency": "USD"
          },
          "taxes": [
            {
              "amount": {
                "amount": 200,
                "currency": "USD"
              },
              "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3"
            }
          ],
          "total": {
            "amount": 1199,
            "currency": "USD"
          }
        }
      ],
      "status": "issued",
      "subtotal": {
        "amount": 999,
        "currency": "USD"
      },
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "total": {
        "amount": 1199,
        "currency": "USD"
      },
      "voidedAt": "2024-06-14T19:38:34Z"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

POST/projects/{project}/creditNotes

Create a credit note

Creates a new credit note for an invoice.

When selected lineItems, taxes or fees are provided, only those will be credited.

Non-refundable taxes will still have to be filed with the tax authorities.

Body

Name
invoice
Type
string
required
Description
The unique identifier for the invoice that the credit note applies to.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
lineItems
Type
nullable array
Description
The line items for the credit note.
Name
invoiceLineItem
Type
string
Description
The unique identifier for the invoice line item that this line item applies to.
Example: "lin_0SNlurA049MEWV11QUKZGDMxJmKe"
Name
amount
Type
nullable integer
Description
The amount to be credited for the line item in the currency of the invoice. If not provided or null the line item will not be credited, but taxes will be credited if provided.
Example: 999
>= 0
Name
taxes
Type
array
Description
The taxes to be credited for this line item. If not provided, no taxes for this line item will be credited.
Name
fees
Type
nullable array
Description
The fees to be credited.
Name
type
Type
string
Description
The type of fee to be credited.
Name
amount
Type
integer
Description
The amount to be credited for the fee in the currency of the invoice.
Example: 999
>= 0

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"

Responses

Returns the created credit note.

Name
object
Type
string
Description
Type of object is always creditNote.
Allowed values: creditNote
Name
id
Type
string
Description
Unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"
Name
createdAt
Type
string
Description
Time when the credit note was created.
Example: "2024-06-14T19:38:34Z"
Name
creditTo
Type
string
Description
Specifies where the credit amount should be credited to. It can have one of the following values:

outOfBand: The amount should be handled outside the system by the customer.

userBalance: The amount should be added to the user balance at Gigs.
Allowed values: outOfBand userBalance
Name
fees
Type
array
Description
The credited fees.
Name
amount
Type
Price
Description
The amount of the fee.
Example: {"amount":100,"currency":"USD"}
Optional: This property may not always be included.
Name
name
Type
string
Description
The name of the fee.
Optional: This property may not always be included.
Example: "Recovery Fee"
Name
type
Type
string
Description
The type of the fee.
Optional: This property may not always be included.
Allowed values: recoveryFee
Name
fileUrl
Type
nullable string
Status
PREVIEW
Description
A signed URL to download the credit note PDF file. The URL is valid for 1 minute.

This field is null for projects without billing enabled, and for credit notes covering US-taxed plans.
Example: "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123"
Name
invoice
Type
string
Description
The unique identifier for the invoice that the credit note applies to.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
lineItems
Type
array
Description
The line items for the credit note.
Name
status
Type
string
Description
The status of the credit note. It can have one of the following values:

issued: The credit note was issued.

voided: The credit note was voided and no longer has any effect.
Allowed values: issued voided
Name
subtotal
Type
Price
Description
The total amount credited before any taxes or fees.
Example: {"amount":999,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
tax
Type
Price
Description
The sum of the amounts in taxes credited for each line item.
Example: {"amount":200,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
total
Type
Price
Description
The total amount credited after taxes and fees.
Example: {"amount":1199,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
voidedAt
Type
nullable string
Description
Time when the credit note was voided.
Example: "2024-06-14T19:38:34Z"

Request

POST

/projects/{project}/creditNotes

curl https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json" \
-d '{
  "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "lineItems": [
    {
      "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "amount": 999,
      "taxes": [
        {
          "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3",
          "amount": 200
        }
      ]
    }
  ],
  "fees": [
    {
      "amount": 999
    }
  ]
}'

Response

{
  "object": "creditNote",
  "id": "crn_0SNlurA049MEWV49X25tqzNV2jji",
  "createdAt": "2024-06-14T19:38:34Z",
  "creditTo": "outOfBand",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123",
  "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "lineItems": [
    {
      "amount": {
        "amount": 999,
        "currency": "USD"
      },
      "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3"
        }
      ],
      "total": {
        "amount": 1199,
        "currency": "USD"
      }
    }
  ],
  "status": "issued",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voidedAt": "2024-06-14T19:38:34Z"
}

GET/projects/{project}/creditNotes/{creditNote}

Retrieve a credit note

Retrieves the details of an existing credit note.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
creditNote
Type
string
required
Description
The unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"

Responses

Returns the credit note.

Name
object
Type
string
Description
Type of object is always creditNote.
Allowed values: creditNote
Name
id
Type
string
Description
Unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"
Name
createdAt
Type
string
Description
Time when the credit note was created.
Example: "2024-06-14T19:38:34Z"
Name
creditTo
Type
string
Description
Specifies where the credit amount should be credited to. It can have one of the following values:

outOfBand: The amount should be handled outside the system by the customer.

userBalance: The amount should be added to the user balance at Gigs.
Allowed values: outOfBand userBalance
Name
fees
Type
array
Description
The credited fees.
Name
amount
Type
Price
Description
The amount of the fee.
Example: {"amount":100,"currency":"USD"}
Optional: This property may not always be included.
Name
name
Type
string
Description
The name of the fee.
Optional: This property may not always be included.
Example: "Recovery Fee"
Name
type
Type
string
Description
The type of the fee.
Optional: This property may not always be included.
Allowed values: recoveryFee
Name
fileUrl
Type
nullable string
Status
PREVIEW
Description
A signed URL to download the credit note PDF file. The URL is valid for 1 minute.

This field is null for projects without billing enabled, and for credit notes covering US-taxed plans.
Example: "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123"
Name
invoice
Type
string
Description
The unique identifier for the invoice that the credit note applies to.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
lineItems
Type
array
Description
The line items for the credit note.
Name
status
Type
string
Description
The status of the credit note. It can have one of the following values:

issued: The credit note was issued.

voided: The credit note was voided and no longer has any effect.
Allowed values: issued voided
Name
subtotal
Type
Price
Description
The total amount credited before any taxes or fees.
Example: {"amount":999,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
tax
Type
Price
Description
The sum of the amounts in taxes credited for each line item.
Example: {"amount":200,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
total
Type
Price
Description
The total amount credited after taxes and fees.
Example: {"amount":1199,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
voidedAt
Type
nullable string
Description
Time when the credit note was voided.
Example: "2024-06-14T19:38:34Z"

Request

GET

/projects/{project}/creditNotes/{creditNote}

curl https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes/{creditNote} \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Response

{
  "object": "creditNote",
  "id": "crn_0SNlurA049MEWV49X25tqzNV2jji",
  "createdAt": "2024-06-14T19:38:34Z",
  "creditTo": "outOfBand",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123",
  "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "lineItems": [
    {
      "amount": {
        "amount": 999,
        "currency": "USD"
      },
      "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3"
        }
      ],
      "total": {
        "amount": 1199,
        "currency": "USD"
      }
    }
  ],
  "status": "issued",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voidedAt": "2024-06-14T19:38:34Z"
}

POST/projects/{project}/creditNotes/{creditNote}/void

Void a credit note

Marks the credit note as void. This reverses the credited amount in the invoice and reported taxes.

Path Parameters

Name
project
Type
string
required
Description
The unique identifier for the project.
Example: "gigs"
Name
creditNote
Type
string
required
Description
The unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"

Responses

Returns the voided credit note.

Name
object
Type
string
Description
Type of object is always creditNote.
Allowed values: creditNote
Name
id
Type
string
Description
Unique identifier for the credit note.
Example: "crn_0SNlurA049MEWV49X25tqzNV2jji"
Name
createdAt
Type
string
Description
Time when the credit note was created.
Example: "2024-06-14T19:38:34Z"
Name
creditTo
Type
string
Description
Specifies where the credit amount should be credited to. It can have one of the following values:

outOfBand: The amount should be handled outside the system by the customer.

userBalance: The amount should be added to the user balance at Gigs.
Allowed values: outOfBand userBalance
Name
fees
Type
array
Description
The credited fees.
Name
amount
Type
Price
Description
The amount of the fee.
Example: {"amount":100,"currency":"USD"}
Optional: This property may not always be included.
Name
name
Type
string
Description
The name of the fee.
Optional: This property may not always be included.
Example: "Recovery Fee"
Name
type
Type
string
Description
The type of the fee.
Optional: This property may not always be included.
Allowed values: recoveryFee
Name
fileUrl
Type
nullable string
Status
PREVIEW
Description
A signed URL to download the credit note PDF file. The URL is valid for 1 minute.

This field is null for projects without billing enabled, and for credit notes covering US-taxed plans.
Example: "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123"
Name
invoice
Type
string
Description
The unique identifier for the invoice that the credit note applies to.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
lineItems
Type
array
Description
The line items for the credit note.
Name
status
Type
string
Description
The status of the credit note. It can have one of the following values:

issued: The credit note was issued.

voided: The credit note was voided and no longer has any effect.
Allowed values: issued voided
Name
subtotal
Type
Price
Description
The total amount credited before any taxes or fees.
Example: {"amount":999,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
tax
Type
Price
Description
The sum of the amounts in taxes credited for each line item.
Example: {"amount":200,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
total
Type
Price
Description
The total amount credited after taxes and fees.
Example: {"amount":1199,"currency":"USD"}
Name
amount
Type
integer
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: "USD"
Name
voidedAt
Type
nullable string
Description
Time when the credit note was voided.
Example: "2024-06-14T19:38:34Z"

Request

POST

/projects/{project}/creditNotes/{creditNote}/void

curl https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes/{creditNote}/void \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${GIGS_TOKEN}" \
-H "Accept: application/json"

Response

{
  "object": "creditNote",
  "id": "crn_0SNlurA049MEWV49X25tqzNV2jji",
  "createdAt": "2024-06-14T19:38:34Z",
  "creditTo": "outOfBand",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123",
  "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "lineItems": [
    {
      "amount": {
        "amount": 999,
        "currency": "USD"
      },
      "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3"
        }
      ],
      "total": {
        "amount": 1199,
        "currency": "USD"
      }
    }
  ],
  "status": "issued",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voidedAt": "2024-06-14T19:38:34Z"
}