GraphQL API reference: Custom Fields

The GraphQL operations of SI Custom Fields (Fields, Waiver & ID). They use the same address, keys and rules as all our apps: see GraphQL API reference: Rentals & Bookings for how to send a request, and the API overview for keys, limits and errors. The same operations are in REST: REST API reference: Custom Fields.

Needs the Custom Fields app (Fields, Waiver & ID). It works on a store without Rentals & Bookings. Make the key on its API access page; a key made in any of our apps works too, because keys belong to the store. On a store without the app, its operations are refused before anything runs, with errors[].extensions.code: "app_not_installed" and data.app: "fields". Every operation needs a secret key; mutations need Allow changes (write).

ID verification is a status only (NONE, PENDING, VERIFIED, REJECTED or EXPIRED, with the document’s printed expiry date): the API never returns an ID document, an image, a file link or a document id.

Operations #

Operation	Arguments	What it does
rentalOrderFields query · secret key returns RentalOrderFields!	orderId: ID! refresh: Boolean = false	An order’s answers (per line and for the whole cart), the fees they added, the damage waiver line and the ID check’s status. recorded: false when the app has nothing for the order.
rentalFieldGroups query · secret key returns [RentalFieldGroup!]!	–	The field groups and their questions, in the order the storefront shows them.
rentalFieldGroup query · secret key returns RentalFieldGroup	id: ID!	One field group, or null.
rentalCustomerIdVerification query · secret key returns RentalIdVerification!	customerId: ID!	A customer’s ID verification status. Never a document, an image or a file.
rentalFieldsDefinitionsExport query · secret key returns RentalFieldsFile!	input: RentalFieldsDefinitionsExportInput!	The question definitions as a file: JSON (lossless, to copy to another store or keep as a backup) or CSV (to edit in a spreadsheet).
createRentalFieldsImport mutation · secret key returns RentalFieldsImportPayload!	input: RentalFieldsImportCreateInput!	Upload a definitions file (JSON or CSV, at most 5 MB). It is checked in the background: read it with rentalFieldsImport until its status is PREVIEW or FAILED.
rentalFieldsImport query · secret key returns RentalFieldsImport	id: ID!	One import: its checked plan, errors and warnings, or its result.
rentalFieldsImports query · secret key returns [RentalFieldsImport!]!	first: Int = 20	The latest imports, newest first.
recheckRentalFieldsImport mutation · secret key returns RentalFieldsImportPayload!	id: ID!	Check an import again (after STALE: the field groups changed since the check).
applyRentalFieldsImport mutation · secret key returns RentalFieldsImportPayload!	id: ID! planHash: String!	Apply the plan the preview showed (planHash must be that preview’s). All or nothing, in the background: read the import until APPLIED, FAILED or STALE.
cancelRentalFieldsImport mutation · secret key returns RentalFieldsImportPayload!	id: ID!	Drop an import that wasn’t applied.
createRentalFieldsAnswersExport mutation · secret key returns RentalFieldsAnswersExportPayload!	input: RentalFieldsAnswersExportInput!	Make a CSV of the answers customers gave on orders in a date range (confirm: true: it holds personal data). Read it with rentalFieldsAnswersExport until READY.
rentalFieldsAnswersExport query · secret key returns RentalFieldsAnswersExport	id: ID!	One answers export; while READY, a fresh 15-minute downloadUrl on every read.
rentalFieldsAnswersExports query · secret key returns [RentalFieldsAnswersExport!]!	first: Int = 20	The latest answers exports, newest first.
updateRentalFieldsOptionsSettings mutation · secret key returns RentalFieldsOptionsSettingsPayload!	input: RentalFieldsOptionsSettingsInput!	Whether priced options on products that aren’t rentals are taxed.

query OrderAnswers {
  rentalOrderFields(orderId: "5550001") {
    recorded name
    lines { title answers { label value } fees { label amount } }
    cartAnswers
    waiver { state amount label }
    idVerification { mode status expiresAt }
  }
  rentalCustomerIdVerification(customerId: "555001") { status expiresAt }
}

