Shopify Customer

This page documents the Shopify Customer model.

Data Shape

Gadget's database stores Shopify Customer records by storing and retrieving each of the fields defined on the model in the Gadget Editor to a managed database. Gadget has generated a GraphQL type matching the configured fields for Shopify Customer:

Shopify Customer Schema
1export interface ShopifyCustomer {
2 __typename: "ShopifyCustomer";
3
4 /** The globally unique, unchanging identifier for this record. Assigned and managed by Shopify. */
5 id: Scalars["GadgetID"];
6
7 /** The time at which this record was first created. Set once upon record creation and never changed. Managed by Gadget. */
8 createdAt: Scalars["DateTime"];
9
10 /** The time at which this record was last changed. Set each time the record is successfully acted upon by an action. Managed by Gadget. */
11 updatedAt: Scalars["DateTime"];
12
13 /** The current state this record is in. Changed by invoking actions. Managed by Gadget. */
14 state: Scalars["RecordState"];
15
16 acceptsMarketing: Scalars["Boolean"] | null;
17
18 acceptsMarketingUpdatedAt: Scalars["DateTime"] | null;
19
20 shopifyCreatedAt: Scalars["DateTime"] | null;
21
22 currency: Scalars["String"] | null;
23
24 email: Scalars["String"] | null;
25
26 firstName: Scalars["String"] | null;
27
28 lastName: Scalars["String"] | null;
29
30 lastOrderName: Scalars["String"] | null;
31
32 marketingOptInLevel: Scalars["String"] | null;
33
34 metafield: Scalars["JSON"] | null;
35
36 multipassIdentifier: Scalars["String"] | null;
37
38 note: Scalars["String"] | null;
39
40 ordersCount: Scalars["Float"] | null;
41
42 phone: Scalars["String"] | null;
43
44 tags: Scalars["JSON"] | null;
45
46 taxExempt: Scalars["Boolean"] | null;
47
48 taxExemptions: Scalars["JSON"] | null;
49
50 totalSpent: Scalars["String"] | null;
51
52 shopifyUpdatedAt: Scalars["DateTime"] | null;
53
54 verifiedEmail: Scalars["Boolean"] | null;
55
56 shop: ShopifyShop | null;
57
58 shopId: Scalars["GadgetID"] | null;
59
60 /** Get all the fields for this record. Useful for not having to list out all the fields you want to retrieve, but slower. */
61 _all: Scalars["JSONObject"];
62}
1type ShopifyCustomer {
2 """
3 The globally unique, unchanging identifier for this record. Assigned and managed by Shopify.
4 """
5 id: GadgetID!
6
7 """
8 The time at which this record was first created. Set once upon record creation and never changed. Managed by Gadget.
9 """
10 createdAt: DateTime!
11
12 """
13 The time at which this record was last changed. Set each time the record is successfully acted upon by an action. Managed by Gadget.
14 """
15 updatedAt: DateTime!
16
17 """
18 The current state this record is in. Changed by invoking actions. Managed by Gadget.
19 """
20 state: RecordState!
21 acceptsMarketing: Boolean
22 acceptsMarketingUpdatedAt: DateTime
23 shopifyCreatedAt: DateTime
24 currency: String
25 email: String
26 firstName: String
27 lastName: String
28 lastOrderName: String
29 marketingOptInLevel: String
30 metafield: JSON
31 multipassIdentifier: String
32 note: String
33 ordersCount: Float
34 phone: String
35 tags: JSON
36 taxExempt: Boolean
37 taxExemptions: JSON
38 totalSpent: String
39 shopifyUpdatedAt: DateTime
40 verifiedEmail: Boolean
41 shop: ShopifyShop
42 shopId: GadgetID
43
44 """
45 Get all the fields for this record. Useful for not having to list out all the fields you want to retrieve, but slower.
46 """
47 _all: JSONObject!
48}

You can preview what a real record's shape looks like by fetching it using the example-app API Playground.

Any fetched Shopify Customer record will have this same ShopifyCustomer type, and expose the same data by default, regardless of if it's fetched by ID or as part of a findMany. This means you can select any of the record's fields wherever you like in a GraphQL query according to the use case at hand.

Retrieving one Shopify Customer record

Individual Shopify Customer records can be retrieved using the "find by ID" API endpoint. You can also return only some fields, or extra fields beyond what Gadget retrieves by default, using the select option.

The findOne function throws an error if no matching record is found, which you will need to catch and handle. Alternatively, you can use the maybeFindOne function, which returns null if no record is found, without throwing an error.

Similarly, the useFindOne React hook returns (but does not throw) an error when no matching record is found, while the useMaybeFindOne hook simply returns null if no record is found, without also returning an error.

Get one Shopify Customer
const shopifyCustomerRecord = await api.shopifyCustomer.findOne("some-id");
console.log(shopifyCustomerRecord.id); //=> a string
console.log(shopifyCustomerRecord.createdAt); //=> a Date object
const [result, refresh] = useFindOne(api.shopifyCustomer, "some-id");
const { data, error, fetching } = result;
console.log(data?.id); //=> a string
console.log(data?.createdAt); //=> a Date object
1query GetOneShopifyCustomer($id: GadgetID!) {
2 shopifyCustomer(id: $id) {
3 __typename
4 id
5 state
6 acceptsMarketing
7 acceptsMarketingUpdatedAt
8 createdAt
9 currency
10 email
11 firstName
12 lastName
13 lastOrderName
14 marketingOptInLevel
15 metafield
16 multipassIdentifier
17 note
18 ordersCount
19 phone
20 shopifyCreatedAt
21 shopifyUpdatedAt
22 tags
23 taxExempt
24 taxExemptions
25 totalSpent
26 updatedAt
27 verifiedEmail
28 }
29}
Variables
json
{ "id": "some-id" }

Retrieving the first of many Shopify Customer records

The first record from a list of records can be retrieved using the "find first" API endpoint. The source list of records can be filtered using the filter option, sorted using the sort option, searched using the search option, though no pagination options are available on this endpoint. You can also return only some fields, or extra fields beyond what Gadget retrieves by default using the select option.

