Shopify

Authentication Type: OAuth (Client Credentials) Description: Access Shopify store data including customers, orders, products, fulfillments, draft orders, and refunds. Supports 13 operations across orders, products, customers, fulfillments, draft orders, and refund management.

Authentication

To authenticate with the Shopify integration, you need a Shopify app configured with the Client Credentials grant type. This uses short-lived tokens (24-hour expiry) that are automatically refreshed.

Go to your Shopify Partners Dashboard and create a new app (or open an existing one)
Under Configuration, add the following Admin API access scopes:

Scope	Required For
`read_customers`	Search Customers, Get Customer, Get Orders by Email
`write_customers`	(reserved for future write operations)
`read_orders`	Get Order, List Orders, Get Fulfillments
`write_orders`	Calculate Refund, Create Refund
`read_all_orders`	Get Orders by Email (access orders older than 60 days)
`read_products`	Get Product, List Products
`read_draft_orders`	(read access for draft order queries)
`write_draft_orders`	Create Draft Order, Send Invoice, Complete Draft Order
`read_locations`	Get Fulfillments (resolves fulfillment location names)

Install the app on your store
In Cotera, enter three credential fields:
- shopDomain: Your store domain (e.g., yourstore.myshopify.com)
- clientId: The app's Client ID from the Partners Dashboard
- clientSecret: The app's Client Secret from the Partners Dashboard

Cotera automatically handles token exchange and refresh using the Shopify Client Credentials Grant. Tokens are cached and refreshed before expiry.

Order Management

Retrieve and browse orders from your Shopify store.

Get Order

Get detailed information about a specific Shopify order by its internal ID or human-readable order number. Returns the full order including line items, customer details, shipping address, financial and fulfillment status.

Operation Type: Query (Read)

Parameters:

orderId string (nullable): The internal Shopify order ID (e.g., "5678901234"). Use this OR orderNumber, not both.
orderNumber string (nullable): The human-readable order number (e.g., "1001" or "#1001"). Use this OR orderId, not both.

Returns:

id string: Order ID
name string: Order name (e.g., "#1001")
email string (nullable): Customer email on the order
phone string (nullable): Customer phone number
createdAt string: Order creation timestamp (ISO 8601)
updatedAt string: Last update timestamp
closedAt string (nullable): When the order was closed
cancelledAt string (nullable): When the order was cancelled
cancelReason string (nullable): Reason for cancellation
totalPrice string: Total order price
subtotalPrice string: Subtotal before tax/shipping
totalTax string: Total tax amount
totalDiscounts string: Total discount amount
currency string: Currency code (e.g., "USD")
financialStatus string: Payment status (paid, pending, refunded, etc.)
fulfillmentStatus string (nullable): Fulfillment status (fulfilled, partial, null)
orderNumber number: Human-readable order number
note string (nullable): Internal note on the order
tags string: Comma-separated tags
customer object (nullable): Customer who placed the order
- id string: Customer ID
- email string (nullable): Customer email
- firstName string (nullable): First name
- lastName string (nullable): Last name
lineItems array of objects: Items in the order
- id string: Line item ID
- productId string (nullable): Product ID
- title string: Product title
- quantity number: Quantity ordered
- price string: Item price
- sku string (nullable): SKU
- variantId string (nullable): Variant ID
- variantTitle string (nullable): Variant title
- fulfillmentStatus string (nullable): Per-item fulfillment status
shippingAddress object (nullable): Shipping address
- address1 string (nullable): Street address
- address2 string (nullable): Apartment/suite
- city string (nullable): City
- province string (nullable): State/province
- country string (nullable): Country
- zip string (nullable): Zip/postal code

Example Usage:

{
  "orderId": "5678901234"
}

Or by order number:

{
  "orderNumber": "1001"
}

List Orders

List recent Shopify orders with optional filters for status, financial status, fulfillment status, and date ranges. Use this to get a high-level view of orders or to find orders matching specific criteria.

Operation Type: Query (Read)

Parameters:

