SearchAF Logo

Shopify#

Shopify embedded app integration

Get shop configuration status#

GET/shopify/shop/status

Check if a Shopify shop has completed OAuth and has a configured project. Used by the embedded app to determine which UI to show (wizard vs dashboard).

Authentication: Requires Shopify session token via Authorization header. The shop domain is extracted from the session token's 'dest' claim.

Called from the Shopify embedded app on initial load.

Authentication required: shopifySessionToken

Code Examples#

curl -X GET "https://searchaf.antfly.io/api/v1/shopify/shop/status" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "has_oauth": true,
  "has_project": false,
  "shop_domain": "example.myshopify.com",
  "project": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Store",
    "slug": "my-store",
    "description": "E-commerce store for outdoor gear",
    "project_type": "woocommerce",
    "antfly_cluster_id": "string",
    "integration_config": {},
    "tables": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "project_id": "550e8400-e29b-41d4-a716-446655440000",
        "slug": "products",
        "is_default": true,
        "created_at": "2025-10-02T15:30:00Z",
        "updated_at": "2025-10-02T15:30:00Z"
      }
    ],
    "status": "active",
    "created_at": "2025-10-02T15:30:00Z",
    "updated_at": "2025-10-02T15:30:00Z",
    "settings": {}
  }
}

Get widget configuration for shop#

GET/shopify/widget-config

Returns the configuration needed for the theme extension widget, including a read-only API key, table slug, and API URL. This endpoint is used by the embedded app dashboard to sync configuration to app metafields.

Authentication: Requires Shopify session token via Authorization header. The shop domain is extracted from the session token's 'dest' claim.

Authentication required: shopifySessionToken

Code Examples#

curl -X GET "https://searchaf.antfly.io/api/v1/shopify/widget-config" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "api_key": "searchaf_ro_abc123...",
  "table_slug": "products",
  "api_url": "https://searchaf.antfly.io/api/v1"
}

Create a Shopify project#

POST/shopify/projects

Creates a new project linked to a Shopify shop. This endpoint:

  1. Looks up shop details from the user's pending OAuth token (user_shop_tokens)
  2. Creates a new project with type "shopify"
  3. Links the shop to the project by creating shopify_shops record
  4. Moves the access token from user_shop_tokens to shopify_access_tokens

Requires the user to have completed OAuth with the Shopify shop first. Called from the SearchAF dashboard after OAuth completion.

Authentication required: bearerAuth

Request Body#

Example:

{
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "shop_domain": "my-store.myshopify.com"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/shopify/projects" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "shop_domain": "my-store.myshopify.com"
}'

Responses#

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Store",
  "slug": "my-store",
  "description": "E-commerce store for outdoor gear",
  "project_type": "woocommerce",
  "antfly_cluster_id": "string",
  "integration_config": {},
  "tables": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "project_id": "550e8400-e29b-41d4-a716-446655440000",
      "slug": "products",
      "is_default": true,
      "created_at": "2025-10-02T15:30:00Z",
      "updated_at": "2025-10-02T15:30:00Z"
    }
  ],
  "status": "active",
  "created_at": "2025-10-02T15:30:00Z",
  "updated_at": "2025-10-02T15:30:00Z",
  "settings": {}
}

Get sync job status#

GET/shopify/sync/{id}

Poll sync job status to track product sync progress. Returns current status, progress percentage, and any error messages.

Use this endpoint to poll for sync completion (typically every 2 seconds). Stop polling when status is 'completed' or 'failed'.

Called from the Shopify embedded app dashboard.

Authentication required: shopifySessionToken

Parameters#

NameTypeLocationRequiredDescription
idstringpathYesSync job ID

Code Examples#

curl -X GET "https://searchaf.antfly.io/api/v1/shopify/sync/123e4567-e89b-12d3-a456-426614174000" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "shopify_shop_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "progress_percent": 45,
  "last_cursor": "string",
  "error_message": "string",
  "started_at": "2025-10-02T15:30:00Z",
  "completed_at": "2025-10-02T15:30:00Z",
  "created_at": "2025-10-02T15:30:00Z",
  "updated_at": "2025-10-02T15:30:00Z"
}

Shopify webhook#

POST/webhooks/shopify

Handle Shopify webhook events (app/uninstalled, shop/update, etc). This endpoint:

  1. Verifies the HMAC signature from Shopify
  2. Routes to the appropriate handler based on X-Shopify-Topic header

For app/uninstalled events:

  • Freezes the associated project (sets status to 'frozen')
  • Deletes access tokens for the shop
  • Updates shop records with uninstall timestamp

This webhook is automatically called by Shopify based on the configured topics.

Parameters#

NameTypeLocationRequiredDescription
X-Shopify-Hmac-Sha256stringheaderYesHMAC signature for webhook verification
X-Shopify-Shop-DomainstringheaderNoShop domain (optional, included in payload)
X-Shopify-TopicstringheaderYesWebhook topic (e.g., app/uninstalled, shop/update)

Request Body#

Example:

{
    "id": 123456,
    "domain": "example.myshopify.com"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/webhooks/shopify" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "id": 123456,
    "domain": "example.myshopify.com"
}'

Responses#

{
  "received": true
}