The findFirst function throws an error if no matching record is found, which you will need to catch and handle. Alternatively, you can use the maybeFindFirst function, which returns null if no record is found, without throwing an error.

Similarly, the useFindFirst React hook returns (but does not throw) an error when no matching record is found, while the useMaybeFindFirst hook simply returns null if no record is found, without also returning an error.

Get one Shopify Customer
const shopifyCustomerRecord = await api.shopifyCustomer.findFirst();
console.log(shopifyCustomerRecord.id); //=> a string
console.log(shopifyCustomerRecord.createdAt); //=> a Date object
const [result, refresh] = useFindFirst(api.shopifyCustomer);
const { data, error, fetching } = result;
console.log(data?.id); //=> a string
console.log(data?.createdAt); //=> a Date object
1query FindManyShopifyCustomers(
2 $first: Int
3 $search: String
4 $sort: [ShopifyCustomerSort!]
5 $filter: [ShopifyCustomerFilter!]
6) {
7 shopifyCustomers(first: $first, search: $search, sort: $sort, filter: $filter) {
8 edges {
9 node {
10 __typename
11 id
12 state
13 acceptsMarketing
14 acceptsMarketingUpdatedAt
15 createdAt
16 currency
17 email
18 firstName
19 lastName
20 lastOrderName
21 marketingOptInLevel
22 metafield
23 multipassIdentifier
24 note
25 ordersCount
26 phone
27 shopifyCreatedAt
28 shopifyUpdatedAt
29 tags
30 taxExempt
31 taxExemptions
32 totalSpent
33 updatedAt
34 verifiedEmail
35 }
36 }
37 }
38}
Variables
json
{ "first": 1 }

Retrieving many Shopify Customer records

Pages of Shopify Customer records can be retrieved by using the "find many" API endpoint. The returned records can be filtered using the filter option, sorted using the sort option, searched using the search option, and paginated using standard Relay-style pagination options. You can also return only some fields, or extra fields beyond what Gadget retrieves by default using the select option.

This GraphQL endpoint returns records in the Relay Connection style (as a list of edges with nodes and cursors) so they can be paginated. The shopifyCustomers GraphQL endpoint works with any Relay-compatible caching client, or you can use Gadget's JS client for pagination with the findMany function.

Find a page of Shopify Customers

Fetch a page of records with the shopifyCustomer.findMany JS method or the shopifyCustomers GraphQL field. No options are required. The records returned will be implicitly sorted by ID ascending.

Find many Shopify Customers
const shopifyCustomerRecords = await api.shopifyCustomer.findMany();
console.log(shopifyCustomerRecords.length); //=> a number
console.log(shopifyCustomerRecords[0].id); //=> a string
const [result, refresh] = useFindMany(api.shopifyCustomer);
const { data, error, fetching } = result;
console.log(data?.length); //=> a number
console.log(data?.[0].length); //=> a string
1query FindManyShopifyCustomers {
2 shopifyCustomers {
3 edges {
4 node {
5 __typename
6 id
7 state
8 # ...
9 createdAt
10 updatedAt
11 }
12 }
13 }
14}
Variables
json
{}

Sorting

Records can be sorted in the database to retrieve them in a certain order. Records are always implicitly sorted by ID ascending unless an explicit sort on the id field is defined. The GraphQL type ShopifyCustomerSort defines which fields can be sorted by.

Records can be sorted by multiple different fields and in multiple different directions by passing a list of ShopifyCustomerSort instead of just one.

GraphQL
1input ShopifyCustomerSort {
2 id: SortOrder
3 createdAt: SortOrder
4 updatedAt: SortOrder
5 state: SortOrder
6 acceptsMarketing: SortOrder
7 acceptsMarketingUpdatedAt: SortOrder
8 shopifyCreatedAt: SortOrder
9 currency: SortOrder
10 email: SortOrder
11 firstName: SortOrder
12 lastName: SortOrder
13 lastOrderName: SortOrder
14 marketingOptInLevel: SortOrder
15 metafield: SortOrder
16 multipassIdentifier: SortOrder
17 note: SortOrder
18 ordersCount: SortOrder
19 phone: SortOrder
20 tags: SortOrder
21 taxExempt: SortOrder
22 taxExemptions: SortOrder
23 totalSpent: SortOrder
24 shopifyUpdatedAt: SortOrder
25 verifiedEmail: SortOrder
26}

Pass the sort option to the JS client, or the sort variable to a GraphQL query to sort the records returned.

Sort Shopify Customer by most recently created
const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
sort: { createdAt: "Descending" },
});
const [result, refresh] = useFindMany(api.shopifyCustomer, {
sort: { createdAt: "Descending" },
});
const { data, error, fetching } = result;
1query FindManyShopifyCustomers($sort: [ShopifyCustomerSort!]) {
2 shopifyCustomers(sort: $sort) {
3 edges {
4 node {
5 __typename
6 id
7 state
8 # ...
9 createdAt
10 updatedAt
11 }
12 }
13 }
14}
Variables
json
{ "sort": { "createdAt": "Descending" } }

Sort by multiple fields by passing an array of { [field]: "Ascending" | "Descending" } objects.

Sort Shopify Customer by multiple fields
const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
sort: [{ state: "Descending" }, { createdAt: "Ascending" }],
});
const [result, refresh] = useFindMany(api.shopifyCustomer, {
sort: [{ state: "Descending" }, { createdAt: "Ascending" }],
});
const { data, error, fetching } = result;
1query FindManyShopifyCustomers($sort: [ShopifyCustomerSort!]) {
2 shopifyCustomers(sort: $sort) {
3 edges {
4 node {
5 __typename
6 id
7 state
8 # ...
9 createdAt
10 updatedAt
11 }
12 }
13 }
14}
Variables
json
{ "sort": [{ "state": "Descending" }, { "createdAt": "Ascending" }] }

