Development API reference

The guide is intended for software developers implementing customised user experiences or merchants interested in what additional capabilities the app can provide.
The information saved in the app is stored in the internal app's database and the corresponding Shopify metafields. The app's database provides an ability to search the stored data, whereas metafields offer an easy way to embed the data into Shopify's notifications and the merchant's website.
Metafields
All metafields saved by the app are stored under the "serializer" namespace.
Product variant
Product variant metafields are stored in JSON format under the "properties" key. When populated, the following fields are available:
Field name
Type
Description
trackable
Boolean
It informs whether the product variant is trackable or not. The field is mapped from the "Track items" checkbox in the app.
autoGeneratable
Boolean
It informs whether new items can be automatically generated with unique item IDs and default warranty durations when an order is created.
warrantyDuration
Undefined (not populated), null or JSON object containing the following fields:

unit - string. Possible values are "day", "month" or "year".
value - integer, the minimum value is 1.
It contains a default warranty duration for the product variant items. Note that each item's warrantyDuration can be overridden.
customFields
Undefined (not populated for the saved products before the "Custom fields" feature release) or an array of JSON objects containing the following fields:

key - string.
trackable - boolean.
It contains information on which custom fields are trackable for the respective product variant. The field's key is mapped from the "Key" input field on the "Settings" page within the app. Whereas trackable value is mapped from the "Track <custom field name>" checkbox in the app.
Order
Order metafields are stored in JSON format under the "properties" key. When populated, the following fields are available:
Field name
Type
Description
currentTotalTrackable
Integer
It highlights how many items within the order are currently trackable. Note that more items may be stored than currentTotalTrackable due to order edits outside the app. When this value is lower than the number of items stored, a warning appears in the app.
items
Array of items
See the table below for the information about item fields.
Item fields:
Field name
Type
Description
lineItemId
Integer
Shopify's numeric line item ID.
productVariantId
Integer
Shopify's numeric product variant ID.
itemId
String
Globally unique item ID generated by the app. It can be used as a serial number.
serialNumber
String or undefined (not populated)
Manually entered serial number. The app only enforces uniqueness per line item. Theoretically, different manufacturers could be using the same serial number for different products.
warrantyDuration
Undefined (not populated), null or JSON object containing the following fields:

unit - string. Possible values are "day", "month" or "year".
value - integer, the minimum value is 1.
It contains a warranty duration for the item.
customFields
Undefined (not populated for the saved items before the "Custom fields" feature release) or an array of JSON objects containing the following fields:

key - string. Max length - 30 characters.
value - string. Max length - 200 characters.
It contains a list of all custom field values and keys associated with the item.
The data first saved in the app's database is updated in the Shopify metafields. Metafield edits are not synchronised with the database. Therefore, please do not edit or delete the metafields. Please get in touch with me if you wish to sync the metafields with the app's database.
Access the data from the app's database
The app provides a secure REST API to the internal items' data via Shopify's app proxy /apps/serializer/items endpoint using HTTP GET method. The API may be particularly useful for item verification, e.g. the customer could enter the received item's serial number and ensure it is an original product from the merchant's store.
The endpoint accepts the following API query filters:
Filter name
Type
Description
orderId
Integer
Shopify's numeric order ID.
customerId
Integer
Shopify's numeric customer ID.
productVariantId
Integer
Shopify's numeric product variant ID.
lineItemId
Integer
Shopify's numeric line item ID.
serialNumber
String
Manually entered serial number.
itemId
String
Globally unique item ID generated by the app.
itemRef
String
It filters results by serialNumber or itemId. The filter may be helpful when the store uses both serialNumber and itemId fields as serial numbers.
cursor
String
Results are limited to 100 items per request. The filter provides a capability to paginate through the results.
The API endpoint requires at least one of the following filters to be used: orderId, customerId, serialNumber, itemId or itemRef. For example, GET /apps/serializer/items?orderId=4460047270069.
The endpoint response contains the following JSON data:
Field name
Type
Description
previous
String
Cursor to the previous page.
hasPrevious
Boolean
It highlights whether the previous page exists.
next
String
Cursor to the next page.
hasNext
String
It highlights whether the next page exists.
results
Array of items
See the table below for the information about item fields.
Item fields:
Field name
Type
Description
lineItemId
Integer
Shopify's numeric line item ID.
productVariantId
Integer
Shopify's numeric customer ID.
itemId
String
Globally unique item ID generated by the app. It can be used as a serial number.
serialNumber
String or undefined (not populated)
Manually entered serial number. The app only enforces uniqueness per line item. Theoretically, different manufacturers could use the same serial number for different products.
warrantyDuration
Undefined (not populated), null or JSON object containing the following fields:

unit - string. Possible values are "day", "month" or "year".
value - integer, the minimum value is 1.
It contains a warranty duration for the item.
customFields
Undefined (not populated for the saved items before the "Custom fields" feature release) or an array of JSON objects containing the following fields:

key - string. Max length - 30 characters.
value - string. Max length - 200 characters.
It contains a list of all custom field values and keys associated with the item.
orderId
Integer
Shopify's numeric order ID.
autoGenerated
Boolean
False when new items were added during the order edit, i.e. via "Adjust quantity". True otherwise.
createdAt
UTC timestamp in ISO-8601 format, string representation
Date and time when the item was first saved in the app's database.
updatedAt
UTC timestamp in ISO-8601 format, string representation
Date and time the item was last updated in the app's database.

Field name	Type	Description
trackable	Boolean	It informs whether the product variant is trackable or not. The field is mapped from the "Track items" checkbox in the app.
autoGeneratable	Boolean	It informs whether new items can be automatically generated with unique item IDs and default warranty durations when an order is created.
warrantyDuration	Undefined (not populated), null or JSON object containing the following fields: unit - string. Possible values are "day", "month" or "year". value - integer, the minimum value is 1.	It contains a default warranty duration for the product variant items. Note that each item's warrantyDuration can be overridden.
customFields	Undefined (not populated for the saved products before the "Custom fields" feature release) or an array of JSON objects containing the following fields: key - string. trackable - boolean.	It contains information on which custom fields are trackable for the respective product variant. The field's key is mapped from the "Key" input field on the "Settings" page within the app. Whereas trackable value is mapped from the "Track <custom field name>" checkbox in the app.

Field name	Type	Description
currentTotalTrackable	Integer	It highlights how many items within the order are currently trackable. Note that more items may be stored than currentTotalTrackable due to order edits outside the app. When this value is lower than the number of items stored, a warning appears in the app.
items	Array of items	See the table below for the information about item fields.

Field name	Type	Description
lineItemId	Integer	Shopify's numeric line item ID.
productVariantId	Integer	Shopify's numeric product variant ID.
itemId	String	Globally unique item ID generated by the app. It can be used as a serial number.
serialNumber	String or undefined (not populated)	Manually entered serial number. The app only enforces uniqueness per line item. Theoretically, different manufacturers could be using the same serial number for different products.
warrantyDuration	Undefined (not populated), null or JSON object containing the following fields: unit - string. Possible values are "day", "month" or "year". value - integer, the minimum value is 1.	It contains a warranty duration for the item.
customFields	Undefined (not populated for the saved items before the "Custom fields" feature release) or an array of JSON objects containing the following fields: key - string. Max length - 30 characters. value - string. Max length - 200 characters.	It contains a list of all custom field values and keys associated with the item.

Filter name	Type	Description
orderId	Integer	Shopify's numeric order ID.
customerId	Integer	Shopify's numeric customer ID.
productVariantId	Integer	Shopify's numeric product variant ID.
lineItemId	Integer	Shopify's numeric line item ID.
serialNumber	String	Manually entered serial number.
itemId	String	Globally unique item ID generated by the app.
itemRef	String	It filters results by serialNumber or itemId. The filter may be helpful when the store uses both serialNumber and itemId fields as serial numbers.
cursor	String	Results are limited to 100 items per request. The filter provides a capability to paginate through the results.

Field name	Type	Description
previous	String	Cursor to the previous page.
hasPrevious	Boolean	It highlights whether the previous page exists.
next	String	Cursor to the next page.
hasNext	String	It highlights whether the next page exists.
results	Array of items	See the table below for the information about item fields.

Field name	Type	Description
lineItemId	Integer	Shopify's numeric line item ID.
productVariantId	Integer	Shopify's numeric customer ID.
itemId	String	Globally unique item ID generated by the app. It can be used as a serial number.
serialNumber	String or undefined (not populated)	Manually entered serial number. The app only enforces uniqueness per line item. Theoretically, different manufacturers could use the same serial number for different products.
warrantyDuration	Undefined (not populated), null or JSON object containing the following fields: unit - string. Possible values are "day", "month" or "year". value - integer, the minimum value is 1.	It contains a warranty duration for the item.
customFields	Undefined (not populated for the saved items before the "Custom fields" feature release) or an array of JSON objects containing the following fields: key - string. Max length - 30 characters. value - string. Max length - 200 characters.	It contains a list of all custom field values and keys associated with the item.
orderId	Integer	Shopify's numeric order ID.
autoGenerated	Boolean	False when new items were added during the order edit, i.e. via "Adjust quantity". True otherwise.
createdAt	UTC timestamp in ISO-8601 format, string representation	Date and time when the item was first saved in the app's database.
updatedAt	UTC timestamp in ISO-8601 format, string representation	Date and time the item was last updated in the app's database.

Last modified 6mo ago