status string (nullable): Filter by order status: open, closed, cancelled, any (default: open)
financialStatus string (nullable): Filter by financial status: authorized, pending, paid, partially_paid, refunded, voided, partially_refunded, any
fulfillmentStatus string (nullable): Filter by fulfillment status: shipped, partial, unshipped, unfulfilled, any
createdAtMin string (nullable): Show orders created at or after this date (ISO 8601)
createdAtMax string (nullable): Show orders created at or before this date (ISO 8601)
updatedAtMin string (nullable): Show orders updated at or after this date (ISO 8601)
updatedAtMax string (nullable): Show orders updated at or before this date (ISO 8601)
limit number (nullable): Maximum number of orders to return (default: 50, max: 250)

Returns:

orders array of objects: List of orders matching the filters
- id string: Order ID
- name string: Order name (e.g., "#1001")
- email string (nullable): Customer email
- createdAt string: Order creation timestamp
- updatedAt string: Last update timestamp
- totalPrice string: Total order price
- subtotalPrice string: Subtotal
- currency string: Currency code
- financialStatus string: Payment status
- fulfillmentStatus string (nullable): Fulfillment status
- orderNumber number: Human-readable order number
- note string (nullable): Internal note
- tags string: Comma-separated tags
- lineItemCount number: Number of line items
- customer object (nullable): Customer details
count number: Total number of orders returned

Example Usage:

{
  "status": "open",
  "financialStatus": "paid",
  "fulfillmentStatus": "unfulfilled",
  "limit": 25
}

Get Customer Orders by Email

Find a customer by their email address and retrieve all their orders with details including line items, pricing, and fulfillment status. Use this for support workflows where you have the customer's email but not their order ID.

Operation Type: Query (Read)

Parameters:

customerEmail string (required): Email address of the customer to find orders for

Returns:

customer object: Customer information
- id string: Customer ID
- email string: Customer email
- firstName string (nullable): First name
- lastName string (nullable): Last name
- totalSpent string (nullable): Total amount spent
- currency string (nullable): Currency code
- ordersCount number: Total number of orders
orders array of objects: All orders placed by this customer
- id string: Order ID
- name string: Order name (e.g., "#1001")
- email string (nullable): Email on the order
- createdAt string: Order creation timestamp
- updatedAt string: Last update timestamp
- totalPrice string: Total price
- subtotalPrice string: Subtotal
- currency string: Currency code
- financialStatus string: Payment status
- fulfillmentStatus string (nullable): Fulfillment status
- lineItems array of objects: Items in the order
  - id string: Line item ID
  - productId string (nullable): Product ID
  - title string: Product title
  - quantity number: Quantity ordered
  - price string: Item price
  - variant object (nullable): Variant details (id, title)

Example Usage:

{
  "customerEmail": "john.smith@example.com"
}

Product Catalog

Browse and look up products in your Shopify store.

Get Product by ID

Get detailed information about a specific Shopify product including all variants, images, and options. Use this when you need the full product details like pricing, inventory, and available sizes/colors.

Operation Type: Query (Read)

Parameters:

productId string (required): The numeric Shopify product ID (e.g., "7890123456")

Returns:

id string: Product ID
title string: Product title
bodyHtml string (nullable): HTML product description
vendor string (nullable): Product vendor
productType string (nullable): Product type category
handle string (nullable): URL-friendly handle
status string: Product status (active, draft, archived)
publishedAt string (nullable): When the product was published
createdAt string: Creation timestamp
updatedAt string: Last update timestamp
tags string: Comma-separated tags
variants array of objects: Product variants
- id string: Variant ID
- title string: Variant title (e.g., "Large / Blue")
- price string: Variant price
- compareAtPrice string (nullable): Compare-at price for sales
- sku string (nullable): SKU
- inventoryQuantity number (nullable): Stock quantity
- weight number (nullable): Weight (not available via GraphQL, always null)
- weightUnit string (nullable): Weight unit (not available via GraphQL, always null)
images array of objects: Product images
- id string: Image ID
- src string: Image URL
- position number: Display order
- width number (nullable): Image width in pixels
- height number (nullable): Image height in pixels
options array of objects: Product options (e.g., Size, Color)
- id string: Option ID
- name string: Option name
- values array of strings: Available values

Example Usage:

{
  "productId": "7890123456"
}

List Products

List Shopify products with optional filters for title, vendor, product type, collection, and date ranges. Returns summary info with variant count and price ranges for each product.