All primitive field types in Gadget are sortable so you are able to sort by fields you have added to a model as well.

Sort Shopify Customers by ID descending
const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
sort: { id: "Descending" },
});
const [result, refresh] = useFindMany(api.shopifyCustomer, {
sort: { id: "Descending" },
});
const { data, error, fetching } = result;
1query FindManyShopifyCustomers($sort: [ShopifyCustomerSort!]) {
2 shopifyCustomers(sort: $sort) {
3 edges {
4 node {
5 __typename
6 id
7 state
8 # ...
9 createdAt
10 updatedAt
11 }
12 }
13 }
14}
Variables
json
{ "sort": { "id": "Descending" } }

Searching

Shopify Customer records can be searched using Gadget's built in full text search functionality. Gadget search is appropriate for powering autocompletes, searchable tables, or other experiences where humans are writing search queries. It's typo tolerant, synonym aware and supports simple search operators like ! to exclude search terms.

Search Shopify Customers by passing the search parameter with a search query string.

Search isn't field specific in Gadget -- all String or RichText field types are searched with the built in search functionality.

Full text search Shopify Customers
const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
search: "a specific phrase to search for",
});
const [result, refresh] = useFindMany(api.shopifyCustomer, {
search: "a specific phrase to search for",
});
const { data, error, fetching } = result;
1query FindManyShopifyCustomers($search: String) {
2 shopifyCustomers(search: $search) {
3 edges {
4 node {
5 __typename
6 id
7 state
8 # ...
9 createdAt
10 updatedAt
11 }
12 }
13 }
14}
Variables
json
{ "search": "a specific phrase to search for" }

Filtering

Shopify Customer records can be filtered to return only the appropriate records. Records can be filtered on any field, including those managed by Gadget or fields added by developers. Filters can be combined with sorts, searches and paginated using cursor-based Relay pagination.

Filter Shopify Customers by passing the filter parameter with a filter object. Filter objects are nestable boolean conditions expressed as JS objects capturing a key, an operator, and usually a value.

The GraphQL type ShopifyCustomerFilter defines which fields can be filtered on.

Records can be filtered by multiple different fields. If you want to combine filters using boolean logic, nest them under the AND, OR, or NOT keys of a parent filter. Filters can be nested deeply by passing multiple levels boolean condition filters.

You can also pass a list of filters to the filter parameter which will be implicitly ANDed with one another such that they all need to match for a record to be returned.

Available filters
GraphQL
1input ShopifyCustomerFilter {
2 AND: [ShopifyCustomerFilter]
3 OR: [ShopifyCustomerFilter]
4 NOT: [ShopifyCustomerFilter]
5 id: IDFilter
6 createdAt: DateTimeFilter
7 updatedAt: DateTimeFilter
8 state: StateFilter
9 acceptsMarketing: BooleanFilter
10 acceptsMarketingUpdatedAt: DateTimeFilter
11 shopifyCreatedAt: DateTimeFilter
12 currency: StringFilter
13 email: StringFilter
14 firstName: StringFilter
15 lastName: StringFilter
16 lastOrderName: StringFilter
17 marketingOptInLevel: StringFilter
18 metafield: JSONFilter
19 multipassIdentifier: StringFilter
20 note: StringFilter
21 ordersCount: FloatFilter
22 phone: StringFilter
23 tags: JSONFilter
24 taxExempt: BooleanFilter
25 taxExemptions: JSONFilter
26 totalSpent: StringFilter
27 shopifyUpdatedAt: DateTimeFilter
28 verifiedEmail: BooleanFilter
29 shop: IDFilter
30}
Find Shopify Customers created in the last day
const yesterday = new Date(Date.now() - 864e5);
const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
filter: { createdAt: { greaterThan: yesterday } },
});
const yesterday = new Date(Date.now() - 864e5);
const [result, refresh] = useFindMany(api.shopifyCustomer, {
filter: { createdAt: { greaterThan: yesterday } },
});
const { data, error, fetching } = result;
1query FindManyShopifyCustomers($filter: [ShopifyCustomerFilter!]) {
2 shopifyCustomers(filter: $filter) {
3 edges {
4 node {
5 __typename
6 id
7 state
8 # ...
9 createdAt
10 updatedAt
11 }
12 }
13 }
14}
Variables
json
{ "filter": { "createdAt": { "greaterThan": "2023-02-04T23:47:48.246Z" } } }
Shopify Customers created this week or updated today
1const yesterday = new Date(Date.now() - 86400000);
2const oneWeekAgo = new Date(Date.now() - 604800000);
3const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
4 filter: {
5 OR: [
6 {
7 createdAt: { greaterThan: oneWeekAgo },
8 },
9 {
10 updated: { greaterThan: yesterday },
11 },
12 ],
13 },
14});
1const yesterday = new Date(Date.now() - 86400000);
2const oneWeekAgo = new Date(Date.now() - 604800000);
3const [result, refresh] = useFindMany(api.shopifyCustomer, {
4 filter: {
5 OR: [
6 {
7 createdAt: { greaterThan: oneWeekAgo },
8 },
9 {
10 updated: { greaterThan: yesterday },
11 },
12 ],
13 },
14});
15const { data, error, fetching } = result;
1query FindManyShopifyCustomers($filter: [ShopifyCustomerFilter!]) {
2 shopifyCustomers(filter: $filter) {
3 edges {
4 node {
5 __typename
6 id
7 state
8 # ...
9 createdAt
10 updatedAt
11 }
12 }
13 }
14}
Variables
json
1{
2 "filter": {
3 "OR": [
4 { "createdAt": { "greaterThan": "2023-01-29T23:47:48.246Z" } },
5 { "updated": { "greaterThan": "2023-02-04T23:47:48.246Z" } }
6 ]
7 }
8}
Filter records that are in the created state
const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
filter: {
state: { inState: "created" },
},
});
1const [result, refresh] = useFindMany(api.shopifyCustomer, {
2 filter: {
3 state: { inState: "created" },
4 },
5});
6const { data, error, fetching } = result;
1query FindManyShopifyCustomers($filter: [ShopifyCustomerFilter!]) {
2 shopifyCustomers(filter: $filter) {
3 edges {
4 node {
5 __typename
6 id
7 state
8 # ...
9 createdAt
10 updatedAt
11 }
12 }
13 }
14}
Variables
json
{ "filter": { "state": { "inState": "created" } } }

