{ "openapi": "3.1.0", "info": { "title": "Gigs Billing API", "description": "Manage invoices and credit notes within Gigs.", "contact": { "name": "Gigs Support", "email": "support@gigs.com" }, "version": "2026-01-29.319" }, "servers": [ { "url": "https://api.gigs.com", "description": "production" } ], "paths": { "/projects/{project}/creditNotes": { "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/project" } ], "get": { "tags": [ "Credit Notes" ], "operationId": "CreditNotesList", "summary": "List all credit notes", "description": "Returns a list of credit notes.", "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/listAfter" }, { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/listBefore" }, { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/listLimit" }, { "name": "invoice", "in": "query", "description": "The unique identifier for the invoice to be filtered by.", "schema": { "type": "string", "examples": [ "inv_0SNlurA049MEWV1QTRqvd18YuG25" ] } }, { "name": "status", "in": "query", "description": "A comma-separated list of statuses to filter the credit notes by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "issued", "voided" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of credit notes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `creditNote`.", "items": { "$ref": "#/components/schemas/creditNote" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "creditNote", "id": "crn_0SNlurA049MEWV49X25tqzNV2jji", "metadata": {}, "createdAt": "2024-06-14T19:38:34Z", "creditTo": "outOfBand", "fees": [ { "amount": { "amount": 100, "currency": "USD" }, "name": "Recovery Fee", "type": "recoveryFee" } ], "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123", "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25", "lineItems": [ { "amount": { "amount": 999, "currency": "USD" }, "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe", "tax": { "amount": 200, "currency": "USD" }, "taxes": [ { "amount": { "amount": 200, "currency": "USD" }, "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3" } ], "total": { "amount": 1199, "currency": "USD" } } ], "number": "3l4rLP-DE-CN-2026-06-10001", "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 } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "creditNote", "id": "crn_0SNlurA049MEWV49X25tqzNV2jji", "metadata": {}, "createdAt": "2024-06-14T19:38:34Z", "creditTo": "outOfBand", "fees": [ { "amount": { "amount": 100, "currency": "USD" }, "name": "Recovery Fee", "type": "recoveryFee" } ], "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123", "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25", "lineItems": [ { "amount": { "amount": 999, "currency": "USD" }, "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe", "tax": { "amount": 200, "currency": "USD" }, "taxes": [ { "amount": { "amount": 200, "currency": "USD" }, "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3" } ], "total": { "amount": 1199, "currency": "USD" } } ], "number": "3l4rLP-DE-CN-2026-06-10001", "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 } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "404": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/notFound" }, "422": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/unprocessableEntity" } } }, "post": { "tags": [ "Credit Notes" ], "operationId": "CreditNotesCreate", "summary": "Create a credit note", "description": "Creates a new credit note for an invoice.\n\nWhen only `invoice` is provided, the full amount of the invoice will be credited, including all taxes and fees.\nIf the invoice has already been partially credited, the remaining amount will be credited.\n\nWhen selected `lineItems`, `taxes` or `fees` are provided, only those will be credited. \n\nNon-refundable taxes will still have to be filed with the tax authorities.\n", "requestBody": { "description": "Properties of the new credit note.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "string", "description": "The unique identifier for the invoice that the credit note applies to.", "examples": [ "inv_0SNlurA049MEWV1QTRqvd18YuG25" ] }, "metadata": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/metadataUpdate" }, "lineItems": { "type": [ "array", "null" ], "description": "The line items for the credit note.", "items": { "type": "object", "properties": { "invoiceLineItem": { "type": "string", "description": "The unique identifier for the invoice line item that this line item applies to.", "examples": [ "lin_0SNlurA049MEWV11QUKZGDMxJmKe" ] }, "amount": { "type": [ "integer", "null" ], "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.", "minimum": 0, "examples": [ 999 ] }, "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.", "items": { "type": "object", "properties": { "invoiceTax": { "type": "string", "description": "The unique identifier for the invoice tax that this tax applies to.", "examples": [ "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3" ] }, "amount": { "type": "integer", "description": "The amount to be credited for the tax in the currency of the invoice.", "minimum": 0, "examples": [ 200 ] } } } } } } }, "fees": { "type": [ "array", "null" ], "description": "The fees to be credited.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of fee to be credited." }, "amount": { "type": "integer", "description": "The amount to be credited for the fee in the currency of the invoice.", "minimum": 0, "examples": [ 999 ] } } } } }, "required": [ "invoice" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25", "metadata": {}, "lineItems": [ { "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe", "amount": 999, "taxes": [ { "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3", "amount": 200 } ] } ], "fees": [ { "amount": 999 } ] } }, "Example - Required": { "summary": "Example - Required", "value": { "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25" } } } } }, "required": true }, "responses": { "201": { "description": "Returns the created credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/creditNote" }, "examples": { "Example": { "summary": "Example", "value": { "object": "creditNote", "id": "crn_0SNlurA049MEWV49X25tqzNV2jji", "metadata": {}, "createdAt": "2024-06-14T19:38:34Z", "creditTo": "outOfBand", "fees": [ { "amount": { "amount": 100, "currency": "USD" }, "name": "Recovery Fee", "type": "recoveryFee" } ], "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123", "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25", "lineItems": [ { "amount": { "amount": 999, "currency": "USD" }, "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe", "tax": { "amount": 200, "currency": "USD" }, "taxes": [ { "amount": { "amount": 200, "currency": "USD" }, "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3" } ], "total": { "amount": 1199, "currency": "USD" } } ], "number": "3l4rLP-DE-CN-2026-06-10001", "status": "issued", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "total": { "amount": 1199, "currency": "USD" }, "voidedAt": "2024-06-14T19:38:34Z" } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "404": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/notFound" }, "422": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/creditNotes/{creditNote}": { "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/project" }, { "name": "creditNote", "in": "path", "description": "The unique identifier for the credit note.", "required": true, "schema": { "type": "string", "examples": [ "crn_0SNlurA049MEWV49X25tqzNV2jji" ] } } ], "get": { "tags": [ "Credit Notes" ], "operationId": "CreditNotesRetrieve", "summary": "Retrieve a credit note", "description": "Retrieves the details of an existing credit note.", "responses": { "200": { "description": "Returns the credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/creditNote" }, "examples": { "Example": { "summary": "Example", "value": { "object": "creditNote", "id": "crn_0SNlurA049MEWV49X25tqzNV2jji", "metadata": {}, "createdAt": "2024-06-14T19:38:34Z", "creditTo": "outOfBand", "fees": [ { "amount": { "amount": 100, "currency": "USD" }, "name": "Recovery Fee", "type": "recoveryFee" } ], "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123", "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25", "lineItems": [ { "amount": { "amount": 999, "currency": "USD" }, "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe", "tax": { "amount": 200, "currency": "USD" }, "taxes": [ { "amount": { "amount": 200, "currency": "USD" }, "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3" } ], "total": { "amount": 1199, "currency": "USD" } } ], "number": "3l4rLP-DE-CN-2026-06-10001", "status": "issued", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "total": { "amount": 1199, "currency": "USD" }, "voidedAt": "2024-06-14T19:38:34Z" } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "404": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/notFound" } } } }, "/projects/{project}/creditNotes/{creditNote}/void": { "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/project" }, { "name": "creditNote", "in": "path", "description": "The unique identifier for the credit note.", "required": true, "schema": { "type": "string", "examples": [ "crn_0SNlurA049MEWV49X25tqzNV2jji" ] } } ], "post": { "tags": [ "Credit Notes" ], "operationId": "CreditNotesVoid", "summary": "Void a credit note", "description": "\n> #### Deprecated\n>\n> This endpoint is deprecated and will be removed in the future.\n> This endpoint should no longer be used and will be removed in a future version.\n\n\nMarks the credit note as void. This reverses the credited amount in the invoice and reported taxes.", "responses": { "200": { "description": "Returns the voided credit note.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/creditNote" }, "examples": { "Example": { "summary": "Example", "value": { "object": "creditNote", "id": "crn_0SNlurA049MEWV49X25tqzNV2jji", "metadata": {}, "createdAt": "2024-06-14T19:38:34Z", "creditTo": "outOfBand", "fees": [ { "amount": { "amount": 100, "currency": "USD" }, "name": "Recovery Fee", "type": "recoveryFee" } ], "fileUrl": "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123", "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25", "lineItems": [ { "amount": { "amount": 999, "currency": "USD" }, "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe", "tax": { "amount": 200, "currency": "USD" }, "taxes": [ { "amount": { "amount": 200, "currency": "USD" }, "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3" } ], "total": { "amount": 1199, "currency": "USD" } } ], "number": "3l4rLP-DE-CN-2026-06-10001", "status": "issued", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "total": { "amount": 1199, "currency": "USD" }, "voidedAt": "2024-06-14T19:38:34Z" } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "404": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/notFound" }, "422": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/unprocessableEntity" } }, "deprecated": true } }, "/projects/{project}/invoices": { "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/project" } ], "get": { "tags": [ "Invoices" ], "operationId": "InvoicesList", "summary": "List all invoices", "description": "Returns a list of invoices.", "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/listAfter" }, { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/listBefore" }, { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/listLimit" }, { "name": "user", "in": "query", "description": "The unique identifier of the user to filter by.", "schema": { "type": "string", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] } }, { "name": "subscription", "in": "query", "description": "The unique identifier of the subscription to filter by.", "schema": { "type": "string", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] } }, { "name": "subscriptionAddon", "in": "query", "description": "The unique identifier of the subscription addon to filter by.", "schema": { "type": "string", "examples": [ "sad_0SNlurA049MEWV2UNWPbDfW5B40U" ] } }, { "name": "subscriptionChange", "in": "query", "description": "The unique identifier of the subscription change to filter by.", "schema": { "type": "string", "examples": [ "sch_0SNlurA049MEWV3bE0SMtbIEJApp" ] } }, { "name": "status", "in": "query", "description": "A comma-separated list of statuses to filter by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "draft", "finalized", "paid", "voided" ] } }, "style": "form", "explode": false }, { "name": "reason", "in": "query", "description": "A comma-separated list of reasons to filter by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "other", "subscriptionChange", "subscriptionCreation", "subscriptionRenewal", "subscriptionRestore" ] } }, "style": "form", "explode": false } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of invoices.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `invoice`.", "items": { "$ref": "#/components/schemas/invoice" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "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", "expiresAt": "2024-02-11T11:13: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" } } ], "number": "3l4rLP-DE-2026-06-10001", "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 } }, "Example - Required": { "summary": "Example - Required", "value": { "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", "expiresAt": "2024-02-11T11:13: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" } } ], "number": "3l4rLP-DE-2026-06-10001", "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 } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "404": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/notFound" }, "422": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/invoices/{invoice}": { "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/project" }, { "name": "invoice", "in": "path", "description": "The unique identifier for the invoice.", "required": true, "schema": { "type": "string", "examples": [ "inv_0SNlurA049MEWV1QTRqvd18YuG25" ] } } ], "get": { "tags": [ "Invoices" ], "operationId": "InvoicesRetrieve", "summary": "Retrieve an invoice", "description": "Retrieves the details of an existing invoice.", "responses": { "200": { "description": "Returns the invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "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", "expiresAt": "2024-02-11T11:13: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" } } ], "number": "3l4rLP-DE-2026-06-10001", "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" } }, "Example - Required": { "summary": "Example - Required", "value": { "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", "expiresAt": "2024-02-11T11:13: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" } } ], "number": "3l4rLP-DE-2026-06-10001", "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" } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "404": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/notFound" } } } }, "/projects/{project}/invoices/{invoice}/pay": { "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/project" }, { "name": "invoice", "in": "path", "description": "The unique identifier for the invoice.", "required": true, "schema": { "type": "string", "examples": [ "inv_0SNlurA049MEWV1QTRqvd18YuG25" ] } } ], "post": { "tags": [ "Invoices" ], "operationId": "InvoicesPay", "summary": "Pay an invoice", "description": "Marks the invoice as paid. This activates or allows to renew the products associated with the invoice.", "responses": { "200": { "description": "Returns the invoice.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/invoice" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "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", "expiresAt": "2024-02-11T11:13: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" } } ], "number": "3l4rLP-DE-2026-06-10001", "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" } }, "Example - Required": { "summary": "Example - Required", "value": { "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", "expiresAt": "2024-02-11T11:13: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" } } ], "number": "3l4rLP-DE-2026-06-10001", "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" } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "404": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/notFound" } } } }, "/projects/{project}/quotes": { "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/project" } ], "post": { "tags": [ "Quotes" ], "operationId": "QuotesCreate", "summary": "Create a quote", "description": "Creates a quote for the given plan or add-on, allowing you to preview its final price with all applicable taxes and fees.", "requestBody": { "description": "Properties of the new quote.", "content": { "application/json": { "schema": { "type": "object", "properties": { "addon": { "type": [ "string", "null" ], "description": "The unique identifier for the addon for which this quote is being created. Either plan or addon should be present, but not both.", "examples": [ "add_0SNlurA049MEWV4VxLfwJc7PJtHc" ] }, "address": { "type": [ "string", "null" ], "description": "The unique identifier representing the address for tax calculation purposes. Required when quoting local plans or addons for local plans.", "examples": [ "adr_0SNlurA049MEWV5ELDmnaqVXgTFT" ] }, "creditedPlan": { "type": [ "string", "null" ], "description": "The unique identifier for the credited plan this quote is being created with. The price of the credited plan is used to adjust the final plan price when quoting immediate subscription changes.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "plan": { "type": [ "string", "null" ], "description": "The unique identifier for the plan for which this quote is being created. Either plan or addon should be present, but not both.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "user": { "type": "string", "description": "The unique identifier for the user for which this quote is being created.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] }, "voucher": { "type": [ "string", "null" ], "description": "The unique identifier for the voucher to apply to this quote.", "examples": [ "vou_0SNlurA049MEWV0h2jfjkdiOdplN" ] } }, "required": [ "user" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN" } }, "Example - Required": { "summary": "Example - Required", "value": { "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" } } } } }, "required": true }, "responses": { "201": { "description": "Returns the created quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/quote" }, "examples": { "Example": { "summary": "Example", "value": { "object": "quote", "id": "quo_0SNlurA049MEWV2X9NicYieFQ4Kc", "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "createdAt": "2024-01-09T15:00:51Z", "discount": { "amount": 100, "currency": "USD" }, "expiredAt": "2024-02-01T11:12:13Z", "fees": [ { "amount": { "amount": 100, "currency": "USD" }, "name": "Recovery Fee", "type": "recoveryFee" } ], "lineItems": [ { "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "discount": { "amount": 100, "currency": "USD" }, "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxes": [ { "amount": { "amount": 200, "currency": "USD" }, "inclusive": false, "jurisdiction": "Federal", "name": "Federal TRS Fund" } ], "total": { "amount": 1099, "currency": "USD" } } ], "reason": "other", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxExemptionReason": "calculationFailed", "total": { "amount": 1199, "currency": "USD" }, "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN" } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "422": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/quotes/{quote}": { "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/project" }, { "name": "quote", "in": "path", "description": "The unique identifier for the quote.", "required": true, "schema": { "type": "string", "examples": [ "quo_0SNlurA049MEWV2X9NicYieFQ4Kc" ] } } ], "get": { "tags": [ "Quotes" ], "operationId": "QuotesRetrieve", "summary": "Retrieve a quote", "description": "Retrieves the details of an existing quote.", "responses": { "200": { "description": "Returns the quote.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/quote" }, "examples": { "Example": { "summary": "Example", "value": { "object": "quote", "id": "quo_0SNlurA049MEWV2X9NicYieFQ4Kc", "address": "adr_0SNlurA049MEWV5ELDmnaqVXgTFT", "createdAt": "2024-01-09T15:00:51Z", "discount": { "amount": 100, "currency": "USD" }, "expiredAt": "2024-02-01T11:12:13Z", "fees": [ { "amount": { "amount": 100, "currency": "USD" }, "name": "Recovery Fee", "type": "recoveryFee" } ], "lineItems": [ { "addon": "add_0SNlurA049MEWV4VxLfwJc7PJtHc", "creditedPlan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "discount": { "amount": 100, "currency": "USD" }, "plan": "pln_0SNlurA049MEWV3V0q7gjQbM4EVo", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxes": [ { "amount": { "amount": 200, "currency": "USD" }, "inclusive": false, "jurisdiction": "Federal", "name": "Federal TRS Fund" } ], "total": { "amount": 1099, "currency": "USD" } } ], "reason": "other", "subtotal": { "amount": 999, "currency": "USD" }, "tax": { "amount": 200, "currency": "USD" }, "taxExemptionReason": "calculationFailed", "total": { "amount": 1199, "currency": "USD" }, "user": "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d", "voucher": "vou_0SNlurA049MEWV0h2jfjkdiOdplN" } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "404": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/notFound" } } } }, "/projects/{project}/vouchers": { "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/project" } ], "get": { "tags": [ "Vouchers" ], "operationId": "VouchersList", "summary": "List all vouchers", "description": "Returns a list of vouchers. The vouchers returned are sorted by creation date, with the most recently created vouchers appearing first.", "parameters": [ { "name": "status", "in": "query", "description": "The status to filter the vouchers by.", "schema": { "type": "array", "default": [ "available" ], "items": { "type": "string", "enum": [ "available", "retired" ] } }, "style": "form", "explode": false }, { "name": "code", "in": "query", "description": "The voucher code to filter the vouchers by.", "schema": { "type": "string", "examples": [ "SummerCode" ] } }, { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/listAfter" }, { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/listBefore" }, { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/listLimit" } ], "responses": { "200": { "description": "Returns a dictionary with an items property that contains an array of vouchers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "type": "string", "const": "list", "description": "Type of object is always `list`." }, "items": { "type": "array", "description": "List of objects of type `voucher`.", "items": { "$ref": "#/components/schemas/voucher" } }, "moreItemsAfter": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `after` pagination parameter if more items are available sorted after the current batch of items." }, "moreItemsBefore": { "type": [ "string", "null" ], "description": "A unique identifier to be used as `before` pagination parameter if more items are available sorted before the current batch of items." } }, "required": [ "object", "items", "moreItemsAfter", "moreItemsBefore" ] }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "list", "items": [ { "object": "voucher", "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "createdAt": "2021-02-14T19:38:34Z", "name": "Black Friday", "priceDiscount": { "amount": 999, "currency": "USD" }, "priceDiscountPercentage": 30.12, "recurrence": { "type": "once", "durationInMonths": null }, "redemptions": 2, "retiredReason": null, "status": "available" } ], "moreItemsAfter": null, "moreItemsBefore": null } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "list", "items": [ { "object": "voucher", "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "createdAt": "2021-02-14T19:38:34Z", "name": "Black Friday", "priceDiscount": { "amount": 999, "currency": "USD" }, "priceDiscountPercentage": 30.12, "recurrence": { "type": "once", "durationInMonths": null }, "redemptions": 2, "retiredReason": null, "status": "available" } ], "moreItemsAfter": null, "moreItemsBefore": null } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "422": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/unprocessableEntity" } } }, "post": { "tags": [ "Vouchers" ], "operationId": "VouchersCreate", "summary": "Create a voucher", "description": "Creates a new voucher in the specified project.", "requestBody": { "description": "Optional and required parameters to be passed in the request body to create a voucher.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The voucher's name.", "examples": [ "Monthly Basic 15%" ] }, "priceDiscount": { "type": [ "object", "null" ], "description": "The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.", "properties": { "amount": { "type": "integer", "description": "The discount amount in the currency's minor unit, e.g. \"cents\" for many currencies.\n\nMost currencies have two decimals, so USD 9.99 is `999`. These currencies have a different number of decimals, e.g. JPY 28,500 is `28500`:\n\n- 0 decimals: CLP, ISK, JPY, KRW\n", "minimum": 1, "examples": [ 999 ] }, "currency": { "type": "string", "format": "ISO 4217", "description": "Three-letter ISO 4217 currency code. Must be a supported currency.", "examples": [ "USD" ] } }, "required": [ "amount", "currency" ] }, "priceDiscountPercentage": { "type": [ "number", "null" ], "description": "The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.", "maximum": 100, "minimum": 1, "examples": [ 30.12 ] }, "recurrence": { "type": "object", "description": "Details on whether and for how long the discounts applied via the voucher recur.", "properties": { "type": { "type": "string", "enum": [ "once", "repeating", "forever" ], "description": "Whether and how the voucher discount recurs.", "examples": [ "once" ] }, "durationInMonths": { "type": [ "integer", "null" ], "description": "For how many months is the discount applied via the voucher. Only applicable when 'recurrence.type' is 'repeating'.", "minimum": 1 } }, "required": [ "type" ] } }, "required": [ "name", "recurrence" ] }, "examples": { "One time flat discount": { "summary": "One time flat discount", "value": { "name": "Monthly Basic 15%", "priceDiscount": { "amount": 999, "currency": "USD" }, "priceDiscountPercentage": null, "recurrence": { "type": "once", "durationInMonths": null } } }, "Recurring percentage discount": { "summary": "Recurring percentage discount", "value": { "name": "Monthly Basic 15%", "priceDiscount": null, "priceDiscountPercentage": 30.12, "recurrence": { "type": "repeating", "durationInMonths": 3 } } } } } }, "required": true }, "responses": { "201": { "description": "Returns the newly created voucher.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/voucher" }, "examples": { "One time flat discount": { "summary": "One time flat discount", "value": { "object": "voucher", "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "createdAt": "2021-02-14T19:38:34Z", "name": "Black Friday", "priceDiscount": { "amount": 999, "currency": "USD" }, "priceDiscountPercentage": null, "recurrence": { "type": "once", "durationInMonths": null }, "redemptions": 2, "retiredReason": null, "status": "available" } }, "Recurring percentage discount": { "summary": "Recurring percentage discount", "value": { "object": "voucher", "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "createdAt": "2021-02-14T19:38:34Z", "name": "Black Friday", "priceDiscount": null, "priceDiscountPercentage": 30.12, "recurrence": { "type": "repeating", "durationInMonths": 3 }, "redemptions": 2, "retiredReason": null, "status": "available" } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "422": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/unprocessableEntity" } } } }, "/projects/{project}/vouchers/{voucher}": { "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/project" }, { "name": "voucher", "in": "path", "description": "The unique identifier for the voucher.", "required": true, "schema": { "type": "string", "examples": [ "vou_0SNlurA049MEWV0h2jfjkdiOdplN" ] } } ], "get": { "tags": [ "Vouchers" ], "operationId": "VouchersRetrieve", "summary": "Retrieve a voucher", "description": "Retrieves the details of an existing voucher. You need only supply the unique voucher identifier that was returned upon voucher creation.", "responses": { "200": { "description": "Returns the voucher object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/voucher" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "voucher", "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "createdAt": "2021-02-14T19:38:34Z", "name": "Black Friday", "priceDiscount": { "amount": 999, "currency": "USD" }, "priceDiscountPercentage": 30.12, "recurrence": { "type": "once", "durationInMonths": null }, "redemptions": 2, "retiredReason": null, "status": "available" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "voucher", "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "createdAt": "2021-02-14T19:38:34Z", "name": "Black Friday", "priceDiscount": { "amount": 999, "currency": "USD" }, "priceDiscountPercentage": 30.12, "recurrence": { "type": "once", "durationInMonths": null }, "redemptions": 2, "retiredReason": null, "status": "available" } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "404": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/notFound" } } } }, "/projects/{project}/vouchers/{voucher}/retire": { "parameters": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/parameters/project" }, { "name": "voucher", "in": "path", "description": "The unique identifier for the voucher.", "required": true, "schema": { "type": "string", "examples": [ "vou_0SNlurA049MEWV0h2jfjkdiOdplN" ] } } ], "post": { "tags": [ "Vouchers" ], "operationId": "VouchersRetire", "summary": "Retire a voucher", "description": "Retires the voucher. This marks the voucher as no longer redeemable for new subscriptions, but does not affect any active discounts.", "responses": { "200": { "description": "Returns the voucher.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/voucher" }, "examples": { "Example - Full": { "summary": "Example - Full", "value": { "object": "voucher", "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "createdAt": "2021-02-14T19:38:34Z", "name": "Black Friday", "priceDiscount": { "amount": 999, "currency": "USD" }, "priceDiscountPercentage": 30.12, "recurrence": { "type": "once", "durationInMonths": null }, "redemptions": 2, "retiredReason": null, "status": "available" } }, "Example - Required": { "summary": "Example - Required", "value": { "object": "voucher", "id": "vou_0SNlurA049MEWV0h2jfjkdiOdplN", "createdAt": "2021-02-14T19:38:34Z", "name": "Black Friday", "priceDiscount": { "amount": 999, "currency": "USD" }, "priceDiscountPercentage": 30.12, "recurrence": { "type": "once", "durationInMonths": null }, "redemptions": 2, "retiredReason": null, "status": "available" } } } } } }, "403": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/permissionDenied" }, "404": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/notFound" }, "422": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/responses/unprocessableEntity" } } } } }, "components": { "schemas": { "creditNote": { "type": "object", "title": "CreditNote", "description": "Credit notes adjust an invoice amount after it has been finalized. Used to issue credit or refunds.", "properties": { "object": { "type": "string", "const": "creditNote", "description": "Type of object is always `creditNote`." }, "id": { "type": "string", "description": "Unique identifier for the credit note.", "examples": [ "crn_0SNlurA049MEWV49X25tqzNV2jji" ] }, "metadata": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the credit note was created.", "examples": [ "2024-06-14T19:38:34Z" ] }, "creditTo": { "type": "string", "enum": [ "outOfBand", "pspRefund", "userBalance" ], "description": "Specifies where the credit amount should be credited to. It can have one of the following values:\n\n - `outOfBand`: The amount should be handled outside the system by the customer.\n - `pspRefund`: The amount will be refunded by Gigs through to the payment service provider used to pay the invoice.\n - `userBalance`: The amount should be added to the user balance at Gigs.\n" }, "fees": { "type": "array", "description": "The credited fees.", "items": { "type": "object", "properties": { "amount": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The amount of the fee.", "examples": [ { "amount": 100, "currency": "USD" } ] }, "name": { "type": "string", "description": "The name of the fee.", "examples": [ "Recovery Fee" ] }, "type": { "type": "string", "enum": [ "recoveryFee" ], "description": "The type of the fee." } }, "required": [ "amount", "name", "type" ] } }, "fileUrl": { "type": [ "string", "null" ], "format": "uri", "description": "A signed URL to download the credit note PDF file.\nThe URL is valid for 1 minute.\n\nThis field is `null` for projects without billing enabled,\nfor credit notes covering US-taxed plans, and for credit notes whose\ninvoice was not issued by Gigs as the merchant of record.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "https://files.gigs.com/creditNotes/crn_0SNlurA049MEWV49X25tqzNV2jji.pdf?signature=abc123" ] }, "invoice": { "type": "string", "description": "The unique identifier for the invoice that the credit note applies to.", "examples": [ "inv_0SNlurA049MEWV1QTRqvd18YuG25" ] }, "lineItems": { "type": "array", "description": "The line items for the credit note.", "items": { "type": "object", "title": "CreditNoteLineItem", "properties": { "amount": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The amount credited for this line item before taxes.", "examples": [ { "amount": 999, "currency": "USD" } ] }, "invoiceLineItem": { "type": "string", "description": "The unique identifier for the invoice line item that the line item applies to.", "examples": [ "lin_0SNlurA049MEWV11QUKZGDMxJmKe" ] }, "tax": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The sum of the amount in taxes credited for this line item.", "examples": [ { "amount": 200, "currency": "USD" } ] }, "taxes": { "type": "array", "description": "The taxes credited for this line item.", "items": { "type": "object", "properties": { "amount": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The amount credited for this tax.", "examples": [ { "amount": 200, "currency": "USD" } ] }, "invoiceTax": { "type": "string", "description": "Unique identifier of the invoice's line item tax being credited.", "examples": [ "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3" ] } }, "required": [ "amount", "invoiceTax" ] } }, "total": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount credited for this line item after taxes.", "examples": [ { "amount": 1199, "currency": "USD" } ] } }, "required": [ "amount", "invoiceLineItem", "tax", "taxes", "total" ] } }, "number": { "type": [ "string", "null" ], "description": "The sequential number identifying this credit note, unique across all Gigs credit notes and immutable once assigned.\n\nCredit notes have their own number series, separate from invoices, so a credit note and the invoice it credits never share a number. It is case-sensitive.\n", "examples": [ "3l4rLP-DE-CN-2026-06-10001" ] }, "status": { "type": "string", "enum": [ "issued", "voided" ], "description": "The status of the credit note. It can have one of the following values:\n\n - `issued`: The credit note was issued.\n - `voided`: The credit note was voided and no longer has any effect.\n" }, "subtotal": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount credited before any taxes or fees.", "examples": [ { "amount": 999, "currency": "USD" } ] }, "tax": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The sum of the amounts in taxes credited for each line item.", "examples": [ { "amount": 200, "currency": "USD" } ] }, "total": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount credited after taxes and fees.", "examples": [ { "amount": 1199, "currency": "USD" } ] }, "voidedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the credit note was voided.", "examples": [ "2024-06-14T19:38:34Z" ] } }, "required": [ "object", "id", "metadata", "creditTo", "fees", "fileUrl", "invoice", "lineItems", "number", "status", "subtotal", "tax", "total", "createdAt", "voidedAt" ] }, "invoice": { "type": "object", "title": "Invoice", "description": "Invoices describe the amount due to a user for a given subscription period, including any relevant taxes and fees.", "properties": { "object": { "type": "string", "const": "invoice", "description": "Type of object is always `invoice`." }, "id": { "type": "string", "description": "Unique identifier for the invoice.", "examples": [ "inv_0SNlurA049MEWV1QTRqvd18YuG25" ] }, "address": { "type": [ "string", "null" ], "description": "The unique identifier for the address this invoice relates to.", "examples": [ "adr_0SNlurA049MEWV5ELDmnaqVXgTFT" ] }, "appliedBalance": { "anyOf": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price" }, { "type": "null" } ], "description": "The amount of user balance applied to pay this invoice.", "examples": [ { "amount": 1199, "currency": "USD" } ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the invoice was created.", "examples": [ "2024-01-09T15:00:51Z" ] }, "discount": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total discount applied. This is the sum of the discounts of each line item.", "examples": [ { "amount": 100, "currency": "USD" } ] }, "dueAt": { "type": [ "string", "null" ], "format": "date-time", "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.\n\nThis 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`.\n", "examples": [ "2024-02-01T11:12:13Z" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the overdue period ends and the subscription is ended.\n\nThis field will have a value once a `finalized` invoice enters its overdue period. For all other invoices, this field will be `null`.\n", "examples": [ "2024-02-11T11:13:13Z" ] }, "fees": { "type": "array", "description": "The fees for the invoice.", "items": { "type": "object", "properties": { "amount": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The amount of the fee.", "examples": [ { "amount": 100, "currency": "USD" } ] }, "name": { "type": "string", "description": "The name of the fee.", "examples": [ "Recovery Fee" ] }, "type": { "type": "string", "enum": [ "recoveryFee" ], "description": "The type of the fee." } }, "required": [ "amount", "name", "type" ] } }, "fileUrl": { "type": [ "string", "null" ], "format": "uri", "description": "A signed URL to download the invoice PDF file.\nThe URL is valid for 1 minute.\n\nThis field is `null` for invoices that haven't been finalized,\nfor projects without billing enabled, for invoices covering\nUS-taxed plans, and for invoices where Gigs is not the merchant\nof record.\n\n\n\n> #### Preview\n>\n> This property is currently in preview and might change in the future.\n>\n> We’re excited to hear your feedback and ideas. Please send an email\n> to [support@gigs.com](mailto:support@gigs.com) to share your thoughts.\n", "examples": [ "https://files.gigs.com/invoices/inv_0SNlurA049MEWV1QTRqvd18YuG25.pdf?signature=abc123" ] }, "finalizedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the invoice was finalized and could no longer be changed.", "examples": [ "2024-02-01T11:12:13Z" ] }, "lineItems": { "type": "array", "description": "The line items that make up the invoice.", "items": { "type": "object", "title": "InvoiceLineItem", "properties": { "object": { "type": "string", "const": "invoiceLineItem", "description": "Type of object is always `invoiceLineItem`." }, "id": { "type": "string", "description": "Unique identifier for this line item.", "examples": [ "lin_0SNlurA049MEWV11QUKZGDMxJmKe" ] }, "addon": { "type": [ "string", "null" ], "description": "The unique identifier for the addon this line item refers to, if any. Either plan or addon will be present, but not both.", "examples": [ "add_0SNlurA049MEWV4VxLfwJc7PJtHc" ] }, "creditedPlan": { "type": [ "string", "null" ], "description": "The unique identifier for the credited plan this line item refers to, if any. The value of the credited plan price is subtracted to calculate the line item amount. Only present for line items created for invoices of subscription changes.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "discount": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The discount applied to this line item.", "examples": [ { "amount": 100, "currency": "USD" } ] }, "plan": { "type": [ "string", "null" ], "description": "The unique identifier for the plan this line item refers to, if any. Either plan or addon will be present, but not both.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "subscription": { "type": [ "string", "null" ], "description": "The unique identifier for the subscription this line item refers to. Present for line items with plans.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] }, "subscriptionAddon": { "type": [ "string", "null" ], "description": "The unique identifier for the subscription addon this line item refers to. Present for line items with addons.", "examples": [ "sad_0SNlurA049MEWV2UNWPbDfW5B40U" ] }, "subscriptionChange": { "type": [ "string", "null" ], "description": "The unique identifier for the subscription change this line item refers to. Present for line items that were created for an invoice of a subscription change.", "examples": [ "sch_0SNlurA049MEWV3bE0SMtbIEJApp" ] }, "subtotal": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The price of the line item before any discounts or taxes are applied.", "examples": [ { "amount": 999, "currency": "USD" } ] }, "tax": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount of taxes applied to this line item.", "examples": [ { "amount": 200, "currency": "USD" } ] }, "taxes": { "type": "array", "description": "The taxes applied to this line item.", "items": { "type": "object", "title": "InvoiceTax", "properties": { "object": { "type": "string", "const": "invoiceTax", "description": "Type of object is always `invoiceTax`." }, "id": { "type": "string", "description": "Unique identifier for the invoice tax.", "examples": [ "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3" ] }, "amount": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The amount of the tax.", "examples": [ { "amount": 200, "currency": "USD" } ] }, "inclusive": { "type": "boolean", "default": false, "description": "Whether the tax is included in the product price or not.", "examples": [ false ] }, "jurisdiction": { "type": [ "string", "null" ], "description": "The optional jurisdiction of the tax.", "examples": [ "Federal" ] }, "name": { "type": "string", "description": "The name of the tax.", "examples": [ "Federal TRS Fund" ] } }, "required": [ "object", "id", "amount", "inclusive", "jurisdiction", "name" ] } }, "total": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount for this line item after all discounts and taxes are applied.", "examples": [ { "amount": 1099, "currency": "USD" } ] } }, "required": [ "object", "id", "addon", "creditedPlan", "discount", "plan", "subscription", "subscriptionAddon", "subscriptionChange", "subtotal", "tax", "taxes", "total" ] } }, "number": { "type": [ "string", "null" ], "description": "The sequential number identifying this invoice, unique across all Gigs invoices and immutable once assigned.\n\nThe number is assigned when the invoice is finalized, so a draft never has one. It is case-sensitive.\n", "examples": [ "3l4rLP-DE-2026-06-10001" ] }, "overdueAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the invoice is considered overdue. Once this happens, `invoiceOverdueAction`, which can be configured on project or subscription level, is applied.\n\nThis 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`.\n", "examples": [ "2024-02-01T11:13:13Z" ] }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Time when the invoice was paid.", "examples": [ "2024-02-01T11:13:13Z" ] }, "payment": { "type": [ "string", "null" ], "description": "The unique identifier for the payment associated with the invoice, if any. Only present if the invoice has been paid using Gigs Payments.", "examples": [ "pay_0SNlurA049MEWV2HRA0slWFuS8DV" ] }, "period": { "anyOf": [ { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/period" }, { "type": "null" } ], "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." }, "reason": { "type": "string", "enum": [ "other", "subscriptionChange", "subscriptionCreation", "subscriptionRenewal", "subscriptionRestore" ], "description": "The reason this invoice was created. It can have one of the following values:\n\n - `subscriptionCreation`: The invoice is due to a new subscription.\n - `subscriptionRenewal`: The invoice is due to a recurring subscription renewal.\n - `subscriptionChange`: The invoice is due to a subscription change (e.g. plan upgrade).\n - `subscriptionRestore`: The invoice is due to a subscription restore.\n - `other`: The invoice is not related to a subscription but due an e.g. one-time addon.\n" }, "status": { "type": "string", "enum": [ "draft", "finalized", "paid", "voided" ], "description": "The status of the invoice. It can have one of the following values:\n\n - `draft`: The invoice is still being edited.\n - `finalized`: The invoice can no longer be changed and is awaiting payment.\n - `paid`: The invoice was paid. This causes the associated resources to activated.\n - `voided`: The invoice was voided and no longer has any effect.\n", "examples": [ "draft" ] }, "subscription": { "type": "string", "description": "The unique identifier for the subscription that this invoice relates to.", "examples": [ "sub_0SNlurA049MEWV2gSfSxi00xlPIi" ] }, "subtotal": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount before any discounts, taxes or fees are applied.", "examples": [ { "amount": 999, "currency": "USD" } ] }, "tax": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount of taxes. This is the sum of the taxes of each line item.", "examples": [ { "amount": 200, "currency": "USD" } ] }, "taxExemptionReason": { "type": [ "string", "null" ], "enum": [ null, "calculationFailed", "fullyDiscounted", "inclusiveTaxExceedsPrice", "userExempted" ], "description": "The reason for the invoice having no taxes calculated, if any. It can have one of the following values:\n\n - `calculationFailed`: The tax calculation failed for an unspecified reason.\n - `fullyDiscounted`: The invoice is fully discounted due to a voucher or a free product.\n - `inclusiveTaxExceedsPrice`: The calculated tax is too large to be included in the price.\n - `userExempted`: The user is marked as exempted from taxes.\n", "examples": [ "calculationFailed" ] }, "total": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount after all discounts, taxes and fees are applied.", "examples": [ { "amount": 1199, "currency": "USD" } ] }, "voucher": { "type": [ "string", "null" ], "description": "The unique identifier for the voucher applied to the invoice, if any.", "examples": [ "vou_0SNlurA049MEWV0h2jfjkdiOdplN" ] } }, "required": [ "object", "id", "address", "appliedBalance", "discount", "dueAt", "expiresAt", "fees", "fileUrl", "lineItems", "number", "overdueAt", "payment", "period", "reason", "status", "subscription", "subtotal", "tax", "taxExemptionReason", "total", "voucher", "createdAt", "finalizedAt", "paidAt" ] }, "quote": { "type": "object", "title": "Quote", "description": "Quotes provide a preview of the invoices, including taxes and fees, that will occur when creating a subscription or add-on.", "properties": { "object": { "type": "string", "const": "quote", "description": "Type of object is always `quote`." }, "id": { "type": "string", "description": "Unique identifier for the quote.", "examples": [ "quo_0SNlurA049MEWV2X9NicYieFQ4Kc" ] }, "address": { "type": [ "string", "null" ], "description": "The unique identifier for the address that the taxes were quoted for. Present when quoting local plans.", "examples": [ "adr_0SNlurA049MEWV5ELDmnaqVXgTFT" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the quote was created.", "examples": [ "2024-01-09T15:00:51Z" ] }, "discount": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total discount applied. This is the sum of the discounts of each line item.", "examples": [ { "amount": 100, "currency": "USD" } ] }, "expiredAt": { "type": "string", "format": "date-time", "description": "The timestamp indicating when the quote expires. Set to 2 hours after the quote's creation time.", "examples": [ "2024-02-01T11:12:13Z" ] }, "fees": { "type": "array", "description": "The fees for the quote.", "items": { "type": "object", "properties": { "amount": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The amount of the fee.", "examples": [ { "amount": 100, "currency": "USD" } ] }, "name": { "type": "string", "description": "The name of the fee.", "examples": [ "Recovery Fee" ] }, "type": { "type": "string", "enum": [ "recoveryFee" ], "description": "The type of the fee." } }, "required": [ "amount", "name", "type" ] } }, "lineItems": { "type": "array", "description": "The line items that make up the quote.", "items": { "type": "object", "title": "QuoteLineItem", "properties": { "addon": { "type": [ "string", "null" ], "description": "The unique identifier for the addon this line item refers to, if any. Either plan or addon will be present, but not both.", "examples": [ "add_0SNlurA049MEWV4VxLfwJc7PJtHc" ] }, "creditedPlan": { "type": [ "string", "null" ], "description": "The unique identifier for the credited plan this line item refers to, if any. The price of the credited plan is used to adjust the final plan price when quoting immediate subscription changes. Only present for line items generated as part of a subscription change quote.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "discount": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The discount applied to this line item.", "examples": [ { "amount": 100, "currency": "USD" } ] }, "plan": { "type": [ "string", "null" ], "description": "The unique identifier for the plan this line item refers to, if any. Either plan or addon will be present, but not both.", "examples": [ "pln_0SNlurA049MEWV3V0q7gjQbM4EVo" ] }, "subtotal": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The price of the line item before any discounts or taxes are applied.", "examples": [ { "amount": 999, "currency": "USD" } ] }, "tax": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount of taxes applied to this line item.", "examples": [ { "amount": 200, "currency": "USD" } ] }, "taxes": { "type": "array", "description": "The taxes applied to this line item.", "items": { "type": "object", "title": "QuoteTax", "properties": { "amount": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The amount of the tax.", "examples": [ { "amount": 200, "currency": "USD" } ] }, "inclusive": { "type": "boolean", "default": false, "description": "Whether the tax is included in the product price or not.", "examples": [ false ] }, "jurisdiction": { "type": [ "string", "null" ], "description": "The optional jurisdiction of the tax.", "examples": [ "Federal" ] }, "name": { "type": "string", "description": "The name of the tax.", "examples": [ "Federal TRS Fund" ] } }, "required": [ "amount", "inclusive", "jurisdiction", "name" ] } }, "total": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount for this line item after all discounts or taxes are applied.", "examples": [ { "amount": 1099, "currency": "USD" } ] } }, "required": [ "addon", "creditedPlan", "discount", "plan", "subtotal", "tax", "taxes", "total" ] } }, "reason": { "type": "string", "enum": [ "other", "subscriptionChange", "subscriptionCreation" ], "description": "The reason this quote was created. It can have one of the following values:\n\n - `subscriptionCreation`: The quote is for a new subscription.\n - `subscriptionChange`: The quote is for a subscription change (e.g. plan upgrade).\n - `other`: The quote is not related to a subscription but due an e.g. one-time addon.\n" }, "subtotal": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount before any discounts, taxes or fees are applied.", "examples": [ { "amount": 999, "currency": "USD" } ] }, "tax": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount of taxes. This is the sum of the taxes of each line item.", "examples": [ { "amount": 200, "currency": "USD" } ] }, "taxExemptionReason": { "type": [ "string", "null" ], "enum": [ null, "calculationFailed", "fullyDiscounted", "inclusiveTaxExceedsPrice", "userExempted" ], "description": "The reason for the taxes not being calculated, if any. It can have one of the following values:\n\n - `calculationFailed`: The tax calculation failed for an unspecified reason.\n - `inclusiveTaxExceedsPrice`: The calculated tax is too large to be included in the price.\n - `fullyDiscounted`: The quote is fully discounted due to a voucher or a free product.\n - `userExempted`: The user is marked as exempted from taxes.\n", "examples": [ "calculationFailed" ] }, "total": { "$ref": "https://api.gigs.com/openapi/core.yaml#/components/schemas/price", "description": "The total amount after all discounts, taxes and fees are applied.", "examples": [ { "amount": 1199, "currency": "USD" } ] }, "user": { "type": "string", "description": "The unique identifier for the user that this quote belongs to.", "examples": [ "usr_0SNlurA049MEWV4OpCwsNyC9Kn2d" ] }, "voucher": { "type": [ "string", "null" ], "description": "The unique identifier for the voucher applied to the quote, if any.", "examples": [ "vou_0SNlurA049MEWV0h2jfjkdiOdplN" ] } }, "required": [ "object", "id", "address", "discount", "fees", "lineItems", "reason", "subtotal", "tax", "taxExemptionReason", "total", "user", "voucher", "createdAt", "expiredAt" ] }, "voucher": { "type": "object", "title": "Voucher", "description": "Vouchers describe the discounts to apply to quotes and subscriptions.", "properties": { "object": { "type": "string", "const": "voucher", "description": "Type of object is always `voucher`." }, "id": { "type": "string", "description": "Unique identifier for the voucher.", "examples": [ "vou_0SNlurA049MEWV0h2jfjkdiOdplN" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Time when the voucher was created.", "examples": [ "2021-02-14T19:38:34Z" ] }, "name": { "type": "string", "description": "The voucher's name.", "examples": [ "Black Friday" ] }, "priceDiscount": { "type": [ "object", "null" ], "description": "The price amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.", "properties": { "amount": { "type": "integer", "description": "The discount amount in the currency's minor unit, e.g. \"cents\" for many currencies.\n\nMost currencies have two decimals, so USD 9.99 is `999`. These currencies have a different number of decimals, e.g. JPY 28,500 is `28500`:\n\n- 0 decimals: CLP, ISK, JPY, KRW\n", "minimum": 1, "examples": [ 999 ] }, "currency": { "type": "string", "format": "ISO 4217", "description": "Three-letter ISO 4217 currency code. Must be a supported currency.", "examples": [ "USD" ] } }, "required": [ "amount", "currency" ] }, "priceDiscountPercentage": { "type": [ "number", "null" ], "description": "The percentage amount of the discount applied via the voucher. A voucher object has always either a priceDiscount or a priceDiscountPercentage.", "maximum": 100, "minimum": 1, "examples": [ 30.12 ] }, "recurrence": { "type": "object", "description": "Details on whether and for how long the discounts applied via the voucher recur.", "properties": { "type": { "type": "string", "enum": [ "once", "repeating", "forever" ], "description": "Whether and how the voucher discount recurs.", "examples": [ "once" ] }, "durationInMonths": { "type": [ "integer", "null" ], "description": "For how many months is the discount applied via the voucher. Only applicable when 'recurrence.type' is 'repeating'.", "minimum": 1 } }, "required": [ "type", "durationInMonths" ] }, "redemptions": { "type": "integer", "description": "Number of times the voucher has been redeemed.", "examples": [ 2 ] }, "retiredReason": { "type": [ "null", "string" ], "enum": [ null, "manualAction", "expired", "maxRedemptionsReached", "unknown" ], "description": "Label indicating the reason why the voucher is retired." }, "status": { "type": "string", "enum": [ "available", "retired" ] } }, "required": [ "object", "id", "name", "priceDiscount", "priceDiscountPercentage", "recurrence", "redemptions", "retiredReason", "status", "createdAt" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Credit Notes", "description": "Operations to manage credit notes." }, { "name": "Invoices", "description": "Operations to manage invoices." }, { "name": "Quotes", "description": "Operations to manage quotes." }, { "name": "Vouchers", "description": "Operations to manage vouchers." } ] }