Operation Type: Query (Read)

Parameters:

title string (nullable): Filter products by title
vendor string (nullable): Filter products by vendor
productType string (nullable): Filter products by product type
collectionId string (nullable): Filter products by collection ID
publishedStatus string (nullable): Filter by published status: published, unpublished, any (default: any)
createdAtMin string (nullable): Show products created at or after this date (ISO 8601)
createdAtMax string (nullable): Show products created at or before this date (ISO 8601)
updatedAtMin string (nullable): Show products updated at or after this date (ISO 8601)
updatedAtMax string (nullable): Show products updated at or before this date (ISO 8601)
limit number (nullable): Maximum number of products to return (default: 50, max: 250)

Returns:

products array of objects: List of products matching the filters
- id string: Product ID
- title string: Product title
- vendor string (nullable): Vendor name
- productType string (nullable): Product type
- handle string (nullable): URL handle
- status string: Product status
- publishedAt string (nullable): Publication date
- createdAt string: Creation date
- updatedAt string: Last update date
- tags string: Comma-separated tags
- variantCount number: Number of variants
- imageCount number: Number of images
- priceRange object: Price range across variants
  - min string: Lowest variant price
  - max string: Highest variant price
count number: Total number of products returned

Example Usage:

{
  "vendor": "Nike",
  "productType": "Shoes",
  "publishedStatus": "published",
  "limit": 50
}

Customer Management

Find and look up customer details in your Shopify store.

Search Customers

Search for Shopify customers by name, email, phone, or other fields. Returns matching customers with their order history stats, contact info, and default address.

Operation Type: Query (Read)

Parameters:

query string (required): Search query to find customers. Searches across name, email, phone, and other fields.
limit number (nullable): Maximum number of customers to return (default: 50, max: 250)

Returns:

customers array of objects: Matching customers
- id string: Customer ID
- email string (nullable): Email address
- firstName string (nullable): First name
- lastName string (nullable): Last name
- phone string (nullable): Phone number
- ordersCount number: Total number of orders
- totalSpent string: Total amount spent
- currency string (nullable): Currency code
- state string: Account state (enabled, disabled, invited)
- tags string: Comma-separated tags
- createdAt string: Account creation date
- updatedAt string: Last update date
- verifiedEmail boolean: Whether email is verified
- note string (nullable): Internal note
- defaultAddress object (nullable): Default shipping address
count number: Total number of matching customers

Example Usage:

{
  "query": "john smith",
  "limit": 10
}

Get Customer by ID

Get detailed information about a specific Shopify customer by their ID, including all addresses, order stats, and account details. Use this after finding a customer via search to get their full profile.

Operation Type: Query (Read)

Parameters:

customerId string (required): The numeric Shopify customer ID (e.g., "1234567890")

Returns:

id string: Customer ID
email string (nullable): Email address
firstName string (nullable): First name
lastName string (nullable): Last name
phone string (nullable): Phone number
ordersCount number: Total number of orders
totalSpent string: Total amount spent
currency string (nullable): Currency code
state string: Account state
tags string: Comma-separated tags
createdAt string: Account creation date
updatedAt string: Last update date
verifiedEmail boolean: Whether email is verified
note string (nullable): Internal note
taxExempt boolean: Whether customer is tax exempt
addresses array of objects: All saved addresses
- id string: Address ID
- address1 string (nullable): Street address
- address2 string (nullable): Apartment/suite
- city string (nullable): City
- province string (nullable): State/province
- country string (nullable): Country
- zip string (nullable): Zip/postal code
- phone string (nullable): Phone number
- name string (nullable): Full name
- company string (nullable): Company name
- isDefault boolean: Whether this is the default address

Example Usage:

{
  "customerId": "1234567890"
}

Fulfillment Management

Get detailed fulfillment and shipping information for orders.

Get Order Fulfillments

Get detailed fulfillment information for an order including tracking numbers, shipping carrier, fulfillment status, and which line items were included in each shipment. Also includes fulfillment location names.

Operation Type: Query (Read)

Parameters:

orderId string (required): Shopify order ID to get fulfillments for

Returns:

orderId string: Order ID
fulfillments array of objects: Fulfillments for the order
- id string: Fulfillment ID
- status string: Fulfillment status (fulfilled, partial, cancelled)
- trackingNumber string (nullable): Tracking number
- trackingUrls array of strings: Tracking URLs
- trackingCompany string (nullable): Shipping carrier
- createdAt string: Fulfillment creation date
- updatedAt string: Last update date
- shipmentStatus string (nullable): Shipment delivery status
- lineItems array of objects: Items in this fulfillment
  - id string: Line item ID
  - title string: Product title
  - quantity number: Quantity fulfilled
  - variantId string (nullable): Variant ID
  - variantTitle string (nullable): Variant title
- location object (nullable): Fulfillment location
  - id string: Location ID
  - name string: Location name

Example Usage:

{
  "orderId": "5678901234"
}

Draft Order Management

Create, send invoices for, and complete draft orders. Draft orders let you build custom orders for customers and send them an invoice to pay before fulfillment.

Create Draft Order

Create a draft order in Shopify with custom line items, customer info, shipping address, and optional discounts. Use this for custom quotes, manual orders, B2B invoicing, or any order that needs customer payment before fulfillment.

Operation Type: Mutation (Write)

Parameters:

lineItems array of objects (required): Items to include in the draft order. At least one line item is required.
- title string: Product or line item name shown on the invoice
- price string: Unit price as a decimal string (e.g., "299.99")
- quantity number: Number of units
- variantId string (nullable): Shopify product variant ID if from your catalog. Pass null for custom line items.
customerEmail string (nullable): Email address of the customer
customerId string (nullable): Shopify customer ID if already known. Takes precedence over customerEmail.
note string (nullable): Internal note attached to the draft order (visible to staff only)
shippingAddress object (nullable): Shipping address. Pass null for digital products or services.
- firstName string (nullable): Recipient's first name
- lastName string (nullable): Recipient's last name
- address1 string (nullable): Street address
- city string (nullable): City
- province string (nullable): State or province
- zip string (nullable): ZIP or postal code
- country string (nullable): Country code (e.g., "US", "CA")
appliedDiscount object (nullable): Discount to apply to the entire order
- description string (nullable): Reason for the discount (internal)
- valueType string: Either "percentage" or "fixed_amount"
- value string: Discount value (e.g., "10" for 10%, or "5.00" for $5 off)
- title string (nullable): Discount title shown to customer

Returns:

draftOrderId string: The draft order ID (use with send-invoice and complete tools)
name string: Draft order name/number (e.g., "#D1234")
status string: Status ("open", "invoice_sent", or "completed")
totalPrice string: Total price
currency string: Currency code
invoiceUrl string (nullable): URL the customer can visit to pay
createdAt string: Creation timestamp

Example Usage:

{
  "lineItems": [
    {
      "title": "Custom Website Design Package",
      "price": "2500.00",
      "quantity": 1,
      "variantId": null
    }
  ],
  "customerEmail": "client@example.com",
  "note": "Q1 consulting engagement",
  "appliedDiscount": {
    "valueType": "percentage",
    "value": "10",
    "title": "Early Bird Discount"
  }
}

Send Draft Order Invoice

Send an invoice email to a customer for a draft order. The email contains a link where the customer can review the order and complete payment.

Operation Type: Mutation (Write)

Parameters:

draftOrderId string (required): The draft order ID from create-draft-order
to string (nullable): Email address to send the invoice to. If null, sends to the email on the draft order.
subject string (nullable): Custom email subject line. If null, uses Shopify's default.
customMessage string (nullable): Custom message to include in the invoice email body

Returns:

success boolean: Whether the invoice was sent successfully
draftOrderId string: The draft order ID

Example Usage:

{
  "draftOrderId": "1234567890",
  "subject": "Your invoice from Our Store",
  "customMessage": "Thanks for your order! Please complete payment at your earliest convenience."
}

Complete Draft Order

Convert a draft order into a real Shopify order. This finalizes the draft and creates a standard order that can be fulfilled.

Operation Type: Mutation (Write)

Parameters:

draftOrderId string (required): The draft order ID to complete
paymentPending boolean (nullable): If true, marks the order as "payment pending" (customer has not yet paid). If false or null, marks it as paid. Use true for net-30 terms or when completing before payment.

Returns:

draftOrderId string: The draft order ID
orderId string (nullable): The Shopify order ID of the created order
orderName string (nullable): The order name/number (e.g., "#1234")
status string: Draft order status after completion ("completed")

Example Usage:

{
  "draftOrderId": "1234567890",
  "paymentPending": false
}

Refund Management

Calculate and process refunds for orders and line items.

Calculate Refund

Calculate the refund amount and transactions for specific line items. Use this before creating an actual refund to preview accurate amounts and get the transaction data needed for processing.

Operation Type: Mutation (Write)

Parameters:

orderId string (required): Shopify order ID to calculate refund for
lineItemIds array of strings (required): Array of line item IDs to refund
quantities array of numbers (required): Array of quantities to refund for each line item (same order as lineItemIds)
refundShipping boolean (nullable): Whether to refund shipping costs
reason string (nullable): Reason for the refund

Returns:

orderId string: Order ID
refundAmount string: Total calculated refund amount
currency string: Currency code
transactions array of objects: Suggested refund transactions (pass to Create Refund)
- parentId string: Parent transaction ID
- amount string: Transaction amount
- gateway string: Payment gateway
- maxRefundable string: Maximum refundable amount
refundLineItems array of objects: Line items being refunded
- lineItemId string: Line item ID
- quantity number: Quantity to refund
- price string: Item price
- subtotal string: Subtotal for this item
shipping object: Shipping refund details
- amount string: Shipping refund amount
- maxRefundable string: Maximum refundable shipping

Example Usage:

{
  "orderId": "5678901234",
  "lineItemIds": ["11111111", "22222222"],
  "quantities": [1, 2],
  "refundShipping": true,
  "reason": "Customer requested return due to sizing issue"
}

Create Refund

Process an actual refund for a Shopify order. Use the transaction data from Calculate Refund to ensure accurate processing. This will charge back the customer's payment method and update the order status.

Operation Type: Mutation (Write)

Parameters:

orderId string (required): Shopify order ID to create refund for
lineItemIds array of strings (required): Array of line item IDs to refund
quantities array of numbers (required): Array of quantities to refund for each line item (same order as lineItemIds)
refundShipping boolean (nullable): Whether to refund shipping costs
reason string (nullable): Reason for the refund
notify boolean (nullable): Whether to notify the customer via email
transactionData string (nullable): JSON string of transaction data from Calculate Refund (required for processing)

Returns:

refundId string: Created refund ID
orderId string: Order ID
refundAmount string: Total refund amount
currency string: Currency code
status string: Refund status (success or pending)
createdAt string: Refund creation timestamp
reason string (nullable): Refund reason
transactions array of objects: Refund transactions
- id string: Transaction ID
- amount string: Transaction amount
- kind string: Transaction kind (refund)
- gateway string: Payment gateway
- status string: Transaction status

Example Usage:

{
  "orderId": "5678901234",
  "lineItemIds": ["11111111"],
  "quantities": [1],
  "refundShipping": false,
  "reason": "Defective product",
  "notify": true,
  "transactionData": "{\"transactions\":[{\"parentId\":\"12345\",\"amount\":\"25.99\",\"gateway\":\"shopify_payments\"}]}"
}

Common Use Cases

Customer Service and Support:

Look up customer order history by email address for support inquiries
Search customers by name or phone number to find their account
Get full customer profiles with saved addresses and order stats
Track fulfillment status and shipping information for delivery inquiries
Process partial or full refunds for returns and complaints

Order Management:

List recent unfulfilled orders to prioritize shipping
Filter orders by financial or fulfillment status for operational dashboards
Get detailed order information including line items and shipping address
Monitor order volume and trends over time with date range filters

Product and Inventory:

Browse products by vendor, type, or collection to review catalog
Get full product details including variant pricing and inventory levels
Monitor recently updated products for catalog change tracking
Review price ranges across product variants

Draft Orders and Invoicing:

Create custom quotes and manual orders for B2B customers
Send professional invoices with payment links via email
Support net-30 or other deferred payment terms
Build orders with custom line items not tied to catalog products

Financial Operations:

Calculate refund amounts before processing to ensure accuracy
Process refunds with detailed transaction tracking
Track refund status and payment gateway information
Generate order financial reports filtered by payment status