Most field types in Gadget are filterable, so you are able to filter by fields you have added to a model as well.

const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
filter: {
id: { isSet: true },
},
});
1const [result, refresh] = useFindMany(api.shopifyCustomer, {
2 filter: {
3 id: { isSet: true },
4 },
5});
6const { data, error, fetching } = result;
1query FindManyShopifyCustomers($filter: [ShopifyCustomerFilter!]) {
2 shopifyCustomers(filter: $filter) {
3 edges {
4 node {
5 __typename
6 id
7 state
8 # ...
9 createdAt
10 updatedAt
11 }
12 }
13 }
14}
Variables
json
{ "filter": { "id": { "isSet": true } } }

Pagination

All Gadget record lists, including the top level Shopify Customer finder as well as associations to Shopify Customer, are structured as GraphQL connections. GraphQL connections are the de facto standard for querying lists and support cursor-based forward and backward pagination. When querying via GraphQL, you must select the edges field and then the node field to get the Shopify Customer record. When querying using a Gadget API client, the GraphQL queries are generated for you and the records are unwrapped and returned as a GadgetRecordList ready for use.

Shopify Customer pagination supports the standard GraphQL connection pagination arguments: first + after, or last + before. Pagination is done using cursors, which you can retrieve from the edge.cursor field or the pageInfo.startCursor properties.

Get the first page of 25 Shopify Customers
const shopifyCustomerRecords = await api.shopifyCustomer.findMany({ first: 25 });
console.log(shopifyCustomerRecords.length); //=> no greater than 25
const [result, refresh] = useFindMany(api.shopifyCustomer, { first: 25 });
const { data, error, fetching } = result;
console.log(data?.length); //=> no greater than 25
1query FindManyShopifyCustomers($first: Int, $after: String) {
2 shopifyCustomers(first: $first, after: $after) {
3 edges {
4 cursor
5 node {
6 __typename
7 id
8 state
9 # ...
10 createdAt
11 updatedAt
12 }
13 }
14 pageInfo {
15 endCursor
16 hasNextPage
17 hasPreviousPage
18 startCursor
19 }
20 }
21}
Variables
json
{ "first": 25 }

The after cursor used in this example data won't return any records if used in a real API request.

Next 25 Shopify Customer records after cursor
const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
after: "abcdefg",
first: 25,
});
const [result, refresh] = useFindMany(api.shopifyCustomer, {
after: "abcdefg",
first: 25,
});
const { data, error, fetching } = result;
1query FindManyShopifyCustomers($first: Int, $after: String) {
2 shopifyCustomers(first: $first, after: $after) {
3 edges {
4 cursor
5 node {
6 __typename
7 id
8 state
9 # ...
10 createdAt
11 updatedAt
12 }
13 }
14 pageInfo {
15 endCursor
16 hasNextPage
17 hasPreviousPage
18 startCursor
19 }
20 }
21}
Variables
json
{ "first": 25, "after": "abcdefg" }

Pagination Limits

Root-level record finders like shopifyCustomers support a maximum page size of 250 records and a default page size of 50 records. The page size is controlled using the first or last GraphQL field arguments.

Related record finders that access lists of records through a has many or has many field support a maximum page size of 100 records and a default page size of 50 records.

Get the next or previous page

When using the generated JavaScript API client, including the api parameter in a Gadget code effect, the record lists returned from findMany calls can be paginated using the nextPage() or previousPage() option.

Both nextPage() and previousPage() will throw an error if the corresponding hasNextPage or hasPreviousPage is false.

JavaScript
1const shopifyCustomerRecords = await api.shopifyCustomer.findMany();
2if (shopifyCustomerRecords.hasNextPage) {
3 const nextPage = await shopifyCustomerRecords.nextPage();
4}
5if (shopifyCustomerRecords.hasPreviousPage) {
6 const prevPage = await shopifyCustomerRecords.previousPage();
7}

When using React and paging through records, you can use cursors to get the previous or next pages of records. This is an example of a React component that pages forward and backward through 2 records at a time for props.model.name.

React
1import { api } from "../api"; // your Gadget project's API Client
2import { useFindMany } from "@gadgetinc/react";
3import { useCallback, useState } from "react";
4
5export default function TestComponent() {
6 const NUM_ON_PAGE = 2; // the number of records per page
7
8 const [cursor, setCursor] = useState({ first: NUM_ON_PAGE });
9 // using Gadget React hooks to fetch records of shopifyCustomer
10 const [{ data, fetching, error }] = useFindMany(api.shopifyCustomer, {
11 ...cursor,
12 });
13
14 const getNextPage = useCallback(() => {
15 // use first + after to page forwards
16 setCursor({ first: NUM_ON_PAGE, after: data.endCursor });
17 }, [data]);
18
19 const getPreviousPage = useCallback(() => {
20 // use last + before to page backwards
21 setCursor({ last: NUM_ON_PAGE, before: data.startCursor });
22 }, [data]);
23
24 return (
25 <div>
26 <button onClick={getPreviousPage} disabled={!data?.hasPreviousPage}>
27 Previous page
28 </button>
29 <button onClick={getNextPage} disabled={!data?.hasNextPage}>
30 Next page
31 </button>
32 {!fetching && data.map((d) => <div>{d.id}</div>)}
33 </div>
34 );
35}

Get all records

If you need to get all available data for Shopify Customer, you will need to paginate through all pages of data. If you have a large amount of data, this can take a long time. Make sure you need to collect all data at once before writing a pagination loop that reads all records! If you are querying records for display in a UI and cannot display all your records at once, we don't recommend fetching all the data beforehand - instead, use the cursor to read additional data when the user needs it.

