Actions

The ballerinax/shopify.admin package exposes the following clients:

Client	Purpose
`Client`	Shopify Admin REST API: manage customers, products, orders, fulfillments, webhooks, and more.

Client

Shopify Admin REST API: manage customers, products, orders, fulfillments, webhooks, and more.

Configuration

Field	Type	Default	Description
`xShopifyAccessToken`	`string`	Required	The Shopify Admin API access token (`X-Shopify-Access-Token` header).

Initializing the client

import ballerinax/shopify.admin;

configurable string accessToken = ?;
configurable string storeUrl = ?;

admin:ApiKeysConfig apiKeyConfig = {
    xShopifyAccessToken: accessToken
};

admin:Client shopify = check new (apiKeyConfig, storeUrl);

Operations

Customer management

getCustomers

Retrieves a list of customers with optional filtering by IDs, date ranges, and pagination.

Parameters:

Name	Type	Required	Description
`ids`	`string?`	No	Comma-separated list of customer IDs to restrict results.
`sinceId`	`string?`	No	Restrict results to those after the specified ID.
`createdAtMin`	`string?`	No	Show customers created after this date (ISO 8601).
`createdAtMax`	`string?`	No	Show customers created before this date (ISO 8601).
`updatedAtMin`	`string?`	No	Show customers last updated after this date (ISO 8601).
`updatedAtMax`	`string?`	No	Show customers last updated before this date (ISO 8601).
`'limit`	`int?`	No	Maximum number of results to show (default: 50, max: 250).
`fields`	`string?`	No	Comma-separated list of fields to include in the response.

Returns: CustomerList|error

Sample code:

admin:CustomerList customers = check shopify->getCustomers('limit = 10);

Sample response:

{
  "customers": [
    {
      "id": 6940095127745,
      "first_name": "Steve",
      "last_name": "Lastnameson",
      "email": "[email protected]",
      "orders_count": 0,
      "state": "disabled",
      "total_spent": "0.00",
      "created_at": "2024-01-15T10:30:00-05:00"
    }
  ]
}

createCustomer

Creates a new customer record.

Parameters:

Name	Type	Required	Description
`payload`	`CreateCustomer`	Yes	The Customer object to be created.

Returns: CustomerObject|error

Sample code:

admin:CreateCustomer payload = {
    customer: {
        first_name: "Steve",
        last_name: "Lastnameson",
        email: "[email protected]"
    }
};
admin:CustomerObject result = check shopify->createCustomer(payload);

Sample response:

{
  "customer": {
    "id": 6940095127745,
    "first_name": "Steve",
    "last_name": "Lastnameson",
    "email": "[email protected]",
    "created_at": "2024-01-15T10:30:00-05:00",
    "orders_count": 0,
    "state": "disabled",
    "total_spent": "0.00",
    "verified_email": true
  }
}

getCustomer

Retrieves a single customer by ID.

Parameters:

Name	Type	Required	Description
`customerId`	`string`	Yes	The customer ID.
`fields`	`string?`	No	Comma-separated list of fields to include.

Returns: CustomerObject|error

Sample code:

admin:CustomerObject customer = check shopify->getCustomer("6940095127745");

Sample response:

{
  "customer": {
    "id": 6940095127745,
    "first_name": "Steve",
    "last_name": "Lastnameson",
    "email": "[email protected]",
    "orders_count": 0,
    "state": "disabled"
  }
}

updateCustomer

Updates an existing customer.

Parameters:

Name	Type	Required	Description
`customerId`	`string`	Yes	The customer ID.
`payload`	`UpdateCustomer`	Yes	The Customer object with updated fields.

Returns: CustomerObject|error

Sample code:

admin:CustomerObject updated = check shopify->updateCustomer("6940095127745", {
    customer: {
        first_name: "Steven",
        tags: "VIP,loyal"
    }
});

Sample response:

{
  "customer": {
    "id": 6940095127745,
    "first_name": "Steven",
    "last_name": "Lastnameson",
    "email": "[email protected]",
    "tags": "VIP,loyal"
  }
}

searchCustomers

Searches for customers matching a supplied query.

Parameters:

Name	Type	Required	Description
`query`	`string?`	No	Text to search for in the shop's customer data.
`'order`	`string?`	No	Field and direction by which to order results (default: `last_order_date DESC`).
`'limit`	`int?`	No	Maximum number of results (default: 50, max: 250).
`fields`	`string?`	No	Comma-separated list of fields to include.

Returns: CustomerList|error

Sample code:

admin:CustomerList results = check shopify->searchCustomers(query = "steve");

Sample response:

{
  "customers": [
    {
      "id": 6940095127745,
      "first_name": "Steve",
      "last_name": "Lastnameson",
      "email": "[email protected]"
    }
  ]
}

Product management

getProducts

Retrieves a list of products with optional filtering by title, vendor, status, collection, and date ranges.

Parameters:

Name	Type	Required	Description
`ids`	`string?`	No	Comma-separated list of product IDs.
`'limit`	`int?`	No	Maximum results per page (default: 50, max: 250).
`title`	`string?`	No	Filter by product title.
`vendor`	`string?`	No	Filter by product vendor.
`productType`	`string?`	No	Filter by product type.
`status`	`string?`	No	Filter by status: `active`, `archived`, or `draft` (default: `active`).
`fields`	`string?`	No	Comma-separated list of fields to include.

Returns: ProductList|error

Sample code:

admin:ProductList products = check shopify->getProducts(status = "active", 'limit = 5);

Sample response:

{
  "products": [
    {
      "id": 7982605344961,
      "title": "Classic T-Shirt",
      "vendor": "Acme",
      "product_type": "Apparel",
      "status": "active",
      "created_at": "2024-01-10T08:00:00-05:00"
    }
  ]
}

createProduct

Creates a new product.

Parameters:

Name	Type	Required	Description
`payload`	`CreateProduct`	Yes	The Product object to be created.

Returns: ProductObject|error

Sample code:

admin:ProductObject product = check shopify->createProduct({
    product: {
        title: "Classic T-Shirt",
        body_html: "<p>A comfortable cotton t-shirt.</p>",
        vendor: "Acme",
        product_type: "Apparel",
        tags: "cotton,summer"
    }
});

Sample response:

{
  "product": {
    "id": 7982605344961,
    "title": "Classic T-Shirt",
    "body_html": "<p>A comfortable cotton t-shirt.</p>",
    "vendor": "Acme",
    "product_type": "Apparel",
    "status": "draft",
    "tags": "cotton,summer"
  }
}

getProduct

Retrieves a single product by ID.

Parameters:

Name	Type	Required	Description
`productId`	`string`	Yes	The product ID.
`fields`	`string?`	No	Comma-separated list of fields to include.

Returns: ProductObject|error

Sample code:

admin:ProductObject product = check shopify->getProduct("7982605344961");

Sample response:

{
  "product": {
    "id": 7982605344961,
    "title": "Classic T-Shirt",
    "vendor": "Acme",
    "product_type": "Apparel",
    "status": "active"
  }
}

updateProduct

Updates a product and its variants and images.

Parameters:

Name	Type	Required	Description
`productId`	`string`	Yes	The product ID.
`payload`	`UpdateProduct`	Yes	The Product object with updated fields.

Returns: ProductObject|error

Sample code:

admin:ProductObject updated = check shopify->updateProduct("7982605344961", {
    product: {
        title: "Premium Classic T-Shirt",
        status: "active"
    }
});

Sample response:

{
  "product": {
    "id": 7982605344961,
    "title": "Premium Classic T-Shirt",
    "vendor": "Acme",
    "status": "active"
  }
}

Product variants

getProductVariants

Retrieves a list of product variants for a given product.

Parameters:

Name	Type	Required	Description
`productId`	`string`	Yes	The product ID.
`fields`	`string?`	No	Comma-separated list of fields to include.
`'limit`	`int?`	No	Maximum results per page.
`sinceId`	`string?`	No	Restrict results to after the specified ID.

Returns: ProductVariantList|error

Sample code:

admin:ProductVariantList variants = check shopify->getProductVariants("7982605344961");

Sample response:

{
  "variants": [
    {
      "id": 43503271895233,
      "product_id": 7982605344961,
      "title": "Small / Blue",
      "price": "19.99",
      "sku": "TSHIRT-S-BLUE",
      "inventory_quantity": 50
    }
  ]
}

createProductVariant

Creates a new product variant.

Parameters:

Name	Type	Required	Description
`productId`	`string`	Yes	The product ID.
`payload`	`CreateProductVariant`	Yes	The Product variant object to be created.

Returns: ProductVariantObject|error

Sample code:

admin:ProductVariantObject variant = check shopify->createProductVariant("7982605344961", {
    variant: {
        option1: "Large",
        price: "24.99",
        sku: "TSHIRT-L-BLUE"
    }
});

Sample response:

{
  "variant": {
    "id": 43503271895300,
    "product_id": 7982605344961,
    "title": "Large",
    "price": "24.99",
    "sku": "TSHIRT-L-BLUE"
  }
}

getProductVariant

Retrieves a single product variant by its ID.

Parameters:

Name	Type	Required	Description
`variantId`	`string`	Yes	The variant ID.
`fields`	`string?`	No	Comma-separated list of fields to include.

Returns: ProductVariantObject|error

Sample code:

admin:ProductVariantObject variant = check shopify->getProductVariant("43503271895233");

Sample response:

{
  "variant": {
    "id": 43503271895233,
    "product_id": 7982605344961,
    "title": "Small / Blue",
    "price": "19.99",
    "sku": "TSHIRT-S-BLUE"
  }
}

updateProductVariant

Updates an existing product variant.

Parameters:

Name	Type	Required	Description
`variantId`	`string`	Yes	The variant ID.
`payload`	`UpdateProductVariant`	Yes	The Product variant object with updated fields.

Returns: ProductVariantObject|error

Sample code:

admin:ProductVariantObject updated = check shopify->updateProductVariant("43503271895233", {
    variant: {
        price: "22.99"
    }
});

Sample response:

{
  "variant": {
    "id": 43503271895233,
    "price": "22.99",
    "sku": "TSHIRT-S-BLUE"
  }
}

Order management

getOrders

Retrieves a list of orders with optional filtering by status, financial status, fulfillment status, and date ranges.

Parameters:

Name	Type	Required	Description
`ids`	`string?`	No	Comma-separated list of order IDs.
`'limit`	`int?`	No	Maximum results per page (default: 50, max: 250).
`status`	`string?`	No	Filter by order status: `open`, `closed`, `cancelled`, or `any` (default: `open`).
`financialStatus`	`string?`	No	Filter by financial status: `authorized`, `pending`, `paid`, `partially_paid`, `refunded`, `voided`, `partially_refunded`, `any`, or `unpaid`.
`fulfillmentStatus`	`string?`	No	Filter by fulfillment status: `shipped`, `partial`, `unshipped`, `any`, or `unfulfilled`.
`fields`	`string?`	No	Comma-separated list of fields to include.

Returns: OrderList|error

Sample code:

admin:OrderList orders = check shopify->getOrders(status = "open", 'limit = 10);

Sample response:

{
  "orders": [
    {
      "id": 5553109696705,
      "name": "#1001",
      "email": "[email protected]",
      "total_price": "49.98",
      "financial_status": "paid",
      "fulfillment_status": null,
      "created_at": "2024-01-20T14:00:00-05:00"
    }
  ]
}

createOrder

Creates an order. By default, product inventory is not claimed.

Parameters:

Name	Type	Required	Description
`payload`	`CreateOrder`	Yes	The Order object to be created.

Returns: OrderObject|error

Sample code:

admin:OrderObject newOrder = check shopify->createOrder({
    'order: {
        line_items: [
            {
                variant_id: 43503271895233,
                quantity: 2
            }
        ],
        customer: {
            id: 6940095127745
        },
        financial_status: "pending"
    }
});

Sample response:

{
  "order": {
    "id": 5553109696705,
    "name": "#1001",
    "total_price": "39.98",
    "financial_status": "pending",
    "fulfillment_status": null,
    "line_items": [
      {
        "id": 12345678901234,
        "variant_id": 43503271895233,
        "title": "Classic T-Shirt",
        "quantity": 2,
        "price": "19.99"
      }
    ]
  }
}

getOrder

Retrieves a specific order by ID.

Parameters:

Name	Type	Required	Description
`orderId`	`string`	Yes	The order ID.
`fields`	`string?`	No	Comma-separated list of fields to include.

Returns: OrderObject|error

Sample code:

admin:OrderObject order = check shopify->getOrder("5553109696705");

Sample response:

{
  "order": {
    "id": 5553109696705,
    "name": "#1001",
    "email": "[email protected]",
    "total_price": "49.98",
    "financial_status": "paid",
    "fulfillment_status": null
  }
}

updateOrder

Updates an existing order.

Parameters:

Name	Type	Required	Description
`orderId`	`string`	Yes	The order ID.
`payload`	`UpdateOrder`	Yes	The Order object with updated fields.

Returns: OrderObject|error

Sample code:

admin:OrderObject updated = check shopify->updateOrder("5553109696705", {
    'order: {
        note: "Customer requested gift wrapping",
        tags: "gift,priority"
    }
});

Sample response:

{
  "order": {
    "id": 5553109696705,
    "name": "#1001",
    "note": "Customer requested gift wrapping",
    "tags": "gift,priority"
  }
}

Fulfillments

getOrderFulfillments

Retrieves fulfillments associated with an order.

Parameters:

Name	Type	Required	Description
`orderId`	`string`	Yes	The order ID.
`createdAtMin`	`string?`	No	Show fulfillments created after this date (ISO 8601).
`createdAtMax`	`string?`	No	Show fulfillments created before this date (ISO 8601).
`fields`	`string?`	No	Comma-separated list of fields to include.
`'limit`	`int?`	No	Maximum results (default: 50, max: 250).

Returns: OrderFulfillmentsList|error

Sample code:

admin:OrderFulfillmentsList fulfillments = check shopify->getOrderFulfillments("5553109696705");

Sample response:

{
  "fulfillments": [
    {
      "id": 4521387524289,
      "order_id": 5553109696705,
      "status": "success",
      "tracking_company": "UPS",
      "tracking_numbers": ["1Z999AA10123456784"],
      "created_at": "2024-01-22T10:00:00-05:00"
    }
  ]
}

createOrderFulfillment

Creates a fulfillment for the specified order and line items. If no line item IDs are specified, all unfulfilled and partially fulfilled line items are fulfilled.

Parameters:

Name	Type	Required	Description
`orderId`	`string`	Yes	The order ID.
`payload`	`CreateOrderFulfillment`	Yes	The fulfillment object to be created.

Returns: OrderFulfillmentObject|error

Sample code:

admin:OrderFulfillmentObject fulfillment = check shopify->createOrderFulfillment("5553109696705", {
    fulfillment: {
        tracking_company: "UPS",
        tracking_numbers: ["1Z999AA10123456784"],
        notify_customer: "true"
    }
});

Sample response:

{
  "fulfillment": {
    "id": 4521387524289,
    "order_id": 5553109696705,
    "status": "success",
    "tracking_company": "UPS",
    "tracking_numbers": ["1Z999AA10123456784"]
  }
}

Draft orders

createDraftOrder

Creates a draft order for deferred or manual order workflows.

Parameters:

Name	Type	Required	Description
`payload`	`CreateDraftOrder`	Yes	The Draft order object to be created.
`customerId`	`string?`	No	Used to load the customer and associate their email.
`useCustomerDefaultAddress`	`boolean?`	No	Load customer shipping information if `true`.

Returns: DraftOrderObject|error

Sample code:

admin:DraftOrderObject draft = check shopify->createDraftOrder({
    draft_order: {
        line_items: [
            {
                title: "Custom Item",
                price: "29.99",
                quantity: 1
            }
        ],
        customer: {
            id: 6940095127745
        }
    }
});

Sample response:

{
  "draft_order": {
    "id": 1078505537729,
    "name": "#D1",
    "status": "open",
    "total_price": "29.99",
    "subtotal_price": "29.99",
    "customer": {
      "id": 6940095127745,
      "first_name": "Steve"
    }
  }
}

Transactions & refunds

createTransactionForOrder

Creates a transaction for an order (e.g., capture, sale, or external payment).

Parameters:

Name	Type	Required	Description
`orderId`	`string`	Yes	The order ID.
`payload`	`CreateTransaction`	Yes	The Transaction object to be created.
`'source`	`string?`	No	Set to `external` for cash transactions.

Returns: TransactionObject|error

Sample code:

admin:TransactionObject txn = check shopify->createTransactionForOrder("5553109696705", {
    'transaction: {
        kind: "capture",
        amount: "49.98"
    }
});

