Invoices

The Invoice resource

Properties

Name
object
Type
string
Description
Type of object is always invoice.
Name
id
Type
string
Description
Unique identifier for the invoice.
Example: inv_0SNlurA049MEWV1QTRqvd18YuG25
Name
discount
Type
object
Description
The total discount applied.
Name
amount
Type
integer
required
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
required
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: USD
Name
fees
Type
array
Description
The fees for the invoice.
Name
lineItems
Type
array
Description
The line items that make up the invoice.
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 object
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
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: 2021-01-21T19:32:13Z
Name
end
Type
string
required
Description
End of the period.
Example: 2021-02-20T19:38:34Z
Name
reason
Type
string
Description
The reason for the invoice. It can have one of the following values:

subscriptionCreation: The invoice is due to a new subscription.

subscriptionRenewal: The invoice is due to a subscription renewal.

other: The invoice is not related to a subscription but due an e.g. one-time addon order.
Allowed values: other, subscriptionCreation, subscriptionRenewal
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
object
Description
The total amount before any discounts, taxes or fees are applied.
Name
amount
Type
integer
required
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
required
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: USD
Name
tax
Type
object
Description
The total amount of taxes. This is the sum of the taxes of each line item.
Name
amount
Type
integer
required
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
required
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: USD
Name
total
Type
object
Description
The total amount after all discounts, taxes and fees are applied.
Name
amount
Type
integer
required
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
required
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: USD
Name
createdAt
Type
string
Description
Time when the invoice was created.
Example: 2024-01-09T15:00:51Z
Name
finalizedAt
Type
nullable string
Description
Time when the invoice was finalized and could no longer be changed.
Example: 2024-02-01T11:12:13Z

Response

{
  "object": "invoice",
  "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "discount": {
    "amount": 999,
    "currency": "USD"
  },
  "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": 999,
    "currency": "USD"
  },
  "total": {
    "amount": 999,
    "currency": "USD"
  },
  "createdAt": "2024-01-09T15:00:51Z",
  "finalizedAt": "2024-02-01T11:12:13Z"
}

GET/projects/{project}/invoices/{id}

Retrieve a invoice

Retrieves the details of an existing invoice.

Preview

This endpoint is currently in preview and might change in the future.

We’re excited to hear your feedback and ideas. Please send an email to support@gigs.com to share your thoughts.

Path Parameters

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

Response Schemas

Name
object
Type
string
required
Description
Type of object is always invoice.
Name
id
Type
string
required
Description
Unique identifier for the invoice.
Example: inv_0SNlurA049MEWV1QTRqvd18YuG25
Name
discount
Type
object
required
Description
The total discount applied.
Name
amount
Type
integer
required
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
required
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: USD
Name
fees
Type
array
required
Description
The fees for the invoice.
Name
lineItems
Type
array
required
Description
The line items that make up the invoice.
Name
payment
Type
nullable string
required
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 object
required
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
required
Description
Sequence number of the period.
Example: 1
>= 1
Name
start
Type
string
required
Description
Beginning of the period.
Example: 2021-01-21T19:32:13Z
Name
end
Type
string
required
Description
End of the period.
Example: 2021-02-20T19:38:34Z
Name
reason
Type
string
required
Description
The reason for the invoice. It can have one of the following values:

subscriptionCreation: The invoice is due to a new subscription.

subscriptionRenewal: The invoice is due to a subscription renewal.

other: The invoice is not related to a subscription but due an e.g. one-time addon order.
Allowed values: other, subscriptionCreation, subscriptionRenewal
Name
status
Type
string
required
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
required
Description
The unique identifier for the subscription that this invoice relates to.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
subtotal
Type
object
required
Description
The total amount before any discounts, taxes or fees are applied.
Name
amount
Type
integer
required
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
required
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: USD
Name
tax
Type
object
required
Description
The total amount of taxes. This is the sum of the taxes of each line item.
Name
amount
Type
integer
required
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
required
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: USD
Name
total
Type
object
required
Description
The total amount after all discounts, taxes and fees are applied.
Name
amount
Type
integer
required
Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example: 999
>= 0
Name
currency
Type
string
required
Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example: USD
Name
createdAt
Type
string
required
Description
Time when the invoice was created.
Example: 2024-01-09T15:00:51Z
Name
finalizedAt
Type
nullable string
required
Description
Time when the invoice was finalized and could no longer be changed.
Example: 2024-02-01T11:12:13Z