If you need all data for analytics applications or to collect some statistics on your data, consider options like intermediate models and pre-defined data rollups.

If you have determined that you need all your data, you can fetch it using cursors and a loop. We also suggest using select so that you only grab fields that are needed, in addition to applying a filter, if possible. Using first with the maximum allowable value will also allow you to grab the maximum number of records you can at once.

Page through all records
JavaScript
1const allRecords = []; // use allRecords to store all records
2let records = await api.shopifyCustomer.findMany({
3 first: 250,
4 select: {
5 id: true,
6 },
7 filter: {
8 // add filter conditions, if possible
9 },
10});
11
12allRecords.push(...records);
13
14// loop through additional pages to get all protected orders
15while (records.hasNextPage) {
16 // paginate
17 records = await records.nextPage();
18 allRecords.push(...records);
19}

Selecting fields, and fields of fields

When using the JavaScript client, all of findOne, maybeFindOne, findMany, findFirst, maybeFindFirst, and various action functions, allow requesting specific fields of a Shopify Customer and its relationships. The select option controls which fields are selected in the generated GraphQL query sent to the Gadget API. Pass each field you want to select in an object, with true as the value for scalar fields, and a nested object of the same shape for nested fields.

Gadget has a default selection that will retrieve all of the scalar fields for a Shopify Customer. If you don't pass a select option to a record finder, this default selection will be used.

Select only some Shopify Customer fields
1// fetch only the id, state, and createdAt field
2const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
3 select: { id: true, state: true, createdAt: true },
4});
5// fetch all the scalar fields for the model, but no relationship fields
6const shopifyCustomerRecords = await api.shopifyCustomer.findMany();
1// fetch only the id, state, and createdAt field
2const [result, refresh] = useFindMany(api.shopifyCustomer, {
3 select: { id: true, state: true, createdAt: true },
4});
5const { data, error, fetching } = result;
6// fetch all the scalar fields for the model, but no relationship fields
7const [result, refresh] = useFindMany(api.shopifyCustomer);
8const { data, error, fetching } = result;
Type Safety

The select option is fully type safe if you're using TypeScript. The returned GadgetRecord type will have a <Shape> exactly matching the fields and nested fields you selected. For more information, see Type Safety .

This behavior of selecting only some fields is built right into GraphQL. If you want to limit or expand what you retrieve from a GraphQL query, include or exclude those fields in your GraphQL query. For more information on executing GraphQL queries, see GraphQL.

Select nested Shopify Customer fields
1// fetch the id, state, and createdAt field, and fetch some nested fields from an example relationship field named `someRelatedObject`
2const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
3 select: {
4 id: true,
5 state: true,
6 createdAt: true,
7 someRelatedObject: { id: true, createdAt: true },
8 },
9});
1// fetch the id, state, and createdAt field, and fetch some nested fields from an example relationship field named `someRelatedObject`
2const [result, refresh] = useFindMany(api.shopifyCustomer, {
3 select: {
4 id: true,
5 state: true,
6 createdAt: true,
7 someRelatedObject: { id: true, createdAt: true },
8 },
9});
10const { data, error, fetching } = result;

Combining parameters

Sort, search, filtering, selection, and pagination parameters can be combined to access the exact set of records needed for your use case.

Combining Parameters
1const shopifyCustomerRecords = await api.shopifyCustomer.findMany({
2 search: "<some search query>",
3 sort: { createdAt: "Descending" },
4 filter: { updatedAt: { greaterThan: new Date(Date.now() - 864e5) } },
5 select: { id: true, createdAt: true },
6 first: 25,
7 after: "abcdefg",
8});
1const [result, refresh] = useFindMany(api.shopifyCustomer, {
2 search: "<some search query>",
3 sort: { createdAt: "Descending" },
4 filter: { updatedAt: { greaterThan: new Date(Date.now() - 864e5) } },
5 select: { id: true, createdAt: true },
6 first: 25,
7 after: "abcdefg",
8});
9const { data, error, fetching } = result;
1query FindManyShopifyCustomers(
2 $after: String
3 $before: String
4 $first: Int
5 $last: Int
6 $search: String
7 $sort: [ShopifyCustomerSort!]
8 $filter: [ShopifyCustomerFilter!]
9) {
10 shopifyCustomers(
11 after: $after
12 before: $before
13 first: $first
14 last: $last
15 search: $search
16 sort: $sort
17 filter: $filter
18 ) {
19 edges {
20 cursor
21 node {
22 __typename
23 id
24 state
25 acceptsMarketing
26 acceptsMarketingUpdatedAt
27 createdAt
28 currency
29 email
30 firstName
31 lastName
32 lastOrderName
33 marketingOptInLevel
34 metafield
35 multipassIdentifier
36 note
37 ordersCount
38 phone
39 shopifyCreatedAt
40 shopifyUpdatedAt
41 tags
42 taxExempt
43 taxExemptions
44 totalSpent
45 updatedAt
46 verifiedEmail
47 }
48 }
49 pageInfo {
50 endCursor
51 hasNextPage
52 hasPreviousPage
53 startCursor
54 }
55 }
56}
Variables
json
1{
2 "search": "<some search query>",
3 "sort": { "createdAt": "Descending" },
4 "filter": { "updatedAt": { "greaterThan": "2023-02-04T23:47:48.442Z" } },
5 "first": 25,
6 "after": "abcdefg"
7}

Invoking Actions

Shopify Customer records are changed by invoking Actions. Actions are the things that "do" stuff -- update records, make API calls, call backend code, etc. Actions with a GraphQL API trigger each have one corresponding GraphQL mutation and a corresponding function available in the API client libraries. Nested Actions can also be invoked with the API client, by providing the actions as input to any relationship fields.

Action Result format

Each API action returns results in the same format that includes a success indicator, errors, and the actual result if the action succeeded. The result is the record that was acted on for a model action, or a list of records for a bulk action, or a JSON blob for Global Actions. Model actions that delete the record don't return the record.

