givingfuel_create_coupon

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.

Argument	Type	Description
name*	string	Internal coupon name.
codes*	array	One or more redeemable codes.
expires	string	When the coupon expires; omit for no expiry.
form_id	integer	Restrict the coupon to this form; omit for all forms.
currency	string	Currency code, default USD.
available	integer	How many times the coupon can be used; -1 = unlimited (default).
discount_type*	string	fixed (a currency amount) or percent.
discount_value*	number	Discount amount: currency units for a fixed discount, percent (1-100) for a percent discount.

Input schema (JSON)

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

givingfuel_delete_coupon

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}.

destructive

Argument	Type	Description
confirm*	boolean	Must be true: the user approved permanently deleting this coupon.
coupon_id*	integer	GivingFuel coupon id to delete.

Input schema (JSON)

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

givingfuel_get_coupon

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

read-only

Argument	Type	Description
coupon_id*	integer	GivingFuel coupon id (from givingfuel_list_coupons).

Input schema (JSON)

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

givingfuel_get_customer

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

read-only

Argument	Type	Description
customer_id*	integer	GivingFuel customer id (from givingfuel_list_customers, or an order's customerId).

Input schema (JSON)

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

givingfuel_get_form

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

read-only

Argument	Type	Description
form_id*	integer	GivingFuel form id (from givingfuel_list_forms).

Input schema (JSON)

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

givingfuel_get_form_inventory

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

read-only

Argument	Type	Description
form_id*	integer	GivingFuel form id.

Input schema (JSON)

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

givingfuel_get_order

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}.

read-only

Argument	Type	Description
order_id*	integer	GivingFuel order id (from givingfuel_list_orders).
include_transactions	boolean	Also return the order's transactions.

Input schema (JSON)

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

givingfuel_get_subscription

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

read-only

Argument	Type	Description
subscription_id*	integer	GivingFuel subscription id (from givingfuel_list_subscriptions).

Input schema (JSON)

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

givingfuel_get_transaction

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

read-only

Argument	Type	Description
transaction_id*	integer	GivingFuel transaction id (from givingfuel_list_transactions).

Input schema (JSON)

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

givingfuel_list_coupons

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}.

read-only

Argument	Type	Description
code	string	Only global coupons with this code (ignored with form_id).
sort	string	Sort by id: asc or desc (the vendor default applies when omitted).
limit	integer	Results per page, 1-50 (default 25).
form_id	integer	Only coupons of this form; omit for the account-wide (global) coupons.
starting_after	integer	Cursor: pass the previous reply's next_starting_after to get the next page.

Input schema (JSON)

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

givingfuel_list_customers

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.

read-only

Argument	Type	Description
sort	string	Sort by id: asc or desc (the vendor default applies when omitted).
email	string	Only the donor with this email address.
limit	integer	Results per page, 1-50 (default 25).
created_after	string	Only records created after this time.
updated_after	string	Only records updated after this time.
created_before	string	Only records created before this time.
starting_after	integer	Cursor: pass the previous reply's next_starting_after to get the next page.
updated_before	string	Only records updated before this time.

Input schema (JSON)

givingfuel_list_forms

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.

read-only

Argument	Type	Description
sort	string	Sort by id: asc or desc (the vendor default applies when omitted).
limit	integer	Results per page, 1-50 (default 25).
created_after	string	Only records created after this time.
updated_after	string	Only records updated after this time.
created_before	string	Only records created before this time.
starting_after	integer	Cursor: pass the previous reply's next_starting_after to get the next page.
updated_before	string	Only records updated before this time.

Input schema (JSON)

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

givingfuel_list_orders

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.

read-only

Argument	Type	Description
sort	string	Sort by id: asc or desc (the vendor default applies when omitted).
email	string	Only orders placed with this email address.
limit	integer	Results per page, 1-50 (default 25).
status	string	Order status string as the vendor returns it (for example "completed" or "active").
form_id	integer	Only orders of this form.
customer_id	integer	Only orders of this customer (donor) id.
order_number	string	Only the order with this order number.
created_after	string	Only records created after this time.
updated_after

givingfuel_list_subscriptions

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.

read-only

Argument	Type	Description
sort	string	Sort by id: asc or desc (the vendor default applies when omitted).
email	string	Only subscriptions of orders placed with this email.
limit	integer	Results per page, 1-50 (default 25).
status	string	Subscription status string as the vendor returns it (for example "completed" or "active").
form_id	integer	Only subscriptions of this form.
order_id	integer	Only subscriptions of this order id.
customer_id	integer	Only subscriptions of this customer (donor) id.
order_number	string	Only subscriptions of this order number.
created_after

givingfuel_list_transactions

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.

read-only

Argument	Type	Description
sort	string	Sort by id: asc or desc (the vendor default applies when omitted).
type	string	Transaction type.
email	string	Only transactions of orders placed with this email.
limit	integer	Results per page, 1-50 (default 25).
status	string	Transaction status string as the vendor returns it (for example "completed" or "active").
form_id	integer	Only transactions of this form.
order_id	integer	Only transactions of this order id.
reference	string	Only the transaction with this payment reference (txReference).
customer_id

GivingFuel MCP by usefulapi

Try it

givingfuel_create_coupon

GivingFuel MCP by usefulapi

Try it

givingfuel_create_coupon

Tools (15)