Invoice

OpenAPI Schema

The following schema is based on OpenAPI 3.0 and is provided in our downloadable OpenAPI document.

{
  "description": "An invoice.",
  "properties": {
    "acceptedPaymentTypes": {
      "description": "An array of payment types this invoice accepts.",
      "items": {
        "description": "A string identifying a specific payment type.",
        "enum": [
          "cash-check",
          "credit-card"
        ],
        "type": "string"
      },
      "type": "array"
    },
    "activity": {
      "description": "A list of activities that have occurred with this invoice.",
      "items": {
        "$ref": "#/components/schemas/InvoiceActivity"
      },
      "readOnly": true,
      "type": "array"
    },
    "brandTheme": {
      "$ref": "#/components/schemas/BrandTheme"
    },
    "brandThemeId": {
      "description": "The identifier for the brand theme this invoice uses.",
      "type": "integer"
    },
    "cancelationMessage": {
      "description": "Optional cancelation message to include in studio-to-client emails\nsent when invoice status moves to canceled state.",
      "type": "string"
    },
    "contact": {
      "allOf": [
        {
          "readOnly": true
        },
        {
          "$ref": "#/components/schemas/Contact"
        }
      ]
    },
    "contactId": {
      "$ref": "#/components/schemas/Id"
    },
    "contracts": {
      "description": "An array of linked contracts.",
      "items": {
        "$ref": "#/components/schemas/ContractMinimal"
      },
      "readOnly": true,
      "type": "array"
    },
    "created": {
      "description": "The creation date of this invoice.",
      "format": "date-time",
      "readOnly": true,
      "type": "string"
    },
    "creditCardOnFile": {
      "allOf": [
        {
          "$ref": "#/components/schemas/InvoiceCreditCard"
        },
        {
          "nullable": true
        }
      ],
      "description": "The credit card on file for this invoice, if applicable."
    },
    "creditCardTransactions": {
      "description": "An array of invoice credit card transactions, showing all attempts\nto charge a card for this invoice, including approved/declined\nattempts.",
      "items": {
        "$ref": "#/components/schemas/InvoiceCreditCardTransaction"
      },
      "readOnly": true,
      "title": "Credit Card Transaction for Invoice",
      "type": "array"
    },
    "currencyCode": {
      "description": "Identifies the currency used for this invoice.",
      "readOnly": true,
      "type": "string"
    },
    "currencySymbol": {
      "description": "The currency symbol for the currency used for this invoice.",
      "readOnly": true,
      "type": "string"
    },
    "customInvoiceId": {
      "description": "A client-facing identifier for this invoice, starting at 1000 for\neach studio.",
      "readOnly": true,
      "type": "integer"
    },
    "discountTotal": {
      "description": "The total amount of all discounts applied to this invoice.",
      "readOnly": true,
      "type": "number"
    },
    "discounts": {
      "description": "An array of discounts applied to this invoice template.",
      "items": {
        "$ref": "#/components/schemas/InvoiceDiscount"
      },
      "maxItems": 1,
      "type": "array"
    },
    "dueTotal": {
      "description": "The total amount of this invoice that is due.",
      "readOnly": true,
      "type": "number"
    },
    "emailAutomationGroupId": {
      "description": "The identifier for the email automation group this invoice uses.",
      "nullable": true,
      "type": "integer"
    },
    "finalDueDate": {
      "description": "The date on which this invoice must be paid in full.",
      "format": "date-time",
      "nullable": true,
      "readOnly": true,
      "type": "string"
    },
    "grandTotal": {
      "description": "The invoice grand total.",
      "type": "number"
    },
    "id": {
      "description": "The identifier for this invoice.",
      "type": "integer"
    },
    "installments": {
      "description": "An array of invoice installments, defining the installment schedule\nfor this invoice. Installments are required for invoices having a grandTotal\ngreater than zero, but disallowed for Invoices having a grandTotal of zero.",
      "items": {
        "$ref": "#/components/schemas/InvoiceInstallment"
      },
      "type": "array"
    },
    "invoiceRetainerLabel": {
      "description": "This label represents how the studio wishes to refer to the initial\npayment represented by `retainerPercent` or `retainerFixedAmount` for this\ninvoice. This property is required if `retainerPercent` or\n`retainerFixedAmount` contain non-null values.\n\nThe following labels are available. You are responsible for displaying\nappropriate human-readable strings for these labels, translated for your\naudience.\n\n| ShootProof Identifier | Description |\n| --------------------- | ----------- |\n| `non-refundable-payment` | The initial payment should be referred to as a \"non-refundable payment\" when displaying the invoice to the studio's customer. |\n| `deposit` | The initial payment should be referred to as a \"deposit\" when displaying the invoice to the studio's customer. |\n| `retainer` | The initial payment should be referred to as a \"retainer\" when displaying the invoice to the studio's customer. |",
      "enum": [
        "non-refundable-payment",
        "deposit",
        "retainer"
      ],
      "nullable": true,
      "type": "string"
    },
    "invoiceStatus": {
      "description": "The human-readable name of the current status of this invoice.",
      "enum": [
        "unpaid",
        "partially-paid",
        "paid-in-full",
        "canceled",
        "archived"
      ],
      "type": "string"
    },
    "invoiceTemplateId": {
      "description": "The identifier for the invoice template from which this invoice was\ncreated.",
      "nullable": true,
      "type": "integer"
    },
    "isHidden": {
      "description": "Whether or not the invoice should be hidden",
      "type": "boolean"
    },
    "issueDate": {
      "description": "The date on which this invoice was issued.",
      "format": "date-time",
      "type": "string"
    },
    "items": {
      "description": "An array of line items for this invoice.",
      "items": {
        "$ref": "#/components/schemas/InvoiceItem"
      },
      "type": "array"
    },
    "languageCode": {
      "description": "The Unicode CLDR language tag for the language used in this invoice.",
      "type": "string"
    },
    "links": {
      "$ref": "#/components/schemas/Links"
    },
    "notesToClient": {
      "description": "Notes to display on the invoice for the client.",
      "type": "string"
    },
    "paidTotal": {
      "description": "The total amount of this invoice that has been paid.",
      "readOnly": true,
      "type": "number"
    },
    "paymentConfirmationText": {
      "description": "A message sent to the client upon receipt of payment.",
      "type": "string"
    },
    "payments": {
      "description": "An array of invoice payments, showing a history of all payments made\non this invoice.",
      "items": {
        "$ref": "#/components/schemas/InvoicePayment"
      },
      "readOnly": true,
      "type": "array"
    },
    "publicId": {
      "description": "The public identifier for this invoice (may be used in the portal\nwebsite).",
      "pattern": "^[a-fA-F0-9]{32}$",
      "readOnly": true,
      "type": "string"
    },
    "retainerFixedAmount": {
      "description": "Suggested fixed amount of retainer. If a retainer is defined, one of\n`retainerPercent` or `retainerFixedAmount` will be non-null.",
      "nullable": true,
      "type": "number"
    },
    "retainerPercent": {
      "description": "Suggested amount of retainer in a percentage from 1-100. If a\nretainer is defined, one of `retainerPercent` or\n`retainerFixedAmount` will be non-null.",
      "maximum": 100,
      "minimum": 1,
      "nullable": true,
      "type": "number"
    },
    "retainerTotal": {
      "description": "The total amount for the invoice retainer.",
      "readOnly": true,
      "type": "number"
    },
    "salesTaxPercent": {
      "description": "A decimal number from 0-100, specifying the sales tax percentage.",
      "maximum": 100,
      "minimum": 0,
      "nullable": true,
      "type": "number"
    },
    "salesTaxTitle": {
      "description": "A label to apply to the sales tax percent on the invoice when viewed\nby the client.",
      "nullable": true,
      "type": "string"
    },
    "salesTaxTotal": {
      "description": "The total amount of sales tax on the invoice.",
      "type": "number"
    },
    "subtotal": {
      "description": "The invoice subtotal.",
      "type": "number"
    },
    "taxableSubtotal": {
      "description": "The taxable subtotal of the invoice, based on its taxable items.",
      "type": "number"
    },
    "type": {
      "description": "The type of object represented.",
      "enum": [
        "invoice"
      ],
      "type": "string"
    }
  },
  "required": [
    "type",
    "brandThemeId",
    "contactId",
    "issueDate",
    "acceptedPaymentTypes",
    "salesTaxPercent",
    "languageCode",
    "subtotal",
    "grandTotal",
    "items"
  ],
  "title": "Invoice",
  "type": "object"
}