Contents

Invoices

ShootProof provides invoicing to help studios manage the business of their brands. Through invoicing, a brand can set up any fee structure and payment schedule, event allowing one or more parties to pay on the same invoice.

Lists all invoices for the current brand.

Returns a list of all invoices for the current brand. Query string parameters may be used to affect the response, including pagination, sorting, and filtering.

get
/studio/brand/{brandId}/invoice

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

Query Parameters

Property Description
filterContactId

The invoice client contact ID by which to filter results.

filterExcludeLinkedToContract

Indicates that invoices linked to contract(s) should be excluded from the results.

filterHidden

Indicates whether or not hidden invoices should be included in the results. If not provided in the request both hidden and visible invoices will be returned.

filterInvoiceGrouping

Indicates the grouping of invoices that should be returned.

Note: All groups, excluding canceled_hidden, are NOT including hidden invoices. This filter will also override the filterHidden param.

filterOrderId

Note: this filter is accepted for testing purposes, but not yet implemented. All results will be returned. The invoice order ID by which to filter results.

page

The page of results to return.

rows

The number of rows to return on each page of results.

searchContactInfo

Customer name or email address by which to filter results.

searchCustomInvoiceId

The customer-facing invoice identifier by which to filter results.

searchInvoiceItem

The name or description of invoice items by which to filter results.

searchInvoiceStatus

The invoice status by which to filter results. To filter by past due invoices, pass the string past_due in this parameter.

sortBy

The property by which items returned should be sorted.

sortType

The direction in which sorting should occur.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

Invoices list response.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
items

A collection of resources returned in the current result set.

Property Description
amountDue nullable

The total amount remaining to be paid on this invoice against the grand total.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

contactName

The full name of the contact associated with this invoice.

contracts

An array of linked contracts.

created

The creation date of this invoice.

currencyCode

Identifies the currency represented in price.

currencySymbol

The currency symbol for the currency used for this invoice.

customInvoiceId

A client-facing identifier for this invoice, starting at 1000 for each studio.

finalDueDate nullable

The date on which this invoice must be paid in full.

grandTotal nullable

The grand total of all items on the invoice, including any applicable sales tax.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceStatus

The human-readable name of the current status of this invoice.

isHidden

Whether or not the invoice is hidden

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

publicId

The public identifier for this invoice (may be used in the portal website).

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

type

The type of object represented.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

meta required read-only

Metadata describing the current result set.

Property Description
currentPage

The current page of results returned.

invoiceTotals required

Total counts for various types of invoices in various states.

rows

The number of rows returned per page for the current result set.

totalItems

The total number of items in the result set. This may be affected by active search/filter parameters.

totalPages

The total number of pages in the result set. This is affected by the rows parameter (totalItems / rows == totalPages).

type

The model type for the list response object.

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/InvoiceCollection"
        }
      }
    },
    "description": "Invoices list response."
  }
}

Creates a new invoice for the current brand.

post
/studio/brand/{brandId}/invoice

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

The invoice object to create.

application/vnd.shootproof+json
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice uses.

cancelationMessage

Optional cancelation message to include in studio-to-client emails sent when invoice status moves to canceled state.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

creditCardOnFile required nullable

The credit card on file for this invoice, if applicable.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

grandTotal

The invoice grand total.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
invoiceStatus

The human-readable name of the current status of this invoice.

invoiceTemplateId nullable

The identifier for the invoice template from which this invoice was created.

isHidden

Whether or not the invoice should be hidden

issueDate

The date on which this invoice was issued.

items

An array of line items for this invoice.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

notesToClient

Notes to display on the invoice for the client.

paymentConfirmationText

A message sent to the client upon receipt of payment.

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

salesTaxPercent nullable

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

salesTaxTotal

The total amount of sales tax on the invoice.

subtotal

The invoice subtotal.

taxableSubtotal

The taxable subtotal of the invoice, based on its taxable items.

type

The type of object represented.

OpenAPI Schema

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

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/Invoice"
      }
    }
  },
  "description": "The invoice object to create.",
  "required": true
}

201 Created

The successfully-created invoice.

Headers
Header Description
Location

The URL to the newly-created invoice.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

activity read-only

A list of activities that have occurred with this invoice.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice uses.

cancelationMessage

Optional cancelation message to include in studio-to-client emails sent when invoice status moves to canceled state.

contact required read-only

The base definition for a contact.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

contracts read-only

An array of linked contracts.

created read-only

The creation date of this invoice.

creditCardOnFile required nullable

The credit card on file for this invoice, if applicable.

creditCardTransactions read-only

An array of invoice credit card transactions, showing all attempts to charge a card for this invoice, including approved/declined attempts.

currencyCode read-only

Identifies the currency used for this invoice.

currencySymbol read-only

The currency symbol for the currency used for this invoice.

customInvoiceId read-only

A client-facing identifier for this invoice, starting at 1000 for each studio.

dueTotal read-only

The total amount of this invoice that is due.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

finalDueDate nullable read-only

The date on which this invoice must be paid in full.

grandTotal

The invoice grand total.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
invoiceStatus

The human-readable name of the current status of this invoice.

invoiceTemplateId nullable

The identifier for the invoice template from which this invoice was created.

isHidden

Whether or not the invoice should be hidden

issueDate

The date on which this invoice was issued.

items

An array of line items for this invoice.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

notesToClient

Notes to display on the invoice for the client.

paidTotal read-only

The total amount of this invoice that has been paid.

paymentConfirmationText

A message sent to the client upon receipt of payment.

payments read-only

An array of invoice payments, showing a history of all payments made on this invoice.

publicId read-only

The public identifier for this invoice (may be used in the portal website).

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerTotal read-only

The total amount for the invoice retainter.

salesTaxPercent nullable

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

salesTaxTotal

The total amount of sales tax on the invoice.

subtotal

The invoice subtotal.

taxableSubtotal

The taxable subtotal of the invoice, based on its taxable items.

type

