GivingFuel MCP by usefulapi

List the account's GivingFuel forms (donation / fundraising pages): id, name, status (open or closed), created and updated dates. Use the form ids to filter orders, transactions and subscriptions. GET /forms.

{
  "type": "object",
  "properties": {
    "created_after": {
      "description": "Only records created after this time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only records created before this time.",
      "type": "string"
    },
    "updated_after": {
      "description": "Only records updated after this time.",
      "type": "string"
    },
    "updated_before": {
      "description": "Only records updated before this time.",
      "type": "string"
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One form by id: name, status, accounting reference, time zone and its field layout. GET /forms/{id}.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "GivingFuel form id (from givingfuel_list_forms)."
    }
  },
  "required": [
    "form_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Inventory items of a form (limited-quantity items): path, name, sold and remaining quantity. GET /forms/{id}/inventory.

{
  "type": "object",
  "properties": {
    "form_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "GivingFuel form id."
    }
  },
  "required": [
    "form_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List donation orders (one per checkout): order number, donor billing name and address, form, total, currency and status, newest or oldest first. Filter by form, status, donor email, customer id, order number or dates. GET /search/orders.

{
  "type": "object",
  "properties": {
    "form_id": {
      "description": "Only orders of this form.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "status": {
      "description": "Order status string as the vendor returns it (for example \"completed\" or \"active\").",
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "email": {
      "description": "Only orders placed with this email address.",
      "type": "string",
      "minLength": 3,
      "maxLength": 254
    },
    "customer_id": {
      "description": "Only orders of this customer (donor) id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "order_number": {
      "description": "Only the order with this order number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "created_after": {
      "description": "Only records created after this time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only records created before this time.",
      "type": "string"
    },
    "updated_after": {
      "description": "Only records updated after this time.",
      "type": "string"
    },
    "updated_before": {
      "description": "Only records updated before this time.",
      "type": "string"
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One order by id with the donor's billing details, form, totals and status. Set include_transactions to embed the payments (charges and refunds) of the order. GET /search/orders/{id}.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "GivingFuel order id (from givingfuel_list_orders)."
    },
    "include_transactions": {
      "description": "Also return the order's transactions.",
      "type": "boolean"
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List payment transactions (money movements): amount, deductible amount, currency, type (charge, refund, voucher), payment method, masked card, status, form and donor email. Filter by type, method, form, order, donor or dates. GET /search/transactions.

{
  "type": "object",
  "properties": {
    "form_id": {
      "description": "Only transactions of this form.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "type": {
      "description": "Transaction type.",
      "type": "string",
      "enum": [
        "charge",
        "refund",
        "voucher",
        "cash",
        "preauth",
        "chargeback"
      ]
    },
    "payment_method": {
      "description": "Payment method.",
      "type": "string",
      "enum": [
        "card",
        "check",
        "offline"
      ]
    },
    "status": {
      "description": "Transaction status string as the vendor returns it (for example \"completed\" or \"active\").",
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "order_id": {
      "description": "Only transactions of this order id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "customer_id": {
      "description": "Only transactions of this customer (donor) id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "email": {
      "description": "Only transactions of orders placed with this email.",
      "type": "string",
      "minLength": 3,
      "maxLength": 254
    },
    "order_number": {
      "description": "Only transactions of this order number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "reference": {
      "description": "Only the transaction with this payment reference (txReference).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "created_after": {
      "description": "Only records created after this time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only records created before this time.",
      "type": "string"
    },
    "updated_after": {
      "description": "Only records updated after this time.",
      "type": "string"
    },
    "updated_before": {
      "description": "Only records updated before this time.",
      "type": "string"
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One transaction by id: amounts, type, payment method, masked card, gateway message and status. GET /search/transactions/{id}.

{
  "type": "object",
  "properties": {
    "transaction_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "GivingFuel transaction id (from givingfuel_list_transactions)."
    }
  },
  "required": [
    "transaction_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List recurring donations (subscriptions): amount, schedule, status, last and next payment date, payments remaining, form and donor email. Filter by form, status, donor, or next/last payment date. GET /search/subscriptions.

{
  "type": "object",
  "properties": {
    "form_id": {
      "description": "Only subscriptions of this form.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "status": {
      "description": "Subscription status string as the vendor returns it (for example \"completed\" or \"active\").",
      "type": "string",
      "minLength": 1,
      "maxLength": 60
    },
    "order_id": {
      "description": "Only subscriptions of this order id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "customer_id": {
      "description": "Only subscriptions of this customer (donor) id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "email": {
      "description": "Only subscriptions of orders placed with this email.",
      "type": "string",
      "minLength": 3,
      "maxLength": 254
    },
    "order_number": {
      "description": "Only subscriptions of this order number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "next_payment_after": {
      "description": "Only subscriptions scheduled to run after this time.",
      "type": "string"
    },
    "last_payment_after": {
      "description": "Only subscriptions last processed after this time.",
      "type": "string"
    },
    "created_after": {
      "description": "Only records created after this time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only records created before this time.",
      "type": "string"
    },
    "updated_after": {
      "description": "Only records updated after this time.",
      "type": "string"
    },
    "updated_before": {
      "description": "Only records updated before this time.",
      "type": "string"
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One recurring donation by id: amount, schedule, status, last and next payment, payments remaining. GET /search/subscriptions/{id}.

{
  "type": "object",
  "properties": {
    "subscription_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "GivingFuel subscription id (from givingfuel_list_subscriptions)."
    }
  },
  "required": [
    "subscription_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List customer records (donors): id, email, billing name and address, lifetime amount, created and updated dates. Filter by email or dates. New donors can take up to 5 minutes to appear. GET /search/customers.

{
  "type": "object",
  "properties": {
    "email": {
      "description": "Only the donor with this email address.",
      "type": "string",
      "minLength": 3,
      "maxLength": 254
    },
    "created_after": {
      "description": "Only records created after this time.",
      "type": "string"
    },
    "created_before": {
      "description": "Only records created before this time.",
      "type": "string"
    },
    "updated_after": {
      "description": "Only records updated after this time.",
      "type": "string"
    },
    "updated_before": {
      "description": "Only records updated before this time.",
      "type": "string"
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One donor (customer record) by id: email, billing details and total amount. GET /search/customers/{id}.

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "GivingFuel customer id (from givingfuel_list_customers, or an order's customerId)."
    }
  },
  "required": [
    "customer_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List GivingFuel coupons: account-wide ones, or only those of one form when form_id is given. Shows discounts, codes, availability, redeemed count and expiry. GET /coupons/global or /coupons/forms/{id}.

{
  "type": "object",
  "properties": {
    "form_id": {
      "description": "Only coupons of this form; omit for the account-wide (global) coupons.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "code": {
      "description": "Only global coupons with this code (ignored with form_id).",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "limit": {
      "description": "Results per page, 1-50 (default 25).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "starting_after": {
      "description": "Cursor: pass the previous reply's next_starting_after to get the next page.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "sort": {
      "description": "Sort by id: asc or desc (the vendor default applies when omitted).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One coupon by id with its discounts, codes, availability and redeemed counts. GET /coupons/{id}.

{
  "type": "object",
  "properties": {
    "coupon_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "GivingFuel coupon id (from givingfuel_list_coupons)."
    }
  },
  "required": [
    "coupon_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a discount coupon in the live GivingFuel account (it can be redeemed by donors right away). One discount (fixed amount or percent) and one or more codes; optionally limited to one form, to a number of uses, and to an expiry date. Not idempotent: calling it twice creates two coupons. POST /coupons.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Internal coupon name."
    },
    "codes": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      },
      "description": "One or more redeemable codes."
    },
    "discount_value": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000000,
      "description": "Discount amount: currency units for a fixed discount, percent (1-100) for a percent discount."
    },
    "discount_type": {
      "type": "string",
      "enum": [
        "fixed",
        "percent"
      ],
      "description": "fixed (a currency amount) or percent."
    },
    "currency": {
      "description": "Currency code, default USD.",
      "type": "string",
      "pattern": "^[A-Za-z]{3}$"
    },
    "available": {
      "description": "How many times the coupon can be used; -1 = unlimited (default).",
      "type": "integer",
      "minimum": -1,
      "maximum": 1000000
    },
    "form_id": {
      "description": "Restrict the coupon to this form; omit for all forms.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "expires": {
      "description": "When the coupon expires; omit for no expiry.",
      "type": "string"
    }
  },
  "required": [
    "name",
    "codes",
    "discount_value",
    "discount_type"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: permanently delete a coupon from the live GivingFuel account; its codes stop working immediately and this cannot be undone. Show the coupon (givingfuel_get_coupon) and get the user's approval first, then call with confirm: true. GET /coupons/{id}, then DELETE /coupons/{id}.

{
  "type": "object",
  "properties": {
    "coupon_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "GivingFuel coupon id to delete."
    },
    "confirm": {
      "type": "boolean",
      "const": true,
      "description": "Must be true: the user approved permanently deleting this coupon."
    }
  },
  "required": [
    "coupon_id",
    "confirm"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}