Invoices

Invoices describe the amount due to a user for a given subscription period, including any relevant taxes and fees.

Properties

Name
object
Type
string
Description
Type of object is always invoice.
Allowed values: invoice
Name
id
Type
string
Description
Unique identifier for the invoice.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
address
Type
nullable string
Description
The unique identifier for the address this invoice relates to.
Example: "adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
Name
appliedBalance
Type
nullable Price
Description
The amount of user balance applied to pay this invoice.
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.
Optional: This property may not always be included.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Optional: This property may not always be included.
Example: "USD"
Name
createdAt
Type
string
Description
Time when the invoice was created.
Example: "2024-01-09T15:00:51Z"
Name
discount
Type
Price
Description
The total discount applied. This is the sum of the discounts of each line item.
Example: {"amount":100,"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
dueAt
Type
nullable string
Description
Time when the invoice is due to be paid. After this time and the invoiceGracePeriodDays, which can be configured on project or subscription level, the invoice becomes overdue.

This field will have a value for invoices in the finalized state that have a reason of subscriptionRenewal. For all other invoices, this field will be null.
Example: "2024-02-01T11:12:13Z"
Name
fees
Type
array
Description
The fees for the invoice.
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 invoice PDF file. The URL is valid for 1 minute.

This field is null for projects without billing enabled, and for invoices covering US-taxed plans.
Example: "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123"
Name
finalizedAt
Type
nullable string
Description
Time when the invoice was finalized and could no longer be changed.
Example: "2024-02-01T11:12:13Z"
Name
lineItems
Type
array
Description
The line items that make up the invoice.
Name
overdueAt
Type
nullable string
Description
Time when the invoice is considered overdue. Once this happens, invoiceOverdueAction, which can be configured on project or subscription level, is applied.

This field will have a value for invoices in the finalized state that have a reason of subscriptionRenewal. For all other invoices, this field will be null.
Example: "2024-02-01T11:13:13Z"
Name
paidAt
Type
nullable string
Description
Time when the invoice was paid.
Example: "2024-02-01T11:13:13Z"
Name
payment
Type
nullable string
Description
The unique identifier for the payment associated with the invoice, if any. Only present if the invoice has been paid using Gigs Payments.
Example: "pay_0SNlurA049MEWV2HRA0slWFuS8DV"
Name
period
Type
nullable Period
Description
The subscription period that this invoice relates to. It might not be present for new subscriptions if the period has not been defined yet.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
Example: "2021-02-20T19:38:34Z"
Name
reason
Type
string
Description
The reason this invoice was created. It can have one of the following values:

subscriptionCreation: The invoice is due to a new subscription.

subscriptionRenewal: The invoice is due to a recurring subscription renewal.

subscriptionChange: The invoice is due to a subscription change (e.g. plan upgrade).

subscriptionRestore: The invoice is due to a subscription restore.

other: The invoice is not related to a subscription but due an e.g. one-time addon.
Allowed values: other subscriptionChange subscriptionCreation subscriptionRenewal subscriptionRestore
Name
status
Type
string
Description
The status of the invoice. It can have one of the following values:

draft: The invoice is still being edited.

finalized: The invoice can no longer be changed and is awaiting payment.

paid: The invoice was paid. This causes the associated resources to activated.

voided: The invoice was voided and no longer has any effect.
Example: "draft"
Allowed values: draft finalized paid voided
Name
subscription
Type
string
Description
The unique identifier for the subscription that this invoice relates to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
subtotal
Type
Price
Description
The total amount before any discounts, taxes or fees are applied.
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 total amount of taxes. This is the sum of the taxes of 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
taxExemptionReason
Type
nullable string
Description
The reason for the invoice having no taxes calculated, if any. It can have one of the following values:

calculationFailed: The tax calculation failed for an unspecified reason.

fullyDiscounted: The invoice is fully discounted due to a voucher or a free product.

inclusiveTaxExceedsPrice: The calculated tax is too large to be included in the price.

userExempted: The user is marked as exempted from taxes.
Example: "calculationFailed"
Allowed values: calculationFailed fullyDiscounted inclusiveTaxExceedsPrice userExempted
Name
total
Type
Price
Description
The total amount after all discounts, taxes and fees are applied.
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
voucher
Type
nullable string
Description
The unique identifier for the voucher applied to the invoice, if any.
Example: "vou_0SNlurA049MEWV0h2jfjkdiOdplN"

Example

{
  "object": "invoice",
  "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
  "appliedBalance": {
    "amount": 1199,
    "currency": "USD"
  },
  "createdAt": "2024-01-09T15:01:51.0Z",
  "discount": {
    "amount": 100,
    "currency": "USD"
  },
  "dueAt": "2024-02-01T11:12:13Z",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "fileUrl": "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123",
  "finalizedAt": "2024-02-01T11:12:13Z",
  "lineItems": [
    {
      "object": "invoiceLineItem",
      "id": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
      "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
      "subscriptionChange": "sch_0SNlurA049MEWV3bE0SMtbIEJApp",
      "subtotal": {
        "amount": 999,
        "currency": "USD"
      },
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "object": "invoiceTax",
          "id": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3",
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "inclusive": false,
          "jurisdiction": "Federal",
          "name": "Federal TRS Fund"
        }
      ],
      "total": {
        "amount": 1099,
        "currency": "USD"
      }
    }
  ],
  "overdueAt": "2024-02-01T11:13:13Z",
  "paidAt": "2024-02-01T11:13:13Z",
  "payment": "pay_0SNlurA049MEWV2HRA0slWFuS8DV",
  "period": {
    "number": 1,
    "start": "2021-01-21T19:32:13.0Z",
    "end": "2021-02-20T19:38:34.0Z"
  },
  "reason": "other",
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "taxExemptionReason": "calculationFailed",
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
}