The type of object represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "201": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Invoice"
        }
      }
    },
    "description": "The successfully-created invoice.",
    "headers": {
      "Location": {
        "description": "The URL to the newly-created invoice.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  }
}

Lists all invoice item templates for the current brand.

get
/studio/brand/{brandId}/invoice/item-template

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

Query Parameters

Property Description
page

The page of results to return.

rows

The number of rows to return on each page of results.

searchNameDescription

Search invoice item templates by the name and description fields.

sortBy

The property by which items returned should be sorted.

sortType

The direction in which sorting should occur.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

Invoice item templates list response.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
items

A collection of resources returned in the current result set.

Property Description
created read-only

The creation date of this invoice item template.

description

A description for this invoice item template.

id

The identifier for this invoice item template.

isTaxable

Whether this invoice item template is taxable.

itemPrice

The price for a single one of this invoice item template.

name

The name of this invoice item template.

quantity

The default quantity for this invoice item template.

totalPrice

The invoice item template price multiplied by the quantity.

type

The type of object represented.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

meta read-only

Metadata describing the current result set.

Property Description
currentPage

The current page of results returned.

rows

The number of rows returned per page for the current result set.

totalItems

The total number of items in the result set. This may be affected by active search/filter parameters.

totalPages

The total number of pages in the result set. This is affected by the rows parameter (totalItems / rows == totalPages).

type

The model type for the list response object.

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "allOf": [
            {
              "properties": {
                "items": {
                  "items": {
                    "$ref": "#/components/schemas/InvoiceItemTemplate"
                  },
                  "type": "array"
                },
                "type": {
                  "description": "The model type for the list response object.",
                  "enum": [
                    "invoice-item-template-collection"
                  ],
                  "type": "string"
                }
              }
            },
            {
              "$ref": "#/components/schemas/List"
            }
          ],
          "description": "A collection of invoice item templates"
        }
      }
    },
    "description": "Invoice item templates list response."
  }
}

Creates a new invoice item template for the current brand.

post
/studio/brand/{brandId}/invoice/item-template

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

The invoice item template object to create.

application/vnd.shootproof+json
Property Description
description

A description for this invoice item template.

id

The identifier for this invoice item template.

isTaxable

Whether this invoice item template is taxable.

itemPrice

The price for a single one of this invoice item template.

name

The name of this invoice item template.

quantity

The default quantity for this invoice item template.

totalPrice

The invoice item template price multiplied by the quantity.

type

The type of object represented.

OpenAPI Schema

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

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/InvoiceItemTemplate"
      }
    }
  },
  "description": "The invoice item template object to create.",
  "required": true
}

201 Created

The successfully-created invoice item template.

Headers
Header Description
Location

The URL to the newly-created invoice item template.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
created read-only

The creation date of this invoice item template.

description

A description for this invoice item template.

id

The identifier for this invoice item template.

isTaxable

Whether this invoice item template is taxable.

itemPrice

The price for a single one of this invoice item template.

name

The name of this invoice item template.

quantity

The default quantity for this invoice item template.

totalPrice

The invoice item template price multiplied by the quantity.

type

The type of object represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "201": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/InvoiceItemTemplate"
        }
      }
    },
    "description": "The successfully-created invoice item template.",
    "headers": {
      "Location": {
        "description": "The URL to the newly-created invoice item template.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  }
}

Removes an invoice item template.

delete
/studio/brand/{brandId}/invoice/item-template/{invoiceItemTemplateId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceItemTemplateId required

The invoice item template identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

204 No Content

Successful deletion response.

OpenAPI Schema

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

{
  "204": {
    "description": "Successful deletion response."
  }
}

Returns a single invoice item template by ID.

get
/studio/brand/{brandId}/invoice/item-template/{invoiceItemTemplateId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceItemTemplateId required

The invoice item template identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

An invoice item template.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
created read-only

The creation date of this invoice item template.

description

A description for this invoice item template.

id

The identifier for this invoice item template.

isTaxable

Whether this invoice item template is taxable.

itemPrice

The price for a single one of this invoice item template.

name

The name of this invoice item template.

quantity

The default quantity for this invoice item template.

totalPrice

The invoice item template price multiplied by the quantity.

type

The type of object represented.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/InvoiceItemTemplate"
        }
      }
    },
    "description": "An invoice item template."
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

Partially updates an invoice item template.

patch
/studio/brand/{brandId}/invoice/item-template/{invoiceItemTemplateId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceItemTemplateId required

The invoice item template identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

The invoice item template object to update. Only provide those properties that need updating.

application/vnd.shootproof+json
Property Description
description

A description for this invoice item template.

id

The identifier for this invoice item template.

isTaxable

Whether this invoice item template is taxable.

itemPrice

The price for a single one of this invoice item template.

name

The name of this invoice item template.

quantity

The default quantity for this invoice item template.

totalPrice

The invoice item template price multiplied by the quantity.

type

The type of object represented.

OpenAPI Schema

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

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/InvoiceItemTemplate"
      }
    }
  },
  "description": "The invoice item template object to update. Only provide those\nproperties that need updating.",
  "required": true
}

200 OK

The successfully-updated invoice item template.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
created read-only

The creation date of this invoice item template.

description

A description for this invoice item template.

id

The identifier for this invoice item template.

isTaxable

Whether this invoice item template is taxable.

itemPrice

The price for a single one of this invoice item template.

name

The name of this invoice item template.

quantity

The default quantity for this invoice item template.

totalPrice

The invoice item template price multiplied by the quantity.

type

The type of object represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/InvoiceItemTemplate"
        }
      }
    },
    "description": "The successfully-updated invoice item template."
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  }
}

Fully updates an invoice item template.

put
/studio/brand/{brandId}/invoice/item-template/{invoiceItemTemplateId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceItemTemplateId required

The invoice item template identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

The invoice item template object to update.

application/vnd.shootproof+json
Property Description
description

A description for this invoice item template.

id

The identifier for this invoice item template.

isTaxable

Whether this invoice item template is taxable.

itemPrice

The price for a single one of this invoice item template.

name

The name of this invoice item template.

quantity

The default quantity for this invoice item template.

totalPrice

The invoice item template price multiplied by the quantity.

type

The type of object represented.

OpenAPI Schema

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

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/InvoiceItemTemplate"
      }
    }
  },
  "description": "The invoice item template object to update.",
  "required": true
}

200 OK

The successfully-updated invoice item template.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
created read-only

The creation date of this invoice item template.

description

A description for this invoice item template.

id

The identifier for this invoice item template.

isTaxable

Whether this invoice item template is taxable.

itemPrice

The price for a single one of this invoice item template.

name

The name of this invoice item template.

quantity

The default quantity for this invoice item template.

totalPrice

The invoice item template price multiplied by the quantity.

type

The type of object represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/InvoiceItemTemplate"
        }
      }
    },
    "description": "The successfully-updated invoice item template."
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  }
}

Lists all invoice templates for the current brand.

Returns a list of all invoice templates for the current brand. Query string parameters may be used to affect the response, including pagination, sorting, and filtering of results.

get
/studio/brand/{brandId}/invoice/template

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

Query Parameters

Property Description
page

The page of results to return.

rows

The number of rows to return on each page of results.

searchInvoiceItem

The name or description of invoice items by which to filter results.

searchName

Invoice template name by which to filter results.

sortBy

The property by which items returned should be sorted.

sortType

The direction in which sorting should occur.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