The success field returns a boolean indicating if the action executed as expected. Any execution errors are returned in the errors object, which will always be null if success is true or contain ExecutionError objects if success is false.

ExecutionError objects always have a message describing what error prevented the action from succeeding, as well as a code attribute that gives a stable, searchable, human readable error class code for referencing this specific error. Details on each error code can be found in the Errors documentation. All ExecutionError object types returned by the GraphQL object can be one of many types of error, where some types have extra data that is useful for remedying the error. All error types will always have message and code properties, but some, like InvalidRecordError have extra fields for use by clients.

Errors when using the generated client

The generated JavaScript client automatically interprets errors from invoking actions and throws JavaScript Error instances if the action didn't succeed. The Error objects it throws are rich, and expose extra error properties beyond just message and code if they exist.

Errors thrown by the JavaScript client are easiest to catch by using a try/catch statement around an await, like so:

JavaScript
1import {
2 GadgetOperationError,
3 InvalidRecordError,
4} from "@gadget-client/example-app";
5
6// must be in an async function to use `await` syntax
7const runAction = async () => {
8 try {
9 return await api.exampleModel.create({
10 exampleModel: { name: "example record name" },
11 });
12 } catch (error) {
13 if (error instanceof GadgetOperationError) {
14 // a recognized general error has occurred, retry the operation or inspect error.code`
15 console.error(error);
16 } else if (error instanceof InvalidRecordError) {
17 // the submitted input data for the action was invalid, inspect the invalid fields which `InvalidRecordError` exposes
18 console.error(error.validationErrors);
19 } else {
20 // an unrecognized error occurred, like an HTTP connection interrupted error or a syntax error. Re-throw it because it's not clear what to do to fix ti
21 throw error;
22 }
23 }
24};

For more information on error codes, consult the Errors documentation.

Shopify Customer create

Input

create accepts the following input parameters:

create Input Data
1export interface CreateShopifyCustomerInput {
2 id?: (Scalars["GadgetID"] | null) | null;
3
4 acceptsMarketing?: (Scalars["Boolean"] | null) | null;
5
6 acceptsMarketingUpdatedAt?: Date | Scalars["ISO8601DateString"] | null;
7
8 shopifyCreatedAt?: Date | Scalars["ISO8601DateString"] | null;
9
10 currency?: (Scalars["String"] | null) | null;
11
12 email?: (Scalars["String"] | null) | null;
13
14 firstName?: (Scalars["String"] | null) | null;
15
16 lastName?: (Scalars["String"] | null) | null;
17
18 lastOrderName?: (Scalars["String"] | null) | null;
19
20 marketingOptInLevel?: (Scalars["String"] | null) | null;
21
22 metafield?: (Scalars["JSON"] | null) | null;
23
24 multipassIdentifier?: (Scalars["String"] | null) | null;
25
26 note?: (Scalars["String"] | null) | null;
27
28 ordersCount?: (Scalars["Float"] | null) | null;
29
30 phone?: (Scalars["String"] | null) | null;
31
32 tags?: (Scalars["JSON"] | null) | null;
33
34 taxExempt?: (Scalars["Boolean"] | null) | null;
35
36 taxExemptions?: (Scalars["JSON"] | null) | null;
37
38 totalSpent?: (Scalars["String"] | null) | null;
39
40 shopifyUpdatedAt?: Date | Scalars["ISO8601DateString"] | null;
41
42 verifiedEmail?: (Scalars["Boolean"] | null) | null;
43
44 shop?: ShopifyShopBelongsToInput | null;
45}
46
47export interface CreateShopifyCustomerArguments {
48 shopifyCustomer?: CreateShopifyCustomerInput | null;
49}
1input CreateShopifyCustomerInput {
2 id: GadgetID
3 acceptsMarketing: Boolean
4 acceptsMarketingUpdatedAt: DateTime
5 shopifyCreatedAt: DateTime
6 currency: String
7 email: String
8 firstName: String
9 lastName: String
10 lastOrderName: String
11 marketingOptInLevel: String
12 metafield: JSON
13 multipassIdentifier: String
14 note: String
15 ordersCount: Float
16 phone: String
17 tags: JSON
18 taxExempt: Boolean
19 taxExemptions: JSON
20 totalSpent: String
21 shopifyUpdatedAt: DateTime
22 verifiedEmail: Boolean
23 shop: ShopifyShopBelongsToInput
24}
25
26input CreateShopifyCustomerArguments {
27 shopifyCustomer: CreateShopifyCustomerInput
28}
Example create Invocation
1const shopifyCustomerRecord = await api.shopifyCustomer.create({
2 shopifyCustomer: {
3 // field values for Shopify Customer
4 },
5});
6console.log(shopifyCustomerRecord.id); //=> a string
1const [result, createShopifyCustomer] = useAction(api.shopifyCustomer.create);
2const { data, error, fetching } = result;
3await createShopifyCustomer({
4 shopifyCustomer: {
5 // field values for Shopify Customer
6 },
7});
8console.log(data?.id); //=> a string
1mutation ($shopifyCustomer: CreateShopifyCustomerInput) {
2 createShopifyCustomer(shopifyCustomer: $shopifyCustomer) {
3 success
4 errors {
5 message
6 ... on InvalidRecordError {
7 validationErrors {
8 apiIdentifier
9 message
10 }
11 record
12 model {
13 apiIdentifier
14 }
15 }
16 }
17 shopifyCustomer {
18 __typename
19 id
20 state
21 acceptsMarketing
22 acceptsMarketingUpdatedAt
23 createdAt
24 currency
25 email
26 firstName
27 lastName
28 lastOrderName
29 marketingOptInLevel
30 metafield
31 multipassIdentifier
32 note
33 ordersCount
34 phone
35 shopifyCreatedAt
36 shopifyUpdatedAt
37 tags
38 taxExempt
39 taxExemptions
40 totalSpent
41 updatedAt
42 verifiedEmail
43 }
44 }
45}
Variables
json
{ "shopifyCustomer": {} }
Output