GET/projects/{project}/invoices

List all invoices

Returns a list of invoices.

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
user
Type
string
Description
The unique identifier of the user to filter by.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
Name
subscription
Type
string
Description
The unique identifier of the subscription to filter by.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
subscriptionAddon
Type
string
Description
The unique identifier of the subscription addon to filter by.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
subscriptionChange
Type
string
Description
The unique identifier of the subscription change to filter by.
Example: "sch_0SNlurA049MEWV3bE0SMtbIEJApp"
Name
status
Type
array
Description
A comma-separated list of statuses to filter by.
Name
reason
Type
array
Description
A comma-separated list of reasons to filter by.

Responses

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

Name
object
Type
string
Description
Type of object is always list.
Allowed values: list
Name
items
Type
array
Description
List of objects of type invoice.
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}/invoices

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

Responses

{
  "object": "list",
  "items": [
    {
      "object": "invoice",
      "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
      "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
      "appliedBalance": {
        "amount": 1199,
        "currency": "USD"
      },
      "createdAt": "2024-01-09T15:00:51Z",
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "dueAt": "2024-02-01T11:12:13Z",
      "fees": [
        {
          "amount": {
            "amount": 100,
            "currency": "USD"
          },
          "name": "Recovery Fee",
          "type": "recoveryFee"
        }
      ],
      "fileUrl": "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123",
      "finalizedAt": "2024-02-01T11:12:13Z",
      "lineItems": [
        {
          "object": "invoiceLineItem",
          "id": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
          "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
          "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
          "discount": {
            "amount": 100,
            "currency": "USD"
          },
          "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
          "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
          "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
          "subscriptionChange": "sch_0SNlurA049MEWV3bE0SMtbIEJApp",
          "subtotal": {
            "amount": 999,
            "currency": "USD"
          },
          "tax": {
            "amount": 200,
            "currency": "USD"
          },
          "taxes": [
            {
              "object": "invoiceTax",
              "id": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3",
              "amount": {
                "amount": 200,
                "currency": "USD"
              },
              "inclusive": false,
              "jurisdiction": "Federal",
              "name": "Federal TRS Fund"
            }
          ],
          "total": {
            "amount": 1099,
            "currency": "USD"
          }
        }
      ],
      "overdueAt": "2024-02-01T11:13:13Z",
      "paidAt": "2024-02-01T11:13:13Z",
      "payment": "pay_0SNlurA049MEWV2HRA0slWFuS8DV",
      "period": {
        "number": 1,
        "start": "2021-01-21T19:32:13Z",
        "end": "2021-02-20T19:38:34Z"
      },
      "reason": "other",
      "status": "draft",
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "subtotal": {
        "amount": 999,
        "currency": "USD"
      },
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxExemptionReason": "calculationFailed",
      "total": {
        "amount": 1199,
        "currency": "USD"
      },
      "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}

GET/projects/{project}/invoices/{invoice}

Retrieve an invoice

Retrieves the details of an existing invoice.

Path Parameters

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

Responses

Returns the invoice.

Name
object
Type
string
Description
Type of object is always invoice.
Allowed values: invoice
Name
id
Type
string
Description
Unique identifier for the invoice.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
address
Type
nullable string
Description
The unique identifier for the address this invoice relates to.
Example: "adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
Name
appliedBalance
Type
nullable Price
Description
The amount of user balance applied to pay this invoice.
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.
Optional: This property may not always be included.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Optional: This property may not always be included.
Example: "USD"
Name
createdAt
Type
string
Description
Time when the invoice was created.
Example: "2024-01-09T15:00:51Z"
Name
discount
Type
Price
Description
The total discount applied. This is the sum of the discounts of each line item.
Example: {"amount":100,"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
dueAt
Type
nullable string
Description
Time when the invoice is due to be paid. After this time and the invoiceGracePeriodDays, which can be configured on project or subscription level, the invoice becomes overdue.

This field will have a value for invoices in the finalized state that have a reason of subscriptionRenewal. For all other invoices, this field will be null.
Example: "2024-02-01T11:12:13Z"
Name
fees
Type
array
Description
The fees for the invoice.
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 invoice PDF file. The URL is valid for 1 minute.

This field is null for projects without billing enabled, and for invoices covering US-taxed plans.
Example: "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123"
Name
finalizedAt
Type
nullable string
Description
Time when the invoice was finalized and could no longer be changed.
Example: "2024-02-01T11:12:13Z"
Name
lineItems
Type
array
Description
The line items that make up the invoice.
Name
overdueAt
Type
nullable string
Description
Time when the invoice is considered overdue. Once this happens, invoiceOverdueAction, which can be configured on project or subscription level, is applied.

This field will have a value for invoices in the finalized state that have a reason of subscriptionRenewal. For all other invoices, this field will be null.
Example: "2024-02-01T11:13:13Z"
Name
paidAt
Type
nullable string
Description
Time when the invoice was paid.
Example: "2024-02-01T11:13:13Z"
Name
payment
Type
nullable string
Description
The unique identifier for the payment associated with the invoice, if any. Only present if the invoice has been paid using Gigs Payments.
Example: "pay_0SNlurA049MEWV2HRA0slWFuS8DV"
Name
period
Type
nullable Period
Description
The subscription period that this invoice relates to. It might not be present for new subscriptions if the period has not been defined yet.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
Example: "2021-02-20T19:38:34Z"
Name
reason
Type
string
Description
The reason this invoice was created. It can have one of the following values:

subscriptionCreation: The invoice is due to a new subscription.

subscriptionRenewal: The invoice is due to a recurring subscription renewal.

subscriptionChange: The invoice is due to a subscription change (e.g. plan upgrade).

subscriptionRestore: The invoice is due to a subscription restore.

other: The invoice is not related to a subscription but due an e.g. one-time addon.
Allowed values: other subscriptionChange subscriptionCreation subscriptionRenewal subscriptionRestore
Name
status
Type
string
Description
The status of the invoice. It can have one of the following values:

draft: The invoice is still being edited.

finalized: The invoice can no longer be changed and is awaiting payment.

paid: The invoice was paid. This causes the associated resources to activated.

voided: The invoice was voided and no longer has any effect.
Example: "draft"
Allowed values: draft finalized paid voided
Name
subscription
Type
string
Description
The unique identifier for the subscription that this invoice relates to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
subtotal
Type
Price
Description
The total amount before any discounts, taxes or fees are applied.
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 total amount of taxes. This is the sum of the taxes of 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
taxExemptionReason
Type
nullable string
Description
The reason for the invoice having no taxes calculated, if any. It can have one of the following values:

calculationFailed: The tax calculation failed for an unspecified reason.

fullyDiscounted: The invoice is fully discounted due to a voucher or a free product.

inclusiveTaxExceedsPrice: The calculated tax is too large to be included in the price.

userExempted: The user is marked as exempted from taxes.
Example: "calculationFailed"
Allowed values: calculationFailed fullyDiscounted inclusiveTaxExceedsPrice userExempted
Name
total
Type
Price
Description
The total amount after all discounts, taxes and fees are applied.
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
voucher
Type
nullable string
Description
The unique identifier for the voucher applied to the invoice, if any.
Example: "vou_0SNlurA049MEWV0h2jfjkdiOdplN"

Request

GET

/projects/{project}/invoices/{invoice}

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

Responses

{
  "object": "invoice",
  "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
  "appliedBalance": {
    "amount": 1199,
    "currency": "USD"
  },
  "createdAt": "2024-01-09T15:00:51Z",
  "discount": {
    "amount": 100,
    "currency": "USD"
  },
  "dueAt": "2024-02-01T11:12:13Z",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "fileUrl": "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123",
  "finalizedAt": "2024-02-01T11:12:13Z",
  "lineItems": [
    {
      "object": "invoiceLineItem",
      "id": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
      "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
      "subscriptionChange": "sch_0SNlurA049MEWV3bE0SMtbIEJApp",
      "subtotal": {
        "amount": 999,
        "currency": "USD"
      },
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "object": "invoiceTax",
          "id": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3",
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "inclusive": false,
          "jurisdiction": "Federal",
          "name": "Federal TRS Fund"
        }
      ],
      "total": {
        "amount": 1099,
        "currency": "USD"
      }
    }
  ],
  "overdueAt": "2024-02-01T11:13:13Z",
  "paidAt": "2024-02-01T11:13:13Z",
  "payment": "pay_0SNlurA049MEWV2HRA0slWFuS8DV",
  "period": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "reason": "other",
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "taxExemptionReason": "calculationFailed",
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
}

POST/projects/{project}/invoices/{invoice}/pay

Pay an invoice

Marks the invoice as paid. This activates or allows to renew the products associated with the invoice.

Path Parameters

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

Responses

Returns the invoice.

Name
object
Type
string
Description
Type of object is always invoice.
Allowed values: invoice
Name
id
Type
string
Description
Unique identifier for the invoice.
Example: "inv_0SNlurA049MEWV1QTRqvd18YuG25"
Name
address
Type
nullable string
Description
The unique identifier for the address this invoice relates to.
Example: "adr_0SNlurA049MEWV5ELDmnaqVXgTFT"
Name
appliedBalance
Type
nullable Price
Description
The amount of user balance applied to pay this invoice.
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.
Optional: This property may not always be included.
Example: 999
>= 0
Name
currency
Type
string
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Optional: This property may not always be included.
Example: "USD"
Name
createdAt
Type
string
Description
Time when the invoice was created.
Example: "2024-01-09T15:00:51Z"
Name
discount
Type
Price
Description
The total discount applied. This is the sum of the discounts of each line item.
Example: {"amount":100,"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
dueAt
Type
nullable string
Description
Time when the invoice is due to be paid. After this time and the invoiceGracePeriodDays, which can be configured on project or subscription level, the invoice becomes overdue.

This field will have a value for invoices in the finalized state that have a reason of subscriptionRenewal. For all other invoices, this field will be null.
Example: "2024-02-01T11:12:13Z"
Name
fees
Type
array
Description
The fees for the invoice.
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 invoice PDF file. The URL is valid for 1 minute.

This field is null for projects without billing enabled, and for invoices covering US-taxed plans.
Example: "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123"
Name
finalizedAt
Type
nullable string
Description
Time when the invoice was finalized and could no longer be changed.
Example: "2024-02-01T11:12:13Z"
Name
lineItems
Type
array
Description
The line items that make up the invoice.
Name
overdueAt
Type
nullable string
Description
Time when the invoice is considered overdue. Once this happens, invoiceOverdueAction, which can be configured on project or subscription level, is applied.

This field will have a value for invoices in the finalized state that have a reason of subscriptionRenewal. For all other invoices, this field will be null.
Example: "2024-02-01T11:13:13Z"
Name
paidAt
Type
nullable string
Description
Time when the invoice was paid.
Example: "2024-02-01T11:13:13Z"
Name
payment
Type
nullable string
Description
The unique identifier for the payment associated with the invoice, if any. Only present if the invoice has been paid using Gigs Payments.
Example: "pay_0SNlurA049MEWV2HRA0slWFuS8DV"
Name
period
Type
nullable Period
Description
The subscription period that this invoice relates to. It might not be present for new subscriptions if the period has not been defined yet.
Name
number
Type
integer
Description
Sequence number of the period.
Optional: This property may not always be included.
Example: 1
>= 1
Name
start
Type
string
Description
Beginning of the period.
Optional: This property may not always be included.
Example: "2021-01-21T19:32:13Z"
Name
end
Type
string
Description
End of the period.
Optional: This property may not always be included.
Example: "2021-02-20T19:38:34Z"
Name
reason
Type
string
Description
The reason this invoice was created. It can have one of the following values:

subscriptionCreation: The invoice is due to a new subscription.

subscriptionRenewal: The invoice is due to a recurring subscription renewal.

subscriptionChange: The invoice is due to a subscription change (e.g. plan upgrade).

subscriptionRestore: The invoice is due to a subscription restore.

other: The invoice is not related to a subscription but due an e.g. one-time addon.
Allowed values: other subscriptionChange subscriptionCreation subscriptionRenewal subscriptionRestore
Name
status
Type
string
Description
The status of the invoice. It can have one of the following values:

draft: The invoice is still being edited.

finalized: The invoice can no longer be changed and is awaiting payment.

paid: The invoice was paid. This causes the associated resources to activated.

voided: The invoice was voided and no longer has any effect.
Example: "draft"
Allowed values: draft finalized paid voided
Name
subscription
Type
string
Description
The unique identifier for the subscription that this invoice relates to.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
subtotal
Type
Price
Description
The total amount before any discounts, taxes or fees are applied.
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 total amount of taxes. This is the sum of the taxes of 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
taxExemptionReason
Type
nullable string
Description
The reason for the invoice having no taxes calculated, if any. It can have one of the following values:

calculationFailed: The tax calculation failed for an unspecified reason.

fullyDiscounted: The invoice is fully discounted due to a voucher or a free product.

inclusiveTaxExceedsPrice: The calculated tax is too large to be included in the price.

userExempted: The user is marked as exempted from taxes.
Example: "calculationFailed"
Allowed values: calculationFailed fullyDiscounted inclusiveTaxExceedsPrice userExempted
Name
total
Type
Price
Description
The total amount after all discounts, taxes and fees are applied.
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
voucher
Type
nullable string
Description
The unique identifier for the voucher applied to the invoice, if any.
Example: "vou_0SNlurA049MEWV0h2jfjkdiOdplN"

Request

POST

/projects/{project}/invoices/{invoice}/pay

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

Responses

{
  "object": "invoice",
  "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT",
  "appliedBalance": {
    "amount": 1199,
    "currency": "USD"
  },
  "createdAt": "2024-01-09T15:00:51Z",
  "discount": {
    "amount": 100,
    "currency": "USD"
  },
  "dueAt": "2024-02-01T11:12:13Z",
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "fileUrl": "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123",
  "finalizedAt": "2024-02-01T11:12:13Z",
  "lineItems": [
    {
      "object": "invoiceLineItem",
      "id": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
      "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
      "subscriptionChange": "sch_0SNlurA049MEWV3bE0SMtbIEJApp",
      "subtotal": {
        "amount": 999,
        "currency": "USD"
      },
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "object": "invoiceTax",
          "id": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3",
          "amount": {
            "amount": 200,
            "currency": "USD"
          },
          "inclusive": false,
          "jurisdiction": "Federal",
          "name": "Federal TRS Fund"
        }
      ],
      "total": {
        "amount": 1099,
        "currency": "USD"
      }
    }
  ],
  "overdueAt": "2024-02-01T11:13:13Z",
  "paidAt": "2024-02-01T11:13:13Z",
  "payment": "pay_0SNlurA049MEWV2HRA0slWFuS8DV",
  "period": {
    "number": 1,
    "start": "2021-01-21T19:32:13Z",
    "end": "2021-02-20T19:38:34Z"
  },
  "reason": "other",
  "status": "draft",
  "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
  "subtotal": {
    "amount": 999,
    "currency": "USD"
  },
  "tax": {
    "amount": 200,
    "currency": "USD"
  },
  "taxExemptionReason": "calculationFailed",
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN"
}

{ "object": "invoice", "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25", "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "appliedBalance": { "amount": 1199, "currency": "USD" }, "createdAt": "2024-01-09T15:01:51.0Z", "discount": { "amount": 100, "currency": "USD" }, "dueAt": "2024-02-01T11:12:13Z", "fees": [ { "amount": { "amount": 100, "currency": "USD" }, "name": "Recovery Fee", "type": "recoveryFee" } ], "fileUrl": "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123", "finalizedAt": "2024-02-01T11:12:13Z", "lineItems": [ { "object": "invoiceLineItem", "id": "lin_0SNlurA049MEWV11QUKZGDMxJmKe", "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "discount": { "amount": 100, "currency": "USD" }, "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "subscriptionChange": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxes": [ { "object": "invoiceTax", "id": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3", "amount": { "amount": 200, "currency": "USD" }, "inclusive": false, "jurisdiction": "Federal", "name": "Federal TRS Fund" } ], "total": { "amount": 1099, "currency": "USD" } } ], "overdueAt": "2024-02-01T11:13:13Z", "paidAt": "2024-02-01T11:13:13Z", "payment": "pay_0SNlurA049MEWV2HRA0slWFuS8DV", "period": { "number": 1, "start": "2021-01-21T19:32:13.0Z", "end": "2021-02-20T19:38:34.0Z" }, "reason": "other", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxExemptionReason": "calculationFailed", "total": { "amount": 1199, "currency": "USD" }, "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN" }

List all invoices

Returns a list of invoices.

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
user
Type
string
Description
The unique identifier of the user to filter by.
Example: "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d"
Name
subscription
Type
string
Description
The unique identifier of the subscription to filter by.
Example: "sub_0SNlurA049MEWV2gSfSxi00xlPIi"
Name
subscriptionAddon
Type
string
Description
The unique identifier of the subscription addon to filter by.
Example: "sad_0SNlurA049MEWV2UNWPbDfW5B40U"
Name
subscriptionChange
Type
string
Description
The unique identifier of the subscription change to filter by.
Example: "sch_0SNlurA049MEWV3bE0SMtbIEJApp"
Name
status
Type
array
Description
A comma-separated list of statuses to filter by.
Name
reason
Type
array
Description
A comma-separated list of reasons to filter by.

{ "object": "list", "items": [ { "object": "invoice", "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25", "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "appliedBalance": { "amount": 1199, "currency": "USD" }, "createdAt": "2024-01-09T15:00:51Z", "discount": { "amount": 100, "currency": "USD" }, "dueAt": "2024-02-01T11:12:13Z", "fees": [ { "amount": { "amount": 100, "currency": "USD" }, "name": "Recovery Fee", "type": "recoveryFee" } ], "fileUrl": "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123", "finalizedAt": "2024-02-01T11:12:13Z", "lineItems": [ { "object": "invoiceLineItem", "id": "lin_0SNlurA049MEWV11QUKZGDMxJmKe", "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "discount": { "amount": 100, "currency": "USD" }, "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "subscriptionChange": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxes": [ { "object": "invoiceTax", "id": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3", "amount": { "amount": 200, "currency": "USD" }, "inclusive": false, "jurisdiction": "Federal", "name": "Federal TRS Fund" } ], "total": { "amount": 1099, "currency": "USD" } } ], "overdueAt": "2024-02-01T11:13:13Z", "paidAt": "2024-02-01T11:13:13Z", "payment": "pay_0SNlurA049MEWV2HRA0slWFuS8DV", "period": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "reason": "other", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxExemptionReason": "calculationFailed", "total": { "amount": 1199, "currency": "USD" }, "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN" } ], "moreItemsAfter": null, "moreItemsBefore": null }

{ "object": "invoice", "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25", "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "appliedBalance": { "amount": 1199, "currency": "USD" }, "createdAt": "2024-01-09T15:00:51Z", "discount": { "amount": 100, "currency": "USD" }, "dueAt": "2024-02-01T11:12:13Z", "fees": [ { "amount": { "amount": 100, "currency": "USD" }, "name": "Recovery Fee", "type": "recoveryFee" } ], "fileUrl": "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123", "finalizedAt": "2024-02-01T11:12:13Z", "lineItems": [ { "object": "invoiceLineItem", "id": "lin_0SNlurA049MEWV11QUKZGDMxJmKe", "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "discount": { "amount": 100, "currency": "USD" }, "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "subscriptionChange": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxes": [ { "object": "invoiceTax", "id": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3", "amount": { "amount": 200, "currency": "USD" }, "inclusive": false, "jurisdiction": "Federal", "name": "Federal TRS Fund" } ], "total": { "amount": 1099, "currency": "USD" } } ], "overdueAt": "2024-02-01T11:13:13Z", "paidAt": "2024-02-01T11:13:13Z", "payment": "pay_0SNlurA049MEWV2HRA0slWFuS8DV", "period": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "reason": "other", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxExemptionReason": "calculationFailed", "total": { "amount": 1199, "currency": "USD" }, "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN" }

Pay an invoice

Marks the invoice as paid. This activates or allows to renew the products associated with the invoice.

Path Parameters

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

{ "object": "invoice", "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25", "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "appliedBalance": { "amount": 1199, "currency": "USD" }, "createdAt": "2024-01-09T15:00:51Z", "discount": { "amount": 100, "currency": "USD" }, "dueAt": "2024-02-01T11:12:13Z", "fees": [ { "amount": { "amount": 100, "currency": "USD" }, "name": "Recovery Fee", "type": "recoveryFee" } ], "fileUrl": "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123", "finalizedAt": "2024-02-01T11:12:13Z", "lineItems": [ { "object": "invoiceLineItem", "id": "lin_0SNlurA049MEWV11QUKZGDMxJmKe", "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "discount": { "amount": 100, "currency": "USD" }, "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U", "subscriptionChange": "sch_0SNlurA049MEWV3bE0SMtbIEJApp", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxes": [ { "object": "invoiceTax", "id": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3", "amount": { "amount": 200, "currency": "USD" }, "inclusive": false, "jurisdiction": "Federal", "name": "Federal TRS Fund" } ], "total": { "amount": 1099, "currency": "USD" } } ], "overdueAt": "2024-02-01T11:13:13Z", "paidAt": "2024-02-01T11:13:13Z", "payment": "pay_0SNlurA049MEWV2HRA0slWFuS8DV", "period": { "number": 1, "start": "2021-01-21T19:32:13Z", "end": "2021-02-20T19:38:34Z" }, "reason": "other", "status": "draft", "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxExemptionReason": "calculationFailed", "total": { "amount": 1199, "currency": "USD" }, "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN" }