Invoice templates list response.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
items

A collection of resources returned in the current result set.

Property Description
created

The creation date of this invoice template.

id

The identifier for this invoice template.

invoiceItemCount

The number of invoice items on this invoice template.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

name

The name of this invoice template.

type

The type of object represented.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

meta read-only

Metadata describing the current result set.

Property Description
currentPage

The current page of results returned.

rows

The number of rows returned per page for the current result set.

totalItems

The total number of items in the result set. This may be affected by active search/filter parameters.

totalPages

The total number of pages in the result set. This is affected by the rows parameter (totalItems / rows == totalPages).

type

The model type for the list response object.

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/List"
            },
            {
              "properties": {
                "items": {
                  "items": {
                    "description": "An invoice template as viewed from a collection.",
                    "properties": {
                      "created": {
                        "description": "The creation date of this invoice template.",
                        "format": "date-time",
                        "type": "string"
                      },
                      "id": {
                        "description": "The identifier for this invoice template.",
                        "type": "integer"
                      },
                      "invoiceItemCount": {
                        "description": "The number of invoice items on this invoice\ntemplate.",
                        "type": "integer"
                      },
                      "links": {
                        "$ref": "#/components/schemas/Links"
                      },
                      "name": {
                        "description": "The name of this invoice template.",
                        "type": "string"
                      },
                      "type": {
                        "description": "The type of object represented.",
                        "enum": [
                          "invoice-template"
                        ],
                        "type": "string"
                      }
                    },
                    "required": [
                      "type",
                      "links",
                      "id",
                      "name",
                      "invoiceItemCount",
                      "created"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                },
                "type": {
                  "description": "The model type for the list response object.",
                  "enum": [
                    "invoice-template-collection"
                  ],
                  "type": "string"
                }
              },
              "type": "object"
            }
          ],
          "description": "A collection of invoice templates."
        }
      }
    },
    "description": "Invoice templates list response."
  }
}

Creates a new invoice template for the current brand.

post
/studio/brand/{brandId}/invoice/template

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

The invoice template object to create.

application/vnd.shootproof+json
Property Description
acceptedPaymentTypes

An array of payment types this invoice template accepts.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice template uses.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice template uses.

grandTotal

The invoice template grand total.

id

The identifier for this invoice template

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
items

An array of line items for this invoice template.

languageCode

The Unicode CLDR language tag for the language used in this invoice template.

name

The name of this invoice template.

notesToClient

Notes to display on the invoice for the client.

paymentConfirmationText

A message sent to the client upon receipt of payment.

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

salesTaxPercent

A decimal number from 0-100, specifying the sales tax percentage. Required if salesTaxTitle has a non-zero length value.

salesTaxTitle

A label to apply to the sales tax percent on the invoice when viewed by the client. Required if salesTaxPercent has a non-zero length value.

salesTaxTotal

The total amount of sales tax on the invoice template.

subtotal

The invoice template subtotal.

taxableSubtotal

The taxable subtotal of the invoice template, based on its taxable items.

type

The type of object represented.

OpenAPI Schema

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

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/InvoiceTemplate"
      }
    }
  },
  "description": "The invoice template object to create.",
  "required": true
}

201 Created

The successfully-created invoice template.

Headers
Header Description
Location

The URL to the newly-created invoice template.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice template accepts.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice template uses.

created read-only

The creation date of this invoice.

currencyCode read-only

Identifies the currency represented in price.

currencySymbol read-only

The currency symbol for the currency used for this invoice template.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice template uses.

grandTotal

The invoice template grand total.

id

The identifier for this invoice template

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
items

An array of line items for this invoice template.

languageCode

The Unicode CLDR language tag for the language used in this invoice template.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

name

The name of this invoice template.

notesToClient

Notes to display on the invoice for the client.

paymentConfirmationText

A message sent to the client upon receipt of payment.

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

salesTaxPercent

A decimal number from 0-100, specifying the sales tax percentage. Required if salesTaxTitle has a non-zero length value.

salesTaxTitle

A label to apply to the sales tax percent on the invoice when viewed by the client. Required if salesTaxPercent has a non-zero length value.

salesTaxTotal

The total amount of sales tax on the invoice template.

subtotal

The invoice template subtotal.

taxableSubtotal

The taxable subtotal of the invoice template, based on its taxable items.

type

The type of object represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "201": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/InvoiceTemplate"
        }
      }
    },
    "description": "The successfully-created invoice template.",
    "headers": {
      "Location": {
        "description": "The URL to the newly-created invoice template.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  }
}

Removes an invoice template.

delete
/studio/brand/{brandId}/invoice/template/{invoiceTemplateId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceTemplateId required

The invoice template identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

204 No Content

Successful deletion response.

OpenAPI Schema

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

{
  "204": {
    "description": "Successful deletion response."
  }
}

Returns a single invoice template by ID.

get
/studio/brand/{brandId}/invoice/template/{invoiceTemplateId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceTemplateId required

The invoice template identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

An invoice template.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice template accepts.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice template uses.

created read-only

The creation date of this invoice.

currencyCode read-only

Identifies the currency represented in price.

currencySymbol read-only

The currency symbol for the currency used for this invoice template.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice template uses.

grandTotal

The invoice template grand total.

id

The identifier for this invoice template

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
items

An array of line items for this invoice template.

languageCode

The Unicode CLDR language tag for the language used in this invoice template.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

name

The name of this invoice template.

notesToClient

Notes to display on the invoice for the client.

paymentConfirmationText

A message sent to the client upon receipt of payment.

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

salesTaxPercent

A decimal number from 0-100, specifying the sales tax percentage. Required if salesTaxTitle has a non-zero length value.

salesTaxTitle

A label to apply to the sales tax percent on the invoice when viewed by the client. Required if salesTaxPercent has a non-zero length value.

salesTaxTotal

The total amount of sales tax on the invoice template.

subtotal

The invoice template subtotal.

taxableSubtotal

The taxable subtotal of the invoice template, based on its taxable items.

type

The type of object represented.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/InvoiceTemplate"
        }
      }
    },
    "description": "An invoice template."
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

Fully updates an invoice template.

