Cratejoy MCP by usefulapi

The store-level metadata record (id, store_id, created_at, updated_at, data: free-form JSON attached to the store). GET /v1/metadata/.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List customers (id, name, email, country, location, num_orders, num_subscriptions, subscription_status, total_revenue). Filter by email or name, or with `filters` (e.g. { 'addresses.city': 'Austin' }). Relationships: addresses, logs, carts, notes, orders, shipments, subscriptions. GET /v1/customers/.

{
  "type": "object",
  "properties": {
    "email": {
      "description": "Exact customer email.",
      "type": "string",
      "minLength": 3,
      "maxLength": 200
    },
    "name": {
      "description": "Customer name contains this text (case-insensitive).",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "filters": {
      "description": "Extra Cratejoy filters as { '[relation.]property[__comparison]': value }. Comparisons: eq (default), ne, lt, le, gt, ge, like, ilike (% is the wildcard), in, nin (comma-separated), is_null. Status columns take integers. Example: { 'customer.email__like': '%@example.com' }.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 80
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 200
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          }
        ]
      }
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "page": {
      "description": "Page number, counting from 0 (default 0). Pass the previous reply's next_page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One customer by id, optionally with relationships (addresses, subscriptions, orders, shipments, notes...). GET /v1/customers/{customer_id}/.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Cratejoy customer id."
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List subscriptions (id, status, autorenew, billing_name, start_date, end_date, skipped_date, is_test, product_billing_id). Filter by status and end-date range, or with `filters` (e.g. { 'customer.email__like': '%@example.com' }). Relationships: customer, billing, term, product, address, orders, shipments, logs. GET /v1/subscriptions/.

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Subscription status (unpaid, suspended and others are deprecated by Cratejoy).",
      "type": "string",
      "enum": [
        "unpaid",
        "active",
        "cancelled",
        "suspended",
        "expired",
        "past_due",
        "pending_renewal",
        "renewing",
        "unpaid_order_failed",
        "transferred"
      ]
    },
    "ends_after": {
      "description": "Only subscriptions whose end_date is on or after this date/date-time.",
      "type": "string"
    },
    "ends_before": {
      "description": "Only subscriptions whose end_date is on or before this date/date-time.",
      "type": "string"
    },
    "filters": {
      "description": "Extra Cratejoy filters as { '[relation.]property[__comparison]': value }. Comparisons: eq (default), ne, lt, le, gt, ge, like, ilike (% is the wildcard), in, nin (comma-separated), is_null. Status columns take integers. Example: { 'customer.email__like': '%@example.com' }.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 80
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 200
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          }
        ]
      }
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "page": {
      "description": "Page number, counting from 0 (default 0). Pass the previous reply's next_page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One subscription by id, optionally with relationships (customer, billing, term, product, address, orders, shipments, logs). GET /v1/subscriptions/{sub_id}/.

{
  "type": "object",
  "properties": {
    "subscription_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Cratejoy subscription id."
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    }
  },
  "required": [
    "subscription_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Coupons applied to a subscription's next renewal (coupon_id, code_used, enabled, num_renewals). GET /v1/subscriptions/{sub_id}/coupons/.

{
  "type": "object",
  "properties": {
    "subscription_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Cratejoy subscription id."
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "page": {
      "description": "Page number, counting from 0 (default 0). Pass the previous reply's next_page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100000
    }
  },
  "required": [
    "subscription_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List orders (id, customer_id, placed_at, status, financial_status, fulfillment_status, is_renewal, is_gift, sub_total, total, total_shipping, total_tax). Amounts are in cents. Filter by payment status and placed-at range, or with `filters`. Relationships: customer, products, coupons, bill_address, ship_address, fulfillments, transactions, subscriptions. GET /v1/orders/.

{
  "type": "object",
  "properties": {
    "financial_status": {
      "description": "Payment status of the order.",
      "type": "string",
      "enum": [
        "pending",
        "authorized",
        "partially_paid",
        "paid",
        "partially_refunded",
        "refunded",
        "voided"
      ]
    },
    "placed_after": {
      "description": "Only orders placed on or after this date/date-time.",
      "type": "string"
    },
    "placed_before": {
      "description": "Only orders placed on or before this date/date-time.",
      "type": "string"
    },
    "filters": {
      "description": "Extra Cratejoy filters as { '[relation.]property[__comparison]': value }. Comparisons: eq (default), ne, lt, le, gt, ge, like, ilike (% is the wildcard), in, nin (comma-separated), is_null. Status columns take integers. Example: { 'customer.email__like': '%@example.com' }.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 80
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 200
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          }
        ]
      }
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "page": {
      "description": "Page number, counting from 0 (default 0). Pass the previous reply's next_page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One order by id, optionally with relationships (customer, products, coupons, addresses, fulfillments, transactions). GET /v1/orders/{order_id}/.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Cratejoy order id."
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List shipments (id, customer_id, status, created_at, target_at, shipped_at, tracking_number, is_gift). Filter by status and creation range, or with `filters`. Relationships: customer, fulfillments, labels, ship_address, subscriptions. GET /v1/shipments/.

{
  "type": "object",
  "properties": {
    "status": {
      "description": "Shipment status.",
      "type": "string",
      "enum": [
        "unshipped",
        "shipped",
        "cancelled"
      ]
    },
    "created_after": {
      "description": "Only shipments created on or after this date/date-time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only shipments created on or before this date/date-time.",
      "type": "string"
    },
    "filters": {
      "description": "Extra Cratejoy filters as { '[relation.]property[__comparison]': value }. Comparisons: eq (default), ne, lt, le, gt, ge, like, ilike (% is the wildcard), in, nin (comma-separated), is_null. Status columns take integers. Example: { 'customer.email__like': '%@example.com' }.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 80
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 200
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          }
        ]
      }
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "page": {
      "description": "Page number, counting from 0 (default 0). Pass the previous reply's next_page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One shipment by id, optionally with relationships (customer, fulfillments, labels, ship_address, subscriptions). GET /v1/shipments/{ship_id}/.

{
  "type": "object",
  "properties": {
    "shipment_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Cratejoy shipment id."
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    }
  },
  "required": [
    "shipment_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List products (id, name, sku, slug, description, visible, listed, giftable, ship_option, ship_weight, has_subscribers). Filter by type or with `filters` (e.g. { 'visible': true }). Relationships: billing, instances, variants, subscription_types. GET /v1/products/.

{
  "type": "object",
  "properties": {
    "product_type": {
      "description": "Product type.",
      "type": "string",
      "enum": [
        "subscription",
        "one_time",
        "gift_card"
      ]
    },
    "filters": {
      "description": "Extra Cratejoy filters as { '[relation.]property[__comparison]': value }. Comparisons: eq (default), ne, lt, le, gt, ge, like, ilike (% is the wildcard), in, nin (comma-separated), is_null. Status columns take integers. Example: { 'customer.email__like': '%@example.com' }.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 80
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 200
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          }
        ]
      }
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "page": {
      "description": "Page number, counting from 0 (default 0). Pass the previous reply's next_page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One product by id, optionally with relationships. GET /v1/products/{prod_id}/.

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Cratejoy product id."
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    }
  },
  "required": [
    "product_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List payment transactions (id, created_at, result: authorized/captured/failed/refunded, total in cents, is_test, order). Filter by result and creation range, or with `filters`. GET /v1/transactions/.

{
  "type": "object",
  "properties": {
    "result": {
      "description": "Transaction result.",
      "type": "string",
      "enum": [
        "authorized",
        "captured",
        "failed",
        "refunded",
        "failed_refund"
      ]
    },
    "created_after": {
      "description": "Only transactions created on or after this date/date-time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only transactions created on or before this date/date-time.",
      "type": "string"
    },
    "filters": {
      "description": "Extra Cratejoy filters as { '[relation.]property[__comparison]': value }. Comparisons: eq (default), ne, lt, le, gt, ge, like, ilike (% is the wildcard), in, nin (comma-separated), is_null. Status columns take integers. Example: { 'customer.email__like': '%@example.com' }.",
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 80
      },
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string",
            "maxLength": 200
          },
          {
            "type": "number"
          },
          {
            "type": "boolean"
          }
        ]
      }
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    },
    "limit": {
      "description": "Results per page, 1-100 (default 25).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 100
    },
    "page": {
      "description": "Page number, counting from 0 (default 0). Pass the previous reply's next_page.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One payment transaction by id. GET /v1/transactions/{trans_id}/.

{
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Cratejoy transaction id."
    },
    "with": {
      "description": "Relationships to embed: comma-separated names (e.g. 'customer,orders'), 'all', or an empty string for none. Omit it for the vendor default.",
      "type": "string",
      "pattern": "^(?:all|[a-z_]+(?:,[a-z_]+)*)?$"
    }
  },
  "required": [
    "transaction_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: skip a subscriber's next renewal (action 'skip') or undo the skip (action 'unskip'). Requires confirm=true. Repeating the same action changes nothing more. This changes a merchant customer's subscription in Cratejoy; it is not this server's own billing. PUT /v1/subscriptions/{sub_id}/skip/.

{
  "type": "object",
  "properties": {
    "subscription_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Cratejoy subscription id."
    },
    "action": {
      "type": "string",
      "enum": [
        "skip",
        "unskip"
      ],
      "description": "'skip' skips the next renewal; 'unskip' restores it."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: confirms the customer's renewal schedule should change."
    }
  },
  "required": [
    "subscription_id",
    "action",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: cancel a subscriber's subscription in Cratejoy (the customer stops receiving boxes and renewals). This cancels the merchant's customer subscription, NOT this server's Pro plan (use the *_cancel_subscription tool for that). Requires confirm=true. A cancelled subscription can be restored with cratejoy_reactivate_subscription. PUT /v1/subscriptions/{sub_id}/cancel/.

{
  "type": "object",
  "properties": {
    "subscription_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Cratejoy subscription id."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: confirms the customer's subscription should be cancelled."
    },
    "log_note": {
      "description": "Optional note recorded in the subscription's log.",
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    }
  },
  "required": [
    "subscription_id",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: reactivate a cancelled subscription so it renews and charges the customer again. Requires confirm=true. Reactivating an active subscription changes nothing more. PUT /v1/subscriptions/{sub_id}/reactivate/.

{
  "type": "object",
  "properties": {
    "subscription_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Cratejoy subscription id."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: confirms the subscription should renew (and be charged) again."
    },
    "log_note": {
      "description": "Optional note recorded in the subscription's log.",
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    }
  },
  "required": [
    "subscription_id",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: retry the renewal of a PAST-DUE subscription whose renewal failed within the last 30 days. This charges the customer's saved payment method. Requires confirm=true. PUT /v1/subscriptions/{sub_id}/renew/.

{
  "type": "object",
  "properties": {
    "subscription_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Cratejoy subscription id (status past_due)."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: confirms the customer's payment method should be charged."
    },
    "log_note": {
      "description": "Optional note recorded in the subscription's log.",
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    }
  },
  "required": [
    "subscription_id",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}