Imports and answer exports run in the background: create one, then read it until its status settles. A preview expires after 24 hours; an answers file is deleted 24 hours after it is ready.

RentalFieldsDefinitionsExportInput

Field	Type	Notes
format	RentalFieldsDefinitionsFormat!
groupIds	[ID!]	Only these field groups (their numeric ids); all when left out.
includeSettings	Boolean = false	Also the damage waiver, ID check, priced-option and message settings (JSON only; never the ID staff email).

RentalFieldsImportCreateInput

Field	Type	Notes
filename	String!
content	String!	The file’s text (UTF-8, at most 5 MB).
format	RentalFieldsImportFormat = AUTO
conflict	RentalFieldsImportConflict = SKIP
importDisabled	Boolean	Turn imported groups off so they can be checked first. Left out: on for a file from another store, off for this store’s.
includeSettings	Boolean = false	Also import the waiver, ID, priced-option and message settings of a JSON file (never an ID staff email).
kind	RentalFieldsImportKind = DEFINITIONS
mapping	RentalFieldsColumnMappingInput	Format MAPPED: which of the file’s columns (header names) holds what.

RentalFieldsColumnMappingInput – Which column of a spreadsheet holds what (header names of the file). Only question is required.

Field	Type	Notes
sourceName	String!	A name for this kind of file; the mapping is remembered under it.
question	String!
group	String
type	String
option	String
price	String
required	String
help	String
placeholder	String

RentalFieldsAnswersExportInput

Field	Type	Notes
from	String!	First day (YYYY-MM-DD, the store’s time zone).
to	String!	Last day (YYYY-MM-DD); at most 366 days after from.
layout	RentalFieldsAnswersLayout = WIDE
groupKeys	[String!]	Only the questions of these field groups (their keys); every answer when left out.
includeCartAnswers	Boolean = true	Also the cart page questions (one row per order in the wide layout).
includeCustomerId	Boolean = false
confirm	Boolean!	Must be true: the file holds what customers typed.

RentalFieldsOptionsSettingsInput

Field	Type	Notes
taxable	Boolean!	Charge tax on priced options of products that aren’t rentals.

Enum	Values
RentalFieldsDefinitionsFormat	JSON CSV
RentalFieldsImportFormat	AUTO – By the file name and its first character. JSON CSV EASIFY – An Easify Product Options CSV (its option import / export). Groups arrive turned off and shown nowhere. MAPPED – Any spreadsheet (CSV), read through mapping. Groups arrive turned off and shown nowhere.
RentalFieldsImportConflict	SKIP – Keep the store’s group. REPLACE – Replace the store’s group and its whole question list. COPY – Import a copy with new keys (key_2, …; question keys renamed and the rules that name them rewritten).
RentalFieldsImportKind	DEFINITIONS – Field groups (create, replace, skip or copy). UPDATE – Only the labels and prices of the store’s questions and options change (a JSON or CSV file of this app).
RentalFieldsAnswersLayout	WIDE – One row per order line with answers (and one row per order for the cart questions), a column per question. LONG – One row per answer.