put
/studio/brand/{brandId}/invoice/template/{invoiceTemplateId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceTemplateId required

The invoice template identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

The invoice template object to update.

application/vnd.shootproof+json
Property Description
acceptedPaymentTypes

An array of payment types this invoice template accepts.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice template uses.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice template uses.

grandTotal

The invoice template grand total.

id

The identifier for this invoice template

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
items

An array of line items for this invoice template.

languageCode

The Unicode CLDR language tag for the language used in this invoice template.

name

The name of this invoice template.

notesToClient

Notes to display on the invoice for the client.

paymentConfirmationText

A message sent to the client upon receipt of payment.

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

salesTaxPercent

A decimal number from 0-100, specifying the sales tax percentage. Required if salesTaxTitle has a non-zero length value.

salesTaxTitle

A label to apply to the sales tax percent on the invoice when viewed by the client. Required if salesTaxPercent has a non-zero length value.

salesTaxTotal

The total amount of sales tax on the invoice template.

subtotal

The invoice template subtotal.

taxableSubtotal

The taxable subtotal of the invoice template, based on its taxable items.

type

The type of object represented.

OpenAPI Schema

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

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/InvoiceTemplate"
      }
    }
  },
  "description": "The invoice template object to update.",
  "required": true
}

200 OK

The successfully-updated invoice template.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice template accepts.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice template uses.

created read-only

The creation date of this invoice.

currencyCode read-only

Identifies the currency represented in price.

currencySymbol read-only

The currency symbol for the currency used for this invoice template.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice template uses.

grandTotal

The invoice template grand total.

id

The identifier for this invoice template

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
items

An array of line items for this invoice template.

languageCode

The Unicode CLDR language tag for the language used in this invoice template.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

name

The name of this invoice template.

notesToClient

Notes to display on the invoice for the client.

paymentConfirmationText

A message sent to the client upon receipt of payment.

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

salesTaxPercent

A decimal number from 0-100, specifying the sales tax percentage. Required if salesTaxTitle has a non-zero length value.

salesTaxTitle

A label to apply to the sales tax percent on the invoice when viewed by the client. Required if salesTaxPercent has a non-zero length value.

salesTaxTotal

The total amount of sales tax on the invoice template.

subtotal

The invoice template subtotal.

taxableSubtotal

The taxable subtotal of the invoice template, based on its taxable items.

type

The type of object represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/InvoiceTemplate"
        }
      }
    },
    "description": "The successfully-updated invoice template."
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  }
}

Removes an invoice.

delete
/studio/brand/{brandId}/invoice/{invoiceId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceId required

An invoice identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

204 No Content

Successful deletion response.

OpenAPI Schema

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

{
  "204": {
    "description": "Successful deletion response."
  }
}

Returns a single invoice by ID.

get
/studio/brand/{brandId}/invoice/{invoiceId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceId required

An invoice identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

An invoice

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

activity read-only

A list of activities that have occurred with this invoice.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice uses.

cancelationMessage

Optional cancelation message to include in studio-to-client emails sent when invoice status moves to canceled state.

contact required read-only

The base definition for a contact.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

contracts read-only

An array of linked contracts.

created read-only

The creation date of this invoice.

creditCardOnFile required nullable

The credit card on file for this invoice, if applicable.

creditCardTransactions read-only

An array of invoice credit card transactions, showing all attempts to charge a card for this invoice, including approved/declined attempts.

currencyCode read-only

Identifies the currency used for this invoice.

currencySymbol read-only

The currency symbol for the currency used for this invoice.

customInvoiceId read-only

A client-facing identifier for this invoice, starting at 1000 for each studio.

dueTotal read-only

The total amount of this invoice that is due.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

finalDueDate nullable read-only

The date on which this invoice must be paid in full.

grandTotal

The invoice grand total.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
invoiceStatus

The human-readable name of the current status of this invoice.

invoiceTemplateId nullable

The identifier for the invoice template from which this invoice was created.

isHidden

Whether or not the invoice should be hidden

issueDate

The date on which this invoice was issued.

items

An array of line items for this invoice.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

notesToClient

Notes to display on the invoice for the client.

paidTotal read-only

The total amount of this invoice that has been paid.

paymentConfirmationText

A message sent to the client upon receipt of payment.

payments read-only

An array of invoice payments, showing a history of all payments made on this invoice.

publicId read-only

The public identifier for this invoice (may be used in the portal website).

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerTotal read-only

The total amount for the invoice retainter.

salesTaxPercent nullable

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

salesTaxTotal

The total amount of sales tax on the invoice.

subtotal

The invoice subtotal.

taxableSubtotal

The taxable subtotal of the invoice, based on its taxable items.

type

The type of object represented.

Error Response

API errors come in two kinds of varieties: 400s and 500s.

Any error with a status code of 400 to 499 is considered a client error. This means it’s usually an error you can handle in your app, and then resend a modified request to the ShootProof API to get a successful response.

An error in the range of 500 to 599, on the other hand, is a different story. These errors usually mean that a problem occured on the server and resending the request with modifications will not fix the issue.

Pay careful attention to the status codes. We try to stick as close as possible to their defined semantics. For a complete list of HTTP status codes, take a look at the official HTTP Status Code Registry.

Check out our errors guide for more information.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

Validation Error Example
{
  "detail": "There was a problem with your request. Please see `info` for more information.",
  "info": {
    "errors": {
      "type": {
        "isEmpty": "Value is required and can't be empty"
      }
    }
  },
  "status": 400,
  "title": "Bad Request",
  "type": "https://developer.shootproof.com/errors#error-bad-request"
}
Forbidden Error Example
{
  "detail": "You do not have permission to access the requested resource.",
  "status": 403,
  "title": "Forbidden",
  "type": "https://developer.shootproof.com/errors#error-forbidden"
}
Not Found Error Example
{
  "detail": "The requested resource could not be found.",
  "status": 404,
  "title": "Not Found",
  "type": "https://developer.shootproof.com/errors#error-not-found"
}
Server Error Example
{
  "detail": "An error occurred on the server. If this error continues to occur, please contact support.",
  "status": 500,
  "title": "Internal Server Error",
  "type": "https://developer.shootproof.com/errors#error-server-error"
}
Unauthorized Error Example
{
  "detail": "No authorization credentials provided. You must provide an authorization token for this request.",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://developer.shootproof.com/errors#error-unauthorized"
}

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Invoice"
        }
      }
    },
    "description": "An invoice"
  },
  "default": {
    "$ref": "#/components/responses/defaultError"
  }
}

Partially updates an invoice.

