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
- fees
- Type
- array
- Description
- The credited fees.
- Name
- amount
- Type
- object
- 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
- 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:issuedvoided
- Name
- subtotal
- Type
- object
- 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
- object
- 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
- object
- 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",
"fees": [
{
"amount": {
"amount": 100,
"currency": "USD"
},
"name": "Recovery Fee",
"type": "recoveryFee"
}
],
"invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
"lineItems": [
{
"amount": {
"amount": 999,
"currency": "USD"
},
"invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
"tax": {
"amount": 200,
"currency": "USD"
},
"taxes": [
{
"amount": {
"amount": 200,
"currency": "USD"
},
"inclusive": false,
"name": "State Sales Tax",
"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"
}
List all credit notes
Returns a list of credit notes.
Path Parameters
- Name
- project
- Type
- string
- Description
The unique identifier for the project.
Example:"gigs"
required
Query Parameters
- Name
- after
- Type
- string
- Description
A cursor for use in pagination. The
afterparameter 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
beforeparameter 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.
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
afterpagination 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
beforepagination parameter if more items are available sorted before the current batch of items.
Request
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"
Response
{
"object": "list",
"items": [
{
"object": "creditNote",
"id": "crn_0SNlurA049MEWV49X25tqzNV2jji",
"createdAt": "2024-06-14T19:38:34Z",
"fees": [
{
"amount": {
"amount": 100,
"currency": "USD"
},
"name": "Recovery Fee",
"type": "recoveryFee"
}
],
"invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
"lineItems": [
{
"amount": {
"amount": 999,
"currency": "USD"
},
"invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
"tax": {
"amount": 200,
"currency": "USD"
},
"taxes": [
{
"amount": {
"amount": 200,
"currency": "USD"
},
"inclusive": false,
"name": "State Sales Tax",
"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
}
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
- Description
The unique identifier for the invoice that the credit note applies to.
Example:"inv_0SNlurA049MEWV1QTRqvd18YuG25"
required- 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
- Description
The unique identifier for the project.
Example:"gigs"
required
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
- fees
- Type
- array
- Description
- The credited fees.
- Name
- amount
- Type
- object
- 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
- 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:issuedvoided
- Name
- subtotal
- Type
- object
- 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
- object
- 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
- object
- 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
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",
"fees": [
{
"amount": {
"amount": 100,
"currency": "USD"
},
"name": "Recovery Fee",
"type": "recoveryFee"
}
],
"invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
"lineItems": [
{
"amount": {
"amount": 999,
"currency": "USD"
},
"invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
"tax": {
"amount": 200,
"currency": "USD"
},
"taxes": [
{
"amount": {
"amount": 200,
"currency": "USD"
},
"inclusive": false,
"name": "State Sales Tax",
"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"
}
Retrieve a credit note
Retrieves the details of an existing credit note.
Path Parameters
- Name
- project
- Type
- string
- Description
The unique identifier for the project.
Example:"gigs"
required- Name
- creditNote
- Type
- string
- Description
The unique identifier for the credit note.
Example:"crn_0SNlurA049MEWV49X25tqzNV2jji"
required
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
- fees
- Type
- array
- Description
- The credited fees.
- Name
- amount
- Type
- object
- 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
- 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:issuedvoided
- Name
- subtotal
- Type
- object
- 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
- object
- 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
- object
- 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
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",
"fees": [
{
"amount": {
"amount": 100,
"currency": "USD"
},
"name": "Recovery Fee",
"type": "recoveryFee"
}
],
"invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
"lineItems": [
{
"amount": {
"amount": 999,
"currency": "USD"
},
"invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
"tax": {
"amount": 200,
"currency": "USD"
},
"taxes": [
{
"amount": {
"amount": 200,
"currency": "USD"
},
"inclusive": false,
"name": "State Sales Tax",
"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"
}
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
- Description
The unique identifier for the project.
Example:"gigs"
required- Name
- creditNote
- Type
- string
- Description
The unique identifier for the credit note.
Example:"crn_0SNlurA049MEWV49X25tqzNV2jji"
required
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
- fees
- Type
- array
- Description
- The credited fees.
- Name
- amount
- Type
- object
- 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
- 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:issuedvoided
- Name
- subtotal
- Type
- object
- 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
- object
- 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
- object
- 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
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",
"fees": [
{
"amount": {
"amount": 100,
"currency": "USD"
},
"name": "Recovery Fee",
"type": "recoveryFee"
}
],
"invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
"lineItems": [
{
"amount": {
"amount": 999,
"currency": "USD"
},
"invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
"tax": {
"amount": 200,
"currency": "USD"
},
"taxes": [
{
"amount": {
"amount": 200,
"currency": "USD"
},
"inclusive": false,
"name": "State Sales Tax",
"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"
}