Sample response:

{
  "transaction": {
    "id": 6981435809,
    "order_id": 5553109696705,
    "kind": "capture",
    "amount": "49.98",
    "status": "success",
    "created_at": "2024-01-22T11:00:00-05:00"
  }
}

createRefundForOrder

Creates a refund for an order.

Parameters:

Name	Type	Required	Description
`orderId`	`string`	Yes	The order ID.
`payload`	`CreateRefund`	Yes	The Refund object to be created.

Returns: RefundObject|error

Sample code:

admin:RefundObject refund = check shopify->createRefundForOrder("5553109696705", {
    refund: {
        note: "Customer returned item",
        shipping: {
            full_refund: true
        }
    }
});

Sample response:

{
  "refund": {
    "id": 929361237,
    "order_id": 5553109696705,
    "note": "Customer returned item",
    "created_at": "2024-01-25T09:00:00-05:00"
  }
}

Order risks

getOrderRisks

Retrieves a list of all order risks for an order.

Parameters:

Name	Type	Required	Description
`orderId`	`string`	Yes	The order ID.

Returns: OrderRiskList|error

Sample code:

admin:OrderRiskList risks = check shopify->getOrderRisks("5553109696705");

Sample response:

{
  "risks": [
    {
      "id": 8723457891,
      "order_id": 5553109696705,
      "message": "This order was placed from a proxy IP",
      "recommendation": "investigate",
      "score": "0.8",
      "source": "External",
      "cause_cancel": false,
      "display": true
    }
  ]
}