patch
/studio/brand/{brandId}/invoice/{invoiceId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceId required

An invoice identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

The invoice object to update. Only provide those properties that need updating.

application/vnd.shootproof+json
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

brandThemeId

The identifier for the brand theme this invoice uses.

contactId

The identifier for the contact associated with this invoice.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

invoiceStatus

The human-readable name of the current status of this invoice.

isHidden

Whether or not the invoice is hidden

issueDate

The date on which this invoice was issued.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

notesToClient

Notes to display on the invoice for the client.

paymentConfirmationText

A message sent to the client upon receipt of payment.

salesTaxPercent

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

OpenAPI Schema

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

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "description": "An invoice representation for partial updates.",
        "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"
          },
          "brandThemeId": {
            "description": "The identifier for the brand theme this invoice uses.",
            "type": "integer"
          },
          "contactId": {
            "description": "The identifier for the contact associated with this invoice.",
            "type": "integer"
          },
          "emailAutomationGroupId": {
            "description": "The identifier for the email automation group this invoice\nuses.",
            "nullable": true,
            "type": "integer"
          },
          "invoiceStatus": {
            "description": "The human-readable name of the current status of this invoice.",
            "enum": [
              "unpaid",
              "partially-paid",
              "paid-in-full",
              "canceled",
              "archived"
            ],
            "type": "string"
          },
          "isHidden": {
            "description": "Whether or not the invoice is hidden",
            "type": "boolean"
          },
          "issueDate": {
            "description": "The date on which this invoice was issued.",
            "format": "date-time",
            "type": "string"
          },
          "languageCode": {
            "description": "The Unicode CLDR language tag for the language used in this\ninvoice.",
            "type": "string"
          },
          "notesToClient": {
            "description": "Notes to display on the invoice for the client.",
            "type": "string"
          },
          "paymentConfirmationText": {
            "description": "A message sent to the client upon receipt of payment.",
            "type": "string"
          },
          "salesTaxPercent": {
            "description": "A decimal number from 0-100, specifying the sales tax\npercentage.",
            "maximum": 100,
            "minimum": 0,
            "type": "number"
          },
          "salesTaxTitle": {
            "description": "A label to apply to the sales tax percent on the invoice\nwhen viewed by the client.",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      }
    }
  },
  "description": "The invoice object to update. Only provide those properties that need\nupdating.",
  "required": true
}

200 OK

The successfully-updated invoice.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

activity read-only

A list of activities that have occurred with this invoice.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice uses.

cancelationMessage

Optional cancelation message to include in studio-to-client emails sent when invoice status moves to canceled state.

contact required read-only

The base definition for a contact.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

contracts read-only

An array of linked contracts.

created read-only

The creation date of this invoice.

creditCardOnFile required nullable

The credit card on file for this invoice, if applicable.

creditCardTransactions read-only

An array of invoice credit card transactions, showing all attempts to charge a card for this invoice, including approved/declined attempts.

currencyCode read-only

Identifies the currency used for this invoice.

currencySymbol read-only

The currency symbol for the currency used for this invoice.

customInvoiceId read-only

A client-facing identifier for this invoice, starting at 1000 for each studio.

dueTotal read-only

The total amount of this invoice that is due.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

finalDueDate nullable read-only

The date on which this invoice must be paid in full.

grandTotal

The invoice grand total.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
invoiceStatus

The human-readable name of the current status of this invoice.

invoiceTemplateId nullable

The identifier for the invoice template from which this invoice was created.

isHidden

Whether or not the invoice should be hidden

issueDate

The date on which this invoice was issued.

items

An array of line items for this invoice.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

notesToClient

Notes to display on the invoice for the client.

paidTotal read-only

The total amount of this invoice that has been paid.

paymentConfirmationText

A message sent to the client upon receipt of payment.

payments read-only

An array of invoice payments, showing a history of all payments made on this invoice.

publicId read-only

The public identifier for this invoice (may be used in the portal website).

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerTotal read-only

The total amount for the invoice retainter.

salesTaxPercent nullable

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

salesTaxTotal

The total amount of sales tax on the invoice.

subtotal

The invoice subtotal.

taxableSubtotal

The taxable subtotal of the invoice, based on its taxable items.

type

The type of object represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Invoice"
        }
      }
    },
    "description": "The successfully-updated invoice."
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  }
}

Fully updates an invoice.

put
/studio/brand/{brandId}/invoice/{invoiceId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceId required

An invoice identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

The invoice object to update.

application/vnd.shootproof+json
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice uses.

cancelationMessage

Optional cancelation message to include in studio-to-client emails sent when invoice status moves to canceled state.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

creditCardOnFile required nullable

The credit card on file for this invoice, if applicable.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

grandTotal

The invoice grand total.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
invoiceStatus

The human-readable name of the current status of this invoice.

invoiceTemplateId nullable

The identifier for the invoice template from which this invoice was created.

isHidden

Whether or not the invoice should be hidden

issueDate

The date on which this invoice was issued.

items

An array of line items for this invoice.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

notesToClient

Notes to display on the invoice for the client.

paymentConfirmationText

A message sent to the client upon receipt of payment.

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

salesTaxPercent nullable

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

salesTaxTotal

The total amount of sales tax on the invoice.

subtotal

The invoice subtotal.

taxableSubtotal

The taxable subtotal of the invoice, based on its taxable items.

type

The type of object represented.

OpenAPI Schema

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

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/Invoice"
      }
    }
  },
  "description": "The invoice object to update.",
  "required": true
}

200 OK

The successfully-updated invoice.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

activity read-only

A list of activities that have occurred with this invoice.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice uses.

cancelationMessage

Optional cancelation message to include in studio-to-client emails sent when invoice status moves to canceled state.

contact required read-only

The base definition for a contact.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

contracts read-only

An array of linked contracts.

created read-only

The creation date of this invoice.

creditCardOnFile required nullable

The credit card on file for this invoice, if applicable.

creditCardTransactions read-only

An array of invoice credit card transactions, showing all attempts to charge a card for this invoice, including approved/declined attempts.

currencyCode read-only

Identifies the currency used for this invoice.

currencySymbol read-only

The currency symbol for the currency used for this invoice.

customInvoiceId read-only

A client-facing identifier for this invoice, starting at 1000 for each studio.

dueTotal read-only

The total amount of this invoice that is due.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

finalDueDate nullable read-only

The date on which this invoice must be paid in full.

grandTotal

The invoice grand total.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
invoiceStatus

The human-readable name of the current status of this invoice.

invoiceTemplateId nullable

The identifier for the invoice template from which this invoice was created.

isHidden

Whether or not the invoice should be hidden

issueDate

The date on which this invoice was issued.

items

An array of line items for this invoice.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

notesToClient

Notes to display on the invoice for the client.

paidTotal read-only

The total amount of this invoice that has been paid.

paymentConfirmationText

A message sent to the client upon receipt of payment.

payments read-only

An array of invoice payments, showing a history of all payments made on this invoice.

publicId read-only

The public identifier for this invoice (may be used in the portal website).

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerTotal read-only

The total amount for the invoice retainter.

salesTaxPercent nullable

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

salesTaxTotal

The total amount of sales tax on the invoice.

subtotal

The invoice subtotal.

taxableSubtotal

The taxable subtotal of the invoice, based on its taxable items.

type

