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
createdAt
- Type
- string
- Description
Time when the invoice was created.
Example:2024-01-09T15:00:51Z
- Name
discount
- Type
- object
- Description
- The total discount applied.
- Name
amount
- Type
- integer
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
- Name
fees
- Type
- array
- Description
- The fees for the invoice.
- Name
amount
- Type
- object
- Description
- The amount of the fee.
- Name
name
- Type
- string
- Description
The name of the fee.
Example:Recovery Fee
- Name
type
- Type
- string
- Description
The type of the fee.
- 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
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 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
- Description
Sequence number of the period.
Example:1
>= 1
required- Name
start
- Type
- string
- Description
Beginning of the period.
Example:2021-01-21T19:32:13Z
required- Name
end
- Type
- string
- Description
End of the period.
Example:2021-02-20T19:38:34Z
required
- 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
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
- 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
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
- 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.userExempted
: The user is marked as exempted from taxes.
Example:calculationFailed
Allowed values:, calculationFailed, userExempted
- Name
total
- Type
- object
- Description
- The total amount after all discounts, taxes and fees are applied.
- Name
amount
- Type
- integer
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
Response
{
"object": "invoice",
"id": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
"createdAt": "2024-01-09T15:00:51Z",
"discount": {
"amount": 999,
"currency": "USD"
},
"finalizedAt": "2024-02-01T11:12: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": 999,
"currency": "USD"
},
"taxExemptionReason": "calculationFailed",
"total": {
"amount": 999,
"currency": "USD"
}
}
Retrieve an invoice
Retrieves the details of an existing invoice.
Path Parameters
- Name
project
- Type
- string
- Description
The unique identifier for the project.
Example:gigs
required- Name
invoice
- Type
- string
- Description
The unique identifier for the invoice.
Example:inv_0SNlurA049MEWV1QTRqvd18YuG25
required
Response Schemas
- Name
object
- Type
- string
- Description
Type of object is always
invoice
.
required- Name
id
- Type
- string
- Description
Unique identifier for the invoice.
Example:inv_0SNlurA049MEWV1QTRqvd18YuG25
required- Name
createdAt
- Type
- string
- Description
Time when the invoice was created.
Example:2024-01-09T15:00:51Z
required- Name
discount
- Type
- object
- Description
- The total discount applied.
- Name
amount
- Type
- integer
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
required- Name
fees
- Type
- array
- Description
- The fees for the invoice.
- Name
amount
- Type
- object
- Description
- The amount of the fee.
- Name
name
- Type
- string
- Description
The name of the fee.
Example:Recovery Fee
- Name
type
- Type
- string
- Description
The type of the fee.
required- Name
finalizedAt
- Type
- nullable string
- Description
Time when the invoice was finalized and could no longer be changed.
Example:2024-02-01T11:12:13Z
required- Name
lineItems
- Type
- array
- Description
- The line items that make up the invoice.
required- Name
paidAt
- Type
- nullable string
- Description
Time when the invoice was paid.
Example:2024-02-01T11:13:13Z
required- 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
required- 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
- Description
Sequence number of the period.
Example:1
>= 1
required- Name
start
- Type
- string
- Description
Beginning of the period.
Example:2021-01-21T19:32:13Z
required- Name
end
- Type
- string
- Description
End of the period.
Example:2021-02-20T19:38:34Z
required
required- 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
required- 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
required- Name
subscription
- Type
- string
- Description
The unique identifier for the subscription that this invoice relates to.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
subtotal
- Type
- object
- Description
- The total amount before any discounts, taxes or fees are applied.
- Name
amount
- Type
- integer
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
required- 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
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
required- 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.userExempted
: The user is marked as exempted from taxes.
Example:calculationFailed
Allowed values:, calculationFailed, userExempted
required- Name
total
- Type
- object
- Description
- The total amount after all discounts, taxes and fees are applied.
- Name
amount
- Type
- integer
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
required
Request
curl https://api.gigs.com/projects/{project}/invoices/{invoice} \
-X GET \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"
Response
{
"object": "invoice",
"id": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
"createdAt": "2024-01-09T15:00:51Z",
"discount": {
"amount": 100,
"currency": "USD"
},
"fees": [
{
"amount": {
"amount": 100,
"currency": "USD"
},
"name": "Recovery Fee",
"type": "recoveryFee"
}
],
"finalizedAt": "2024-02-01T11:12:13Z",
"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"
}
}
],
"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"
}
}
List all invoices
Returns a list of invoices.
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
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
subscriptionAddon
- Type
- string
- Description
The unique identifier for the subscription addon to be filtered by.
Example:sad_0SNlurA049MEWV2UNWPbDfW5B40U
- 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
- Description
Type of object is always
list
.
required- Name
items
- Type
- array
- Description
- List of objects of type `invoice`.
required- 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.
required- 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.
required
Request
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",
"createdAt": "2024-01-09T15:00:51Z",
"discount": {
"amount": 100,
"currency": "USD"
},
"fees": [
{
"amount": {
"amount": 100,
"currency": "USD"
},
"name": "Recovery Fee",
"type": "recoveryFee"
}
],
"finalizedAt": "2024-02-01T11:12:13Z",
"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"
}
}
],
"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"
}
}
],
"moreItemsAfter": null,
"moreItemsBefore": null
}
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
- Description
The unique identifier for the project.
Example:gigs
required- Name
invoice
- Type
- string
- Description
The unique identifier for the invoice.
Example:inv_0SNlurA049MEWV1QTRqvd18YuG25
required
Response Schemas
- Name
object
- Type
- string
- Description
Type of object is always
invoice
.
required- Name
id
- Type
- string
- Description
Unique identifier for the invoice.
Example:inv_0SNlurA049MEWV1QTRqvd18YuG25
required- Name
createdAt
- Type
- string
- Description
Time when the invoice was created.
Example:2024-01-09T15:00:51Z
required- Name
discount
- Type
- object
- Description
- The total discount applied.
- Name
amount
- Type
- integer
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
required- Name
fees
- Type
- array
- Description
- The fees for the invoice.
- Name
amount
- Type
- object
- Description
- The amount of the fee.
- Name
name
- Type
- string
- Description
The name of the fee.
Example:Recovery Fee
- Name
type
- Type
- string
- Description
The type of the fee.
required- Name
finalizedAt
- Type
- nullable string
- Description
Time when the invoice was finalized and could no longer be changed.
Example:2024-02-01T11:12:13Z
required- Name
lineItems
- Type
- array
- Description
- The line items that make up the invoice.
required- Name
paidAt
- Type
- nullable string
- Description
Time when the invoice was paid.
Example:2024-02-01T11:13:13Z
required- 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
required- 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
- Description
Sequence number of the period.
Example:1
>= 1
required- Name
start
- Type
- string
- Description
Beginning of the period.
Example:2021-01-21T19:32:13Z
required- Name
end
- Type
- string
- Description
End of the period.
Example:2021-02-20T19:38:34Z
required
required- 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
required- 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
required- Name
subscription
- Type
- string
- Description
The unique identifier for the subscription that this invoice relates to.
Example:sub_0SNlurA049MEWV2gSfSxi00xlPIi
required- Name
subtotal
- Type
- object
- Description
- The total amount before any discounts, taxes or fees are applied.
- Name
amount
- Type
- integer
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
required- 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
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
required- 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.userExempted
: The user is marked as exempted from taxes.
Example:calculationFailed
Allowed values:, calculationFailed, userExempted
required- Name
total
- Type
- object
- Description
- The total amount after all discounts, taxes and fees are applied.
- Name
amount
- Type
- integer
- Description
The price amount in the currency's minor unit, e.g. "cents" for many currencies.
Example:999
>= 0
required- Name
currency
- Type
- string
- Description
Three-letter ISO 4217 currency code. Must be a supported currency.
Example:USD
required
required
Request
curl https://api.gigs.com/projects/{project}/invoices/{invoice}/pay \
-X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer {token}" \
-H "Accept: application/json"
Response
{
"object": "invoice",
"id": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
"createdAt": "2024-01-09T15:00:51Z",
"discount": {
"amount": 100,
"currency": "USD"
},
"fees": [
{
"amount": {
"amount": 100,
"currency": "USD"
},
"name": "Recovery Fee",
"type": "recoveryFee"
}
],
"finalizedAt": "2024-02-01T11:12:13Z",
"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"
}
}
],
"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"
}
}