Type	Fields
RentalOrderFields What the Fields, Waiver & ID app recorded for an order.	orderId: ID!, recorded: Boolean!, name: String, lines: [RentalFieldsLine!]!, cartAnswers: JSON, waiver: RentalDamageWaiver, idVerification: RentalIdVerification, feesTotal: String!, currency: String, syncedAt: String
RentalFieldsLine	kind: String, title: String!, variantTitle: String, quantity: Int, answers: [RentalFieldAnswer!]!, fees: [RentalFieldFee!]!
RentalFieldAnswer	label: String!, value: JSON
RentalFieldFee	label: String!, amount: String!
RentalDamageWaiver	state: String!, amount: String!, label: String
RentalIdVerification An ID verification STATUS. Never a document, an image or a file.	customerId: ID, mode: String!, status: RentalIdStatus!, expiresAt: String
RentalFieldGroup A group of custom fields shown on products (and at checkout).	id: ID!, legacyResourceId: Int!, key: String, name: String!, description: String, enabled: Boolean!, placement: String, scope: String, collections: [String!]!, products: [String!]!, tags: [String!], productTypes: [String!], checkoutCheck: String, position: Int!, fields: [RentalFieldDefinition!]!
RentalFieldDefinition One custom field.	id: ID!, key: String!, type: String!, label: String!, help: String, placeholder: String, required: Boolean!, options: JSON, price: String, priceType: String, chargePer: String, conditions: JSON, min: Float, max: Float, maxlength: Int, audience: String, definition: JSON!
RentalFieldsFile A file, as text.	filename: String!, contentType: String!, byteSize: Int!, content: String!
RentalFieldsImportPayload	import: RentalFieldsImport, userErrors: [RentalUserError!]!
RentalFieldsImport	id: ID!, status: RentalFieldsImportStatus!, format: RentalFieldsImportFormat!, kind: RentalFieldsImportKind!, origin: RentalFieldsImportOrigin!, sourceName: String, filename: String!, byteSize: Int!, conflict: RentalFieldsImportConflict!, importDisabled: Boolean, includeSettings: Boolean!, sourceShop: String, sourcePlatform: String, sourceVersion: Int, planHash: String, counts: RentalFieldsImportCounts, plan: [RentalFieldsImportGroupPlan!]!, settings: [String!]!, messages: [RentalFieldsImportMessage!]!, createdAt: String!, createdBy: String, appliedAt: String, expiresAt: String
RentalFieldsImportCounts	groups: Int!, fields: Int!, create: Int!, replace: Int!, skip: Int!, copy: Int!, update: Int, changes: Int, errors: Int!, warnings: Int!
RentalFieldsImportGroupPlan	key: String!, name: String!, action: RentalFieldsImportAction!, newKey: String, fields: Int!, options: Int!, enabled: Boolean!, unmatched: [RentalFieldsUnmatchedRef!]!, messages: [RentalFieldsImportMessage!]!, changes: [RentalFieldsImportChange!]!
RentalFieldsUnmatchedRef A product or collection of the file that this store doesn’t have.	kind: String!, handle: String, title: String
RentalFieldsImportMessage	severity: RentalFieldsMessageSeverity!, code: String!, message: String!, path: String, row: Int, column: String, groupKey: String, fieldKey: String
RentalFieldsImportChange One label or price that an UPDATE import changes.	fieldKey: String!, fieldLabel: String!, option: String, optionLabel: String, what: String!, old: String, new: String
RentalFieldsAnswersExportPayload	export: RentalFieldsAnswersExport, userErrors: [RentalUserError!]!
RentalFieldsAnswersExport	id: ID!, status: RentalFieldsExportStatus!, from: String, to: String, layout: RentalFieldsAnswersLayout!, rows: Int, byteSize: Int, downloadUrl: String, createdAt: String!, createdBy: String, expiresAt: String, error: String
RentalFieldsOptionsSettingsPayload	options: RentalFieldsOptionsSettings, userErrors: [RentalUserError!]!
RentalFieldsOptionsSettings	taxable: Boolean!

Enum	Values
RentalIdStatus	NONE PENDING VERIFIED REJECTED EXPIRED
RentalFieldsImportStatus	QUEUED CHECKING PREVIEW – Checked: the plan, errors and warnings are ready. Apply it with applyRentalFieldsImport (not while there are errors). STALE – The field groups changed since the check: check again (recheckRentalFieldsImport). FAILED APPLYING APPLIED CANCELLED EXPIRED – The preview expired (24 hours) and its file was deleted.
RentalFieldsImportOrigin	FILE – An uploaded file. LIBRARY – A template of the library.
RentalFieldsImportAction	CREATE REPLACE SKIP COPY UPDATE – Labels and prices of the group’s questions change (kind UPDATE).
RentalFieldsMessageSeverity	ERROR WARNING
RentalFieldsExportStatus	QUEUED RUNNING READY FAILED EXPIRED – Deleted (24 hours after it was ready, or because a customer’s data was erased).