The type of object represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Invoice"
        }
      }
    },
    "description": "The successfully-updated invoice."
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  }
}

Deletes a linked contract from a invoice.

Removes the linked contract from the invoice.

delete
/studio/brand/{brandId}/invoice/{invoiceId}/contract/{contractId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

contractId required

A contract identifier.

invoiceId required

An invoice identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

Responds with the invoice on success.

Headers
Header Description
Content-Location

The URL of the invoice in the response body.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

activity read-only

A list of activities that have occurred with this invoice.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice uses.

cancelationMessage

Optional cancelation message to include in studio-to-client emails sent when invoice status moves to canceled state.

contact required read-only

The base definition for a contact.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

contracts read-only

An array of linked contracts.

created read-only

The creation date of this invoice.

creditCardOnFile required nullable

The credit card on file for this invoice, if applicable.

creditCardTransactions read-only

An array of invoice credit card transactions, showing all attempts to charge a card for this invoice, including approved/declined attempts.

currencyCode read-only

Identifies the currency used for this invoice.

currencySymbol read-only

The currency symbol for the currency used for this invoice.

customInvoiceId read-only

A client-facing identifier for this invoice, starting at 1000 for each studio.

dueTotal read-only

The total amount of this invoice that is due.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

finalDueDate nullable read-only

The date on which this invoice must be paid in full.

grandTotal

The invoice grand total.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
invoiceStatus

The human-readable name of the current status of this invoice.

invoiceTemplateId nullable

The identifier for the invoice template from which this invoice was created.

isHidden

Whether or not the invoice should be hidden

issueDate

The date on which this invoice was issued.

items

An array of line items for this invoice.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

notesToClient

Notes to display on the invoice for the client.

paidTotal read-only

The total amount of this invoice that has been paid.

paymentConfirmationText

A message sent to the client upon receipt of payment.

payments read-only

An array of invoice payments, showing a history of all payments made on this invoice.

publicId read-only

The public identifier for this invoice (may be used in the portal website).

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerTotal read-only

The total amount for the invoice retainter.

salesTaxPercent nullable

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

salesTaxTotal

The total amount of sales tax on the invoice.

subtotal

The invoice subtotal.

taxableSubtotal

The taxable subtotal of the invoice, based on its taxable items.

type

The type of object represented.

404 Not Found

The requested resource could not be found.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Invoice"
        }
      }
    },
    "description": "Responds with the invoice on success.",
    "headers": {
      "Content-Location": {
        "description": "The URL of the invoice in the response body.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "404": {
    "$ref": "#/components/responses/notFoundError"
  }
}

Adds a linked contract to an invoice.

Links the given contract to the invoice.

put
/studio/brand/{brandId}/invoice/{invoiceId}/contract/{contractId}

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

contractId required

A contract identifier.

invoiceId required

An invoice identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

200 OK

Responds with the invoice on success.

Headers
Header Description
Content-Location

The URL of the invoice in the response body.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

activity read-only

A list of activities that have occurred with this invoice.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice uses.

cancelationMessage

Optional cancelation message to include in studio-to-client emails sent when invoice status moves to canceled state.

contact required read-only

The base definition for a contact.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

contracts read-only

An array of linked contracts.

created read-only

The creation date of this invoice.

creditCardOnFile required nullable

The credit card on file for this invoice, if applicable.

creditCardTransactions read-only

An array of invoice credit card transactions, showing all attempts to charge a card for this invoice, including approved/declined attempts.

currencyCode read-only

Identifies the currency used for this invoice.

currencySymbol read-only

The currency symbol for the currency used for this invoice.

customInvoiceId read-only

A client-facing identifier for this invoice, starting at 1000 for each studio.

dueTotal read-only

The total amount of this invoice that is due.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

finalDueDate nullable read-only

The date on which this invoice must be paid in full.

grandTotal

The invoice grand total.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
invoiceStatus

The human-readable name of the current status of this invoice.

invoiceTemplateId nullable

The identifier for the invoice template from which this invoice was created.

isHidden

Whether or not the invoice should be hidden

issueDate

The date on which this invoice was issued.

items

An array of line items for this invoice.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

notesToClient

Notes to display on the invoice for the client.

paidTotal read-only

The total amount of this invoice that has been paid.

paymentConfirmationText

A message sent to the client upon receipt of payment.

payments read-only

An array of invoice payments, showing a history of all payments made on this invoice.

publicId read-only

The public identifier for this invoice (may be used in the portal website).

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerTotal read-only

The total amount for the invoice retainter.

salesTaxPercent nullable

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

salesTaxTotal

The total amount of sales tax on the invoice.

subtotal

The invoice subtotal.

taxableSubtotal

The taxable subtotal of the invoice, based on its taxable items.

type

The type of object represented.

404 Not Found

The requested resource could not be found.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

409 Conflict

If the invoice is linked to a different contract, then we respond with a 409 Conflict response.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "200": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Invoice"
        }
      }
    },
    "description": "Responds with the invoice on success.",
    "headers": {
      "Content-Location": {
        "description": "The URL of the invoice in the response body.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "404": {
    "$ref": "#/components/responses/notFoundError"
  },
  "409": {
    "content": {
      "application/problem+json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    },
    "description": "If the invoice is linked to a different contract, then we respond\nwith a `409 Conflict` response."
  }
}

Sends an email message to the contact for an invoice.

post
/studio/brand/{brandId}/invoice/{invoiceId}/email

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceId required

An invoice identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

The invoice email object used to send an email message.

application/vnd.shootproof+json
Property Description
body

The message to include in the body of the email.

buttonText

The text for the call-to-action button in the email body.

emailTemplateId

The identifier for the email template chosen (if applicable).

headline

The headline to use in the email body.

recipientEmails

Email address(es) to send the email to. If provided, must be an array of valid email addresses. Optional, but may be required by child schemas.

subject

The subject line for the email message.

type

The type of resource represented.

OpenAPI Schema

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

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/InvoiceEmail"
      }
    }
  },
  "description": "The invoice email object used to send an email message.",
  "required": true
}

202 Accepted

Responds with the invoice on success.

Headers
Header Description
Content-Location

The URL of the invoice in the response body.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

activity read-only

A list of activities that have occurred with this invoice.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice uses.

cancelationMessage

Optional cancelation message to include in studio-to-client emails sent when invoice status moves to canceled state.

contact required read-only

The base definition for a contact.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

contracts read-only

An array of linked contracts.

created read-only

The creation date of this invoice.

creditCardOnFile required nullable

The credit card on file for this invoice, if applicable.

creditCardTransactions read-only

An array of invoice credit card transactions, showing all attempts to charge a card for this invoice, including approved/declined attempts.

currencyCode read-only