Request

GET

/projects/{project}/invoices/{id}

curl https://api.gigs.com/projects/{project}/invoices/{id} \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "invoice",
  "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
  "discount": {
    "amount": 100,
    "currency": "USD"
  },
  "fees": [
    {
      "amount": {
        "amount": 100,
        "currency": "USD"
      },
      "name": "Recovery Fee",
      "type": "recoveryFee"
    }
  ],
  "lineItems": [
    {
      "object": "invoiceLineItem",
      "id": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
      "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
      "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
      "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
      "subtotal": {
        "amount": 999,
        "currency": "USD"
      },
      "tax": {
        "amount": 200,
        "currency": "USD"
      },
      "taxes": [
        {
          "object": "invoiceTax",
          "id": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3",
          "amount": {
            "amount": 990,
            "currency": "USD"
          },
          "inclusive": false,
          "jurisdiction": "Federal",
          "name": "Federal TRS Fund"
        }
      ],
      "total": {
        "amount": 1099,
        "currency": "USD"
      }
    }
  ],
  "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"
  },
  "total": {
    "amount": 1199,
    "currency": "USD"
  },
  "createdAt": "2024-01-09T15:00:51Z",
  "finalizedAt": "2024-02-01T11:12:13Z"
}

GET/projects/{project}/invoices

List all invoices

Returns a list of invoices.

Preview

This endpoint is currently in preview and might change in the future.

We’re excited to hear your feedback and ideas. Please send an email to support@gigs.com to share your thoughts.

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.
Default: 10
>= 0
<= 200
Name
user
Type
string
Description
The unique identifier for the user to be filtered by.
Example: usr_0SNlurA049MEWV4OpCwsNyC9Kn2d
Name
subscription
Type
string
Description
The unique identifier for the subscription to be filtered by.
Example: sub_0SNlurA049MEWV2gSfSxi00xlPIi
Name
status
Type
array
Description
A comma-separated list of statuses to filter the invoices by.
Name
reason
Type
array
Description
A comma-separated list of reasons to filter the invoices by.

Response Schemas

Name
object
Type
string
required
Description
Type of object is always list.
Name
items
Type
array
required
Description
List of objects of type invoice.
Name
moreItemsAfter
Type
nullable string
required
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
required
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/{project}/invoices \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"

Response

{
  "object": "list",
  "items": [
    {
      "object": "invoice",
      "id": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
      "discount": {
        "amount": 100,
        "currency": "USD"
      },
      "fees": [
        {
          "amount": {
            "amount": 100,
            "currency": "USD"
          },
          "name": "Recovery Fee",
          "type": "recoveryFee"
        }
      ],
      "lineItems": [
        {
          "object": "invoiceLineItem",
          "id": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
          "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc",
          "discount": {
            "amount": 100,
            "currency": "USD"
          },
          "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo",
          "subscription": "sub_0SNlurA049MEWV2gSfSxi00xlPIi",
          "subscriptionAddon": "sad_0SNlurA049MEWV2UNWPbDfW5B40U",
          "subtotal": {
            "amount": 999,
            "currency": "USD"
          },
          "tax": {
            "amount": 200,
            "currency": "USD"
          },
          "taxes": [
            {
              "object": "invoiceTax",
              "id": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3",
              "amount": {
                "amount": 990,
                "currency": "USD"
              },
              "inclusive": false,
              "jurisdiction": "Federal",
              "name": "Federal TRS Fund"
            }
          ],
          "total": {
            "amount": 1099,
            "currency": "USD"
          }
        }
      ],
      "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"
      },
      "total": {
        "amount": 1199,
        "currency": "USD"
      },
      "createdAt": "2024-01-09T15:00:51Z",
      "finalizedAt": "2024-02-01T11:12:13Z"
    }
  ],
  "moreItemsAfter": null,
  "moreItemsBefore": null
}