createOrderRisk

Creates an order risk for an order.

Parameters:

Name	Type	Required	Description
`orderId`	`string`	Yes	The order ID.
`payload`	`CreateOrderRisk`	Yes	The order risk object to be created.

Returns: OrderRiskObject|error

Sample code:

admin:OrderRiskObject risk = check shopify->createOrderRisk("5553109696705", {
    risk: {
        message: "This order came from an unusual location",
        recommendation: "investigate",
        score: "0.7",
        'source: "External",
        cause_cancel: false,
        display: true
    }
});

Sample response:

{
  "risk": {
    "id": 8723457892,
    "order_id": 5553109696705,
    "message": "This order came from an unusual location",
    "recommendation": "investigate",
    "score": "0.7",
    "source": "External"
  }
}

getOrderRisk

Retrieves a single order risk by its ID.

Parameters:

Name	Type	Required	Description
`orderId`	`string`	Yes	The order ID.
`riskId`	`string`	Yes	The order risk ID.

Returns: OrderRiskObject|error

Sample code:

admin:OrderRiskObject risk = check shopify->getOrderRisk("5553109696705", "8723457891");

Sample response:

{
  "risk": {
    "id": 8723457891,
    "order_id": 5553109696705,
    "message": "This order was placed from a proxy IP",
    "recommendation": "investigate",
    "score": "0.8"
  }
}