Identifies the currency used for this invoice.

currencySymbol read-only

The currency symbol for the currency used for this invoice.

customInvoiceId read-only

A client-facing identifier for this invoice, starting at 1000 for each studio.

dueTotal read-only

The total amount of this invoice that is due.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

finalDueDate nullable read-only

The date on which this invoice must be paid in full.

grandTotal

The invoice grand total.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
invoiceStatus

The human-readable name of the current status of this invoice.

invoiceTemplateId nullable

The identifier for the invoice template from which this invoice was created.

isHidden

Whether or not the invoice should be hidden

issueDate

The date on which this invoice was issued.

items

An array of line items for this invoice.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

notesToClient

Notes to display on the invoice for the client.

paidTotal read-only

The total amount of this invoice that has been paid.

paymentConfirmationText

A message sent to the client upon receipt of payment.

payments read-only

An array of invoice payments, showing a history of all payments made on this invoice.

publicId read-only

The public identifier for this invoice (may be used in the portal website).

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerTotal read-only

The total amount for the invoice retainter.

salesTaxPercent nullable

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

salesTaxTotal

The total amount of sales tax on the invoice.

subtotal

The invoice subtotal.

taxableSubtotal

The taxable subtotal of the invoice, based on its taxable items.

type

The type of object represented.

400 Bad Request

Validation error response. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "202": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Invoice"
        }
      }
    },
    "description": "Responds with the invoice on success.",
    "headers": {
      "Content-Location": {
        "description": "The URL of the invoice in the response body.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/validationError"
  }
}

Creates a payment for an invoice.

post
/studio/brand/{brandId}/invoice/{invoiceId}/payment

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceId required

An invoice identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

The invoice payment object to create.

application/vnd.shootproof+json
Property Description
amount

The amount of this payment.

amountLessRefunds nullable

The total amount of this payment, minus any refunds applied to it. This is null if the payment is a refund.

billingPostalCode

The billing address postal code. May be null for invoice payments made prior to the introduction of this value.

checkNumber nullable

If this payment was made by check, the check number for the payment.

creditCard

When creating a new invoice payment, include the credit card property with this object, if paying by credit card. If you wish to use the invoice credit card that is already on file, set this property to boolean true.

This property is null in responses.

emailAddress

The email address for the person making the payment.

id

The identifier for this invoice payment.

nameOnCard

The card-holder name.

note nullable

A note about the payment.

paymentDate

The date on which this payment was made.

paymentFundsType

The type of funds received for this payment.

type

The type of object represented.

OpenAPI Schema

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

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/InvoicePayment"
      }
    }
  },
  "description": "The invoice payment object to create.",
  "required": true
}

202 Accepted

Responds with the invoice on success.

Headers
Header Description
Content-Location

The URL of the invoice in the response body.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

activity read-only

A list of activities that have occurred with this invoice.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice uses.

cancelationMessage

Optional cancelation message to include in studio-to-client emails sent when invoice status moves to canceled state.

contact required read-only

The base definition for a contact.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

contracts read-only

An array of linked contracts.

created read-only

The creation date of this invoice.

creditCardOnFile required nullable

The credit card on file for this invoice, if applicable.

creditCardTransactions read-only

An array of invoice credit card transactions, showing all attempts to charge a card for this invoice, including approved/declined attempts.

currencyCode read-only

Identifies the currency used for this invoice.

currencySymbol read-only

The currency symbol for the currency used for this invoice.

customInvoiceId read-only

A client-facing identifier for this invoice, starting at 1000 for each studio.

dueTotal read-only

The total amount of this invoice that is due.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

finalDueDate nullable read-only

The date on which this invoice must be paid in full.

grandTotal

The invoice grand total.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
invoiceStatus

The human-readable name of the current status of this invoice.

invoiceTemplateId nullable

The identifier for the invoice template from which this invoice was created.

isHidden

Whether or not the invoice should be hidden

issueDate

The date on which this invoice was issued.

items

An array of line items for this invoice.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

notesToClient

Notes to display on the invoice for the client.

paidTotal read-only

The total amount of this invoice that has been paid.

paymentConfirmationText

A message sent to the client upon receipt of payment.

payments read-only

An array of invoice payments, showing a history of all payments made on this invoice.

publicId read-only

The public identifier for this invoice (may be used in the portal website).

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerTotal read-only

The total amount for the invoice retainter.

salesTaxPercent nullable

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

salesTaxTotal

The total amount of sales tax on the invoice.

subtotal

The invoice subtotal.

taxableSubtotal

The taxable subtotal of the invoice, based on its taxable items.

type

The type of object represented.

400 Bad Request

Validation error response; includes special handling for credit card transaction errors. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
transactionErrors

If the error response includes credit card transaction errors that cannot be related back to a value on the request, this info.transactionErrors object is included. The response will be a 400 Bad Request response and contain this info.transactionErrors property.

Each property name in the transactionErrors object is a key that identifies a unique transaction error type. The value is a human-readable string in English language only, which could be displayed in a client if necessary. Otherwise, it is recommended that the client switch on the transactionErrors key names to display a translated error message in the end user's preferred language describing the error that occurred.

Possible info.transactionErrors keys:

  • noResponseReceived: No response received from payment gateway.
  • declined: Transaction was declined.
  • gatewayRejected: The payment gateway rejected transaction.
  • unexpected: An unexpected error occurred; value will be raw error message directly from the payment gateway.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

402 Payment Required

If using creditCard with a boolean value true and there is no invoice credit card on file, then we respond with a 402 Payment Required response.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

409 Conflict

