Pull from Shopify (GraphQL)

Shopify is an e-commerce platform for online stores and retail point-of-sale systems that consolidates shopping, payments, marketing, shipping, and customer engagement tools into a single unified experience.

Shopify (GraphQL) pulls customer, order, product, and location data into Amperity using the Shopify GraphQL Admin API . It reads the same Shopify store as the REST-based Shopify source and can run alongside it.

Select the data types to pull. Amperity creates a feed and a domain table for each selected data type. Each courier run reads records that were updated within the run’s time range; because Shopify sets the updated timestamp when a record is created, records that are new to the store are included as well. Location records are the exception – Shopify does not filter locations by an updated timestamp, so every location is read on each run.

Beta

The Shopify (GraphQL) connector is currently in beta. Contact your Amperity representative to learn more.

The steps that are required to pull customer, order, product, and location data to Amperity from Shopify (GraphQL):

  1. Get details

  2. Add courier

  3. Run courier

  4. Review feed and domain table

  5. Add to courier group

Get details

Shopify (GraphQL) requires the following configuration details:

  1. The Shop name and Access token for Shopify (GraphQL).

    Generate an Admin API access token by creating and installing a custom app in your Shopify store’s admin. Sending an audience requires the write_customers access scope on the app; pulling data requires read access to the data types that you select.

  2. The data types to pull. You can select any combination of the following:

    • customer, customer-address, customer-metafield, and customer-tags

    • order, order-line, order-line-refund, order-tags, discount-allocation, and discount-codes

    • product, product-tags, and product-variant

    • locations

  3. The Ingest strategy (optional) that controls how Amperity reads from Shopify:

    • auto (the default) runs a bulk export for a full historical load and paginated queries for a run that is bounded to a time range.

    • bulk forces a bulk export, which is worth doing for a bounded but very large backfill.

    • paginated forces paginated queries.

    The order-line-refund data type cannot be exported in bulk. Under auto it is read with paginated queries automatically; when the Ingest strategy is set to bulk and order-line-refund is selected, the run stops with an error.

Note

On the paginated strategy, a parent record that has more than 250 related child records – for example, an order with more than 250 line items, or a customer with more than 250 addresses or metafields – has the additional child records truncated. A bulk export has no such limit. Under auto, a run that is bounded to a time range uses the paginated strategy, so use bulk to read a parent that has a very large number of child records.

Tip

Use SnapPass to securely share configuration details for Shopify (GraphQL) between your company and your Amperity representative.

Add courier

A courier brings data from an external system to Amperity.

To add a courier

  1. From the Sources page, click Add Courier. The Add Courier page opens.

  2. Find, and then click the icon for Shopify (GraphQL). The Add Courier page opens.

  3. Enter the name of the courier. For example: “Shopify (GraphQL)”.

    From the Credential field, select an existing credential or select Create a new credential.

    To add a credential, enter the name of the credential, a description, and the Shopify (GraphQL) Shop name and Access token. Click Save.

    When finished click Continue.

  4. Under Data types, select the data types to pull to Amperity.

  5. Optionally, set the Ingest strategy.

  6. Click Create.

    Amperity creates a feed and a domain table for each selected data type.

Run courier manually

Run the courier again. This time, because the load operations are present and the feeds are configured, the courier will pull data from Shopify (GraphQL).

To run the courier manually

  1. From the Sources tab, open the menu for the courier with updated load operations that is configured for Shopify (GraphQL), and then select Run. The Run Courier dialog box opens.

  2. Select the load option, either for a specific time period or all available data. Actual data will be loaded to a domain table because the feed is configured.

  3. Click Run.

    This time the notification will return a message similar to:

    Completed in 5 minutes 12 seconds

Review feed and domain table

After running the Shopify (GraphQL) courier, a feed and domain table are created automatically for each data type that you selected. You may apply semantic tags to the fields in these tables and you may make a domain table available to Stitch, depending on your use case.

Each domain table’s columns are the fields that Amperity reads for the corresponding Shopify object:

  • Customers – customer identity and contact details, email marketing consent, order and spend summary, and tags, along with each customer’s addresses and metafields.

  • Orders – order identity, financial and fulfillment status, monetary totals, currency, and timestamps, along with line items, refunded line items, tags, discount codes, and per-line discount allocations.

  • Products – product identity, type, status, price range, inventory, and tags, along with each product’s variants (price, inventory, weight, and options).

  • Locations – store locations with their address details.

Add to courier group

  1. From the Sources tab, click Add Courier Group. This opens the Create Courier Group dialog box.

  2. Enter the name of the courier. For example: “Shopify (GraphQL)”.

  3. Add a cron string to the Schedule field to define a schedule for the orchestration group.

    A schedule defines the frequency at which a courier group runs. All couriers in the same courier group run as a unit and all tasks must complete before a downstream process starts. Define a schedule using cron.

    Cron syntax specifies the fixed time, date, or interval at which cron runs. Each line represents a job. 30 8 * * * represents “run at 8:30 AM every day” and 30 8 * * 0 represents “run at 8:30 AM every Sunday”.

    For example:

    ┌───────── minute (0 - 59)
│ ┌─────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌────────────── month (1 - 12)
│ │ │ │ ┌─────────────── day of the week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
│ │ │ │ │
│ │ │ │ │
* * * * * command to execute

    Amperity validates the cron syntax and shows you the results. You may also use crontab guru to validate cron syntax.

  4. Set Status to Enabled.

  5. Specify a time zone.

    A courier group schedule is associated with a time zone. The time zone determines the point at which a courier group’s scheduled start time begins. A time zone should be aligned with the time zone of system from which the data is being pulled.

    Use the Use this time zone for file date ranges checkbox to use the selected time zone to look for files. If unchecked, the courier group uses the current time in UTC to look for files to pick up.

    Note

    The time zone that is chosen for an courier group schedule should consider every downstream business processes that requires the data and also the time zones in which the consumers of that data will operate.

  6. Add at least one courier to the courier group. Select the name of the courier from the Courier dropdown. Click + Add Courier to add more couriers.

  7. Click Add a courier group constraint, and then select a courier group from the dropdown list.

    A wait time is a constraint placed on a courier group that defines an extended time window for data to be made available at the source location.

    Important

    A wait time is not required for a bridge.

    A courier group typically runs on an automated schedule that expects customer data to be available at the source location within a defined time window. However, in some cases, the customer data may be delayed and is not made available within that time window.

  8. For each courier group constraint, apply any offsets.

    A courier can be configured to look for files within range of time that is older than the scheduled time. The scheduled time is in Coordinated Universal Time (UTC), unless the “Use this time zone for file date ranges” checkbox is enabled for the courier group.

    This range is typically 24 hours, but may be configured for longer ranges. For example, it is possible for a data file to be generated with a correct file name and datestamp appended to it, but for that datestamp to represent the previous day because of how an upstream workflow is configured. A wait time helps ensure that the data at the source location is recognized correctly by the courier.

    Warning

    This range of time may affect couriers in a courier group whether or not they run on a schedule. A manually run courier group may not take its schedule into consideration when determining the date range. Only the provided input days to load data from are used as inputs.

  9. Click Save.