updateOrderRisk

Updates an order risk.

Parameters:

Name	Type	Required	Description
`orderId`	`string`	Yes	The order ID.
`riskId`	`string`	Yes	The order risk ID.
`payload`	`UpdateOrderRisk`	Yes	The order risk object with updated fields.

Returns: OrderRiskObject|error

Sample code:

admin:OrderRiskObject updated = check shopify->updateOrderRisk("5553109696705", "8723457891", {
    risk: {
        recommendation: "accept",
        score: "0.2"
    }
});

Sample response:

{
  "risk": {
    "id": 8723457891,
    "order_id": 5553109696705,
    "recommendation": "accept",
    "score": "0.2"
  }
}

Webhook management

getWebhooks

Retrieves a list of webhook subscriptions with optional filtering by address, topic, and date ranges.

Parameters:

Name	Type	Required	Description
`address`	`string?`	No	Filter by the URI that receives the POST request.
`topic`	`string?`	No	Filter by webhook topic (e.g., `orders/create`).
`'limit`	`int?`	No	Maximum results (default: 50, max: 250).
`fields`	`string?`	No	Comma-separated list of fields to include.

Returns: WebhookList|error

Sample code:

admin:WebhookList webhooks = check shopify->getWebhooks(topic = "orders/create");

Sample response:

{
  "webhooks": [
    {
      "id": 1071340091,
      "address": "https://example.com/webhooks/orders",
      "topic": "orders/create",
      "format": "json",
      "created_at": "2024-01-10T08:00:00-05:00"
    }
  ]
}

createWebhook

Creates a new webhook subscription by specifying both an address and a topic.

Parameters:

Name	Type	Required	Description
`payload`	`CreateWebhook`	Yes	The webhook subscription object to be created.

Returns: WebhookObject|error

Sample code:

admin:WebhookObject webhook = check shopify->createWebhook({
    webhook: {
        topic: "orders/create",
        address: "https://example.com/webhooks/orders",
        format: "json"
    }
});

Sample response:

{
  "webhook": {
    "id": 1071340092,
    "address": "https://example.com/webhooks/orders",
    "topic": "orders/create",
    "format": "json",
    "created_at": "2024-01-28T12:00:00-05:00"
  }
}

getWebhook

Retrieves a single webhook subscription by its ID.

Parameters:

Name	Type	Required	Description
`webhookId`	`string`	Yes	The webhook ID.
`fields`	`string?`	No	Comma-separated list of fields to include.

Returns: WebhookObject|error

Sample code:

admin:WebhookObject webhook = check shopify->getWebhook("1071340091");

Sample response:

{
  "webhook": {
    "id": 1071340091,
    "address": "https://example.com/webhooks/orders",
    "topic": "orders/create",
    "format": "json"
  }
}

updateWebhook

Updates a webhook subscription's topic or address URI.

Parameters:

Name	Type	Required	Description
`webhookId`	`string`	Yes	The webhook ID.
`payload`	`UpdateWebhook`	Yes	The webhook object with updated fields.

Returns: WebhookObject|error

Sample code:

admin:WebhookObject updated = check shopify->updateWebhook("1071340091", {
    webhook: {
        address: "https://new-endpoint.example.com/webhooks/orders"
    }
});

Sample response:

{
  "webhook": {
    "id": 1071340091,
    "address": "https://new-endpoint.example.com/webhooks/orders",
    "topic": "orders/create"
  }
}

getWebhookCount

Retrieves a count of existing webhook subscriptions, optionally filtered by address or topic.

Parameters:

Name	Type	Required	Description
`address`	`string?`	No	Filter by the URI that receives the POST request.
`topic`	`string?`	No	Filter by webhook topic.

Returns: WebhookCountObject|error

Sample code:

admin:WebhookCountObject count = check shopify->getWebhookCount();

Sample response:

{
  "count": 4
}

Client​

Configuration​

Initializing the client​

Operations​

Customer management​

Product management​

Product variants​

Order management​

Fulfillments​

Draft orders​

Transactions & refunds​

Order risks​

Webhook management​

Client

Configuration

Initializing the client

Operations

Customer management

Product management

Product variants

Order management

Fulfillments

Draft orders

Transactions & refunds

Order risks

Webhook management