If the payment gateway has not been configured, then we respond with a 409 Conflict response.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "202": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Invoice"
        }
      }
    },
    "description": "Responds with the invoice on success.",
    "headers": {
      "Content-Location": {
        "description": "The URL of the invoice in the response body.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/transactionError"
  },
  "402": {
    "content": {
      "application/problem+json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    },
    "description": "If using `creditCard` with a boolean value `true` and there is no\ninvoice credit card on file, then we respond with a `402 Payment\nRequired` response."
  },
  "409": {
    "content": {
      "application/problem+json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    },
    "description": "If the payment gateway has not been configured, then we respond\nwith a `409 Conflict` response."
  }
}

Creates a refund for an invoice.

post
/studio/brand/{brandId}/invoice/{invoiceId}/refund

Example Request

Path Parameters

Property Description
brandId required

The brand identifier.

invoiceId required

An invoice identifier.

Header Parameters

Property Description
Authentication required

The bearer token used to make authenticated requests to the ShootProof Studio API. See the authorization guide for more information on how to obtain and use bearer tokens.

Request Body

The invoice refund object to create.

application/vnd.shootproof+json
Property Description
amount

The amount of the payment to refund.

emailAdditionalMessage nullable

Optional message to include in email sent to client and payer. May include HTML tags, but only whitelisted tags will be included.

invoicePaymentId

The identifier for the invoice payment to refund.

note nullable

A note about the refund.

refundDate

The date on which this refund was made.

type

The type of object represented.

OpenAPI Schema

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

{
  "content": {
    "application/vnd.shootproof+json": {
      "schema": {
        "$ref": "#/components/schemas/InvoiceRefund"
      }
    }
  },
  "description": "The invoice refund object to create.",
  "required": true
}

202 Accepted

Responds with the invoice on success.

Headers
Header Description
Content-Location

The URL of the invoice in the response body.

Response Body

When the Content-Type of the response is application/vnd.shootproof+json, the following properties will be available in the response body.

Properties
Property Description
acceptedPaymentTypes

An array of payment types this invoice accepts.

activity read-only

A list of activities that have occurred with this invoice.

brandTheme

A brand theme.

brandThemeId

The identifier for the brand theme this invoice uses.

cancelationMessage

Optional cancelation message to include in studio-to-client emails sent when invoice status moves to canceled state.

contact required read-only

The base definition for a contact.

contactId

An entity identifier. It may be either an integer or a universally unique identifier (UUID) represented as a string.

contracts read-only

An array of linked contracts.

created read-only

The creation date of this invoice.

creditCardOnFile required nullable

The credit card on file for this invoice, if applicable.

creditCardTransactions read-only

An array of invoice credit card transactions, showing all attempts to charge a card for this invoice, including approved/declined attempts.

currencyCode read-only

Identifies the currency used for this invoice.

currencySymbol read-only

The currency symbol for the currency used for this invoice.

customInvoiceId read-only

A client-facing identifier for this invoice, starting at 1000 for each studio.

dueTotal read-only

The total amount of this invoice that is due.

emailAutomationGroupId nullable

The identifier for the email automation group this invoice uses.

finalDueDate nullable read-only

The date on which this invoice must be paid in full.

grandTotal

The invoice grand total.

id

The identifier for this invoice.

installments

An array of invoice installments, defining the installment schedule for this invoice.

invoiceRetainerLabel nullable

This label represents how the studio wishes to refer to the initial payment represented by retainerPercent or retainerFixedAmount for this invoice. This property is required if retainerPercent or retainerFixedAmount contain non-null values.

The following labels are available. You are responsible for displaying appropriate human-readable strings for these labels, translated for your audience.

ShootProof Identifier Description
non-refundable-payment The initial payment should be referred to as a "non-refundable payment" when displaying the invoice to the studio's customer.
deposit The initial payment should be referred to as a "deposit" when displaying the invoice to the studio's customer.
retainer The initial payment should be referred to as a "retainer" when displaying the invoice to the studio's customer.
invoiceStatus

The human-readable name of the current status of this invoice.

invoiceTemplateId nullable

The identifier for the invoice template from which this invoice was created.

isHidden

Whether or not the invoice should be hidden

issueDate

The date on which this invoice was issued.

items

An array of line items for this invoice.

languageCode

The Unicode CLDR language tag for the language used in this invoice.

links required read-only

Each property defines a hypertext link relationship as indicated by a link object or array of link objects. The target URL of each hypertext link relationship is related to the current resource according to the defined semantics of the link relationship property name.

notesToClient

Notes to display on the invoice for the client.

paidTotal read-only

The total amount of this invoice that has been paid.

paymentConfirmationText

A message sent to the client upon receipt of payment.

payments read-only

An array of invoice payments, showing a history of all payments made on this invoice.

publicId read-only

The public identifier for this invoice (may be used in the portal website).

retainerFixedAmount nullable

Suggested fixed amount of retainer. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerPercent nullable

Suggested amount of retainer in a percentage from 1-100. If a retainer is defined, one of retainerPercent or retainerFixedAmount will be non-null.

retainerTotal read-only

The total amount for the invoice retainter.

salesTaxPercent nullable

A decimal number from 0-100, specifying the sales tax percentage.

salesTaxTitle nullable

A label to apply to the sales tax percent on the invoice when viewed by the client.

salesTaxTotal

The total amount of sales tax on the invoice.

subtotal

The invoice subtotal.

taxableSubtotal

The taxable subtotal of the invoice, based on its taxable items.

type

The type of object represented.

400 Bad Request

Validation error response; includes special handling for credit card transaction errors. Check the info.errors property in the response for more details.

Response Body

When the Content-Type of the response is application/problem+json, the following properties will be available in the response body.

Properties
Property Description
detail

A longer description of of the error encountered.

info

Additional information that may be provided to aid in error resolution.

Property Description
errors

If the error response is a result of validation errors, it will most likely be a 400 Bad Request response and contain this info.errors property. Each property name in the errors object is a property that failed validation. These properties contain objects with property names in the form of internal validation error message slugs paired with human-readable string values describing the validation failure. Each property may have multiple validation failure messages.

reason

An optional reason for the error response.

In some cases, more information is required to convey information about the error to the client. In these cases, one of the following reason slugs may be used.

Reason Slug Description
contract-not-ready-to-countersign The contract is in a state that does not allow countersigning. Its status must be ready-to-countersign to perform this action.
event-photo-count-limit The event has reached the maximum number of photos allowed.
plan-does-not-allow-uploads The studio is in a plan that does not allow uploads or they have reached the limit of photos the plan allows.
transactionErrors

If the error response includes credit card transaction errors that cannot be related back to a value on the request, this info.transactionErrors object is included. The response will be a 400 Bad Request response and contain this info.transactionErrors property.

Each property name in the transactionErrors object is a key that identifies a unique transaction error type. The value is a human-readable string in English language only, which could be displayed in a client if necessary. Otherwise, it is recommended that the client switch on the transactionErrors key names to display a translated error message in the end user's preferred language describing the error that occurred.

Possible info.transactionErrors keys:

  • noResponseReceived: No response received from payment gateway.
  • declined: Transaction was declined.
  • gatewayRejected: The payment gateway rejected transaction.
  • unexpected: An unexpected error occurred; value will be raw error message directly from the payment gateway.
status

The HTTP status code associated with this error.

title

A short description of the error encountered.

type

A namespace URI uniquely identifying the error type.

OpenAPI Schema

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

{
  "202": {
    "content": {
      "application/vnd.shootproof+json": {
        "schema": {
          "$ref": "#/components/schemas/Invoice"
        }
      }
    },
    "description": "Responds with the invoice on success.",
    "headers": {
      "Content-Location": {
        "description": "The URL of the invoice in the response body.",
        "schema": {
          "format": "uri",
          "type": "string"
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/transactionError"
  }
}