create returns the Shopify Customer. In the JS client, the fields returned can be controlled with the select option. In GraphQL, the return format is the action result format, which includes the record if the action was successful. You can include or exclude the fields you need right in the mutation itself.

create Output Data
type CreateShopifyCustomerResult {
success: Boolean!
errors: [ExecutionError!]
shopifyCustomer: ShopifyCustomer
}

Shopify Customer update

Input

update operates on one Shopify Customer in particular, identified by the id variable.update accepts the following input parameters:

update Input Data
1export interface UpdateShopifyCustomerInput {
2 id?: (Scalars["GadgetID"] | null) | null;
3
4 acceptsMarketing?: (Scalars["Boolean"] | null) | null;
5
6 acceptsMarketingUpdatedAt?: Date | Scalars["ISO8601DateString"] | null;
7
8 shopifyCreatedAt?: Date | Scalars["ISO8601DateString"] | null;
9
10 currency?: (Scalars["String"] | null) | null;
11
12 email?: (Scalars["String"] | null) | null;
13
14 firstName?: (Scalars["String"] | null) | null;
15
16 lastName?: (Scalars["String"] | null) | null;
17
18 lastOrderName?: (Scalars["String"] | null) | null;
19
20 marketingOptInLevel?: (Scalars["String"] | null) | null;
21
22 metafield?: (Scalars["JSON"] | null) | null;
23
24 multipassIdentifier?: (Scalars["String"] | null) | null;
25
26 note?: (Scalars["String"] | null) | null;
27
28 ordersCount?: (Scalars["Float"] | null) | null;
29
30 phone?: (Scalars["String"] | null) | null;
31
32 tags?: (Scalars["JSON"] | null) | null;
33
34 taxExempt?: (Scalars["Boolean"] | null) | null;
35
36 taxExemptions?: (Scalars["JSON"] | null) | null;
37
38 totalSpent?: (Scalars["String"] | null) | null;
39
40 shopifyUpdatedAt?: Date | Scalars["ISO8601DateString"] | null;
41
42 verifiedEmail?: (Scalars["Boolean"] | null) | null;
43
44 shop?: ShopifyShopBelongsToInput | null;
45}
46
47export interface UpdateShopifyCustomerArguments {
48 shopifyCustomer?: UpdateShopifyCustomerInput | null;
49}
1input UpdateShopifyCustomerInput {
2 id: GadgetID
3 acceptsMarketing: Boolean
4 acceptsMarketingUpdatedAt: DateTime
5 shopifyCreatedAt: DateTime
6 currency: String
7 email: String
8 firstName: String
9 lastName: String
10 lastOrderName: String
11 marketingOptInLevel: String
12 metafield: JSON
13 multipassIdentifier: String
14 note: String
15 ordersCount: Float
16 phone: String
17 tags: JSON
18 taxExempt: Boolean
19 taxExemptions: JSON
20 totalSpent: String
21 shopifyUpdatedAt: DateTime
22 verifiedEmail: Boolean
23 shop: ShopifyShopBelongsToInput
24}
25
26input UpdateShopifyCustomerArguments {
27 shopifyCustomer: UpdateShopifyCustomerInput
28}
Example update Invocation
1const shopifyCustomerRecord = await api.shopifyCustomer.update("some-id", {
2 shopifyCustomer: {
3 // field values for Shopify Customer
4 },
5});
6console.log(shopifyCustomerRecord.id); //=> a string
1const [result, updateShopifyCustomer] = useAction(api.shopifyCustomer.update);
2const { data, error, fetching } = result;
3await updateShopifyCustomer({
4 id: "some-id",
5 shopifyCustomer: {
6 // field values for Shopify Customer
7 },
8});
9console.log(data?.id); //=> a string
1mutation ($id: GadgetID!, $shopifyCustomer: UpdateShopifyCustomerInput) {
2 updateShopifyCustomer(id: $id, shopifyCustomer: $shopifyCustomer) {
3 success
4 errors {
5 message
6 ... on InvalidRecordError {
7 validationErrors {
8 apiIdentifier
9 message
10 }
11 record
12 model {
13 apiIdentifier
14 }
15 }
16 }
17 shopifyCustomer {
18 __typename
19 id
20 state
21 acceptsMarketing
22 acceptsMarketingUpdatedAt
23 createdAt
24 currency
25 email
26 firstName
27 lastName
28 lastOrderName
29 marketingOptInLevel
30 metafield
31 multipassIdentifier
32 note
33 ordersCount
34 phone
35 shopifyCreatedAt
36 shopifyUpdatedAt
37 tags
38 taxExempt
39 taxExemptions
40 totalSpent
41 updatedAt
42 verifiedEmail
43 }
44 }
45}
Variables
json
{ "id": "some-id", "shopifyCustomer": {} }
Output

update returns the Shopify Customer. In the JS client, the fields returned can be controlled with the select option. In GraphQL, the return format is the action result format, which includes the record if the action was successful. You can include or exclude the fields you need right in the mutation itself.

update Output Data
type UpdateShopifyCustomerResult {
success: Boolean!
errors: [ExecutionError!]
shopifyCustomer: ShopifyCustomer
}

Shopify Customer delete

The delete action destroys the record.

Input

delete operates on one Shopify Customer in particular, identified by the id variable.

Example delete Invocation
await api.shopifyCustomer.delete("some-id");
const [result, deleteShopifyCustomer] = useAction(api.shopifyCustomer.delete);
const { data, error, fetching } = result;
await deleteShopifyCustomer({
id: "some-id",
});
1mutation ($id: GadgetID!) {
2 deleteShopifyCustomer(id: $id) {
3 success
4 errors {
5 message
6 ... on InvalidRecordError {
7 validationErrors {
8 apiIdentifier
9 message
10 }
11 record
12 model {
13 apiIdentifier
14 }
15 }
16 }
17 }
18}
Variables
json
{ "id": "some-id" }
Output

delete deletes the record, so it returns void in the JS client. In GraphQL it returns only the success and errors from the action result format.

