Integrate with Price History & Schedules using explicit, plan-aware contracts.

Response example

{
  "data": {
    "shop": {
      "domain": "demo.myshopify.com",
      "planTier": "ENTERPRISE"
    },
    "token": {
      "id": 42,
      "label": "ERP Sync",
      "prefix": "chrn_ab12cd34",
      "scopes": [
        "price_changes:read",
        "schedules:read",
        "analytics:read"
      ]
    }
  }
}

Common errors

• AUTH_INVALID Invalid API token.
• PLAN_REQUIRED Merchant API requires ENTERPRISE.
• RATE_LIMITED Request rate exceeded.

Request example

{
  "query": {
    "limit": "50",
    "offset": "0",
    "source": "scheduled",
    "changeType": "decrease"
  }
}

Common errors

• VALIDATION_ERROR Invalid filter values.
• AUTH_FORBIDDEN_SCOPE Missing scope price_changes:read.

Key considerations

Request example

{
  "query": {
    "limit": "25",
    "offset": "0",
    "search": "Blue variant",
    "changeType": "decrease",
    "source": "scheduled",
    "dateFrom": "2026-03-01",
    "dateTo": "2026-03-31",
    "minPrice": "10.00",
    "maxPrice": "99.00"
  }
}

Common errors

• NOT_FOUND Product not found.
• AUTH_FORBIDDEN_SCOPE Missing scope price_changes:read.

Key considerations

Request example

{
  "query": {
    "limit": "25",
    "offset": "0",
    "status": "SCHEDULED",
    "search": "weekend",
    "dateFrom": "2026-03-01",
    "dateTo": "2026-03-31"
  }
}

Common errors

• AUTH_FORBIDDEN_SCOPE Missing scope schedules:read.
• VALIDATION_ERROR Unsupported status filter.

Key considerations

Price-only schedule (PRICE)

{
  "body": {
    "name": "Weekend promo",
    "scheduleType": "SINGLE",
    "priceField": "PRICE",
    "scheduledAt": "2026-03-29T08:00:00.000Z",
    "timezone": "UTC",
    "items": [
      {
        "shopifyVariantId": "gid://shopify/ProductVariant/44893011122420",
        "newPrice": "17.99"
      }
    ]
  }
}

Request fields

• nameOptional

  Optional label (max 255 chars). Must be unique per shop after normalization.

• notesOptional

  Optional operator note saved to schedule audit trail.

• scheduleTypeRequired

  SINGLE or EXPIRES_AT. EXPIRES_AT requires expiresAt.

• priceFieldRequired

  PRICE, COMPARE_AT_PRICE, or BOTH. Controls required item fields and execution behavior.

• scheduledAtRequired

  ISO-8601 datetime. Must satisfy minimum future buffer unless executeImmediately=true.

• expiresAtOptional

  ISO-8601 datetime required for EXPIRES_AT; must be after scheduledAt and at least 2 hours later.

• timezoneOptional

  Optional timezone label (defaults to UTC).

• discountWarningThresholdOptional

  Non-negative number used for large-discount warning checks.

• requiresApprovalOptional

  Flag recorded on schedule for operator workflows.

• executeImmediatelyOptional

  Enterprise-only acceleration flag. Runs as soon as possible and bypasses future-time buffer checks.

• confirmLargeItemCountOptional

  Set true to acknowledge large item-count validation gate.

• confirmLargeDiscountsOptional

  Set true after reviewing warning-level discount/item warnings from prior validation attempts.

• items[]Required

  At least one target item. Each item must resolve to a variant owned by the authenticated shop.

• items[].variantId | items[].shopifyVariantIdRequired

  Provide at least one identifier. If both are provided, they must point to the same shop-owned variant.

• items[].newPriceOptional

  Required for PRICE and BOTH. Not accepted for COMPARE_AT_PRICE.

• items[].newCompareAtPriceOptional

  Required for COMPARE_AT_PRICE and BOTH. Not accepted for PRICE.

Common errors

• AUTH_FORBIDDEN_SCOPE Missing scope: schedules:write.
• VALIDATION_ERROR Schedule payload or validation checks failed (field, item, conflict, timing, or warning-confirmation gates).
• PLAN_REQUIRED Merchant API access requires ENTERPRISE plan.
• RATE_LIMITED Rate limit exceeded. Retry after the reset window.
• PAYLOAD_TOO_LARGE Body too large.
• VALIDATION_ERROR Plan quota/limit conflict while reserving schedule usage (HTTP 409).

Key considerations

Request example

{
  "headers": {
    "Authorization": "Bearer <your_api_token>"
  }
}

Common errors

• NOT_FOUND Schedule not found.
• AUTH_FORBIDDEN_SCOPE Missing scope: schedules:read.
• PLAN_REQUIRED Merchant API access requires ENTERPRISE plan.
• RATE_LIMITED Rate limit exceeded. Retry after the reset window.

Key considerations

Request example

{
  "body": {
    "note": "Cancelled by ERP workflow"
  }
}

Request fields

• noteOptional

  Optional cancellation reason stored in schedule audit history.

Common errors

• NOT_FOUND Schedule not found.
• AUTH_FORBIDDEN_SCOPE Missing scope: schedules:write.
• SCHEDULE_STATE_INVALID Schedule cannot be cancelled in current state (response includes current status).
• PLAN_REQUIRED Merchant API access requires ENTERPRISE plan.
• RATE_LIMITED Rate limit exceeded. Retry after the reset window.

Key considerations

Request example

{
  "query": {
    "requestedDays": "30",
    "topProductsPage": "1",
    "topProductsPageSize": "10",
    "topProductsQuery": "tee"
  }
}

Common errors

• AUTH_FORBIDDEN_SCOPE Missing scope analytics:read.

Key considerations

Request example

{
  "query": {
    "variantId": "gid://shopify/ProductVariant/44893011122420"
  }
}

Common errors

• NOT_FOUND Product analytics not found.
• AUTH_FORBIDDEN_SCOPE Missing scope analytics:read.

Key considerations

Response example

{
  "data": {
    "items": [
      {
        "id": 1,
        "label": "ERP Sync",
        "tokenPrefix": "chrn_ab12cd34",
        "last4": "Qe7m",
        "revokedAt": null
      }
    ]
  }
}

Common errors

• AUTH_FORBIDDEN_SCOPE Missing scope tokens:manage.

Request example

{
  "body": {
    "label": "Data Warehouse",
    "scopes": [
      "price_changes:read",
      "schedules:read",
      "analytics:read"
    ]
  }
}

Common errors

• TOKEN_LIMIT_REACHED Token limit reached for this shop.
• VALIDATION_ERROR Invalid token label or scopes.

Key considerations

Response example

{
  "data": {
    "tokenId": 11,
    "revoked": true,
    "alreadyRevoked": false
  }
}

Common errors

• NOT_FOUND Token not found.
• AUTH_FORBIDDEN_SCOPE Missing scope tokens:manage.

Key considerations