delete Output Data
type DeleteShopifyCustomerResult {
success: Boolean!
errors: [ExecutionError!]
}

Linking to an Existing Child Record

During a create or update operation, you can link to existing child records simply by nesting the data structure on your operation, using an update object wrapper around the child record's properties.

Existing nested child
1const shopifyShopRecord = await api.shopifyShop.create({
2 shopifyShop: {
3 customers: {
4 // Updates existing `shopifyCustomer` record
5 // (`id` of record required),
6 // and links it to shopifyShop.
7 update: {
8 id: "123",
9 acceptsMarketing: "customersAcceptsMarketingValue",
10 },
11 },
12 },
13});
14console.log(shopifyShopRecord.id); //=> a string
1const [result, createShopifyShop] = useAction(api.shopifyShop.create);
2const { data, error, fetching } = result;
3await createShopifyShop({
4 shopifyShop: {
5 customers: {
6 // Updates existing `shopifyCustomer` record
7 // (`id` of record required),
8 // and links it to shopifyShop.
9 update: {
10 id: "123",
11 acceptsMarketing: "customersAcceptsMarketingValue",
12 },
13 },
14 },
15});
16console.log(data?.id); //=> a string
1mutation ($shopifyShop: CreateShopifyShopInput) {
2 createShopifyShop(shopifyShop: $shopifyShop) {
3 success
4 errors {
5 message
6 }
7 shopifyShop {
8 id
9 customers
10 customers {
11 id
12 }
13 }
14 }
15}
Variables
json
{
"customers": {
"update": { "id": "123", "acceptsMarketing": "customersAcceptsMarketingValue" }
}
}

Linking to a New Child Record

During a create or update operation, you can create linked child records simply by nesting the data structure on your operation, using a create object wrapper around the child record's properties.

New nested child
1const shopifyShopRecord = await api.shopifyShop.create({
2 shopifyShop: {
3 customers: {
4 // Creates `shopifyCustomer` record,
5 // linked to shopifyShop.
6 create: {
7 acceptsMarketing: "customersAcceptsMarketingValue",
8 },
9 },
10 },
11});
12console.log(shopifyShopRecord.id); //=> a string
1const [result, createShopifyShop] = useAction(api.shopifyShop.create);
2const { data, error, fetching } = result;
3await createShopifyShop({
4 shopifyShop: {
5 customers: {
6 // Creates `shopifyCustomer` record,
7 // linked to shopifyShop.
8 create: {
9 acceptsMarketing: "customersAcceptsMarketingValue",
10 },
11 },
12 },
13});
14console.log(data?.id); //=> a string
1mutation ($shopifyShop: CreateShopifyShopInput) {
2 createShopifyShop(shopifyShop: $shopifyShop) {
3 success
4 errors {
5 message
6 }
7 shopifyShop {
8 id
9 customers
10 customers {
11 id
12 }
13 }
14 }
15}
Variables
json
{
"customers": { "create": { "acceptsMarketing": "customersAcceptsMarketingValue" } }
}

Linking to an Existing Parent Record

When you wish to link to an existing parent record, you must use a _link property in your data, with the id of the parent record that this child record will belong to.

Linked creation
1const shopifyCustomerRecord = await api.shopifyCustomer.create({
2 shopifyCustomer: {
3 acceptsMarketing: "acceptsMarketingValue",
4 shop: {
5 _link: "123",
6 },
7 },
8});
9console.log(shopifyCustomerRecord.id); //=> a string
1const [result, createShopifyCustomer] = useAction(api.shopifyCustomer.create);
2const { data, error, fetching } = result;
3await createShopifyCustomer({
4 shopifyCustomer: {
5 acceptsMarketing: "acceptsMarketingValue",
6 shop: {
7 _link: "123",
8 },
9 },
10});
11console.log(data?.id); //=> a string
1mutation ($shopifyCustomer: CreateShopifyCustomerInput) {
2 createShopifyCustomer(shopifyCustomer: $shopifyCustomer) {
3 success
4 errors {
5 message
6 }
7 shopifyCustomer {
8 id
9 acceptsMarketing
10 shop {
11 id
12 }
13 }
14 }
15}
Variables
json
{ "acceptsMarketing": "acceptsMarketingValue", "shop": { "_link": "123" } }

Linking to a New Parent Record

You cannot directly link to a new parent record when creation a child record. However, you can jointly create both parent and child via the Linking to a New Child Record method.

Bulk Actions

Actions that support it can be performed in bulk. Bulk Actions are executed as a single GraphQL mutation and have a corresponding function available in the API client libraries. Bulk Actions are performed on a set of ids. Bulk Actions repeat the same action, with the same options and parameters, across all ids and should not be confused with batching up different actions in the same request.

Bulk Actions will be performed on the entire set. If an action fails on an individual record, the Bulk Action will still occur on the other records in the set. Only the records which completed the action successfully will be returned.

Bulk Shopify Customer delete

bulkDeleteShopifyCustomers action destroys the records.

Input

bulkDeleteShopifyCustomers operates on a set of Shopify Customers, identified by the ids variable.

Example bulkDeleteShopifyCustomers Invocation
await api.shopifyCustomer.bulkDelete(["some-id", "another-id"]);
const [shopifyCustomerResult, bulkDelete] = useBulkAction(
api.shopifyCustomer.bulkDelete
);
const { data, error, fetching } = result;
await bulkDelete({ ids: ["some-id", "another-id"] });
1mutation ($ids: [GadgetID!]!) {
2 bulkDeleteShopifyCustomers(ids: $ids) {
3 success
4 errors {
5 message
6 }
7 }
8}
Variables
json
{ "ids": ["some-id", "another-id"] }
Output

bulkDeleteShopifyCustomers deletes the record, so it returns void in the JS client. In GraphQL it returns only the success and errors from the action result format.

bulkDeleteShopifyCustomers Output Data
type BulkDeleteShopifyCustomersResult {
success: Boolean!
errors: [ExecutionError!]
}